List.sort([attributeRef])

Operator Type:

Operator Scope of Action:

Operator Purpose:

Data Type Returned:

Operator First Added:

Operator in Current Baseline:

Operator Last Altered:

Operator Has Optional Arguments:

Function [other Function type actions]

Item [operators of similar scope]

Data manipulation [other Data manipulation operators]

List [about List data type]

v5.8.0

Baseline

As at baseline

[More on optional operator arguments]

Syntax note: Operators without any defined mandatory arguments may omit their empty closing parentheses

List.sort([attributeRef])

List.sort()

The basic form

$MyList = $MyList.sort();

This function re-sorts the referenced list's values in lexical, case-sensitive order. This means sorting all upper case letters before any lower case ones as in "Ant;Bee;Cow;ant;bee;cow". Users of non-accented languages (for the content of their notes) will likely find the case-insensitive List.isort() of more practical use.

A forced numerical sort (1,2,11 not 1,11,2) can be achieved by using List.nsort(). Or, if using $Name or $Path data, use the optional long from (below) and let the nominated attribute's data type set the form of sort, e.g. for date sorting, sort on a Date-type attribute.

The resulting sort order can be reversed overall by chaining the List.sort() and List.reverse() functions:

$MyList = $MyList.sort().reverse();

Sets can be sorted, on the fly, so a sorted output can be passed to a List. Passing the sorted output of a Set to another Set has an unknown outcome, in terms of stored sort order.

List sorting can be used to process group designators. For example:

$MyList=$Colors(children);

finds a list of the colours of each child of the current note, and:

$MyNumber=$Width(children).max;

will find the maximum width of the current container's children. When applied to the attribute $Text:

$Text=$Text(children);

the texts of each child are appended, separated by paragraph breaks.

List.sort(attributeRef)

Here the referenced List must be a list of note names or paths, i.e. a list of $Name data or $Path data (but not a mix of the two). If note names are not unique within the document, path values must be used to achieve correct sort. This is because the stipulated

The attributeRef argument is a $-prefixed attribute reference and indicates the attribute supplying the sorted value in each list item. As a result, this form of sort cannot be used with any other date type of list and cannot be applied to a literal list of values (as they have no attributes!), unlike the short un-argumented form above.

Thus, the sort order is based on the value of the stipulated attributeRef and that value is derived from the $Name or $Path of the list item being evaluated:

$MyList = collect(children, $Name).sort($StartDate);

$MyList = collect_if(find($Prototype=="pArticle"), $Year!="",$Path).sort($Year);

So, in the latter case, $MyList is a list of paths, but the paths are sorted in the order of each item's $Year value rather than the default $OutlineOrder of the source objects. Consider notes 'A', 'B', and 'C' in that existing on that $OutlineOrder. Without the sort, $MyList created above is the paths [/A;/B;/C]. If the notes' respective $Year values are "1965","2010","1980", then a $Year-based sort make the $MyList to be [/A;/C;/B] (i.e. by increasing year value).

In this argument-based usage, the sort ordering is based on the data type of attributeRef:

Number-type: and Interval-type: numerical sort
Date-type: sort on date (implied numerical)
All other types lexical

But if attributeRef is Number-type, List.nsort() could be used instead.

With .sort() lexical sorts are always case-insensitive.

Group designators are allowed in attribute references. For example:

$MyList=$Colors(children);

finds a list of the colours of each child of this note, and:

$MyNumber=$Width(children).max;

will find the maximum width of the container's children. When applied to the attribute $Text:

$Text=$Text(children);

the texts of each child are appended, separated by paragraph breaks.

Legacy: Use of sorting with Set-type data

This operator does not apply to Set-type lists because, as from v9.0.0, Sets now auto-sort A–Z and cannot be (reliably) user-sorted to a different order. However, is passing the result to a List-type or to some other process—i.e. passing the sorted result, not the source Set—then sorted content is possible.

See also—notes linking to here: