NAME
       lsort - Sort the elements of a list

SYNOPSIS
       lsort ?options? list


DESCRIPTION
       This  command  sorts the elements of list, returning a new
       list in sorted order.  The  implementation  of  the  lsort
       command  uses  the  merge-sort algorithm which is a stable
       sort that has O(n log n) performance characteristics.

       By default ASCII sorting is used with the result  returned
       in  increasing  order.   However,  any  of  the  following
       options may be specified before list to control the  sort-
       ing process (unique abbreviations are accepted):

       -ascii              Use  string  comparison  with  Unicode
                           code-point collation order  (the  name
                           is   for  backward-compatability  rea-
                           sons.)  This is the default.

       -dictionary         Use dictionary-style comparison.  This
                           is  the same as -ascii except (a) case
                           is ignored except as a tie-breaker and
                           (b)  if  two  strings contain embedded
                           numbers, the numbers compare as  inte-
                           gers, not characters.  For example, in
                           -dictionary mode, bigBoy sorts between
                           bigbang  and  bigboy,  and  x10y sorts
                           between x9y and x11y.

       -integer            Convert list elements to integers  and
                           use integer comparison.

       -real               Convert  list  elements  to  floating-
                           point values and use floating compari-
                           son.

       -command command    Use  command  as a comparison command.
                           To compare two  elements,  evaluate  a
                           Tcl  script consisting of command with
                           the two  elements  appended  as  addi-
                           tional  arguments.   The script should
                           return an integer less than, equal to,
                           or greater than zero if the first ele-
                           ment is to be  considered  less  than,
                           equal  to, or greater than the second,
                           respectively.

       -increasing         Sort  the  list  in  increasing  order
                           (``smallest''  items  first).  This is
                           the default.

       -decreasing         Sort  the  list  in  decreasing  order
                           (``largest'' items first).

       -index index        If  this  option is specified, each of
                           the elements of list must itself be  a
                           proper  Tcl sublist.  Instead of sort-
                           ing based  on  whole  sublists,  lsort
                           will extract the index'th element from
                           each sublist and  sort  based  on  the
                           given  element.   The  keyword  end is
                           allowed for the index to sort  on  the
                           last  sublist  element,  and end-index
                           sorts on a sublist element offset from
                           the end.  For example,
                                  lsort -integer -index 1 {{First 24} {Second 18} {Third 30}}
                           returns  {Second 18} {First 24} {Third
                           30}, and
                                  lsort -index end-1 {{a 1 e i} {b 2 3 f g} {c 4 5 6 d h}}
                           returns {c 4 5 6 d h} {a 1 e i} {b 2 3
                           f  g}.  This option is much more effi-
                           cient than using -command  to  achieve
                           the same effect.

       -unique             If this option is specified, then only
                           the last  set  of  duplicate  elements
                           found  in  the  list will be retained.
                           Note that  duplicates  are  determined
                           relative to the comparison used in the
                           sort.  Thus if -index 0 is used, {1 a}
                           and  {1  b} would be considered dupli-
                           cates and only the second element,  {1
                           b}, would be retained.


NOTES
       The  options to lsort only control what sort of comparison
       is used, and do not necessarily constrain what the  values
       themselves actually are.  This distinction is only notice-
       able when the list to be sorted has fewer  than  two  ele-
       ments.

       The  lsort command is reentrant, meaning it is safe to use
       as part of the implementation of a  command  used  in  the
       -command option.


EXAMPLES
       Sorting a list using ASCII sorting:
              % lsort {a10 B2 b1 a1 a2}
              B2 a1 a10 a2 b1


       Sorting a list using Dictionary sorting:
              % lsort -dictionary {a10 B2 b1 a1 a2}
              a1 a2 a10 b1 B2


       Sorting lists of integers:
              % lsort -integer {5 3 1 2 11 4}
              1 2 3 4 5 11
              % lsort -integer {1 2 0x5 7 0 4 -1}
              -1 0 1 2 4 0x5 7


       Sorting lists of floating-point numbers:
              % lsort -real {5 3 1 2 11 4}
              1 2 3 4 5 11
              % lsort -real {.5 0.07e1 0.4 6e-1}
              0.4 .5 6e-1 0.07e1


       Sorting using indices:
              % # Note the space character before the c
              % lsort {{a 5} { c 3} {b 4} {e 1} {d 2}}
              { c 3} {a 5} {b 4} {d 2} {e 1}
              % lsort -index 0 {{a 5} { c 3} {b 4} {e 1} {d 2}}
              {a 5} {b 4} { c 3} {d 2} {e 1}
              % lsort -index 1 {{a 5} { c 3} {b 4} {e 1} {d 2}}
              {e 1} {d 2} { c 3} {b 4} {a 5}


       Stripping duplicate values using sorting:
              % lsort -unique {a b c a b c a b c}
              a b c


       More complex sorting using a comparison function:
              % proc compare {a b} {
                  set a0 [lindex $a 0]
                  set b0 [lindex $b 0]
                  if {$a0 < $b0} {
                      return -1
                  } elseif {$a0 > $b0} {
                      return 1
                  }
                  return [string compare [lindex $a 1] [lindex $b 1]]
              }
              % lsort -command compare \
                      {{3 apple} {0x2 carrot} {1 dingo} {2 banana}}
              {1 dingo} {2 banana} {0x2 carrot} {3 apple}


SEE ALSO
       list(n),  lappend(n),  lindex(n),  linsert(n), llength(n),
       lsearch(n), lset(n), lrange(n), lreplace(n)


KEYWORDS
