diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/lsearch.n | 38 | ||||
| -rw-r--r-- | doc/lsort.n | 35 |
2 files changed, 41 insertions, 32 deletions
diff --git a/doc/lsearch.n b/doc/lsearch.n index 302a1f5..b2129aa 100644 --- a/doc/lsearch.n +++ b/doc/lsearch.n @@ -6,10 +6,10 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: lsearch.n,v 1.14 2003/03/17 14:21:40 dkf Exp $ +'\" RCS: @(#) $Id: lsearch.n,v 1.15 2003/10/14 13:38:57 dkf Exp $ '\" .so man.macros -.TH lsearch n 8.4 Tcl "Tcl Built-In Commands" +.TH lsearch n 8.5 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -23,18 +23,14 @@ lsearch \- See if a list contains a particular element This command searches the elements of \fIlist\fR to see if one of them matches \fIpattern\fR. If so, the command returns the index of the first matching element -.VS 8.4 (unless the options \fB\-all\fR or \fB\-inline\fR are specified.) -.VE 8.4 If not, the command returns \fB\-1\fR. The \fIoption\fR arguments indicates how the elements of the list are to be matched against \fIpattern\fR and it must have one of the following values: .TP \fB\-all\fR -.VS 8.4 Changes the result to be the list of all matching indices (or all matching values if \fB\-inline\fR is specified as well.) -.VE 8.4 .TP \fB\-ascii\fR The list elements are to be examined as Unicode strings (the name is @@ -61,22 +57,26 @@ element using the same rules as the \fBstring match\fR command. The list elements are sorted in increasing order. This option is only meaningful when used with \fB\-sorted\fR. .TP +\fB\-index\fR\0\fIindexList\fR +.VS 8.5 +This option is designed for use when searching within nested lists. +The \fIindexList\fR gives a path of indices (much as might be used +with the \fBlsearch\fR command) within each element to allow the +location of the term being matched against. +.VE 8.5 +.TP \fB\-inline\fR -.VS 8.4 The matching value is returned instead of its index (or an empty string if no value matches.) If \fB\-all\fR is also specified, then the result of the command is the list of all values that matched. -.VE 8.4 .TP \fB\-integer\fR The list elements are to be compared as integers. This option is only meaningful when used with \fB\-exact\fR or \fB\-sorted\fR. .TP \fB\-not\fR -.VS 8.4 This negates the sense of the match, returning the index of the first non-matching value in the list. -.VE 8.4 .TP \fB\-real\fR The list elements are to be compared as floating-point values. This @@ -96,13 +96,20 @@ option is mutually exclusive with \fB\-glob\fR and \fB\-regexp\fR, and is treated exactly like \fB-exact\fR when either \fB\-all\fR, or \fB\-not\fR is specified. .TP -\fB\-start\fR \fIindex\fR -.VS 8.4 +\fB\-start\fR\0\fIindex\fR The list is searched starting at position \fIindex\fR. If \fIindex\fR has the value \fBend\fR, it refers to the last element in the list, and \fBend\-\fIinteger\fR refers to the last element in the list minus the specified integer offset. -.VE 8.4 +.TP +\fB\-subindices\fR +.VS 8.5 +If this option is given, the index result from this command (or every +index result when \fB\-all\fR is also specified) will be a complete +path (suitable for use with \fBlindex\fR or \fBlset\fR) within the +overall list to the term found. This option has no effect unless the +\fI\-index\fR is also specified, and is just a convenience short-cut. +.VE 8.5 .PP If \fIoption\fR is omitted then it defaults to \fB\-glob\fR. If more than one of \fB\-exact\fR, \fB\-glob\fR, \fB\-regexp\fR, and @@ -113,7 +120,6 @@ last takes precedence. If more than one of \fB\-increasing\fR and \fB\-decreasing\fR is specified, the option specified last takes precedence. -.VS 8.4 .SH EXAMPLES .CS lsearch {a b c d e} c => 2 @@ -123,14 +129,12 @@ lsearch -inline -not {a20 b35 c47} b* => a20 lsearch -all -inline -not {a20 b35 c47} b* => a20 c47 lsearch -all -not {a20 b35 c47} b* => 0 2 lsearch -start 3 {a b c a b c} c => 5 +lsearch -index 1 -all {{a abc} {b bcd} {c cde}} *bc* => {a abc} {b bcd} .CE -.VE 8.4 .SH "SEE ALSO" -.VS 8.4 foreach(n), list(n), lappend(n), lindex(n), linsert(n), llength(n), lset(n), lsort(n), lrange(n), lreplace(n) -.VE .SH KEYWORDS list, match, pattern, regular expression, search, string diff --git a/doc/lsort.n b/doc/lsort.n index 1af8dc6..217c094 100644 --- a/doc/lsort.n +++ b/doc/lsort.n @@ -7,7 +7,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: lsort.n,v 1.13 2003/03/17 14:21:41 dkf Exp $ +'\" RCS: @(#) $Id: lsort.n,v 1.14 2003/10/14 13:38:58 dkf Exp $ '\" .so man.macros .TH lsort n 8.3 Tcl "Tcl Built-In Commands" @@ -65,32 +65,39 @@ This is the default. \fB\-decreasing\fR Sort the list in decreasing order (``largest'' items first). .TP 20 -\fB\-index\0\fIindex\fR +\fB\-index\0\fIindexList\fR If this option is specified, each of the elements of \fIlist\fR must itself be a proper Tcl sublist. Instead of sorting based on whole -sublists, \fBlsort\fR will extract the \fIindex\fR'th element from -each sublist and sort based on the given element. The keyword -\fBend\fP is allowed for the \fIindex\fP to sort on the last sublist -element, -.VS 8.4 -and \fBend-\fIindex\fR sorts on a sublist element offset from -the end. -.VE +sublists, \fBlsort\fR will extract the \fIindexList\fR'th element from +each sublist +.VS 8.5 +(as if the overall element and the \fIindexList\fR were passed to +\fBlindex\fR) and sort based on the given element. The keyword +\fBend\fP is allowed for each element of the \fIindexList\fR to sort +on the last sublist element, and \fBend-\fIindex\fR sorts on a sublist +element offset from the end. +.VE 8.5 For example, .RS .CS lsort -integer -index 1 {{First 24} {Second 18} {Third 30}} .CE returns \fB{Second 18} {First 24} {Third 30}\fR, and -.VS 8.4 '\" '\" This example is from the test suite! '\" .CS lsort -index end-1 {{a 1 e i} {b 2 3 f g} {c 4 5 6 d h}} .CE -returns \fB{c 4 5 6 d h} {a 1 e i} {b 2 3 f g}\fR. -.VE +returns \fB{c 4 5 6 d h} {a 1 e i} {b 2 3 f g}\fR, +.VS 8.5 +and +.CS +lsort -index {0 1} {{{b i g} 12345} {{d e m o} 34512} {{c o d e} 54321}} +.CE +returns \fB{{d e m o} 34512} {{b i g} 12345} {{c o d e} 54321}\fR +(because \fBe\fR sorts before \fBi\fR which sorts before \fBo\fR.) +.VE 8.5 This option is much more efficient than using \fB\-command\fR to achieve the same effect. .RE @@ -186,10 +193,8 @@ More complex sorting using a comparison function: .CE .SH "SEE ALSO" -.VS 8.4 list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), lset(n), lrange(n), lreplace(n) -.VE .SH KEYWORDS element, list, order, sort |