sort Statement

Sort an array by using an expression to compare array elements with each other.

Syntax	`sort anArray using <expression with element and nextElement>`
Semantics	`sort` allows you to sort an array by using an expression to compare array elements with each other. We do not guarantee what sort algorithm will actually be used. Be aware that sort algorithms are not linear (typically n log n to n² iterations for n elements). Therefore, you should keep the expression as compact as possible. The sort algorithm will call the expression each time two elements need to be compared. The expression must either return a boolean or an integer value. This means the following: Result of compare is boolean true → `element` precedes `nextElement` false → `element` succeeds `nextElement` Result of compare is integer < 0 → `element` precedes `nextElement` = 0 → `element` and `nextElement` are equal > 0 → `element` succeeds `nextElement` When using a boolean expression, make sure that equality always returns true (e.g. by using <= instead of <). Otherwise, the implemented sort algorithm may take longer than necessary or not terminate at all.
Substitutables	`anArray`	Can be any variable or object attribute having the type Array.
	`<expression with element and nextElement>`	This expression must use the currently evaluated array element and its next neighbor and indicates if the current order is OK or not.
	`element` and `nextElement` are keywords and allow you to use relative references (as opposed to normal, absolute indices) to single elements of an array (see Get Array Element Operator []).
Examples	Sort an array of strings in descending order The compare expression uses a boolean return value. Input: an array of names JSON `{"names": ["Irene", "Eliza", "Raymond", "Jane", "David"]}` CODE `set result = sort names using element >= nextElement;` Result: JSON `{"result":["Raymond", "Jane", "Irene", "Eliza", "David"]}`
Examples	Sort an array of integers in ascending order The compare expression uses an integer return value. Input: an array of integers JSON `{"numbers": [23, 12, 15, 5, 3, 10]}` CODE `set result = sort numbers using element - nextElement;` Result: JSON `{"result":[3, 5, 10, 12, 15, 23]}`

Sort an array with complex elements

Sort over two sort keys (string and integer)

The compare expression can be complex and implement a sort by e.g. two sort keys.

Input: an array of a complex article (sort by category and serviceInterval)

JSON

{ "articles": [
    {"name": "AF-1200", "category": "Adapter", "serviceInterval": 52},
    {"name": "CD-2024", "category": "Connector", "serviceInterval": 208},
    {"name": "RC-0002", "category": "Adapter", "serviceInterval": 104},
    {"name": "CD-2002", "category": "Connector", "serviceInterval": 26}
]}

CODE

set result = sort articles
                  using (element.category = nextElement.category 
                         and element.serviceInterval <= nextElement.serviceInterval) 
                  or element.category < nextElement.category;

Result:

JSON

{ "articles": [
    {"name": "AF-1200", "category": "Adapter", "serviceInterval": 52},
    {"name": "RC-0002", "category": "Adapter", "serviceInterval": 104},
    {"name": "CD-2002", "category": "Connector", "serviceInterval": 26},
    {"name": "CD-2024", "category": "Connector", "serviceInterval": 208}
]}

Sort using a complex compare expression

Sometimes compare expressions can be more complex and e.g. include conditions or calculations. You can implement this to the sort statement by providing a dedicated, own compare operation.

CODE

set result = sort articles using compareArticles(element, nextElement);

or

CODE

set result = sort articles using element.compareArticles(nextElement);

compareArticles, in this case, is a custom operation that needs to get two array elements as input, compares them, and returns the result of the comparison either as a boolean or an integer value (see Semantics above).