From ad97db2da4f9b70588a48dbd09698f06adc9176b Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Fri, 7 Oct 2022 22:47:41 +0200 Subject: [PATCH] Document `Array.sort()` and `sort_custom()` using unstable sorting (cherry picked from commit 85b617a6a3a17f05b8e111220daec6eb769a81e8) --- doc/classes/Array.xml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/classes/Array.xml b/doc/classes/Array.xml index 19fa755a48e..2ae380b6bc3 100644 --- a/doc/classes/Array.xml +++ b/doc/classes/Array.xml @@ -343,6 +343,7 @@ Sorts the array. + [b]Note:[/b] The sorting algorithm used is not [url=https://en.wikipedia.org/wiki/Sorting_algorithm#Stability]stable[/url]. This means that values considered equal may have their order changed when using [method sort]. [b]Note:[/b] Strings are sorted in alphabetical order (as opposed to natural order). This may lead to unexpected behavior when sorting an array of strings ending with a sequence of numbers. Consider the following example: [codeblock] var strings = ["string1", "string2", "string10", "string11"] @@ -357,7 +358,8 @@ Sorts the array using a custom method. The arguments are an object that holds the method and the name of such method. The custom method receives two arguments (a pair of elements from the array) and must return either [code]true[/code] or [code]false[/code]. For two elements [code]a[/code] and [code]b[/code], if the given method returns [code]true[/code], element [code]b[/code] will be after element [code]a[/code] in the array. - [b]Note:[/b] You cannot randomize the return value as the heapsort algorithm expects a deterministic result. Doing so will result in unexpected behavior. + [b]Note:[/b] The sorting algorithm used is not [url=https://en.wikipedia.org/wiki/Sorting_algorithm#Stability]stable[/url]. This means that values considered equal may have their order changed when using [method sort_custom]. + [b]Note:[/b] You cannot randomize the return value as the heapsort algorithm expects a deterministic result. Randomizing the return value will result in unexpected behavior. [codeblock] class MyCustomSorter: static func sort_ascending(a, b):