[25] | 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 |
---|