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.
DIAGNOSTICSsort
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 ALSOuniq