Sort

(Engine-Level Function)

Description: Allows the sorting of an array subsection according to the order of another array.
Returns: Nothing
Usage: Script Only.
Function Groups: Array
Related to: PlotXY | TextSearch | SortArray
Format: Sort(KeyArrayElem, SortArrayElem, N, Descending [, TypeText, CaseInsensitive, Locale, CmpFlags])
Parameters:  
KeyArrayElem
Required. An element of the array to be used as the reference for the sort. This array is copied into temporary memory space. The copy is then arranged in order along with the SortArray, but the original copy of the key array is left unchanged after the sort unless it is the same array as SortArray.
If the key array contains text strings, the TypeText parameter should be set to true (non-0) to enable alphabetical ordering, otherwise each element will be converted to a number before use as a sort key.
SortArrayElem

Required. Any array element giving the starting point in the array for the reordering. The subscript for the array may be any numeric expression. If processing a multidimensional array, the usual rules apply to decide which dimension should be used.
The new order for SortArray will be according to the order of the ordered copy of KeyArray. The values in this array may be of any type.
N

Required. Any numeric expression giving the number of array elements to use in the sort. If this number is greater than either of the two array sizes, the number of elements used in the sort will be the lesser of the two array sizes. The maximum value for N is the size of the array.

If the sum of N plus the starting element is greater than the size of the array, this computation will "wrap-around" and resume at element 0. For example if you sort 1,3,2 in ascending order starting at element 2 with an N equal to 3, the result would be 3,1,2.

Demo[0] = 1; Demo[1] = 3; Demo[2] = 2;
Sort(Demo[0], Demo[2], 3, 0);

This may be useful in rare circumstances.
Descending
Required. Any numeric expression that indicates the ordering sequence to use in the sort. If it is true (non-0), the sort will be in descending (decreasing) order. If it is false (0), the sort will be in ascending (increasing) order.
TypeText

Optional. A numeric expression that controls the type of sort according to the following table. Defaults to zero - numeric sorting.

TypeText Sort Performed
0 Numeric sort
1 Alphabetic sort
2 Tag hierarchy sort (Sorts tag names based on hierarchy rather than using a pure alphabetic sort.)
3 Lexicographical sort. If set, consider also setting a locale (7th parameter) or linguistic CmpFlag.
4 Tag hierarchical, lingual sort
CaseInsensitive
An optional parameter that accepts any logical expression. If CaseInsensitive resolves to true (1), the key array is treated as holding case-insensitive strings, thus allowing the caller to sort alphabetically instead of lexically. The default behavior is to sort case-sensitive (lexical sort). This parameter is ignored if TypeText is false (0).
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:

Sort allows the re-ordering of a group of related arrays according to the order of a key array. If KeyArray and SortArray are the same array, the array is arranged in order.


Be aware that sorting is a relatively time-consuming operation. It should not be active during time-critical control, etc.

Do not mix sorting modes. Some code may rely on sorting to be basic case-insensitive alphabetical (non-locale-aware) order, while other code may expect it to be locale-aware. Mixing these is likely to produce errors.
In particular, if you Sort an array and then use TextSearch on it, you must ensure that each uses the same sorting mode with the same locale.

 

This statement performs a "partition sort", using an element of the array as the dividing point, such that all other elements are divided into those greater than and less than the dividing element. Each partition is then recursively sorted. As of VTS version 7.5, the first and middle elements of the array are swapped, making the middle element the partitioning element. This has increased performance gains for arrays whose sizes reach 100,000 or more elements.


This statement is useful when used with PlotXY. For example, if there are two arrays, one having X-value and the other Y-values, of 100 data values that need to be viewed plotted against each other, the Sort statement could re-order the arrays so that the X values increased from left to right and the Y values stayed with their corresponding X values (see example).
The order of the statements is significant. If the sort of the X array were done first, the sort of the Y array would have no effect since the X array would already be in order. In general, the key array should be sorted last.


The statement uses a minimum of eight bytes of temporary memory for each numeric array element in the sort, or more if the element has been declared to be text. This means that at least 8 * N bytes of memory is required, which may be of concern if N is large and the amount of free memory is minimal.
Invalid array entries in the key array are grouped to the end of the array.

Example 1:

If MatchKeys(2, "sort");
[
  Sort(X[0], Y[0], 100, 0) { Sort the Y values first };
  Sort(X[0], X[0], 100, 0) { Sort the X values };
]

The two arrays mentioned in the previous section are sorted in preparation for plotting by the script, which is executed when the user types in "sort" from the keyboard.

Example 2:

Perhaps you have one array of tag names (N) and another array of matching tag descriptions (D). You want to sort both according to the descriptions. These arrays are shown in the following table in order to simplify the example:

N D
B 7
D 1
A 3

 

[
  Sort(D[0], N[0], 3, 0);   { sort entries in Names according to a sorted version of Descriptions }
  Sort(D[0], D[0], 3, 0);   { sort descriptions }
]

The result is:

N D
D 1
A 3
B 7