| Home | Libraries | People | FAQ | More

## Struct template match_results

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.

## Synopsis

    // 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< BidiIter > & 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 &);
    };

## Description

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/destruct

1.     match_results();

   Postconditions: | regex_id() == 0
   Postconditions: | size() == 0
   Postconditions: | empty() == true
   Postconditions: | str() == string_type()

2.     match_results(match_results< BidiIter > const & that);

   Parameters:

   `that` | The `match_results` object to copy

   Postconditions: | regex_id() == that.regex_id().
   Postconditions: | size() == that.size().
   Postconditions: | empty() == that.empty().
   Postconditions: | str(n) == that.str(n) for all positive integers n < that.size().
   Postconditions: | prefix() == that.prefix().
   Postconditions: | suffix() == that.suffix().
   Postconditions: | (*this)[n] == that[n] for all positive integers n < that.size().
   Postconditions: | length(n) == that.length(n) for all positive integers n < that.size().
   Postconditions: | position(n) == that.position(n) for all positive integers n < that.size().

3.     match_results< BidiIter > & operator=(match_results< BidiIter > const & that);

   Parameters:

   `that` | The `match_results` object to copy.

   Postconditions: | regex_id() == that.regex_id().
   Postconditions: | size() == that.size().
   Postconditions: | empty() == that.empty().
   Postconditions: | str(n) == that.str(n) for all positive integers n < that.size().
   Postconditions: | prefix() == that.prefix().
   Postconditions: | suffix() == that.suffix().
   Postconditions: | (*this)[n] == that[n] for all positive integers n < that.size().
   Postconditions: | length(n) == that.length(n) for all positive integers n < that.size().
   Postconditions: | position(n) == that.position(n) for all positive integers n < that.size().

4.     ~match_results();

### `match_results` public member functions

1.     size_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.

2.     bool empty() const;

   Returns size() == 0.

3.     difference_type length(size_type sub = 0) const;

   Returns (*this)[sub].length().

4.     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]

5.     string_type str(size_type sub = 0) const;

   Returns (*this)[sub].str().

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

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

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

9.     const_iterator begin() const;

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

10.     const_iterator end() const;

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

11.     operator bool_type() const;

    Returns a true value if (*this)[0].matched, else returns a false value.

12.     bool operator!() const;

    Returns true if empty() || !(*this)[0].matched, else returns false.

13.     regex_id_type regex_id() const;

    Returns the id of the `basic_regex` object most recently used with this `match_results` object.

14.     nested_results_type const & nested_results() const;

    Returns a Sequence of nested `match_results` elements.

15.     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<`match_results`<BidiIter>, OutputIterator, regex_constants::match_flag_type>`, this function returns `fmt(*this, out, flags)`.

    Otherwise, if `Format` models `Callable<`match_results`<BidiIter>, OutputIterator>`, this function returns `fmt(*this, out)`.

    Otherwise, if `Format` models `Callable<`match_results`<BidiIter> >`, this function returns `std::copy(x.begin(), x.end(), out)`, where `x` is the result of calling `fmt(*this)`.

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

17.     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<`match_results`<BidiIter>, OutputIterator, regex_constants::match_flag_type>`, this function returns a `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<`match_results`<BidiIter>, OutputIterator>`, this function returns a `string_type` object `x` populated by calling `fmt(*this, out)`, where `out` is a `back_insert_iterator` into `x`.

    Otherwise, if `Format` models `Callable<`match_results`<BidiIter> >`, this function returns `fmt(*this)`.

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

19.     void swap(match_results< BidiIter > & that);

    Swaps the contents of two `match_results` objects. Guaranteed not to throw.

    Parameters:

    `that` | The `match_results` object to swap with.

    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.

20.     template<typename Arg> match_results< BidiIter > & let(Arg const & arg);

    TODO document me