1 | '\" |
---|
2 | '\" Copyright (c) 1993 The Regents of the University of California. |
---|
3 | '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. |
---|
4 | '\" Copyright (c) 2001 Kevin B. Kenny <kennykb@acm.org>. All rights reserved. |
---|
5 | '\" Copyright (c) 2003-2004 Donal K. Fellows. |
---|
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: lsearch.n,v 1.34 2008/03/26 09:59:22 dkf Exp $ |
---|
11 | '\" |
---|
12 | .so man.macros |
---|
13 | .TH lsearch 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 | lsearch \- See if a list contains a particular element |
---|
18 | .SH SYNOPSIS |
---|
19 | \fBlsearch \fR?\fIoptions\fR? \fIlist pattern\fR |
---|
20 | .BE |
---|
21 | |
---|
22 | .SH DESCRIPTION |
---|
23 | .PP |
---|
24 | This command searches the elements of \fIlist\fR to see if one |
---|
25 | of them matches \fIpattern\fR. If so, the command returns the index |
---|
26 | of the first matching element |
---|
27 | (unless the options \fB\-all\fR or \fB\-inline\fR are specified.) |
---|
28 | If not, the command returns \fB\-1\fR. The \fIoption\fR arguments |
---|
29 | indicates how the elements of the list are to be matched against |
---|
30 | \fIpattern\fR and must have one of the values below: |
---|
31 | .SS "MATCHING STYLE OPTIONS" |
---|
32 | If all matching style options are omitted, the default matching style |
---|
33 | is \fB\-glob\fR. If more than one matching style is specified, the |
---|
34 | last matching style given takes precedence. |
---|
35 | .TP |
---|
36 | \fB\-exact\fR |
---|
37 | \fIPattern\fR is a literal string that is compared for exact equality |
---|
38 | against each list element. |
---|
39 | .TP |
---|
40 | \fB\-glob\fR |
---|
41 | \fIPattern\fR is a glob-style pattern which is matched against each list |
---|
42 | element using the same rules as the \fBstring match\fR command. |
---|
43 | .TP |
---|
44 | \fB\-regexp\fR |
---|
45 | \fIPattern\fR is treated as a regular expression and matched against |
---|
46 | each list element using the rules described in the \fBre_syntax\fR |
---|
47 | reference page. |
---|
48 | .TP |
---|
49 | \fB\-sorted\fR |
---|
50 | The list elements are in sorted order. If this option is specified, |
---|
51 | \fBlsearch\fR will use a more efficient searching algorithm to search |
---|
52 | \fIlist\fR. If no other options are specified, \fIlist\fR is assumed |
---|
53 | to be sorted in increasing order, and to contain ASCII strings. This |
---|
54 | option is mutually exclusive with \fB\-glob\fR and \fB\-regexp\fR, and |
---|
55 | is treated exactly like \fB\-exact\fR when either \fB\-all\fR or |
---|
56 | \fB\-not\fR are specified. |
---|
57 | .SS "GENERAL MODIFIER OPTIONS" |
---|
58 | These options may be given with all matching styles. |
---|
59 | .TP |
---|
60 | \fB\-all\fR |
---|
61 | . |
---|
62 | Changes the result to be the list of all matching indices (or all matching |
---|
63 | values if \fB\-inline\fR is specified as well.) If indices are returned, the |
---|
64 | indices will be in numeric order. If values are returned, the order of the |
---|
65 | values will be the order of those values within the input \fIlist\fR. |
---|
66 | .TP |
---|
67 | \fB\-inline\fR |
---|
68 | The matching value is returned instead of its index (or an empty |
---|
69 | string if no value matches.) If \fB\-all\fR is also specified, then |
---|
70 | the result of the command is the list of all values that matched. |
---|
71 | .TP |
---|
72 | \fB\-not\fR |
---|
73 | This negates the sense of the match, returning the index of the first |
---|
74 | non-matching value in the list. |
---|
75 | .TP |
---|
76 | \fB\-start\fR\0\fIindex\fR |
---|
77 | The list is searched starting at position \fIindex\fR. |
---|
78 | .VS 8.5 |
---|
79 | The interpretation of the \fIindex\fR value is the same as |
---|
80 | for the command \fBstring index\fR, supporting simple index |
---|
81 | arithmetic and indices relative to the end of the list. |
---|
82 | .VE 8.5 |
---|
83 | .SS "CONTENTS DESCRIPTION OPTIONS" |
---|
84 | These options describe how to interpret the items in the list being |
---|
85 | searched. They are only meaningful when used with the \fB\-exact\fR |
---|
86 | and \fB\-sorted\fR options. If more than one is specified, the last |
---|
87 | one takes precedence. The default is \fB\-ascii\fR. |
---|
88 | .TP |
---|
89 | \fB\-ascii\fR |
---|
90 | The list elements are to be examined as Unicode strings (the name is |
---|
91 | for backward-compatibility reasons.) |
---|
92 | .TP |
---|
93 | \fB\-dictionary\fR |
---|
94 | The list elements are to be compared using dictionary-style |
---|
95 | comparisons (see \fBlsort\fR for a fuller description). Note that this |
---|
96 | only makes a meaningful difference from the \fB\-ascii\fR option when |
---|
97 | the \fB\-sorted\fR option is given, because values are only |
---|
98 | dictionary-equal when exactly equal. |
---|
99 | .TP |
---|
100 | \fB\-integer\fR |
---|
101 | The list elements are to be compared as integers. |
---|
102 | .VS 8.5 |
---|
103 | .TP |
---|
104 | \fB\-nocase\fR |
---|
105 | Causes comparisons to be handled in a case-insensitive manner. Has no |
---|
106 | effect if combined with the \fB\-dictionary\fR, \fB\-integer\fR, or |
---|
107 | \fB\-real\fR options. |
---|
108 | .VE 8.5 |
---|
109 | .TP |
---|
110 | \fB\-real\fR |
---|
111 | The list elements are to be compared as floating-point values. |
---|
112 | .SS "SORTED LIST OPTIONS" |
---|
113 | These options (only meaningful with the \fB\-sorted\fR option) specify |
---|
114 | how the list is sorted. If more than one is given, the last one takes |
---|
115 | precedence. The default option is \fB\-increasing\fR. |
---|
116 | .TP |
---|
117 | \fB\-decreasing\fR |
---|
118 | The list elements are sorted in decreasing order. This option is only |
---|
119 | meaningful when used with \fB\-sorted\fR. |
---|
120 | .TP |
---|
121 | \fB\-increasing\fR |
---|
122 | The list elements are sorted in increasing order. This option is only |
---|
123 | meaningful when used with \fB\-sorted\fR. |
---|
124 | .SS "NESTED LIST OPTIONS" |
---|
125 | .VS 8.5 |
---|
126 | These options are used to search lists of lists. They may be used |
---|
127 | with any other options. |
---|
128 | .TP |
---|
129 | \fB\-index\fR\0\fIindexList\fR |
---|
130 | This option is designed for use when searching within nested lists. |
---|
131 | The \fIindexList\fR argument gives a path of indices (much as might be |
---|
132 | used with the \fBlindex\fR or \fBlset\fR commands) within each element |
---|
133 | to allow the location of the term being matched against. |
---|
134 | .TP |
---|
135 | \fB\-subindices\fR |
---|
136 | If this option is given, the index result from this command (or every |
---|
137 | index result when \fB\-all\fR is also specified) will be a complete |
---|
138 | path (suitable for use with \fBlindex\fR or \fBlset\fR) within the |
---|
139 | overall list to the term found. This option has no effect unless the |
---|
140 | \fI\-index\fR is also specified, and is just a convenience short-cut. |
---|
141 | .VE 8.5 |
---|
142 | .SH EXAMPLES |
---|
143 | Basic searching: |
---|
144 | .CS |
---|
145 | \fBlsearch\fR {a b c d e} c |
---|
146 | \fI\(-> 2\fR |
---|
147 | \fBlsearch\fR -all {a b c a b c} c |
---|
148 | \fI\(-> 2 5\fR |
---|
149 | .CE |
---|
150 | .PP |
---|
151 | Using \fBlsearch\fR to filter lists: |
---|
152 | .CS |
---|
153 | \fBlsearch\fR -inline {a20 b35 c47} b* |
---|
154 | \fI\(-> b35\fR |
---|
155 | \fBlsearch\fR -inline -not {a20 b35 c47} b* |
---|
156 | \fI\(-> a20\fR |
---|
157 | \fBlsearch\fR -all -inline -not {a20 b35 c47} b* |
---|
158 | \fI\(-> a20 c47\fR |
---|
159 | \fBlsearch\fR -all -not {a20 b35 c47} b* |
---|
160 | \fI\(-> 0 2\fR |
---|
161 | .CE |
---|
162 | .PP |
---|
163 | This can even do a |
---|
164 | .QW set-like |
---|
165 | removal operation: |
---|
166 | .CS |
---|
167 | \fBlsearch\fR -all -inline -not -exact {a b c a d e a f g a} a |
---|
168 | \fI\(-> b c d e f g\fR |
---|
169 | .CE |
---|
170 | .PP |
---|
171 | Searching may start part-way through the list: |
---|
172 | .CS |
---|
173 | \fBlsearch\fR -start 3 {a b c a b c} c |
---|
174 | \fI\(-> 5\fR |
---|
175 | .CE |
---|
176 | .PP |
---|
177 | It is also possible to search inside elements: |
---|
178 | .CS |
---|
179 | \fBlsearch\fR -index 1 -all -inline {{a abc} {b bcd} {c cde}} *bc* |
---|
180 | \fI\(-> {a abc} {b bcd}\fR |
---|
181 | .CE |
---|
182 | .SH "SEE ALSO" |
---|
183 | foreach(n), list(n), lappend(n), lindex(n), linsert(n), llength(n), |
---|
184 | lset(n), lsort(n), lrange(n), lreplace(n), |
---|
185 | .VS 8.5 |
---|
186 | string(n) |
---|
187 | .VE |
---|
188 | .SH KEYWORDS |
---|
189 | list, match, pattern, regular expression, search, string |
---|
190 | '\" Local Variables: |
---|
191 | '\" mode: nroff |
---|
192 | '\" End: |
---|