Sort

Description: This statement allows the sorting of an array subsection according to the order of another array.

Returns: Nothing

Usage: Script

Format: Sort(KeyArrayElem, SortArrayElem, N, Descending [, TypeText, CaseInsensitive])

Parameters: KeyArrayElem { Array element } { required } { no default: }

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 facilitate alphabetical ordering, otherwise each element will be converted to a number before use as a sort key.

SortArrayElem { Array element } { required } { no default: }

Any array element giving the starting point in the array for the reordering. The subscript for the array may be any numeric expression. Unless specified, the lowest dimension of a multidimensional array is 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 { numeric } { required } { no default: }

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 arrays.

Descending { numeric } { required } { no default: }

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 { Boolean } { optional } { default: 0 }

An optional parameter that is any logical expression that indicates whether or not the key array contains text strings (i.e. an alphabetical sort is to be done). If true (non-0) the data is text; the default is false (0).

CaseInsensitive { Boolean } { optional } { default: 0 }

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).

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.

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 the example below).

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.

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

Example:

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.