Function

Summary

Matches a regular expression.

Package

lispworks

Signature

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

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

Arguments

pattern

A string or a precompiled regular expression object.

string

A string.

start, end

Bounding index designators of string.

from-end

A generalized boolean.

case-sensitive

A generalized boolean.

brackets-limits

A generalized boolean.

Values

pos

A non-negative integer or nil.

len

A non-negative integer or nil.

brackets-limits-vector

A vector.

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 regular expression object or a string. If pattern is a string then find-regexp-in-string first makes a precompiled regular expression 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 regular expression object, as pattern.

case-sensitive controls whether a string pattern is precompiled as a case sensitive or case insensitive search. A true value other than :default means a case sensitive search. The value nil means a case insensitive search. The default value of case-sensitive is :default which means that a string pattern is compiled with case sensitivity according to the value of the Editor variable DEFAULT-SEARCH-KIND.

When brackets-limits is non-nil, a successful call to find-regexp-in-string returns a third value 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. The default value of brackets-limits is nil.

The regular expression syntax used by find-regexp-in-string is similar to that used by Emacs, as described in the "Regular expression syntax" section of the LispWorks Editor User Guide . (If you use Help > Search to locate this section, select the Contents radio button.)

Example

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