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