28 Regular expressions library [re]

28.10 Class template match_results [re.results]

Class template match_results denotes a collection of character 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 template match_results.

The class template match_results shall satisfy the requirements of an allocator-aware container and of a sequence container, as specified in [sequence.reqmts], except that only operations defined for const-qualified sequence containers are supported.

A default-constructed match_results object has no fully established result state. A match result is ready when, as a consequence of a completed regular expression match modifying such an object, its result state becomes fully established. The effects of calling most member functions from a match_results object that is not ready are undefined.

The sub_match object stored at index 0 represents sub-expression 0, i.e., the whole match. In this case the sub_match member matched is always true. The sub_match object stored at index n denotes what matched the marked sub-expression n within the matched expression. If the sub-expression n participated in a regular expression match then the sub_match member matched evaluates to true, and members first and second denote the range of characters [first,second) which formed that match. Otherwise matched is false, and members first and second point to the end of the sequence that was searched. [ Note: The sub_match objects representing different sub-expressions that did not participate in a regular expression match need not be distinct. — end note ]

namespace std {
  template <class BidirectionalIterator,
            class Allocator = 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_traits<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;

     // [re.results.const], construct/copy/destroy:
     explicit match_results(const Allocator& a = Allocator());
     match_results(const match_results& m);
     match_results(match_results&& m) noexcept;
     match_results& operator=(const match_results& m); 
     match_results& operator=(match_results&& m);
     ~match_results();

     // [re.results.state], state:
     bool ready() const;

     // [re.results.size], size:
     size_type size() const;
     size_type max_size() const;
     bool empty() const;

     // [re.results.acc], element access:
     difference_type length(size_type sub = 0) const;
     difference_type position(size_type sub = 0) const;
     string_type str(size_type sub = 0) const;
     const_reference operator[](size_type n) const;

     const_reference prefix() const;
     const_reference suffix() const;
     const_iterator begin() const;
     const_iterator end() const;
     const_iterator cbegin() const;
     const_iterator cend() const;

     // [re.results.form], format:
     template <class OutputIter>
      OutputIter
      format(OutputIter out,
             const char_type* fmt_first, const char_type* fmt_last,
             regex_constants::match_flag_type flags =
              regex_constants::format_default) const;
     template <class OutputIter, class ST, class SA>
       OutputIter
       format(OutputIter out,
              const basic_string<char_type, ST, SA>& fmt,
              regex_constants::match_flag_type flags =
                regex_constants::format_default) const;
     template <class ST, class SA>
      basic_string<char_type, ST, SA>
      format(const basic_string<char_type, ST, SA>& fmt,
             regex_constants::match_flag_type flags =
               regex_constants::format_default) const;
     string_type
     format(const char_type* fmt,
            regex_constants::match_flag_type flags =
              regex_constants::format_default) const;

     // [re.results.all], allocator:
     allocator_type get_allocator() const;

     // [re.results.swap], swap:
     void swap(match_results& that);
  }; 
}

28.10.1 match_results constructors [re.results.const]

In all match_results constructors, a copy of the Allocator argument shall be 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.

Postconditions: ready() returns false. size() returns 0.

match_results(const match_results& m);

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

match_results(match_results&& m) noexcept;

Effects: Move-constructs an object of class match_results from m satisfying the same postconditions as Table [tab:re:results:assign]. Additionally, the stored Allocator value is move constructed from m.get_allocator().

Throws: Nothing if the allocator's move constructor throws nothing.

match_results& operator=(const match_results& m);

Effects: Assigns m to *this. The postconditions of this function are indicated in Table [tab:re:results:assign].

match_results& operator=(match_results&& m);

Effects: Move-assigns m to *this. The postconditions of this function are indicated in Table [tab:re:results:assign].

Table 141match_results assignment operator effects
ElementValue
ready() m.ready()
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()

28.10.2 match_results state [re.results.state]

bool ready() const;

Returns: true if *this has a fully established result state, otherwise false.

28.10.3 match_results size [re.results.size]

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. [ Note: The state of a match_results object can be modified only by passing that object to regex_match or regex_search. Sections [re.alg.match] and [re.alg.search] specify the effects of those algorithms on their match_results arguments.  — end note ]

size_type max_size() const;

Returns: The maximum number of sub_match elements that can be stored in *this.

bool empty() const;

Returns: size() == 0.

28.10.4 match_results element access [re.results.acc]

difference_type length(size_type sub = 0) const;

Requires: ready() == true.

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

difference_type position(size_type sub = 0) const;

Requires: ready() == true.

Returns: The distance from the start of the target sequence to (*this)[sub].first.

string_type str(size_type sub = 0) const;

Requires: ready() == true.

Returns: string_type((*this)[sub]).

const_reference operator[](size_type n) const;

Requires: ready() == true.

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 >= size() then returns a sub_match object representing an unmatched sub-expression.

const_reference prefix() const;

Requires: ready() == true.

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;

Requires: ready() == true.

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; const_iterator cbegin() const;

Returns: A starting iterator that enumerates over all the sub-expressions stored in *this.

const_iterator end() const; const_iterator cend() const;

Returns: A terminating iterator that enumerates over all the sub-expressions stored in *this.

28.10.5 match_results formatting [re.results.form]

template <class OutputIter> OutputIter format(OutputIter out, const char_type* fmt_first, const char_type* fmt_last, regex_constants::match_flag_type flags = regex_constants::format_default) const;

Requires: ready() == true and OutputIter shall satisfy the requirements for an Output Iterator ([output.iterators]).

Effects: Copies the character sequence [fmt_first,fmt_last) to OutputIter out. Replaces each format specifier or escape sequence in the copied range with either the character(s) it represents or the sequence of characters within *this to which it refers. The bitmasks specified in flags determine which format specifiers and escape sequences are recognized.

Returns: out.

template <class OutputIter, class ST, class SA> OutputIter format(OutputIter out, const basic_string<char_type, ST, SA>& fmt, regex_constants::match_flag_type flags = regex_constants::format_default) const;

Effects: Equivalent to return format(out, fmt.data(), fmt.data() + fmt.size(), flags).

template <class ST, class SA> basic_string<char_type, ST, SA> format(const basic_string<char_type, ST, SA>& fmt, regex_constants::match_flag_type flags = regex_constants::format_default) const;

Requires: ready() == true.

Effects: Constructs an empty string result of type basic_string<char_type, ST, SA> and calls format(back_inserter(result), fmt, flags).

Returns: result.

string_type format(const char_type* fmt, regex_constants::match_flag_type flags = regex_constants::format_default) const;

Requires: ready() == true.

Effects: Constructs an empty string result of type string_type and calls format(back_inserter(result), fmt, fmt + char_traits<char_type>::length(fmt), flags).

Returns: result.

28.10.6 match_results allocator [re.results.all]

allocator_type get_allocator() const;

Returns: A copy of the Allocator that was passed to the object's constructor or, if that allocator has been replaced, a copy of the most recent replacement.

28.10.7 match_results swap [re.results.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.

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

Effects: m1.swap(m2).

28.10.8 match_results non-member functions [re.results.nonmember]

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

Returns: true if neither match result is ready, false if one match result is ready and the other is not. If both match results are ready, returns true only if:

  • m1.empty() && m2.empty(), or

  • !m1.empty() && !m2.empty(), and the following conditions are satisfied:

    • m1.prefix() == m2.prefix(),

    • m1.size() == m2.size() && equal(m1.begin(), m1.end(), m2.begin()), and

    • m1.suffix() == m2.suffix().

Note: The algorithm equal is defined in Clause [algorithms].  — end note ]

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

Returns: !(m1 == m2).