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 ASCII col­
                           lation order.  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


       -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. For example,
                                  lsort -integer -index 1 {{First 24} {Second 18} {Third 30}}
                           returns  {Second 18} {First 24} {Third
                           30}.  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

              % 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

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


KEYWORDS

       element, list, order, sort


Man(1) output converted with man2html