Boost.Regex

class match_results

Contents

Synopsis

Regular expressions are different from many simple pattern-matching algorithms
in that as well as finding an overall match they can also produce
sub-expression matches: each sub-expression being delimited in the pattern by a
pair of parenthesis (...). There has to be some method for reporting
sub-expression matches back to the user: this is achieved this by defining a
class match_results that acts as an indexed collection of sub-expression
matches, each sub-expression match being contained in an object of type
sub_match .

Template class match_results denotes a collection of character sequences
representing the result of a regular expression match. Objects of type
match_results are passed to the algorithms regex_match
and regex_search, and are returned by the
iterator regex_iterator . Storage for
the collection is allocated and freed as necessary by the member functions of
class match_results.

The template class match_results conforms to the requirements of a Sequence, as
specified in (lib.sequence.reqmts), except that only operations defined for
const-qualified Sequences are supported.

Class template match_results is most commonly used as one of the typedefs
cmatch, wcmatch, smatch, or wsmatch:

Effects: Returns a reference to the sub_match object
representing the character sequence that matched marked sub-expression n.
If n == 0 then returns a reference to a sub_match object
representing the character sequence that matched the whole regular
expression. If n is out of range, or if n is an
unmatched sub-expression, then returns a sub_match object whose matched
member is false.

const_reference prefix()const;

Effects: Returns a reference to the sub_match object
representing the character sequence from the start of the string being
matched/searched, to the start of the match found.

const_reference suffix()const;

Effects: Returns a reference to the sub_match object
representing the character sequence from the end of the match found to the end
of the string being matched/searched.

const_iterator begin()const;

Effects: Returns a starting iterator that enumerates over all the marked
sub-expression matches stored in *this.

const_iterator end()const;

Effects: Returns a terminating iterator that enumerates over all the
marked sub-expression matches stored in *this.

Effects: Copies the character sequence [fmt.begin(), fmt.end()) to
OutputIterator out. For each format specifier or escape sequence in fmt,
replace that sequence with either the character(s) it represents, or the
sequence of characters within *this to which it refers. The bitmasks specified
in flags determines what
format specifiers or escape sequences are recognized, by default this is
the format used by ECMA-262, ECMAScript Language Specification, Chapter 15 part
5.4.11 String.prototype.replace.

Effects: Returns a copy of the string fmt. For each format
specifier or escape sequence in fmt, replace that sequence with either
the character(s) it represents, or the sequence of characters within *this to
which it refers. The bitmasks specified in flags
determines what format specifiers or escape sequences
are recognized, by default this is the format used by ECMA-262,
ECMAScript Language Specification, Chapter 15 part 5.4.11
String.prototype.replace.

Allocator access

allocator_type get_allocator()const;

Effects: Returns a copy of the Allocator that was passed to the object's
constructor.

Swap

void swap(match_results& that);

Effects: Swaps the contents of the two sequences.

Postcondition:*this contains the sequence of matched
sub-expressions that were in that, that contains the
sequence of matched sub-expressions that were in *this.

Complexity: constant time.

Captures

Defines an implementation-specific type that satisfies the requirements of
a standard library Sequence (21.1.1 including the optional Table 68
operations), whose value_type is a sub_match<BidirectionalIterator>. This
type happens to be std::vector<sub_match<BidirectionalIterator> >,
but you shouldn't actually rely on that.