1mNAME0m
       lsearch - See if a list contains a particular element

1mSYNOPSIS0m
       1mlsearch 22m?4moptions24m? 4mlist24m 4mpattern0m


1mDESCRIPTION0m
       This  command  searches  the  elements  of  4mlist24m  to see if one of them
       matches 4mpattern24m.  If so, the command returns the  index  of  the  first
       matching  element  (unless  the options 1m-all 22mor 1m-inline 22mare specified.)
       If not, the command returns 1m-122m.  The 4moption24m arguments indicates how the
       elements of the list are to be matched against 4mpattern24m and it must have
       one of the following values:

       1m-all   22mChanges the result to be the list of all  matching  indices  (or
              all matching values if 1m-inline 22mis specified as well.)

       1m-ascii 22mThe  list  elements  are  to be examined as Unicode strings (the
              name is for backward-compatability  reasons.)   This  option  is
              only meaningful when used with 1m-exact 22mor 1m-sorted22m.

       1m-decreasing0m
              The  list  elements are sorted in decreasing order.  This option
              is only meaningful when used with 1m-sorted22m.

       1m-dictionary0m
              The list elements are to be compared using dictionary-style com-
              parisons  (see  1mlsort 22mfor a fuller description).  This option is
              only meaningful when used with 1m-exact 22mor 1m-sorted22m, and it is only
              distinguishable  from  the 1m-ascii 22moption when the 1m-sorted 22moption
              is given, because values are only dictionary-equal when  exactly
              equal.

       1m-exact 22mThe  list  element  must contain exactly the same string as 4mpat-0m
              4mtern24m.

       1m-glob  4m22mPattern24m is a glob-style pattern which is  matched  against  each
              list element using the same rules as the 1mstring match 22mcommand.

       1m-increasing0m
              The  list  elements are sorted in increasing order.  This option
              is only meaningful when used with 1m-sorted22m.

       1m-inline0m
              The matching value is returned instead of its index (or an empty
              string  if  no  value matches.)  If 1m-all 22mis also specified, then
              the result of the  command  is  the  list  of  all  values  that
              matched.

       1m-integer0m
              The  list  elements are to be compared as integers.  This option
              is only meaningful when used with 1m-exact 22mor 1m-sorted22m.

       1m-not   22mThis negates the sense of the match, returning the index of  the
              first non-matching value in the list.

       1m-real  22mThe  list  elements are to be compared as floating-point values.
              This option is only meaningful when used with 1m-exact 22mor 1m-sorted22m.

       1m-regexp0m
              4mPattern24m  is  treated as a regular expression and matched against
              each list element using the rules  described  in  the  1mre_syntax0m
              reference page.

       1m-sorted0m
              The list elements are in sorted order.  If this option is speci-
              fied, 1mlsearch 22mwill use a more efficient searching  algorithm  to
              search 4mlist24m.  If no other options are specified, 4mlist24m is assumed
              to be sorted in increasing order, and to contain ASCII  strings.
              This option is mutually exclusive with 1m-glob 22mand 1m-regexp22m, and is
              treated exactly like 1m-exact 22mwhen either 1m-all22m, or 1m-not 22mis  speci-
              fied.

       1m-start 4m22mindex0m
              The  list  is searched starting at position 4mindex24m.  If 4mindex24m has
              the value 1mend22m, it refers to the last element in  the  list,  and
              1mend-4m22minteger24m  refers  to  the  last element in the list minus the
              specified integer offset.

       If 4moption24m is omitted then it defaults to 1m-glob22m.  If more  than  one  of
       1m-exact22m,  1m-glob22m,  1m-regexp22m, and 1m-sorted 22mis specified, whichever option is
       specified last takes precedence.  If more than one of 1m-ascii22m,  1m-dictio-0m
       1mnary22m,  1m-integer 22mand 1m-real 22mis specified, the option specified last takes
       precedence.  If more than one of 1m-increasing 22mand 1m-decreasing 22mis  speci-
       fied, the option specified last takes precedence.


1mEXAMPLES0m
              1mlsearch 22m{a b c d e} c 4m=>24m 4m20m
              1mlsearch 22m-all {a b c a b c} c 4m=>24m 4m224m 4m50m
              1mlsearch 22m-inline {a20 b35 c47} b* 4m=>24m 4mb350m
              1mlsearch 22m-inline -not {a20 b35 c47} b* 4m=>24m 4ma200m
              1mlsearch 22m-all -inline -not {a20 b35 c47} b* 4m=>24m 4ma2024m 4mc470m
              1mlsearch 22m-all -not {a20 b35 c47} b* 4m=>24m 4m024m 4m20m
              1mlsearch 22m-start 3 {a b c a b c} c 4m=>24m 4m50m


1mSEE ALSO0m
       foreach(n),  list(n),  lappend(n),  lindex(n),  linsert(n), llength(n),
       lset(n), lsort(n), lrange(n), lreplace(n)


1mKEYWORDS0m
