SortArray

(Engine-Level Function)

Description:	Sorts an array of arrays based upon the key information provided by the second parameter. The array is sorted in-place.
Returns:	Nothing
Usage:	Script Only.
Function Groups:	Array
Related to:	Sort
Format:	SortArray(array, [control, start, end]);
Parameters:

Array

Required. The array to be sorted.

The array must contain values, each of which must be either an array of simple values (numbers or text), or a record in the form of an array itself.

Control

Optional. Sets the column to be sorted and the type of sort to be performed. See the Examples section of this topic.

System.SortKeys Struct [
 Column;
 Type;
 Descending;
];

Defaults to, Column: 0, Type: Numeric, Descending: FALSE

This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section.

If your application predates version 11.2, use the backslash notation rather than dot: \System\

Start

Optional. The array index where sorting is to begin. If not specified, array is sorted from the first element.

End

Optional. The last array element to sort. If not specified, array is sorted to the last element. No sorting will be done if End comes before Start.

Locale

Optional. A valid locale name (en-US or fr-FR). Additional modifiers are also allowed such as zh-CN_stroke (Chinese sorting using stroke order)

The case insensitive flag ignored if doing a locale sort. As an alternative, set one of the following in the ComparisonFlags parameter: #LINGUISTIC_IGNORECASE or #NORM_IGNORECASE.

CmpFlags

A set of flags directing how the comparison should be done, as described in https://docs.microsoft.com/en-us/windows/desktop/api/stringapiset/nf-stringapiset-comparestringex

Supported flags include:

#NORM_IGNORECASE

#NORM_IGNORENONSPACE

#NORM_IGNORESYMBOLS

#LINGUISTIC_IGNORECASE

#LINGUISTIC_IGNOREDIACRITIC

#NORM_IGNOREKANATYPE

#NORM_IGNOREWIDTH

#NORM_LINGUISTIC_CASING

#SORT_DIGITSASNUMBERS

#SORT_STRINGSORT

Comments:

This function rapidly sorts vectors of records based upon one or more keys that can be distributed across the records.

The Array parameter cannot be a multi-dimensional array. No sort will happen if you attempt to process a multi-dimensional array.

The elements of SortKeys are as follows:

{0} Column. The field index where the key is located within each record.

{1} Type:

0 => Numeric,
1 => Case insensitive text
2 => Case sensitive text or raw binary.

3 => Locale sort

{2} Descending: TRUE to sort from greatest to least. FALSE to sort from least to greatest.

The value in a field is cast to the selected Type for the purposes of the sort, but is unchanged in the resulting array.

The SortKeys parameter may be an array of SortKey structures. In this case, the array is sorted by multiple keys simultaneously, with the first SortKeys element representing the highest-priority key and so on. This is shown in the third example.

Invalid Data[i][Column] values would be sorted to the end (i.e. higher index values) regardless of the value of Descending.

Examples:

Sort on column 0 of each element of the Data array in numeric ascending order.

SortArray(Data);

Sort on column 0 case-insensitive, binary comparison, in ascending order:

SortArray(Data, System.SortKeys(0, 2, FALSE));

Sort on column 0 numerically in descending order as primary key and secondarily sort numerically on column 1 in ascending order

SortInfo = New(2);
SortInfo[0] = System.SortKeys(0, 0, TRUE);
SortInfo[1] = 1;
SortArray(Data, SortInfo);