distrib/share/tcl/help/tcl/lists/lsort

   1 NAME
   2        lsort - Sort the elements of a list
   3
   4 SYNOPSIS
   5        lsort ?options? list
   6
   7
   8 DESCRIPTION
   9        This command sorts the elements of list, returning a new list in sorted
  10        order.  The implementation of the lsort  command  uses  the  merge-sort
  11        algorithm  which is a stable sort that has O(n log n) performance char-
  12        acteristics.
  13
  14        By default ASCII sorting is used with the result returned in increasing
  15        order.   However,  any of the following options may be specified before
  16        list  to  control  the  sorting  process  (unique   abbreviations   are
  17        accepted):
  18
  19        -ascii              Use  string comparison with Unicode code-point col-
  20                            lation order (the name is for  backward-compatibil-
  21                            ity reasons.)  This is the default.
  22
  23        -dictionary         Use  dictionary-style comparison.  This is the same
  24                            as -ascii except (a) case is ignored  except  as  a
  25                            tie-breaker and (b) if two strings contain embedded
  26                            numbers, the numbers compare as integers, not char-
  27                            acters.   For  example, in -dictionary mode, bigBoy
  28                            sorts between bigbang and bigboy,  and  x10y  sorts
  29                            between x9y and x11y.
  30
  31        -integer            Convert  list  elements to integers and use integer
  32                            comparison.
  33
  34        -real               Convert list elements to floating-point values  and
  35                            use floating comparison.
  36
  37        -command command    Use  command  as  a comparison command.  To compare
  38                            two elements, evaluate a Tcl script  consisting  of
  39                            command  with  the  two  elements appended as addi-
  40                            tional arguments.   The  script  should  return  an
  41                            integer  less  than, equal to, or greater than zero
  42                            if the first element is to be considered less than,
  43                            equal to, or greater than the second, respectively.
  44
  45        -increasing         Sort the list  in  increasing  order  (``smallest''
  46                            items first).  This is the default.
  47
  48        -decreasing         Sort  the  list  in  decreasing  order (``largest''
  49                            items first).
  50
  51        -index index        If this option is specified, each of  the  elements
  52                            of  list  must  itself  be  a  proper  Tcl sublist.
  53                            Instead of sorting based on whole  sublists,  lsort
  54                            will extract the index'th element from each sublist
  55                            and sort based on the given element.   The  keyword
  56                            end  is  allowed  for the index to sort on the last
  57                            sublist element, and end-index sorts on  a  sublist
  58                            element offset from the end.  For example,
  59                                   lsort -integer -index 1 {{First 24} {Second 18} {Third 30}}
  60                            returns {Second 18} {First 24} {Third 30}, and
  61                                   lsort -index end-1 {{a 1 e i} {b 2 3 f g} {c 4 5 6 d h}}
  62                            returns  {c 4 5 6 d h} {a 1 e i} {b 2 3 f g}.  This
  63                            option is much more efficient than  using  -command
  64                            to achieve the same effect.
  65
  66        -unique             If this option is specified, then only the last set
  67                            of duplicate elements found in  the  list  will  be
  68                            retained.  Note that duplicates are determined rel-
  69                            ative to the comparison used in the sort.  Thus  if
  70                            -index  0 is used, {1 a} and {1 b} would be consid-
  71                            ered duplicates and only the second element, {1 b},
  72                            would be retained.
  73
  74 NOTES
  75        The  options to lsort only control what sort of comparison is used, and
  76        do not necessarily constrain what the values themselves  actually  are.
  77        This  distinction  is  only  noticeable  when the list to be sorted has
  78        fewer than two elements.
  79
  80        The lsort command is reentrant, meaning it is safe to use  as  part  of
  81        the implementation of a command used in the -command option.
  82
  83 EXAMPLES
  84        Sorting a list using ASCII sorting:
  85               % lsort {a10 B2 b1 a1 a2}
  86               B2 a1 a10 a2 b1
  87
  88        Sorting a list using Dictionary sorting:
  89               % lsort -dictionary {a10 B2 b1 a1 a2}
  90               a1 a2 a10 b1 B2
  91
  92        Sorting lists of integers:
  93               % lsort -integer {5 3 1 2 11 4}
  94               1 2 3 4 5 11
  95               % lsort -integer {1 2 0x5 7 0 4 -1}
  96               -1 0 1 2 4 0x5 7
  97
  98        Sorting lists of floating-point numbers:
  99               % lsort -real {5 3 1 2 11 4}
 100               1 2 3 4 5 11
 101               % lsort -real {.5 0.07e1 0.4 6e-1}
 102               0.4 .5 6e-1 0.07e1
 103
 104        Sorting using indices:
 105               % # Note the space character before the c
 106               % lsort {{a 5} { c 3} {b 4} {e 1} {d 2}}
 107               { c 3} {a 5} {b 4} {d 2} {e 1}
 108               % lsort -index 0 {{a 5} { c 3} {b 4} {e 1} {d 2}}
 109               {a 5} {b 4} { c 3} {d 2} {e 1}
 110               % lsort -index 1 {{a 5} { c 3} {b 4} {e 1} {d 2}}
 111               {e 1} {d 2} { c 3} {b 4} {a 5}
 112
 113        Stripping duplicate values using sorting:
 114               % lsort -unique {a b c a b c a b c}
 115               a b c
 116
 117        More complex sorting using a comparison function:
 118               % proc compare {a b} {
 119                   set a0 [lindex $a 0]
 120                   set b0 [lindex $b 0]
 121                   if {$a0 < $b0} {
 122                       return -1
 123                   } elseif {$a0 > $b0} {
 124                       return 1
 125                   }
 126                   return [string compare [lindex $a 1] [lindex $b 1]]
 127               }
 128               % lsort -command compare \
 129                       {{3 apple} {0x2 carrot} {1 dingo} {2 banana}}
 130               {1 dingo} {2 banana} {0x2 carrot} {3 apple}
 131
 132
 133 SEE ALSO
 134        list(n),  lappend(n),  lindex(n),  linsert(n),  llength(n), lsearch(n),
 135        lset(n), lrange(n), lreplace(n)
 136
 137
 138 KEYWORDS