32 Regular expressions library [re]

32.9 Class template match_results [re.results]

32.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; [[nodiscard]] 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); }; }

32.9.2 Constructors [re.results.const]

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

🔗

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

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

🔗

match_results& operator=(match_results&& m);

Postconditions: As specified in Table 141 .

Table 141: 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()

32.9.3 State [re.results.state]

🔗

bool ready() const;

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

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

🔗

[[nodiscard]] bool empty() const;

Returns: size() == 0.

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

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

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

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

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