| 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

    template<typename BidiIter>
    struct match_results {
      // types
      typedef iterator_value< BidiIter >::type      char_type;
      typedef std::basic_string< char_type >        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;
      const_reference operator[](size_type) const;
      const_reference operator[](unspecified) 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 OutputIterator>
        OutputIterator
        format(OutputIterator, const string_type &,
               regex_constants::match_flag_type = regex_constants::format_default) const;
      string_type format(const string_type &,
                         regex_constants::match_flag_type = regex_constants::format_default) const;
      void swap(match_results< BidiIter > &) ;
    };

## 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` construct/copy/destruct

1.     match_results();

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

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

   Parameters: |
   `that` | The match_results object to copy
   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().

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

   Parameters: |
   `that` | The match_results object to copy.
   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().

4.     ~match_results();

### `match_results` public member functions

1.     size_type size() const;

   Returns the number of sub_match elements stored in *this.

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 string_type((*this)[sub]).

6.     const_reference operator[](size_type 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.

   Requires: | sub < (*this).size().

7.     const_reference operator[](unspecified mark) const;

   This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

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

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

10.     const_iterator begin() const;

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

11.     const_iterator end() const;

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

12.     operator bool_type() const;

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

13.     bool operator!() const;

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

14.     regex_id_type regex_id() const;

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

15.     nested_results_type const & nested_results() const;

    Returns a Sequence of nested match_results elements.

16.     template<typename OutputIterator>
          OutputIterator
          format(OutputIterator out, const string_type & fmt,
                 regex_constants::match_flag_type flags = regex_constants::format_default) const;

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

17.     string_type format(const string_type & fmt,
                           regex_constants::match_flag_type flags = regex_constants::format_default) const;

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

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

| Copyright © 2003, 2004 Eric Niebler