1lsort(n)                     Tcl Built-In Commands                    lsort(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       lsort - Sort the elements of a list
9

SYNOPSIS

11       lsort ?options? list
12______________________________________________________________________________
13

DESCRIPTION

15       This command sorts the elements of list, returning a new list in sorted
16       order.  The implementation of the lsort  command  uses  the  merge-sort
17       algorithm  which is a stable sort that has O(n log n) performance char‐
18       acteristics.
19
20       By default ASCII sorting is used with the result returned in increasing
21       order.   However,  any of the following options may be specified before
22       list  to  control  the  sorting  process  (unique   abbreviations   are
23       accepted):
24
25       -ascii Use  string  comparison  with Unicode code-point collation order
26              (the name is for backward-compatibility reasons.)  This  is  the
27              default.
28
29       -dictionary
30              Use  dictionary-style  comparison.   This  is the same as -ascii
31              except (a) case is ignored except as a tie-breaker  and  (b)  if
32              two  strings  contain  embedded  numbers, the numbers compare as
33              integers, not characters.  For  example,  in  -dictionary  mode,
34              bigBoy  sorts between bigbang and bigboy, and x10y sorts between
35              x9y and x11y. Overrides the -nocase option.
36
37       -integer
38              Convert list elements to integers and use integer comparison.
39
40       -real  Convert list elements to floating-point values and use  floating
41              comparison.
42
43       -command command
44              Use  command  as a comparison command.  To compare two elements,
45              evaluate a Tcl script consisting of command with  the  two  ele‐
46              ments  appended  as  additional  arguments.   The  script should
47              return an integer less than, equal to, or greater than  zero  if
48              the  first  element  is to be considered less than, equal to, or
49              greater than the second, respectively.
50
51       -increasing
52              Sort the list in increasing order (“smallest”items first).  This
53              is the default.
54
55       -decreasing
56              Sort the list in decreasing order (“largest”items first).
57
58       -indices
59              Return  a  list  of indices into list in sorted order instead of
60              the values themselves.
61
62       -index indexList
63              If this option is specified, each of the elements of  list  must
64              itself  be  a  proper  Tcl  sublist  (unless  -stride  is used).
65              Instead of sorting based on whole sublists, lsort  will  extract
66              the  indexList'th  element  from each sublist (as if the overall
67              element and the indexList were passed to lindex) and sort  based
68              on the given element.  For example,
69
70                     lsort -integer -index 1 \
71                           {{First 24} {Second 18} {Third 30}}
72
73              returns {Second 18} {First 24} {Third 30},
74
75                     lsort -index end-1 \
76                             {{a 1 e i} {b 2 3 f g} {c 4 5 6 d h}}
77
78              returns {c 4 5 6 d h} {a 1 e i} {b 2 3 f g}, and
79
80                     lsort -index {0 1} {
81                         {{b i g} 12345}
82                         {{d e m o} 34512}
83                         {{c o d e} 54321}
84                     }
85
86              returns  {{d  e  m  o}  34512} {{b i g} 12345} {{c o d e} 54321}
87              (because e sorts before i which sorts before o.)  This option is
88              much  more  efficient  than  using  -command to achieve the same
89              effect.
90
91       -stride strideLength
92              If this option is specified, the list is treated  as  consisting
93              of  groups of strideLength elements and the groups are sorted by
94              either their first element or, if the -index option is used,  by
95              the element within each group given by the first index passed to
96              -index (which is then ignored by -index). Elements always remain
97              in the same position within their group.
98
99              The  list  length  must  be an integer multiple of strideLength,
100              which in turn must be at least 2.
101
102              For example,
103
104                     lsort -stride 2 {carrot 10 apple 50 banana 25}
105
106              returns “apple 50 banana 25 carrot 10”, and
107
108                     lsort -stride 2 -index 1 -integer {carrot 10 apple 50 banana 25}
109
110              returns “carrot 10 banana 25 apple 50”.
111
112       -nocase
113              Causes comparisons to be handled in a  case-insensitive  manner.
114              Has  no  effect  if  combined with the -dictionary, -integer, or
115              -real options.
116
117       -unique
118              If this option is specified, then only the last set of duplicate
119              elements  found  in the list will be retained.  Note that dupli‐
120              cates are determined relative to  the  comparison  used  in  the
121              sort.   Thus  if -index 0 is used, {1 a} and {1 b} would be con‐
122              sidered duplicates and only the second element, {1 b}, would  be
123              retained.
124

NOTES

126       The  options to lsort only control what sort of comparison is used, and
127       do not necessarily constrain what the values themselves  actually  are.
128       This  distinction  is  only  noticeable  when the list to be sorted has
129       fewer than two elements.
130
131       The lsort command is reentrant, meaning it is safe to use  as  part  of
132       the implementation of a command used in the -command option.
133

EXAMPLES

135       Sorting a list using ASCII sorting:
136
137              % lsort {a10 B2 b1 a1 a2}
138              B2 a1 a10 a2 b1
139
140       Sorting a list using Dictionary sorting:
141
142              % lsort -dictionary {a10 B2 b1 a1 a2}
143              a1 a2 a10 b1 B2
144
145       Sorting lists of integers:
146
147              % lsort -integer {5 3 1 2 11 4}
148              1 2 3 4 5 11
149              % lsort -integer {1 2 0x5 7 0 4 -1}
150              -1 0 1 2 4 0x5 7
151
152       Sorting lists of floating-point numbers:
153
154              % lsort -real {5 3 1 2 11 4}
155              1 2 3 4 5 11
156              % lsort -real {.5 0.07e1 0.4 6e-1}
157              0.4 .5 6e-1 0.07e1
158
159       Sorting using indices:
160
161              % # Note the space character before the c
162              % lsort {{a 5} { c 3} {b 4} {e 1} {d 2}}
163              { c 3} {a 5} {b 4} {d 2} {e 1}
164              % lsort -index 0 {{a 5} { c 3} {b 4} {e 1} {d 2}}
165              {a 5} {b 4} { c 3} {d 2} {e 1}
166              % lsort -index 1 {{a 5} { c 3} {b 4} {e 1} {d 2}}
167              {e 1} {d 2} { c 3} {b 4} {a 5}
168
169       Sorting a dictionary:                                                   │
170
171              % set d [dict create c d a b h i f g c e]                        │
172              c e a b h i f g                                                  │
173              % lsort -stride 2 $d                                             │
174              a b c e f g h i                                                  │
175
176       Sorting using striding and multiple indices:                            │
177
178              % # Note the first index value is relative to the group          │
179              % lsort -stride 3 -index {0 1} \                                 │
180                   {{Bob Smith} 25 Audi {Jane Doe} 40 Ford}                    │
181              {{Jane Doe} 40 Ford {Bob Smith} 25 Audi}                         │
182
183       Stripping duplicate values using sorting:
184
185              % lsort -unique {a b c a b c a b c}
186              a b c
187
188       More complex sorting using a comparison function:
189
190              % proc compare {a b} {
191                  set a0 [lindex $a 0]
192                  set b0 [lindex $b 0]
193                  if {$a0 < $b0} {
194                      return -1
195                  } elseif {$a0 > $b0} {
196                      return 1
197                  }
198                  return [string compare [lindex $a 1] [lindex $b 1]]
199              }
200              % lsort -command compare \
201                      {{3 apple} {0x2 carrot} {1 dingo} {2 banana}}
202              {1 dingo} {2 banana} {0x2 carrot} {3 apple}
203

SEE ALSO

205       list(n),  lappend(n),  lindex(n),  linsert(n),  llength(n), lsearch(n),
206       lset(n), lrange(n), lreplace(n)
207

KEYWORDS

209       element, list, order, sort
210
211
212
213Tcl                                   8.5                             lsort(n)
Impressum