This version is out of date, covering development from v8.0.0 to v8.x.x. It is maintained here only for inbound reference links from elsewhere. It is no longer actively updated.

Jump to the current version of aTbRef

Tinderbox v8 Icon

List.sort([$Attribute])


Operator Type: 

Operator Scope of Action: 

Operator Purpose: 

Operator First Added: 

Operator Altered: 

 Function   [other Function type actions]

 Item   [operators of similar scope]

 Data manipulation   [other Data manipulation operators]

 Baseline

 


List.sort()

The basic form

$MyList = $MyList.sort(); 

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

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.

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($Attribute)

Here the referenced list must be a list of note names or paths, i.e. a list $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 form of sort cannot be used with any other sort of value list. This operator cannot be applied to any list of values, unlike the short form above.

In this form, the sort order can be based on the value of the stipulated $Attribute, being derived from the item identified by the $Name or $Path that is the list item being evaluated:

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

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

In this long form usage, the sort ordering is based on the data type of $Attribute:

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.