Info Catalog cl: Sequence Functions cl: Sequences cl: Sorting Sequences

cl: Searching Sequences

 
 9.4 Searching Sequences
 =======================
 
 These functions search for elements or subsequences in a sequence.  (See
 also ‘cl-member’ and ‘cl-assoc’; Lists.)
 
  -- Function: cl-find item seq &key :test :test-not :key :start :end
           :from-end
      This function searches SEQ for an element matching ITEM.  If it
      finds a match, it returns the matching element.  Otherwise, it
      returns ‘nil’.  It returns the leftmost match, unless ‘:from-end’
      is true, in which case it returns the rightmost match.  The
      ‘:start’ and ‘:end’ arguments may be used to limit the range of
      elements that are searched.
 
  -- Function: cl-position item seq &key :test :test-not :key :start :end
           :from-end
      This function is like ‘cl-find’, except that it returns the integer
      position in the sequence of the matching item rather than the item
      itself.  The position is relative to the start of the sequence as a
      whole, even if ‘:start’ is non-zero.  The function returns ‘nil’ if
      no matching element was found.
 
  -- Function: cl-count item seq &key :test :test-not :key :start :end
      This function returns the number of elements of SEQ which match
      ITEM.  The result is always a nonnegative integer.
 
    The ‘cl-find-if’, ‘cl-find-if-not’, ‘cl-position-if’,
 ‘cl-position-if-not’, ‘cl-count-if’, and ‘cl-count-if-not’ functions are
 defined similarly.
 
  -- Function: cl-mismatch seq1 seq2 &key :test :test-not :key :start1
           :end1 :start2 :end2 :from-end
      This function compares the specified parts of SEQ1 and SEQ2.  If
      they are the same length and the corresponding elements match
      (according to ‘:test’, ‘:test-not’, and ‘:key’), the function
      returns ‘nil’.  If there is a mismatch, the function returns the
      index (relative to SEQ1) of the first mismatching element.  This
      will be the leftmost pair of elements that do not match, or the
      position at which the shorter of the two otherwise-matching
      sequences runs out.
 
      If ‘:from-end’ is true, then the elements are compared from right
      to left starting at ‘(1- END1)’ and ‘(1- END2)’.  If the sequences
      differ, then one plus the index of the rightmost difference
      (relative to SEQ1) is returned.
 
      An interesting example is ‘(cl-mismatch str1 str2 :key 'upcase)’,
      which compares two strings case-insensitively.
 
  -- Function: cl-search seq1 seq2 &key :test :test-not :key :from-end
           :start1 :end1 :start2 :end2
      This function searches SEQ2 for a subsequence that matches SEQ1 (or
      part of it specified by ‘:start1’ and ‘:end1’).  Only matches that
      fall entirely within the region defined by ‘:start2’ and ‘:end2’
      will be considered.  The return value is the index of the leftmost
      element of the leftmost match, relative to the start of SEQ2, or
      ‘nil’ if no matches were found.  If ‘:from-end’ is true, the
      function finds the _rightmost_ matching subsequence.
 

Info Catalog cl: Sequence Functions cl: Sequences cl: Sorting Sequences