summaryrefslogtreecommitdiffstats
path: root/doc/lsearch.n
diff options
context:
space:
mode:
Diffstat (limited to 'doc/lsearch.n')
-rw-r--r--doc/lsearch.n67
1 files changed, 56 insertions, 11 deletions
diff --git a/doc/lsearch.n b/doc/lsearch.n
index 48c24b8..30ce348 100644
--- a/doc/lsearch.n
+++ b/doc/lsearch.n
@@ -6,7 +6,7 @@
'\" 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.9 2001/11/14 23:38:39 hobbs Exp $
+'\" RCS: @(#) $Id: lsearch.n,v 1.10 2002/03/06 11:28:08 dkf Exp $
'\"
.so man.macros
.TH lsearch n 8.4 Tcl "Tcl Built-In Commands"
@@ -22,10 +22,19 @@ lsearch \- See if a list contains a particular element
.PP
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. 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:
+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 ASCII strings. This option is only
@@ -43,17 +52,30 @@ comparisons. This option is only meaningful when used with
\fB\-exact\fR
The list element must contain exactly the same string as \fIpattern\fR.
.TP
+\fB\-glob\fR
+\fIPattern\fR is a glob-style pattern which is matched against each list
+element using the same rules as the \fBstring match\fR command.
+.TP
\fB\-increasing\fR
The list elements are sorted in increasing order. This option is only
meaningful when used with \fB\-sorted\fR.
.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\-glob\fR
-\fIPattern\fR is a glob-style pattern which is matched against each list
-element using the same rules as the \fBstring match\fR command.
+\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
@@ -69,7 +91,16 @@ The list elements are in sorted order. If this option is specified,
\fBlsearch\fR will use a more efficient searching algorithm to search
\fIlist\fR. If no other options are specified, \fIlist\fR is assumed
to be sorted in increasing order, and to contain ASCII strings. This
-option cannot be used with \fB\-glob\fR or \fB\-regexp\fR.
+option cannot be used with \fB\-all\fR, \fB\-glob\fR, \fB\-not\fR or
+\fB\-regexp\fR.
+.TP
+\fB\-start\fR \fIindex\fR
+.VS 8.4
+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
.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
@@ -77,11 +108,25 @@ than one of \fB\-exact\fR, \fB\-glob\fR, \fB\-regexp\fR, and
precendence. If more than one of \fB\-ascii\fR, \fB\-dictionary\fR,
\fB\-integer\fR and \fB\-real\fR is specified, the option specified
last takes precendence. If more than one of \fB\-increasing\fR and
-\fB\-decreasing\fR is specified, the option specified last takes precedence.
+\fB\-decreasing\fR is specified, the option specified last takes
+precedence.
+
+.SH EXAMPLES
+.VS 8.4
+.CS
+lsearch {a b c d e} c => 2
+lsearch -all {a b c a b c} c => 2 5
+lsearch -data {a20 b35 c47} b* => b35
+lsearch -data -not {a20 b35 c47} b* => a20
+lsearch -all -data -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
+.CE
+.VE 8.4
.SH "SEE ALSO"
.VS 8.4
-list(n), lappend(n), lindex(n), linsert(n), llength(n),
+foreach(n), list(n), lappend(n), lindex(n), linsert(n), llength(n),
lset(n), lsort(n), lrange(n), lreplace(n)
.VE