find-regexp-in-string Function

Summary

Matches a regular expression against a string.

Package

lispworks

Signature

find-regexp-in-string pattern string &key start end from-end case-sensitive brackets-limits space-string => pos, len, brackets-limits-vector

Arguments

Values

Description

The function find-regexp-in-string searches the string string for a match for the regular expression pattern. The index in string of the start of the first match is returned in pos, and the length of the match is len.

If from-end is nil (the default value) then the search starts at index start and ends at index end. start defaults to 0 and end defaults to nil. If from-end is true, then the search direction is reversed.

pattern should be a precompiled-regexp or a string. If pattern is a string then find-regexp-in-string first makes a precompiled-regexp object. This operation allocates, therefore if you need to repeatedly call find-regexp-in-string with the same pattern, it is better to call precompile-regexp once and pass its result, a precompiled-regexp, as pattern.

case-sensitive controls whether a string pattern is precompiled as a case sensitive or case insensitive search. A non-nil value means a case sensitive search. The value nil (the default) means a case insensitive search. case-sensitive is ignored if pattern is not a string.

When brackets-limits is non-nil, a successful call to find-regexp-in-string returns a third value brackets-limits-vector which is a vector specifying the limits of matches of any pair of \( and \) in the search pattern. The length of the vector is twice the number of pairs, and the elements are offsets from the beginning of the match of the whole pattern. Each pair of \( and \) is assigned a number in the order of the appearance of the \( in the pattern. This number multiplied by two is the index into the vector where the match for this pair starts, and the next element specifies the end of the match. When brackets-limits is nil (the default), only two values are returned.

When space-string is non-nil and pattern is a string, then a "Lax whitespace" search is performed. That means that any sequence of space characters in pattern is effectively replaced by the regexp specified by space-string. If space-string is t, it specifies a regexp that matches "whitespace", specifically any non-empty sequence of the space, tab, return or newline characters.

The regular expression syntax used by find-regexp-in-string is similar to that used by Emacs, as described in 28.7 Regular expression syntax.

Examples

This form allocates several regular expression objects:

(loop with pos = 0 
      with len = 0 
      while pos 
      do (multiple-value-setq (pos len) 
             (find-regexp-in-string "[0,2,4,6,8]" "0123456789" 
                                    :start (+ pos len)))
      when pos 
      do (format t "~&Match at pos ~D len ~D~%" 
                 pos len))

This form does the same matching but allocates just one precompiled regular expression object:

(loop with pattern = (precompile-regexp "[0,2,4,6,8]")
      with pos = 0 
      with len = 0 
      while pos 
      do (multiple-value-setq (pos len)
             (find-regexp-in-string pattern "0123456789" 
                                    :start (+ pos len))) 
      when pos do (format t "~&Match at pos ~D len ~D~%" 
                          pos len))

See also

precompile-regexp
regexp-find-symbols
count-regexp-occurrences
precompiled-regexp