| Home | Libraries | People | FAQ | More

### match_results

##### Synopsis

    #include <boost/regex.hpp>

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`:

    template <class BidirectionalIterator,
             class Allocator = std::allocator<sub_match<BidirectionalIterator> >
    class match_results;

    typedef match_results<const char*>              cmatch;
    typedef match_results<const wchar_t*>           wcmatch;
    typedef match_results<string::const_iterator>   smatch;
    typedef match_results<wstring::const_iterator>  wsmatch;

    template <class BidirectionalIterator,
             class Allocator = std::allocator<sub_match<BidirectionalIterator> >
    class match_results
    {
    public:
       typedef          sub_match<BidirectionalIterator>                        value_type;
       typedef          const value_type&                                       const_reference;
       typedef          const_reference                                         reference;
       typedef          implementation defined                                  const_iterator;
       typedef          const_iterator                                          iterator;
       typedef typename iterator_traits<BidirectionalIterator>::difference_type difference_type;
       typedef typename Allocator::size_type                                    size_type;
       typedef          Allocator                                               allocator_type;
       typedef typename iterator_traits<BidirectionalIterator>::value_type      char_type;
       typedef          basic_string<char_type>                                 string_type;

       // construct/copy/destroy:
       explicit match_results(const Allocator& a = Allocator());
       match_results(const match_results& m);
       match_results& operator=(const match_results& m);
       ~match_results();

       // size:
       size_type size() const;
       size_type max_size() const;
       bool empty() const;
       // element access:
       difference_type length(int sub = 0) const;
       difference_type position(unsigned int sub = 0) const;
       string_type str(int sub = 0) const;
       const_reference operator[](int n) const;

       const_reference prefix() const;

       const_reference suffix() const;
       const_iterator begin() const;
       const_iterator end() const;
       // format:
       template <class OutputIterator>
       OutputIterator format(OutputIterator out,
                            const string_type& fmt,
                            match_flag_type flags = format_default) const;
       string_type format(const string_type& fmt,
                         match_flag_type flags = format_default) const;

       allocator_type get_allocator() const;
       void swap(match_results& that);

    #ifdef BOOST_REGEX_MATCH_EXTRA
       typedef typename value_type::capture_sequence_type capture_sequence_type;
       const capture_sequence_type& captures(std::size_t i)const;
    #endif

    };

    template <class BidirectionalIterator, class Allocator>
    bool operator == (const match_results<BidirectionalIterator, Allocator>& m1,
                      const match_results<BidirectionalIterator, Allocator>& m2);
    template <class BidirectionalIterator, class Allocator>
    bool operator != (const match_results<BidirectionalIterator, Allocator>& m1,
                      const match_results<BidirectionalIterator, Allocator>& m2);

    template <class charT, class traits, class BidirectionalIterator, class Allocator>
    basic_ostream<charT, traits>&
       operator << (basic_ostream<charT, traits>& os,
                   const match_results<BidirectionalIterator, Allocator>& m);

    template <class BidirectionalIterator, class Allocator>
    void swap(match_results<BidirectionalIterator, Allocator>& m1,
             match_results<BidirectionalIterator, Allocator>& m2);

##### Description

In all `match_results` constructors, a copy of the Allocator argument is used for any memory allocation performed by the constructor or member functions during the lifetime of the object.

    match_results(const Allocator& a = Allocator());

Effects: Constructs an object of class `match_results`. The postconditions of this function are indicated in the table:

Element | Value
--- | ---
empty() | true
size() | 0
str() | basic_string<charT>()

    match_results(const match_results& m);

Effects: Constructs an object of class match_results, as a copy of m.

    match_results& operator=(const match_results& m);

Effects: Assigns m to *this. The postconditions of this function are indicated in the table:

Element | Value
--- | ---
empty() | m.empty().
size() | m.size().
str(n) | m.str(n) for all integers n < m.size().
prefix() | m.prefix().
suffix() | m.suffix().
(*this)[n] | m[n] for all integers n < m.size().
length(n) | m.length(n) for all integers n < m.size().
position(n) | m.position(n) for all integers n < m.size().

    size_type size()const;

Effects: Returns the number of `sub_match` elements stored in *this; that is the number of marked sub-expressions in the regular expression that was matched plus one.

    size_type max_size()const;

Effects: Returns the maximum number of `sub_match` elements that can be stored in *this.

    bool empty()const;

Effects: Returns size() == 0.

    difference_type length(int sub = 0)const;

Effects: Returns the length of sub-expression sub, that is to say: `(*this)[sub].length()`.

    difference_type position(unsigned int sub = 0)const;

Effects: Returns the starting location of sub-expression sub, or -1 if sub was not matched. Note that if this represents a partial match , then `position()` will return the location of the partial match even though `(*this)[0].matched` is false.

    string_type str(int sub = 0)const;

Effects: Returns sub-expression sub as a string: `string_type((*this)[sub])`.

    const_reference operator[](int n) const;

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 or 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 or 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.

    template <class OutputIterator>
    OutputIterator format(OutputIterator out,
                         const string_type& fmt,
                         match_flag_type flags = format_default);

Requires: The type `OutputIterator` conforms to the Output Iterator requirements (C++ std 24.1.2).

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.

See the format syntax guide for more information.

Returns: out.

    string_type format(const string_type& fmt,
                      match_flag_type flags = format_default);

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.

See the format syntax guide for more information.

    allocator_type get_allocator()const;

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

    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.

    typedef typename value_type::capture_sequence_type capture_sequence_type;

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.

    const capture_sequence_type& captures(std::size_t i)const;

Effects: returns a sequence containing all the captures obtained for sub-expression i.

Returns: `(*this)[i].captures();`

Preconditions: the library must be built and used with BOOST_REGEX_MATCH_EXTRA defined, and you must pass the flag match_extra to the regex matching functions ( `regex_match`, `regex_search`, `regex_iterator` or `regex_token_iterator`) in order for this member function to be defined and return useful information.

Rationale: Enabling this feature has several consequences:

- sub_match occupies more memory resulting in complex expressions running out of memory or stack space more quickly during matching.
- The matching algorithms are less efficient at handling some features (independent sub-expressions for example), even when match_extra is not used.
- The matching algorithms are much less efficient (i.e. slower), when match_extra is used. Mostly this is down to the extra memory allocations that have to take place.

    template <class BidirectionalIterator, class Allocator>
    bool operator == (const match_results<BidirectionalIterator, Allocator>& m1,
                      const match_results<BidirectionalIterator, Allocator>& m2);

Effects: Compares the two sequences for equality.

    template <class BidirectionalIterator, class Allocator>
    bool operator != (const match_results<BidirectionalIterator, Allocator>& m1,
                      const match_results<BidirectionalIterator, Allocator>& m2);

Effects: Compares the two sequences for inequality.

    template <class charT, class traits, class BidirectionalIterator, class Allocator>
    basic_ostream<charT, traits>&
       operator << (basic_ostream<charT, traits>& os,
                   const match_results<BidirectionalIterator, Allocator>& m);

Effects: Writes the contents of m to the stream os as if by calling `os << m.str()`; Returns os.

    template <class BidirectionalIterator, class Allocator>
    void swap(match_results<BidirectionalIterator, Allocator>& m1,
             match_results<BidirectionalIterator, Allocator>& m2);

Effects: Swaps the contents of the two sequences.