1 | '\" |
---|
2 | '\" Copyright (c) 1993 The Regents of the University of California. |
---|
3 | '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. |
---|
4 | '\" Copyright (c) 1999 Scriptics Corporation |
---|
5 | '\" Copyright (c) 2001 Kevin B. Kenny <kennykb@acm.org>. All rights reserved. |
---|
6 | '\" |
---|
7 | '\" See the file "license.terms" for information on usage and redistribution |
---|
8 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
9 | '\" |
---|
10 | '\" RCS: @(#) $Id: lsort.n,v 1.29 2008/03/26 09:59:22 dkf Exp $ |
---|
11 | '\" |
---|
12 | .so man.macros |
---|
13 | .TH lsort n 8.5 Tcl "Tcl Built-In Commands" |
---|
14 | .BS |
---|
15 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
16 | .SH NAME |
---|
17 | lsort \- Sort the elements of a list |
---|
18 | .SH SYNOPSIS |
---|
19 | \fBlsort \fR?\fIoptions\fR? \fIlist\fR |
---|
20 | .BE |
---|
21 | |
---|
22 | .SH DESCRIPTION |
---|
23 | .PP |
---|
24 | This command sorts the elements of \fIlist\fR, returning a new |
---|
25 | list in sorted order. The implementation of the \fBlsort\fR command |
---|
26 | uses the merge\-sort algorithm which is a stable sort that has O(n log |
---|
27 | n) performance characteristics. |
---|
28 | .PP |
---|
29 | By default ASCII sorting is used with the result returned in |
---|
30 | increasing order. However, any of the following options may be |
---|
31 | specified before \fIlist\fR to control the sorting process (unique |
---|
32 | abbreviations are accepted): |
---|
33 | .TP 20 |
---|
34 | \fB\-ascii\fR |
---|
35 | Use string comparison with Unicode code-point collation order (the |
---|
36 | name is for backward-compatibility reasons.) This is the default. |
---|
37 | .TP 20 |
---|
38 | \fB\-dictionary\fR |
---|
39 | Use dictionary-style comparison. This is the same as \fB\-ascii\fR |
---|
40 | except (a) case is ignored except as a tie-breaker and (b) if two |
---|
41 | strings contain embedded numbers, the numbers compare as integers, |
---|
42 | not characters. For example, in \fB\-dictionary\fR mode, \fBbigBoy\fR |
---|
43 | sorts between \fBbigbang\fR and \fBbigboy\fR, and \fBx10y\fR |
---|
44 | sorts between \fBx9y\fR and \fBx11y\fR. |
---|
45 | .TP 20 |
---|
46 | \fB\-integer\fR |
---|
47 | Convert list elements to integers and use integer comparison. |
---|
48 | .TP 20 |
---|
49 | \fB\-real\fR |
---|
50 | Convert list elements to floating-point values and use floating comparison. |
---|
51 | .TP 20 |
---|
52 | \fB\-command\0\fIcommand\fR |
---|
53 | Use \fIcommand\fR as a comparison command. |
---|
54 | To compare two elements, evaluate a Tcl script consisting of |
---|
55 | \fIcommand\fR with the two elements appended as additional |
---|
56 | arguments. The script should return an integer less than, |
---|
57 | equal to, or greater than zero if the first element is to |
---|
58 | be considered less than, equal to, or greater than the second, |
---|
59 | respectively. |
---|
60 | .TP 20 |
---|
61 | \fB\-increasing\fR |
---|
62 | Sort the list in increasing order |
---|
63 | .PQ smallest "items first" . |
---|
64 | This is the default. |
---|
65 | .TP 20 |
---|
66 | \fB\-decreasing\fR |
---|
67 | Sort the list in decreasing order |
---|
68 | .PQ largest "items first" . |
---|
69 | .TP 20 |
---|
70 | \fB\-indices\fR |
---|
71 | .VS "8.5 (TIP#217)" |
---|
72 | Return a list of indices into \fIlist\fR in sorted order instead of |
---|
73 | the values themselves. |
---|
74 | .VE "8.5 (TIP#217)" |
---|
75 | .TP 20 |
---|
76 | \fB\-index\0\fIindexList\fR |
---|
77 | If this option is specified, each of the elements of \fIlist\fR must |
---|
78 | itself be a proper Tcl sublist. Instead of sorting based on whole |
---|
79 | sublists, \fBlsort\fR will extract the \fIindexList\fR'th element from |
---|
80 | each sublist |
---|
81 | .VS 8.5 |
---|
82 | (as if the overall element and the \fIindexList\fR were passed to |
---|
83 | \fBlindex\fR) and sort based on the given element. |
---|
84 | .VE 8.5 |
---|
85 | For example, |
---|
86 | .RS |
---|
87 | .CS |
---|
88 | lsort -integer -index 1 \e |
---|
89 | {{First 24} {Second 18} {Third 30}} |
---|
90 | .CE |
---|
91 | returns \fB{Second 18} {First 24} {Third 30}\fR, and |
---|
92 | '\" |
---|
93 | '\" This example is from the test suite! |
---|
94 | '\" |
---|
95 | .CS |
---|
96 | lsort -index end-1 \e |
---|
97 | {{a 1 e i} {b 2 3 f g} {c 4 5 6 d h}} |
---|
98 | .CE |
---|
99 | returns \fB{c 4 5 6 d h} {a 1 e i} {b 2 3 f g}\fR, |
---|
100 | .VS 8.5 |
---|
101 | and |
---|
102 | .CS |
---|
103 | lsort -index {0 1} { |
---|
104 | {{b i g} 12345} |
---|
105 | {{d e m o} 34512} |
---|
106 | {{c o d e} 54321} |
---|
107 | } |
---|
108 | .CE |
---|
109 | returns \fB{{d e m o} 34512} {{b i g} 12345} {{c o d e} 54321}\fR |
---|
110 | (because \fBe\fR sorts before \fBi\fR which sorts before \fBo\fR.) |
---|
111 | .VE 8.5 |
---|
112 | This option is much more efficient than using \fB\-command\fR |
---|
113 | to achieve the same effect. |
---|
114 | .RE |
---|
115 | .VS 8.5 |
---|
116 | .TP 20 |
---|
117 | \fB\-nocase\fR |
---|
118 | Causes comparisons to be handled in a case-insensitive manner. Has no |
---|
119 | effect if combined with the \fB\-dictionary\fR, \fB\-integer\fR, or |
---|
120 | \fB\-real\fR options. |
---|
121 | .VE 8.5 |
---|
122 | .TP 20 |
---|
123 | \fB\-unique\fR |
---|
124 | If this option is specified, then only the last set of duplicate |
---|
125 | elements found in the list will be retained. Note that duplicates are |
---|
126 | determined relative to the comparison used in the sort. Thus if |
---|
127 | \fI\-index 0\fR is used, \fB{1 a}\fR and \fB{1 b}\fR would be |
---|
128 | considered duplicates and only the second element, \fB{1 b}\fR, would |
---|
129 | be retained. |
---|
130 | .SH "NOTES" |
---|
131 | .PP |
---|
132 | The options to \fBlsort\fR only control what sort of comparison is |
---|
133 | used, and do not necessarily constrain what the values themselves |
---|
134 | actually are. This distinction is only noticeable when the list to be |
---|
135 | sorted has fewer than two elements. |
---|
136 | .PP |
---|
137 | The \fBlsort\fR command is reentrant, meaning it is safe to use as |
---|
138 | part of the implementation of a command used in the \fB\-command\fR |
---|
139 | option. |
---|
140 | .SH "EXAMPLES" |
---|
141 | .PP |
---|
142 | Sorting a list using ASCII sorting: |
---|
143 | .CS |
---|
144 | % \fBlsort\fR {a10 B2 b1 a1 a2} |
---|
145 | B2 a1 a10 a2 b1 |
---|
146 | .CE |
---|
147 | .PP |
---|
148 | Sorting a list using Dictionary sorting: |
---|
149 | .CS |
---|
150 | % \fBlsort\fR -dictionary {a10 B2 b1 a1 a2} |
---|
151 | a1 a2 a10 b1 B2 |
---|
152 | .CE |
---|
153 | .PP |
---|
154 | Sorting lists of integers: |
---|
155 | .CS |
---|
156 | % \fBlsort\fR -integer {5 3 1 2 11 4} |
---|
157 | 1 2 3 4 5 11 |
---|
158 | % \fBlsort\fR -integer {1 2 0x5 7 0 4 -1} |
---|
159 | -1 0 1 2 4 0x5 7 |
---|
160 | .CE |
---|
161 | .PP |
---|
162 | Sorting lists of floating-point numbers: |
---|
163 | .CS |
---|
164 | % \fBlsort\fR -real {5 3 1 2 11 4} |
---|
165 | 1 2 3 4 5 11 |
---|
166 | % \fBlsort\fR -real {.5 0.07e1 0.4 6e-1} |
---|
167 | 0.4 .5 6e-1 0.07e1 |
---|
168 | .CE |
---|
169 | .PP |
---|
170 | Sorting using indices: |
---|
171 | .CS |
---|
172 | % # Note the space character before the c |
---|
173 | % \fBlsort\fR {{a 5} { c 3} {b 4} {e 1} {d 2}} |
---|
174 | { c 3} {a 5} {b 4} {d 2} {e 1} |
---|
175 | % \fBlsort\fR -index 0 {{a 5} { c 3} {b 4} {e 1} {d 2}} |
---|
176 | {a 5} {b 4} { c 3} {d 2} {e 1} |
---|
177 | % \fBlsort\fR -index 1 {{a 5} { c 3} {b 4} {e 1} {d 2}} |
---|
178 | {e 1} {d 2} { c 3} {b 4} {a 5} |
---|
179 | .CE |
---|
180 | .PP |
---|
181 | Stripping duplicate values using sorting: |
---|
182 | .CS |
---|
183 | % \fBlsort\fR -unique {a b c a b c a b c} |
---|
184 | a b c |
---|
185 | .CE |
---|
186 | .PP |
---|
187 | More complex sorting using a comparison function: |
---|
188 | .CS |
---|
189 | % proc compare {a b} { |
---|
190 | set a0 [lindex $a 0] |
---|
191 | set b0 [lindex $b 0] |
---|
192 | if {$a0 < $b0} { |
---|
193 | return -1 |
---|
194 | } elseif {$a0 > $b0} { |
---|
195 | return 1 |
---|
196 | } |
---|
197 | return [string compare [lindex $a 1] [lindex $b 1]] |
---|
198 | } |
---|
199 | % \fBlsort\fR -command compare \e |
---|
200 | {{3 apple} {0x2 carrot} {1 dingo} {2 banana}} |
---|
201 | {1 dingo} {2 banana} {0x2 carrot} {3 apple} |
---|
202 | .CE |
---|
203 | |
---|
204 | .SH "SEE ALSO" |
---|
205 | list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), |
---|
206 | lset(n), lrange(n), lreplace(n) |
---|
207 | |
---|
208 | .SH KEYWORDS |
---|
209 | element, list, order, sort |
---|