SORT Function

Sorts the contents of a dynamic array.

Syntax

SORT(array{, attr#{, value# {, sortOrder}}})

SORT(array{, attr#{, value#}}; sortOrder)

Syntax Elements

array Any DataBasic expression that evaluates to a dynamic array.

attr# Optional. The number of the attribute to sort.

If 0 (default), the complete array is sorted. value# is ignored.
If less than 0, the attribute number is counted from the end of the array; -1 is the last attribute, -2 the second last, etc.

value# Optional. The number of the value to sort within the specified attribute.

If 0 (default), the complete attribute is sorted.
If less than 0, the value number is counted from the end of the attribute.

sortOrder Optional. Any DataBasic expression that evaluates to a string containing a combination of the following letters:

[A || D][L || R]{N}{[S || I]}

where the letters have the following meanings:

[A || D] Sort into ascending/descending order respectively.

[L || R] Sort into ASCII/numeric order respectively.

N Preserve null fields.

[S || I] Case sensitive/insensitive respectively. If omitted, the current case sensitivity setting (set with the CASING statement or at TCL with the CASE command) is used.

Note that you do not need to enable data case-insensitivity to use these options.

The default sort order is "AL".

Note: This parameter can be in any combination of upper and lower case.

Return Value

The return value is a dynamic array containing the selected elements, sorted as specified and separated by attribute marks.

Note: Before sorting, all values and sub-values in the selected elements are promoted to attributes.

If no array or value numbers are specified, or both these parameters are 0, the complete array is returned, with the attributes, values and subvalues sorted into the specified order.
If an attribute number is specified, just that attribute is returned, with the values and subvalues sorted into the specified order.
If both an attribute and a value are specified, just that value from that attribute is returned, with the subvalues sorted into the specified order.

Unless the N sort order option is specified, all null elements are removed.

Comments

If attr# and/or value# are omitted, but sortOrder is included, array must be separated from sortOrder with a semicolon. If a comma is used, an error will be generated at runtime.

Examples

SORTED = SORT(UNSORTED)

Sorts the array UNSORTED into ascending ASCII order and assigns the result to the variable SORTED.

DR = SORT(X; "DR")

Sorts the array X into descending numeric order and assigns the result to the variable DR. Note the semicolon separating the two parameters; this is necessary because no attribute and value are specified.

AL3 = SORT(ARY, 3)

Sorts the third attribute of array ARY into ascending ASCII order and assigns the sorted elements to the variable AL3.

AL23 = SORT(ARY, 3, 2, "DLI")

Sorts the second value of the third attribute of array ARY into descending ASCII order, ignoring case and assigns the sorted elements to the variable AL23.