ABCDEFGHIJKLMNOPQRSTUVWXYZ

lsort

lsort(n)                     Tcl Built-In Commands                    lsort(n)



______________________________________________________________________________

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 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
       list  to  control  the  sorting  process  (unique   abbreviations   are
       accepted):

       -ascii              Use  string  comparison with ASCII collation 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 integers, not char-
                           acters.  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 comparison.

       -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 element 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  sorting 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 efficient 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 rel-
                           ative  to the comparison used in the sort.  Thus if
                           -index 0 is used, {1 a} and {1 b} would be  consid-
                           ered duplicates 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 noticeable when the  list  to  be  sorted  has
       fewer than two elements.

       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
       lappend(n), lindex(n), linsert(n), list(n), llength(n), lrange(n), lre-
       place(n), lsearch(n)


KEYWORDS
       element, list, order, sort



Tcl                                   8.3                             lsort(n)