sort - sort variables

SYNOPSIS

<sort [globalFlags] $var [orderFlags] [$var2 ...]>

DESCRIPTION
The sort function takes one or more variable arguments to be sorted together. If only one variable is given, the return value is given in $ret. Otherwise (more than one variable), the variables are sorted in place, and are treated like the columns of a table to be sorted by rows. The first variable is the primary key to order by. Rows that compare the same for this variable are sorted by the next variable; if the second's values are identical then the third is compared, etc. If all variables' values compare equal for a given pair of rows, the original relative row order is preserved. In version 6 and later, string (but not NATURAL nor FILE) comparisons use the current apicp stringcomparemode setting (here).

Several order flags may appear after each variable, and apply only to the immediately preceding variable:

• DESC Sort this variable in descending order, instead of the default ascending order. Mutually exclusive with itself and ASC.

• ASC Sort this variable in ascending order, the default. Mutually exclusive with itself and DESC.

• ICASE Ignore case when sorting this variable, and sort it alphabetically if it's non-varchar. Thus Norway is equal to norway with this flag, and the integer value 123 is less than 45. The default for strings is to respect case; for NATURAL and FILE sort however, the default is to ignore case. ICASE is exclusive with itself, RCASE and NUM.

• RCASE Respect case when sorting this variable, and sort it alphabetically if it's non-varchar. The default for strings is to respect case; for NATURAL and FILE sort however, the default is to ignore case. RCASE is mutually exclusive with itself, ICASE and NUM. Added in version 8.01.1670609390 20221209.

• NUM Sort numerically: the variable's values are treated as numbers (floating point). This is useful for sorting a varchar variable whose values are numbers, which would otherwise be sorted alphabetically. NUM is mutually exclusive with itself, ICASE, RCASE, NATURAL, and FILE.

• NATURAL Sort "naturally", i.e. alphabetically with some modifications. Non-digit sequences in values are sorted lexically, but with all letters sorting before all non-letters, and tilde (˜) sorting first. Digit sequences are sorted numerically (e.g. so version numbers are compared as humans would). The character set is treated as ASCII (e.g. for categorization and case-folding). Case is ignored by default (but may be respected by adding the RCASE flag). Added in version 8.01.1670609390 20221209. NATURAL is mutually exclusive with itself, FILE, and NUM.

• FILE Sort "naturally" as with NATURAL, but treat values as filenames. Thus empty string, ., .., and hidden (leading .) files will sort first. Also, for natural-sort comparison, the last file extensions are ignored if the values up to that differ. Finally, if the natural-sort comparison is identical, the values are sorted lexically. As with NATURAL, values are treated as ASCII (e.g. for categorization and case-folding). Case is ignored by default (but may be respected by adding the RCASE flag). Added in version 8.01.1670609390 20221209. FILE is mutually exclusive with itself, NATURAL, and NUM.

In addition, there are several flags that may be given immediately before the first variable, as global flags:

• SHORTEST Sort the shortest variable's number of values. Ideally, all variables given to <sort> should have the same number of values, so that a "row" of values across the variables is never broken up. However, if one or more variables are shorter than others, this could cause a "gap" to appear in the shorter variables' arrays (e.g. if the last row became sorted first, there would be no last-row value for the short variables to replace the first).

  With the SHORTEST flag set, these gaps are avoided by only sorting the first N values, where N is the number of values of the shortest variable. Later values are unsorted. Prior to version 5.01.1189552000 20070911, this was the default. In later versions, LONGEST is the default.

• LONGEST Sort the longest variable's number of values. The problem of unequal length variables is handled by sorting all rows, and allowing gaps to appear in shorter variables as needed. These gaps - when they are "internal" or between pre-existing values - are populated with default/empty values. Thus, a short variable may end up with extra values after the <sort> (but not necessarily as many as the longest var). In version 5.01.1189552000 20070911 and later, LONGEST is the default.

If old-style SHORTEST behavior is needed as a default for some reason, it can be restored by editing texis.ini and setting [Texis] Default Vortex Sort Shortest to a non-zero value. Note that this setting is applied at compile-time only.

DIAGNOSTICS
sort returns the sorted list in $ret if one variable is given; otherwise it returns nothing and the variables are sorted in place.

EXAMPLE

<$colors =  red      orange   yellow   green    blue     violet>
<$num    = "FF0000" "FFA500" "FFFF00" "00FF00" "0000FF" "EE82EE">
<sort $num DESC $colors>
<LOOP $colors $num>
  $colors $num
</LOOP>

The output, sorted by descending order of color values (e.g. brightness):

yellow FFFF00
orange FFA500
red FF0000
violet EE82EE
green 00FF00
blue 0000FF

CAVEATS
The sort function was added Aug. 23 1996. The SHORTEST and LONGEST flags were added in version 5.01.1189552000 20070911.

All variables given to sort should have the same number of values. If not, some values may be unsorted, or some variables may have additional values inserted. See the SHORTEST/LONGEST flags.

In version 6 and later, string comparisons use the current apicp stringcomparemode setting (here).

This is one of the few functions in Vortex that modifies its arguments without the $&var reference syntax.

SEE ALSO
uniq