util/X86LINUX64/man/mann/lsearch.n

   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 .TH lsearch n 8.6 Tcl "Tcl Built-In Commands"
  11 .\" The -*- nroff -*- definitions below are for supplemental macros used
  12 .\" in Tcl/Tk manual entries.
  13 .\"
  14 .\" .AP type name in/out ?indent?
  15 .\"     Start paragraph describing an argument to a library procedure.
  16 .\"     type is type of argument (int, etc.), in/out is either "in", "out",
  17 .\"     or "in/out" to describe whether procedure reads or modifies arg,
  18 .\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  19 .\"     needed;  use .AS below instead)
  20 .\"
  21 .\" .AS ?type? ?name?
  22 .\"     Give maximum sizes of arguments for setting tab stops.  Type and
  23 .\"     name are examples of largest possible arguments that will be passed
  24 .\"     to .AP later.  If args are omitted, default tab stops are used.
  25 .\"
  26 .\" .BS
  27 .\"     Start box enclosure.  From here until next .BE, everything will be
  28 .\"     enclosed in one large box.
  29 .\"
  30 .\" .BE
  31 .\"     End of box enclosure.
  32 .\"
  33 .\" .CS
  34 .\"     Begin code excerpt.
  35 .\"
  36 .\" .CE
  37 .\"     End code excerpt.
  38 .\"
  39 .\" .VS ?version? ?br?
  40 .\"     Begin vertical sidebar, for use in marking newly-changed parts
  41 .\"     of man pages.  The first argument is ignored and used for recording
  42 .\"     the version when the .VS was added, so that the sidebars can be
  43 .\"     found and removed when they reach a certain age.  If another argument
  44 .\"     is present, then a line break is forced before starting the sidebar.
  45 .\"
  46 .\" .VE
  47 .\"     End of vertical sidebar.
  48 .\"
  49 .\" .DS
  50 .\"     Begin an indented unfilled display.
  51 .\"
  52 .\" .DE
  53 .\"     End of indented unfilled display.
  54 .\"
  55 .\" .SO ?manpage?
  56 .\"     Start of list of standard options for a Tk widget. The manpage
  57 .\"     argument defines where to look up the standard options; if
  58 .\"     omitted, defaults to "options". The options follow on successive
  59 .\"     lines, in three columns separated by tabs.
  60 .\"
  61 .\" .SE
  62 .\"     End of list of standard options for a Tk widget.
  63 .\"
  64 .\" .OP cmdName dbName dbClass
  65 .\"     Start of description of a specific option.  cmdName gives the
  66 .\"     option's name as specified in the class command, dbName gives
  67 .\"     the option's name in the option database, and dbClass gives
  68 .\"     the option's class in the option database.
  69 .\"
  70 .\" .UL arg1 arg2
  71 .\"     Print arg1 underlined, then print arg2 normally.
  72 .\"
  73 .\" .QW arg1 ?arg2?
  74 .\"     Print arg1 in quotes, then arg2 normally (for trailing punctuation).
  75 .\"
  76 .\" .PQ arg1 ?arg2?
  77 .\"     Print an open parenthesis, arg1 in quotes, then arg2 normally
  78 .\"     (for trailing punctuation) and then a closing parenthesis.
  79 .\"
  80 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  81 .if t .wh -1.3i ^B
  82 .nr ^l \n(.l
  83 .ad b
  84 .\"     # Start an argument description
  85 .de AP
  86 .ie !"\\$4"" .TP \\$4
  87 .el \{\
  88 .   ie !"\\$2"" .TP \\n()Cu
  89 .   el          .TP 15
  90 .\}
  91 .ta \\n()Au \\n()Bu
  92 .ie !"\\$3"" \{\
  93 \&\\$1 \\fI\\$2\\fP (\\$3)
  94 .\".b
  95 .\}
  96 .el \{\
  97 .br
  98 .ie !"\\$2"" \{\
  99 \&\\$1  \\fI\\$2\\fP
 100 .\}
 101 .el \{\
 102 \&\\fI\\$1\\fP
 103 .\}
 104 .\}
 105 ..
 106 .\"     # define tabbing values for .AP
 107 .de AS
 108 .nr )A 10n
 109 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 110 .nr )B \\n()Au+15n
 111 .\"
 112 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 113 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 114 ..
 115 .AS Tcl_Interp Tcl_CreateInterp in/out
 116 .\"     # BS - start boxed text
 117 .\"     # ^y = starting y location
 118 .\"     # ^b = 1
 119 .de BS
 120 .br
 121 .mk ^y
 122 .nr ^b 1u
 123 .if n .nf
 124 .if n .ti 0
 125 .if n \l'\\n(.lu\(ul'
 126 .if n .fi
 127 ..
 128 .\"     # BE - end boxed text (draw box now)
 129 .de BE
 130 .nf
 131 .ti 0
 132 .mk ^t
 133 .ie n \l'\\n(^lu\(ul'
 134 .el \{\
 135 .\"     Draw four-sided box normally, but don't draw top of
 136 .\"     box if the box started on an earlier page.
 137 .ie !\\n(^b-1 \{\
 138 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 139 .\}
 140 .el \}\
 141 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 142 .\}
 143 .\}
 144 .fi
 145 .br
 146 .nr ^b 0
 147 ..
 148 .\"     # VS - start vertical sidebar
 149 .\"     # ^Y = starting y location
 150 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 151 .de VS
 152 .if !"\\$2"" .br
 153 .mk ^Y
 154 .ie n 'mc \s12\(br\s0
 155 .el .nr ^v 1u
 156 ..
 157 .\"     # VE - end of vertical sidebar
 158 .de VE
 159 .ie n 'mc
 160 .el \{\
 161 .ev 2
 162 .nf
 163 .ti 0
 164 .mk ^t
 165 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 166 .sp -1
 167 .fi
 168 .ev
 169 .\}
 170 .nr ^v 0
 171 ..
 172 .\"     # Special macro to handle page bottom:  finish off current
 173 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 174 .\"     # page bottom macro.
 175 .de ^B
 176 .ev 2
 177 'ti 0
 178 'nf
 179 .mk ^t
 180 .if \\n(^b \{\
 181 .\"     Draw three-sided box if this is the box's first page,
 182 .\"     draw two sides but no top otherwise.
 183 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 184 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 185 .\}
 186 .if \\n(^v \{\
 187 .nr ^x \\n(^tu+1v-\\n(^Yu
 188 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 189 .\}
 190 .bp
 191 'fi
 192 .ev
 193 .if \\n(^b \{\
 194 .mk ^y
 195 .nr ^b 2
 196 .\}
 197 .if \\n(^v \{\
 198 .mk ^Y
 199 .\}
 200 ..
 201 .\"     # DS - begin display
 202 .de DS
 203 .RS
 204 .nf
 205 .sp
 206 ..
 207 .\"     # DE - end display
 208 .de DE
 209 .fi
 210 .RE
 211 .sp
 212 ..
 213 .\"     # SO - start of list of standard options
 214 .de SO
 215 'ie '\\$1'' .ds So \\fBoptions\\fR
 216 'el .ds So \\fB\\$1\\fR
 217 .SH "STANDARD OPTIONS"
 218 .LP
 219 .nf
 220 .ta 5.5c 11c
 221 .ft B
 222 ..
 223 .\"     # SE - end of list of standard options
 224 .de SE
 225 .fi
 226 .ft R
 227 .LP
 228 See the \\*(So manual entry for details on the standard options.
 229 ..
 230 .\"     # OP - start of full description for a single option
 231 .de OP
 232 .LP
 233 .nf
 234 .ta 4c
 235 Command-Line Name:      \\fB\\$1\\fR
 236 Database Name:  \\fB\\$2\\fR
 237 Database Class: \\fB\\$3\\fR
 238 .fi
 239 .IP
 240 ..
 241 .\"     # CS - begin code excerpt
 242 .de CS
 243 .RS
 244 .nf
 245 .ta .25i .5i .75i 1i
 246 ..
 247 .\"     # CE - end code excerpt
 248 .de CE
 249 .fi
 250 .RE
 251 ..
 252 .\"     # UL - underline word
 253 .de UL
 254 \\$1\l'|0\(ul'\\$2
 255 ..
 256 .\"     # QW - apply quotation marks to word
 257 .de QW
 258 .ie '\\*(lq'"' ``\\$1''\\$2
 259 .\"" fix emacs highlighting
 260 .el \\*(lq\\$1\\*(rq\\$2
 261 ..
 262 .\"     # PQ - apply parens and quotation marks to word
 263 .de PQ
 264 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 265 .\"" fix emacs highlighting
 266 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 267 ..
 268 .\"     # QR - quoted range
 269 .de QR
 270 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 271 .\"" fix emacs highlighting
 272 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 273 ..
 274 .\"     # MT - "empty" string
 275 .de MT
 276 .QW ""
 277 ..
 278 .BS
 279 '\" Note:  do not modify the .SH NAME line immediately below!
 280 .SH NAME
 281 lsearch \- See if a list contains a particular element
 282 .SH SYNOPSIS
 283 \fBlsearch \fR?\fIoptions\fR? \fIlist pattern\fR
 284 .BE
 285 .SH DESCRIPTION
 286 .PP
 287 This command searches the elements of \fIlist\fR to see if one
 288 of them matches \fIpattern\fR.  If so, the command returns the index
 289 of the first matching element
 290 (unless the options \fB\-all\fR or \fB\-inline\fR are specified.)
 291 If not, the command returns \fB\-1\fR.  The \fIoption\fR arguments
 292 indicates how the elements of the list are to be matched against
 293 \fIpattern\fR and must have one of the values below:
 294 .SS "MATCHING STYLE OPTIONS"
 295 .PP
 296 If all matching style options are omitted, the default matching style
 297 is \fB\-glob\fR.  If more than one matching style is specified, the
 298 last matching style given takes precedence.
 299 .TP
 300 \fB\-exact\fR
 301 .
 302 \fIPattern\fR is a literal string that is compared for exact equality
 303 against each list element.
 304 .TP
 305 \fB\-glob\fR
 306 .
 307 \fIPattern\fR is a glob-style pattern which is matched against each list
 308 element using the same rules as the \fBstring match\fR command.
 309 .TP
 310 \fB\-regexp\fR
 311 .
 312 \fIPattern\fR is treated as a regular expression and matched against
 313 each list element using the rules described in the \fBre_syntax\fR
 314 reference page.
 315 .TP
 316 \fB\-sorted\fR
 317 .
 318 The list elements are in sorted order.  If this option is specified,
 319 \fBlsearch\fR will use a more efficient searching algorithm to search
 320 \fIlist\fR.  If no other options are specified, \fIlist\fR is assumed
 321 to be sorted in increasing order, and to contain ASCII strings.  This
 322 option is mutually exclusive with \fB\-glob\fR and \fB\-regexp\fR, and
 323 is treated exactly like \fB\-exact\fR when either \fB\-all\fR or
 324 \fB\-not\fR are specified.
 325 .SS "GENERAL MODIFIER OPTIONS"
 326 .PP
 327 These options may be given with all matching styles.
 328 .TP
 329 \fB\-all\fR
 330 .
 331 Changes the result to be the list of all matching indices (or all matching
 332 values if \fB\-inline\fR is specified as well.) If indices are returned, the
 333 indices will be in numeric order. If values are returned, the order of the
 334 values will be the order of those values within the input \fIlist\fR.
 335 .TP
 336 \fB\-inline\fR
 337 .
 338 The matching value is returned instead of its index (or an empty
 339 string if no value matches.)  If \fB\-all\fR is also specified, then
 340 the result of the command is the list of all values that matched.
 341 .TP
 342 \fB\-not\fR
 343 .
 344 This negates the sense of the match, returning the index of the first
 345 non-matching value in the list.
 346 .TP
 347 \fB\-start\fR\0\fIindex\fR
 348 .
 349 The list is searched starting at position \fIindex\fR.
 350 The interpretation of the \fIindex\fR value is the same as
 351 for the command \fBstring index\fR, supporting simple index
 352 arithmetic and indices relative to the end of the list.
 353 .SS "CONTENTS DESCRIPTION OPTIONS"
 354 .PP
 355 These options describe how to interpret the items in the list being
 356 searched.  They are only meaningful when used with the \fB\-exact\fR
 357 and \fB\-sorted\fR options.  If more than one is specified, the last
 358 one takes precedence.  The default is \fB\-ascii\fR.
 359 .TP
 360 \fB\-ascii\fR
 361 .
 362 The list elements are to be examined as Unicode strings (the name is
 363 for backward-compatibility reasons.)
 364 .TP
 365 \fB\-dictionary\fR
 366 .
 367 The list elements are to be compared using dictionary-style
 368 comparisons (see \fBlsort\fR for a fuller description). Note that this
 369 only makes a meaningful difference from the \fB\-ascii\fR option when
 370 the \fB\-sorted\fR option is given, because values are only
 371 dictionary-equal when exactly equal.
 372 .TP
 373 \fB\-integer\fR
 374 .
 375 The list elements are to be compared as integers.
 376 .TP
 377 \fB\-nocase\fR
 378 .
 379 Causes comparisons to be handled in a case-insensitive manner.  Has no
 380 effect if combined with the \fB\-dictionary\fR, \fB\-integer\fR, or
 381 \fB\-real\fR options.
 382 .TP
 383 \fB\-real\fR
 384 .
 385 The list elements are to be compared as floating-point values.
 386 .SS "SORTED LIST OPTIONS"
 387 .PP
 388 These options (only meaningful with the \fB\-sorted\fR option) specify
 389 how the list is sorted.  If more than one is given, the last one takes
 390 precedence.  The default option is \fB\-increasing\fR.
 391 .TP
 392 \fB\-decreasing\fR
 393 .
 394 The list elements are sorted in decreasing order.  This option is only
 395 meaningful when used with \fB\-sorted\fR.
 396 .TP
 397 \fB\-increasing\fR
 398 .
 399 The list elements are sorted in increasing order.  This option is only
 400 meaningful when used with \fB\-sorted\fR.
 401 .TP
 402 \fB\-bisect\fR
 403 .VS 8.6
 404 Inexact search when the list elements are in sorted order. For an increasing
 405 list the last index where the element is less than or equal to the pattern
 406 is returned. For a decreasing list the last index where the element is greater
 407 than or equal to the pattern is returned. If the pattern is before the first
 408 element or the list is empty, -1 is returned.
 409 This option implies \fB\-sorted\fR and cannot be used with either \fB\-all\fR
 410 or \fB\-not\fR.
 411 .VE 8.6
 412 .SS "NESTED LIST OPTIONS"
 413 .PP
 414 These options are used to search lists of lists.  They may be used
 415 with any other options.
 416 .TP
 417 \fB\-index\fR\0\fIindexList\fR
 418 .
 419 This option is designed for use when searching within nested lists.
 420 The \fIindexList\fR argument gives a path of indices (much as might be
 421 used with the \fBlindex\fR or \fBlset\fR commands) within each element
 422 to allow the location of the term being matched against.
 423 .TP
 424 \fB\-subindices\fR
 425 .
 426 If this option is given, the index result from this command (or every
 427 index result when \fB\-all\fR is also specified) will be a complete
 428 path (suitable for use with \fBlindex\fR or \fBlset\fR) within the
 429 overall list to the term found.  This option has no effect unless the
 430 \fB\-index\fR is also specified, and is just a convenience short-cut.
 431 .SH EXAMPLES
 432 .PP
 433 Basic searching:
 434 .PP
 435 .CS
 436 \fBlsearch\fR {a b c d e} c
 437       \fI\(-> 2\fR
 438 \fBlsearch\fR -all {a b c a b c} c
 439       \fI\(-> 2 5\fR
 440 .CE
 441 .PP
 442 Using \fBlsearch\fR to filter lists:
 443 .PP
 444 .CS
 445 \fBlsearch\fR -inline {a20 b35 c47} b*
 446       \fI\(-> b35\fR
 447 \fBlsearch\fR -inline -not {a20 b35 c47} b*
 448       \fI\(-> a20\fR
 449 \fBlsearch\fR -all -inline -not {a20 b35 c47} b*
 450       \fI\(-> a20 c47\fR
 451 \fBlsearch\fR -all -not {a20 b35 c47} b*
 452       \fI\(-> 0 2\fR
 453 .CE
 454 .PP
 455 This can even do a
 456 .QW set-like
 457 removal operation:
 458 .PP
 459 .CS
 460 \fBlsearch\fR -all -inline -not -exact {a b c a d e a f g a} a
 461       \fI\(-> b c d e f g\fR
 462 .CE
 463 .PP
 464 Searching may start part-way through the list:
 465 .PP
 466 .CS
 467 \fBlsearch\fR -start 3 {a b c a b c} c
 468       \fI\(-> 5\fR
 469 .CE
 470 .PP
 471 It is also possible to search inside elements:
 472 .PP
 473 .CS
 474 \fBlsearch\fR -index 1 -all -inline {{a abc} {b bcd} {c cde}} *bc*
 475       \fI\(-> {a abc} {b bcd}\fR
 476 .CE
 477 .SH "SEE ALSO"
 478 foreach(n), list(n), lappend(n), lindex(n), linsert(n), llength(n),
 479 lset(n), lsort(n), lrange(n), lreplace(n),
 480 string(n)
 481 .SH KEYWORDS
 482 binary search, linear search,
 483 list, match, pattern, regular expression, search, string
 484 '\" Local Variables:
 485 '\" mode: nroff
 486 '\" End: