array_sort - MethodScript

== array_sort ==

Sorts an array in place, and also returns a reference to the array.

=== Vital Info === {| style="width: 40%;" cellspacing="1" cellpadding="1" border="1" class="wikitable" |- ! scope="col" width="20%" | ! scope="col" width="80%" | |- ! scope="row" | Name | array_sort |- ! scope="row" | Returns | array |- ! scope="row" | Usages | array, [sortType] |- ! scope="row" | Throws | [[../objects/ms.lang.CastException|ms.lang.CastException]]
[[../objects/ms.lang.FormatException|ms.lang.FormatException]] |- ! scope="row" | Since | 3.3.1 |- ! scope="row" | Restricted |

|- ! scope="row" | Optimizations | [[../../Optimizer#OPTIMIZE_DYNAMIC|OPTIMIZE_DYNAMIC]] |}

The complexity of this sort algorithm is guaranteed to be no worse than n log n, as it uses merge sort. The array is sorted in place, a new array is not explicitly created, so if you sort an array that is passed in as a variable, the contents of that variable will be sorted, even if you don't re-assign the returned array back to the variable. If you really need the old array, you should create a copy of the array first, like so: assign(@sorted, array_sort(@array[])). The sort type may be one of the following: REGULAR, NUMERIC, STRING or STRING_IC, or it may be a closure, if the sort should follow custom rules (explained below). A regular sort sorts the elements without changing types first. A numeric sort always converts numeric values to numbers first (so 001 becomes 1). A string sort compares values as strings, and a string_ic sort is the same as a string sort, but the comparison is case-insensitive. If the array contains array values, a CastException is thrown; inner arrays cannot be sorted against each other. If the array is associative, a warning will be raised if the General logging channel is set to verbose, because the array's keys will all be lost in the process. To avoid this warning, and to be more explicit, you can use array_normalize() to normalize the array first. Note that the reason this function is an in place sort instead of explicitly cloning the array is because in most cases, you may not need to actually clone the array, an expensive operation. Due to this, it has slightly different behavior than array_normalize, which could have also been implemented in place. If the sortType is a closure, it will perform a custom sort type, and the array may contain any values, including sub array values. The closure should accept two values, @left and @right, and should return true or a positive integer if the left value is larger than the right, and false or a negative integer if the left value is smaller than the right, and null or 0 if they are equal. The array will then be re-ordered using a merge sort, using your custom comparator to determine the sort order.

=== Usages ===

array_sort(array, [sortType])

=== Examples === ====Example 1==== Regular sort Given the following code:

@array = array('a', 2, 4, 'string');
array_sort(@array, 'REGULAR');
msg(@array);
 Copy Code
1   @array = {{function|array}}('a', 2, 4, 'string');
2   {{function|array_sort}}(@array, 'REGULAR');
3   {{function|msg}}(@array);

The output would be:

{2, 4, a, string}

====Example 2==== Numeric sort Given the following code:

@array = array('03', '02', '4', '1');
array_sort(@array, 'NUMERIC');
msg(@array);
 Copy Code
1   @array = {{function|array}}('03', '02', '4', '1');
2   {{function|array_sort}}(@array, 'NUMERIC');
3   {{function|msg}}(@array);

The output would be:

{1, 02, 03, 4}

====Example 3==== String sort Given the following code:

@array = array('03', '02', '4', '1');
array_sort(@array, 'STRING');
msg(@array);
 Copy Code
1   @array = {{function|array}}('03', '02', '4', '1');
2   {{function|array_sort}}(@array, 'STRING');
3   {{function|msg}}(@array);

The output would be:

{02, 03, 1, 4}

====Example 4==== String sort (with words) Given the following code:

@array = array('Zeta', 'zebra', 'Minecraft', 'mojang', 'Appliance', 'apple');
array_sort(@array, 'STRING');
msg(@array);
 Copy Code
1   @array = {{function|array}}('Zeta', 'zebra', 'Minecraft', 'mojang', 'Appliance', 'apple');
2   {{function|array_sort}}(@array, 'STRING');
3   {{function|msg}}(@array);

The output would be:

{Appliance, Minecraft, Zeta, apple, mojang, zebra}

====Example 5==== Ignore case sort Given the following code:

@array = array('Zeta', 'zebra', 'Minecraft', 'mojang', 'Appliance', 'apple');
array_sort(@array, 'STRING_IC');
msg(@array);
 Copy Code
1   @array = {{function|array}}('Zeta', 'zebra', 'Minecraft', 'mojang', 'Appliance', 'apple');
2   {{function|array_sort}}(@array, 'STRING_IC');
3   {{function|msg}}(@array);

The output would be:

{apple, Appliance, Minecraft, mojang, zebra, Zeta}

====Example 6==== Custom sort Given the following code:

@array = array(
	array(name: 'Jack', age: 20),
	array(name: 'Jill', age: 19)
);
msg("Before sort: @array");
array_sort(@array, closure(@left, @right){
	 return(@left['age'] > @right['age']);
});
msg("After sort: @array");
 Copy Code
1   @array = {{function|array}}(
2     {{function|array}}(name: 'Jack', age: 20),
3     {{function|array}}(name: 'Jill', age: 19)
4   );
5   {{function|msg}}("Before sort: @array");
6   {{function|array_sort}}(@array, {{keyword|closure}}(@left, @right){
7      {{function|return}}(@left['age'] > @right['age']);
8   });
9   {{function|msg}}("After sort: @array");

The output would be:

Before sort: {{age: 20, name: Jack}, {age: 19, name: Jill}}
After sort: {{age: 19, name: Jill}, {age: 20, name: Jack}}

Find a bug in this page? Edit this page yourself, then submit a pull request. (Note this page is automatically generated from the documentation in the source code.)