1mNAME0m
       lsort - Sort the elements of a list

1mSYNOPSIS0m
       1mlsort 22m?4moptions24m? 4mlist0m


1mDESCRIPTION0m
       This command sorts the elements of 4mlist24m, returning a new list in sorted
       order.  The implementation of the 1mlsort  22mcommand  uses  the  merge-sort
       algorithm  which is a stable sort that has O(n log n) performance char-
       acteristics.

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

       1m-ascii              22mUse  string  comparison with ASCII collation order.
                           This is the default.

       1m-dictionary         22mUse dictionary-style comparison.  This is the  same
                           as  1m-ascii  22mexcept  (a) case is ignored except as a
                           tie-breaker and (b) if two strings contain embedded
                           numbers, the numbers compare as integers, not char-
                           acters.  For example, in 1m-dictionary  22mmode,  1mbigBoy0m
                           sorts  between  1mbigbang  22mand 1mbigboy22m, and 1mx10y 22msorts
                           between 1mx9y 22mand 1mx11y22m.

       1m-integer            22mConvert list elements to integers and  use  integer
                           comparison.

       1m-real               22mConvert  list elements to floating-point values and
                           use floating comparison.

       1m-command 4m22mcommand24m    Use 4mcommand24m as a comparison  command.   To  compare
                           two  elements,  evaluate a Tcl script consisting of
                           4mcommand24m 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 element is to be considered less than,
                           equal to, or greater than the second, respectively.

       1m-increasing         22mSort  the  list  in  increasing order (``smallest''
                           items first).  This is the default.

       1m-decreasing         22mSort the  list  in  decreasing  order  (``largest''
                           items first).

       1m-index 4m22mindex24m        If  this  option is specified, each of the elements
                           of 4mlist24m  must  itself  be  a  proper  Tcl  sublist.
                           Instead  of  sorting based on whole sublists, 1mlsort0m
                           will extract the 4mindex24m'th element from each sublist
                           and  sort  based on the given element.  The keyword
                           1mend 22mis allowed for the 4mindex24m to sort  on  the  last
                           sublist element. For example,
                                  lsort -integer -index 1 {{First 24} {Second 18} {Third 30}}
                           returns  1m{Second  18}  {First 24} {Third 30}22m.  This
                           option is much more efficient than  using  1m-command0m
                           to achieve the same effect.

       1m-unique             22mIf this option is specified, then only the last set
                           of duplicate elements found in  the  list  will  be
                           retained.  Note that duplicates are determined rel-
                           ative to the comparison used in the sort.  Thus  if
                           4m-index24m  4m024m is used, 1m{1 a} 22mand 1m{1 b} 22mwould be consid-
                           ered duplicates and only the second element, 1m{1 b}22m,
                           would be retained.


1mNOTES0m
       The  options to 1mlsort 22monly control what sort of comparison is used, and
       do not necessarily constrain what the values themselves  actually  are.
       This  distinction  is  only  noticeable  when the list to be sorted has
       fewer than two elements.

       The 1mlsort 22mcommand is reentrant, meaning it is safe to use  as  part  of
       the implementation of a command used in the 1m-command 22moption.


1mEXAMPLES0m
       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}


1mSEE ALSO0m
       lappend(n), lindex(n), linsert(n), list(n), llength(n), lrange(n), lre-
       place(n), lsearch(n)


1mKEYWORDS0m
