Boost.Regex

Algorithm regex_search

Contents

Synopsis

The algorithm regex_search will search a range denoted by a pair of
bidirectional-iterators for a given regular expression. The algorithm uses
various heuristics to reduce the search time by only checking for a match if a
match could conceivably start at that position. The algorithm is defined as
follows:

Effects: Determines whether there is some sub-sequence within
[first,last) that matches the regular expression e, parameter flags
is used to control how the expression is matched against the character
sequence. Returns true if such a sequence exists, false otherwise.

Throws:std::runtime_error if the complexity of
matching the expression against an N character string begins to exceed O(N2),
or if the program runs out of stack space while matching the expression (if
Boost.regex is configured in recursive mode),
or if the matcher exhausts it's permitted memory allocation (if Boost.regex is
configured in non-recursive mode).

Postconditions: If the function returns false, then the effect on
parameter m is undefined, otherwise the effects on parameter m are
given in the table:

Element

Value

m.size()

e.mark_count()

m.empty()

false

m.prefix().first

first

m.prefix().last

m[0].first

m.prefix().matched

m.prefix().first != m.prefix().second

m.suffix().first

m[0].second

m.suffix().last

last

m.suffix().matched

m.suffix().first != m.suffix().second

m[0].first

The start of the sequence of characters that matched the regular expression

m[0].second

The end of the sequence of characters that matched the regular expression

m[0].matched

true if a full match was found, and false if it was
a partial match (found as a result of the match_partial flag being
set).

m[n].first

For all integers n < m.size(), the start of the sequence that matched
sub-expression n. Alternatively, if sub-expression n did not participate
in the match, then last.

m[n].second

For all integers n < m.size(), the end of the sequence that matched
sub-expression n. Alternatively, if sub-expression n did not participate
in the match, then last.

m[n].matched

For all integers n < m.size(), true if sub-expression n participated
in the match, false otherwise.

Effects: Returns the result of regex_search(s.begin(), s.end(), e,
flags).

Examples

The following example,
takes the contents of a file in the form of a string, and searches for all the
C++ class declarations in the file. The code will work regardless of the way
that std::string is implemented, for example it could easily be modified to
work with the SGI rope class, which uses a non-contiguous storage strategy.