...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
boost::xpressive::match_results — Class template match_results<> holds the results of a regex_match() or a regex_search() as a collection of sub_match objects.
// In header: <boost/xpressive/match_results.hpp> template<typename BidiIter> struct match_results { // types typedef iterator_value< BidiIter >::type char_type; typedef unspecified string_type; typedef std::size_t size_type; typedef sub_match< BidiIter > value_type; typedef iterator_difference< BidiIter >::type difference_type; typedef value_type const & reference; typedef value_type const & const_reference; typedef unspecified iterator; typedef unspecified const_iterator; typedef unspecified nested_results_type; // construct/copy/destruct match_results(); match_results(match_results< BidiIter > const &); match_results& operator=(match_results< BidiIter > const &); ~match_results(); // public member functions size_type size() const; bool empty() const; difference_type length(size_type = 0) const; difference_type position(size_type = 0) const; string_type str(size_type = 0) const; template<typename Sub> const_reference operator[](Sub const &) const; const_reference prefix() const; const_reference suffix() const; const_iterator begin() const; const_iterator end() const; operator bool_type() const; bool operator!() const; regex_id_type regex_id() const; nested_results_type const & nested_results() const; template<typename Format, typename OutputIterator> OutputIterator format(OutputIterator, Format const &, regex_constants::match_flag_type = regex_constants::format_default, unspecified = 0) const; template<typename OutputIterator> OutputIterator format(OutputIterator, char_type const *, regex_constants::match_flag_type = regex_constants::format_default) const; template<typename Format, typename OutputIterator> string_type format(Format const &, regex_constants::match_flag_type = regex_constants::format_default, unspecified = 0) const; string_type format(char_type const *, regex_constants::match_flag_type = regex_constants::format_default) const; void swap(match_results< BidiIter > &); template<typename Arg> match_results< BidiIter > & let(Arg const &); };
Class template match_results<> denotes a collection of sequences representing the result of a regular expression match. Storage for the collection is allocated and freed as necessary by the member functions of class match_results<>.
The class template 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.
match_results
public
construct/copy/destructmatch_results();
Postconditions: |
regex_id() == 0 size() == 0 empty() == true str() == string_type() |
match_results(match_results< BidiIter > const & that);
Parameters: |
|
||
Postconditions: |
regex_id() == that.regex_id(). size() == that.size(). empty() == that.empty(). str(n) == that.str(n) for all positive integers n < that.size(). prefix() == that.prefix(). suffix() == that.suffix(). (*this)[n] == that[n] for all positive integers n < that.size(). length(n) == that.length(n) for all positive integers n < that.size(). position(n) == that.position(n) for all positive integers n < that.size(). |
match_results& operator=(match_results< BidiIter > const & that);
Parameters: |
|
||
Postconditions: |
regex_id() == that.regex_id(). size() == that.size(). empty() == that.empty(). str(n) == that.str(n) for all positive integers n < that.size(). prefix() == that.prefix(). suffix() == that.suffix(). (*this)[n] == that[n] for all positive integers n < that.size(). length(n) == that.length(n) for all positive integers n < that.size(). position(n) == that.position(n) for all positive integers n < that.size(). |
~match_results();
match_results
public member functionssize_type size() const;
Returns one plus the number of marked sub-expressions in the regular expression that was matched if *this represents the result of a successful match. Otherwise returns 0.
bool empty() const;
Returns size() == 0.
difference_type length(size_type sub = 0) const;
Returns (*this)[sub].length().
difference_type position(size_type sub = 0) const;
If !(*this)[sub].matched then returns -1. Otherwise returns std::distance(base, (*this)[sub].first), where base is the start iterator of the sequence that was searched. [Note - unless this is part of a repeated search with a regex_iterator
then base is the same as prefix().first - end note]
string_type str(size_type sub = 0) const;
Returns (*this)[sub].str().
template<typename Sub> const_reference operator[](Sub const & sub) const;
Returns a reference to the sub_match
object representing the sequence that matched marked sub-expression sub. If sub == 0 then returns a reference to a sub_match
object representing the sequence that matched the whole regular expression. If sub >= size() then returns a sub_match
object representing an unmatched sub-expression.
const_reference prefix() const;
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.
Requires: |
(*this)[0].matched is true |
const_reference suffix() const;
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.
Requires: |
(*this)[0].matched is true |
const_iterator begin() const;
Returns a starting iterator that enumerates over all the marked sub-expression matches stored in *this.
const_iterator end() const;
Returns a terminating iterator that enumerates over all the marked sub-expression matches stored in *this.
operator bool_type() const;
Returns a true value if (*this)[0].matched, else returns a false value.
bool operator!() const;
Returns true if empty() || !(*this)[0].matched, else returns false.
regex_id_type regex_id() const;
Returns the id of the basic_regex
object most recently used with this match_results
object.
nested_results_type const & nested_results() const;
Returns a Sequence of nested match_results
elements.
template<typename Format, typename OutputIterator> OutputIterator format(OutputIterator out, Format const & fmt, regex_constants::match_flag_type flags = regex_constants::format_default, unspecified = 0) const;
If Format
models ForwardRange
or is a null-terminated string, this function copies the character sequence in fmt
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 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.
Otherwise, if Format
models Callable<
, this function returns match_results
<BidiIter>, OutputIterator, regex_constants::match_flag_type>fmt(*this, out, flags)
.
Otherwise, if Format
models Callable<
, this function returns match_results
<BidiIter>, OutputIterator>fmt(*this, out)
.
Otherwise, if Format
models Callable<
, this function returns match_results
<BidiIter> >std::copy(x.begin(), x.end(), out)
, where x
is the result of calling fmt(*this)
.
template<typename OutputIterator> OutputIterator format(OutputIterator out, char_type const * fmt, regex_constants::match_flag_type flags = regex_constants::format_default) const;
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
template<typename Format, typename OutputIterator> string_type format(Format const & fmt, regex_constants::match_flag_type flags = regex_constants::format_default, unspecified = 0) const;
If Format
models ForwardRange
or is a null-terminated string, this function returns a copy of the character sequence fmt
. For each format specifier or escape sequence in fmt
, replace that sequence with either the character(s) it represents, or the sequence 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.
Otherwise, if Format
models Callable<
, this function returns a match_results
<BidiIter>, OutputIterator, regex_constants::match_flag_type>string_type
object x
populated by calling fmt(*this, out, flags)
, where out
is a back_insert_iterator
into x
.
Otherwise, if Format
models Callable<
, this function returns a match_results
<BidiIter>, OutputIterator>string_type
object x
populated by calling fmt(*this, out)
, where out
is a back_insert_iterator
into x
.
Otherwise, if Format
models Callable<
, this function returns match_results
<BidiIter> >fmt(*this)
.
string_type format(char_type const * fmt, regex_constants::match_flag_type flags = regex_constants::format_default) const;
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
void swap(match_results< BidiIter > & that);
Swaps the contents of two match_results
objects. Guaranteed not to throw.
Parameters: |
|
||
Postconditions: |
*this contains the sequence of matched sub-expressions that were in that, that contains the sequence of matched sub-expressions that were in *this. |
||
Throws: |
Will not throw. |
template<typename Arg> match_results< BidiIter > & let(Arg const & arg);
TODO document me