28 Text processing library [text]

28.6 Regular expressions library [re]

28.6.9 Class template match_results [re.results]

28.6.9.1 General [re.results.general]

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 meets the requirements of an allocator-aware container ([container.alloc.reqmts]) and of a sequence container ([container.requirements.general], [sequence.reqmts]) except that only copy assignment, move assignment, and operations defined for const-qualified sequence containers are supported and that the semantics of the comparison operator functions are different from those required for a container.

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

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: using value_type = sub_match<BidirectionalIterator>; using const_reference = const value_type&; using reference = value_type&; using const_iterator = implementation-defined; using iterator = const_iterator; using difference_type = typename iterator_traits<BidirectionalIterator>::difference_type; using size_type = typename allocator_traits<Allocator>::size_type; using allocator_type = Allocator; using char_type = typename iterator_traits<BidirectionalIterator>::value_type; using string_type = basic_string<char_type>; // [re.results.const], construct/copy/destroy match_results() : match_results(Allocator()) {} explicit match_results(const Allocator& a); match_results(const match_results& m); match_results(const match_results& m, const Allocator& a); match_results(match_results&& m) noexcept; match_results(match_results&& m, const Allocator& a); 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.6.9.2 Constructors [re.results.const]

Table 117 lists the postconditions of match_results copy/move constructors and copy/move assignment operators.

For move operations, the results of the expressions depending on the parameter m denote the values they had before the respective function calls.

🔗

explicit match_results(const Allocator& a);

Effects: The stored Allocator value is constructed from a.

Postconditions: ready() returns false.

size() returns 0.

🔗

match_results(const match_results& m);
match_results(const match_results& m, const Allocator& a);

Effects: For the first form, the stored Allocator value is obtained as specified in [container.reqmts].

For the second form, the stored Allocator value is constructed from a.

Postconditions: As specified in Table 117 .

🔗

match_results(match_results&& m) noexcept;
match_results(match_results&& m, const Allocator& a);

Effects: For the first form, the stored Allocator value is move constructed from m.get_allocator().

For the second form, the stored Allocator value is constructed from a.

Postconditions: As specified in Table 117 .

Throws: The second form throws nothing if a == m.get_allocator() is true.

🔗

match_results& operator=(const match_results& m);

Postconditions: As specified in Table 117 .

🔗

match_results& operator=(match_results&& m);

Postconditions: As specified in Table 117 .

Table 117: match_results copy/move operation postconditions [tab:re.results.const]

🔗	Element	Value
🔗	ready()	m.ready()
🔗	size()	m.size()
🔗	str(n)	m.str(n) for all non-negative integers n < m.size()
🔗	prefix()	m.prefix()
🔗	suffix()	m.suffix()
🔗	(*this)[n]	m[n] for all non-negative integers n < m.size()
🔗	length(n)	m.length(n) for all non-negative integers n < m.size()
🔗	position(n)	m.position(n) for all non-negative integers n < m.size()

28.6.9.3 State [re.results.state]

🔗

bool ready() const;

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

28.6.9.4 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 1:

The state of a match_results object can be modified only by passing that object to regex_match or regex_search.

Subclauses [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.6.9.5 Element access [re.results.acc]

🔗

difference_type length(size_type sub = 0) const;

Preconditions: ready() == true.

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

🔗

difference_type position(size_type sub = 0) const;

Preconditions: ready() == true.

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

🔗

string_type str(size_type sub = 0) const;

Preconditions: ready() == true.

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

🔗

const_reference operator[](size_type n) const;

Preconditions: 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;

Preconditions: 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;

Preconditions: 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.6.9.6 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;

Preconditions: ready() == true and OutputIter meets the requirements for a Cpp17OutputIterator ([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;

Preconditions: 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;

Preconditions: 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.6.9.7 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.6.9.8 Swap [re.results.swap]

🔗

void swap(match_results& that);

Effects: Swaps the contents of the two sequences.

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.

Complexity: Constant time.

🔗

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

Effects: As if by m1.swap(m2).

28.6.9.9 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

(1.1)
m1.empty() && m2.empty(), or
(1.2)
!m1.empty() && !m2.empty(), and the following conditions are satisfied:
- (1.2.1)
  m1.prefix() == m2.prefix(),
- (1.2.2)
  m1.size() == m2.size() && equal(m1.begin(), m1.end(), m2.begin()), and
- (1.2.3)
  m1.suffix() == m2.suffix().

[Note 1:

The algorithm equal is defined in [algorithms].

— end note]