Tcl Built-In Commands                                 lsearch(1T)





NAME
     lsearch - See if a list contains a particular element

SYNOPSIS
     lsearch ?options? list pattern



DESCRIPTION
     This command searches the elements of list to see if one  of
     them  matches pattern.  If so, the command returns the index
     of the first matching element (unless the  options  -all  or  
     -inline  are  specified.)   If  not, the command returns -1.
     The option arguments indicates how the elements of the  list
     are  to  be  matched against pattern and it must have one of
     the following values:

     -all Changes the result to  be  the  list  of  all  matching  
          indices (or all matching values if -inline is specified  
          as well.)

     -ascii
          The list elements are to be examined as Unicode strings
          (the name is for backward-compatability reasons.)  This
          option is only meaningful  when  used  with  -exact  or
          -sorted.

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

     -dictionary
          The list elements are to be compared using  dictionary-
          style comparisons (see lsort for a fuller description).
          This option is only meaningful when used with -exact or
          -sorted, and it is only distinguishable from the -ascii
          option when the -sorted option is given, because values
          are only dictionary-equal when exactly equal.

     -exact
          The list element must contain exactly the  same  string
          as pattern.

     -glob
          Pattern  is  a  glob-style  pattern  which  is  matched
          against  each  list element using the same rules as the
          string match command.

     -increasing
          The list elements are sorted in increasing order.  This



Tcl                     Last change: 8.4                        1






Tcl Built-In Commands                                 lsearch(1T)



          option is only meaningful when used with -sorted.

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

     -integer
          The list elements are to be compared as integers.  This
          option  is  only  meaningful  when  used with -exact or
          -sorted.

     -not This negates the sense  of  the  match,  returning  the  
          index of the first non-matching value in the list.

     -real
          The list elements are to be compared as  floating-point
          values.   This option is only meaningful when used with
          -exact or -sorted.

     -regexp
          Pattern is treated as a regular expression and  matched
          against  each list element using the rules described in
          the resyntax reference page.

     -sorted
          The list elements are in sorted order.  If this  option
          is specified, lsearch will use a more efficient search-
          ing algorithm to search list.  If no other options  are
          specified,  list  is assumed to be sorted in increasing
          order, and to contain ASCI strings.   This  option  is
          mutually  exclusive  with  -glob  and  -regexp,  and is
          treated exactly like -exact when either -all,  or  -not
          is specified.

     -start index
          The list is searched starting at  position  index.   If  
          index  has the value end, it refers to the last element  
          in the list, and end-integer refers to the last element  
          in the list minus the specified integer offset.

     If option is omitted then it defaults  to  -glob.   If  more
     than  one  of  -exact, -glob, -regexp, and -sorted is speci-
     fied, whichever option is specified last  takes  precedence.
     If  more than one of -ascii, -dictionary, -integer and -real
     is specified, the option specified  last  takes  precedence.
     If  more  than  one of -increasing and -decreasing is speci-
     fied, the option specified last takes precedence.






Tcl                     Last change: 8.4                        2






Tcl Built-In Commands                                 lsearch(1T)



EXAMPLES                                                           
          lsearch {a b c d e} c => 2                               
          lsearch -all {a b c a b c} c => 2 5                      
          lsearch -inline {a20 b35 c47} b* => b35                  
          lsearch -inline -not {a20 b35 c47} b* => a20             
          lsearch -all -inline -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                    


SEE ALSO
     foreach(1T), list(1T), lappend(1T), lindex(1T), linsert(1T),  
     llength(1T), lset(1T), lsort(1T), lrange(1T), lreplace(1T)


KEYWORDS
     list, match, pattern, regular expression, search, string


ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     
       ATRIBUTE TYPE     ATRIBUTE VALUE
    
     Availability         SUNWTcl        
    
     Interface Stability  Uncommitted    
    

NOTES
     Source for Tcl is available on http:/opensolaris.org.






















Tcl                     Last change: 8.4                        3