cppdraft_translate/cppdraft/re/results.md

[re.results]

# 28 Text processing library [[text]](./#text)

## 28.6 Regular expressions library [[re]](re#results)

### 28.6.9 Class template match_results [re.results]

#### [28.6.9.1](#general) General [[re.results.general]](re.results.general)

[1](#general-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11116)

Class template match_results denotes a collection of character
sequences representing the result of a regular expression
match[.](#general-1.sentence-1)

Storage for the collection is allocated and freed as necessary
by the member functions of class template match_results[.](#general-1.sentence-2)

[2](#general-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11123)

The class template match_results meets the requirements of an
allocator-aware container ([[container.alloc.reqmts]](container.alloc.reqmts "23.2.2.5 Allocator-aware containers")) and of
a sequence container ([[container.requirements.general]](container.requirements.general "23.2.2 General containers"), [[sequence.reqmts]](sequence.reqmts "23.2.4 Sequence containers"))
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[.](#general-2.sentence-1)

[3](#general-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11137)

A default-constructed match_results object has no fully established result state[.](#general-3.sentence-1)

A
match result is [*ready*](futures.state#def:ready "32.10.5 Shared state [futures.state]") when, as a consequence of a completed regular expression match
modifying such an object, its result state becomes fully established[.](#general-3.sentence-2)

The effects of calling
most member functions from a match_results object that is not ready are undefined[.](#general-3.sentence-3)

[4](#general-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11143)

The sub_match object stored at index 0 represents sub-expression 0,
i.e., the whole match[.](#general-4.sentence-1)

In this case the sub_match membermatched is always true[.](#general-4.sentence-2)

The sub_match object stored at index n denotes what matched the marked
sub-expression n within the matched expression[.](#general-4.sentence-3)

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[.](#general-4.sentence-4)

Otherwise matched is false, and members first and second point to the end of the sequence
that was searched[.](#general-4.sentence-5)

[*Note [1](#general-note-1)*:

The sub_match objects representing
different sub-expressions that did not participate in a regular expression
match need not be distinct[.](#general-4.sentence-6)

— *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]](#const "28.6.9.2 Constructors"), 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 "28.6.9.3 State"), statebool ready() const; // [[re.results.size]](#size "28.6.9.4 Size"), size size_type size() const;
 size_type max_size() const; bool empty() const; // [[re.results.acc]](#acc "28.6.9.5 Element access"), 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]](#form "28.6.9.6 Formatting"), formattemplate<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]](#all "28.6.9.7 Allocator"), allocator allocator_type get_allocator() const; // [[re.results.swap]](#swap "28.6.9.8 Swap"), swapvoid swap(match_results& that); };}

#### [28.6.9.2](#const) Constructors [[re.results.const]](re.results.const)

[1](#const-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11244)

Table [122](#tab:re.results.const "Table 122: match_­results copy/move operation postconditions") lists the postconditions ofmatch_results copy/move constructors and copy/move assignment operators[.](#const-1.sentence-1)

For move operations,
the results of the expressions depending on the parameter m denote
the values they had before the respective function calls[.](#const-1.sentence-2)

[🔗](#lib:match_results,constructor)

`explicit match_results(const Allocator& a);
`

[2](#const-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11257)

*Effects*: The stored Allocator value is constructed from a[.](#const-2.sentence-1)

[3](#const-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11261)

*Postconditions*: ready() returns false[.](#const-3.sentence-1)

size() returns 0[.](#const-3.sentence-2)

[🔗](#lib:match_results,constructor_)

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

[4](#const-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11274)

*Effects*: For the first form,
the stored Allocator value is obtained
as specified in [[container.reqmts]](container.reqmts "23.2.2.2 Container requirements")[.](#const-4.sentence-1)

For the second form,
the stored Allocator value is constructed from a[.](#const-4.sentence-2)

[5](#const-5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11282)

*Postconditions*: As specified in Table [122](#tab:re.results.const "Table 122: match_­results copy/move operation postconditions")[.](#const-5.sentence-1)

[🔗](#lib:match_results,constructor__)

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

[6](#const-6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11294)

*Effects*: For the first form,
the stored Allocator value is move constructed from m.get_allocator()[.](#const-6.sentence-1)

For the second form,
the stored Allocator value is constructed from a[.](#const-6.sentence-2)

[7](#const-7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11301)

*Postconditions*: As specified in Table [122](#tab:re.results.const "Table 122: match_­results copy/move operation postconditions")[.](#const-7.sentence-1)

[8](#const-8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11305)

*Throws*: The second form throws nothing ifa == m.get_allocator() is true[.](#const-8.sentence-1)

[🔗](#lib:match_results,operator=)

`match_results& operator=(const match_results& m);
`

[9](#const-9)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11317)

*Postconditions*: As specified in Table [122](#tab:re.results.const "Table 122: match_­results copy/move operation postconditions")[.](#const-9.sentence-1)

[🔗](#lib:match_results,operator=_)

`match_results& operator=(match_results&& m);
`

[10](#const-10)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11328)

*Postconditions*: As specified in Table [122](#tab:re.results.const "Table 122: match_­results copy/move operation postconditions")[.](#const-10.sentence-1)

Table [122](#tab:re.results.const) — match_results copy/move operation postconditions [[tab:re.results.const]](./tab:re.results.const)  

| [🔗](#tab:re.results.const-row-1)<br>**Element** | **Value** |
| --- | --- |
| [🔗](#tab:re.results.const-row-2)<br>ready() | m.ready() |
| [🔗](#tab:re.results.const-row-3)<br>size() | m.size() |
| [🔗](#tab:re.results.const-row-4)<br>str(n) | m.str(n) for all non-negative integers n < m.size() |
| [🔗](#tab:re.results.const-row-5)<br>prefix() | m.prefix() |
| [🔗](#tab:re.results.const-row-6)<br>suffix() | m.suffix() |
| [🔗](#tab:re.results.const-row-7)<br>(*this)[n] | m[n] for all non-negative integers n < m.size() |
| [🔗](#tab:re.results.const-row-8)<br>length(n) | m.length(n) for all non-negative integers n < m.size() |
| [🔗](#tab:re.results.const-row-9)<br>position(n) | m.position(n) for all non-negative integers n < m.size() |

#### [28.6.9.3](#state) State [[re.results.state]](re.results.state)

[🔗](#lib:match_results,ready)

`bool ready() const;
`

[1](#state-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11354)

*Returns*: true if *this has a fully established result state, otherwisefalse[.](#state-1.sentence-1)

#### [28.6.9.4](#size) Size [[re.results.size]](re.results.size)

[🔗](#lib:match_results,size)

`size_type size() const;
`

[1](#size-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11368)

*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[.](#size-1.sentence-1)

Otherwise returns 0[.](#size-1.sentence-2)

[*Note [1](#size-note-1)*:

The state of a match_results object can be modified
only by passing that object to regex_match or regex_search[.](#size-1.sentence-3)

Subclauses [[re.alg.match]](re.alg.match "28.6.10.2 regex_­match") and [[re.alg.search]](re.alg.search "28.6.10.3 regex_­search") specify the
effects of those algorithms on their match_results arguments[.](#size-1.sentence-4)

— *end note*]

[🔗](#lib:match_results,max_size)

`size_type max_size() const;
`

[2](#size-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11387)

*Returns*: The maximum number of sub_match elements that can be
stored in *this[.](#size-2.sentence-1)

[🔗](#lib:match_results,empty)

`bool empty() const;
`

[3](#size-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11399)

*Returns*: size() == 0[.](#size-3.sentence-1)

#### [28.6.9.5](#acc) Element access [[re.results.acc]](re.results.acc)

[🔗](#lib:length,match_results)

`difference_type length(size_type sub = 0) const;
`

[1](#acc-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11412)

*Preconditions*: ready() == true[.](#acc-1.sentence-1)

[2](#acc-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11416)

*Returns*: (*this)[sub].length()[.](#acc-2.sentence-1)

[🔗](#lib:position,match_results)

`difference_type position(size_type sub = 0) const;
`

[3](#acc-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11427)

*Preconditions*: ready() == true[.](#acc-3.sentence-1)

[4](#acc-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11431)

*Returns*: The distance from the start of the target sequence
to (*this)[sub].first[.](#acc-4.sentence-1)

[🔗](#lib:match_results,str)

`string_type str(size_type sub = 0) const;
`

[5](#acc-5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11443)

*Preconditions*: ready() == true[.](#acc-5.sentence-1)

[6](#acc-6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11447)

*Returns*: string_type((*this)[sub])[.](#acc-6.sentence-1)

[🔗](#lib:match_results,operator%5b%5d)

`const_reference operator[](size_type n) const;
`

[7](#acc-7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11458)

*Preconditions*: ready() == true[.](#acc-7.sentence-1)

[8](#acc-8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11462)

*Returns*: A reference to the sub_match object representing the
character sequence that matched marked sub-expression n[.](#acc-8.sentence-1)

If n == 0 then returns a reference to a sub_match object representing the
character sequence that matched the whole regular expression[.](#acc-8.sentence-2)

Ifn >= size() then returns a sub_match object representing an
unmatched sub-expression[.](#acc-8.sentence-3)

[🔗](#lib:match_results,prefix)

`const_reference prefix() const;
`

[9](#acc-9)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11478)

*Preconditions*: ready() == true[.](#acc-9.sentence-1)

[10](#acc-10)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11482)

*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[.](#acc-10.sentence-1)

[🔗](#lib:match_results,suffix)

`const_reference suffix() const;
`

[11](#acc-11)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11495)

*Preconditions*: ready() == true[.](#acc-11.sentence-1)

[12](#acc-12)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11499)

*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[.](#acc-12.sentence-1)

[🔗](#lib:match_results,begin)

`const_iterator begin() const;
const_iterator cbegin() const;
`

[13](#acc-13)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11513)

*Returns*: A starting iterator that enumerates over all the
sub-expressions stored in *this[.](#acc-13.sentence-1)

[🔗](#lib:match_results,end)

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

[14](#acc-14)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11526)

*Returns*: A terminating iterator that enumerates over all the
sub-expressions stored in *this[.](#acc-14.sentence-1)

#### [28.6.9.6](#form) Formatting [[re.results.form]](re.results.form)

[🔗](#lib:match_results,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;
`

[1](#form-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11544)

*Preconditions*: ready() == true and OutputIter meets the requirements for a*Cpp17OutputIterator* ([[output.iterators]](output.iterators "24.3.5.4 Output iterators"))[.](#form-1.sentence-1)

[2](#form-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11549)

*Effects*: Copies the character sequence [fmt_first, fmt_last) to
OutputIter out[.](#form-2.sentence-1)

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[.](#form-2.sentence-2)

The bitmasks specified in flags determine which format
specifiers and escape sequences are recognized[.](#form-2.sentence-3)

[3](#form-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11558)

*Returns*: out[.](#form-3.sentence-1)

[🔗](#lib:match_results,format_)

`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;
`

[4](#form-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11573)

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

[🔗](#lib:match_results,format__)

`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;
`

[5](#form-5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11590)

*Preconditions*: ready() == true[.](#form-5.sentence-1)

[6](#form-6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11594)

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

[7](#form-7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11602)

*Returns*: result[.](#form-7.sentence-1)

[🔗](#lib:match_results,format___)

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

[8](#form-8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11615)

*Preconditions*: ready() == true[.](#form-8.sentence-1)

[9](#form-9)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11619)

*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);

[10](#form-10)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11627)

*Returns*: result[.](#form-10.sentence-1)

#### [28.6.9.7](#all) Allocator [[re.results.all]](re.results.all)

[🔗](#lib:get_allocator,match_results)

`allocator_type get_allocator() const;
`

[1](#all-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11640)

*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[.](#all-1.sentence-1)

#### [28.6.9.8](#swap) Swap [[re.results.swap]](re.results.swap)

[🔗](#lib:match_results,swap)

`void swap(match_results& that);
`

[1](#swap-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11654)

*Effects*: Swaps the contents of the two sequences[.](#swap-1.sentence-1)

[2](#swap-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11658)

*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[.](#swap-2.sentence-1)

[3](#swap-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11664)

*Complexity*: Constant time[.](#swap-3.sentence-1)

[🔗](#lib:match_results,swap_)

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

[4](#swap-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11676)

*Effects*: As if by m1.swap(m2)[.](#swap-4.sentence-1)

#### [28.6.9.9](#nonmember) Non-member functions [[re.results.nonmember]](re.results.nonmember)

[🔗](#lib:operator==,match_results)

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

[1](#nonmember-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L11690)

*Returns*: true if neither match result is ready, false if one match result is ready and the
other is not[.](#nonmember-1.sentence-1)

If both match results are ready, returns true only if

- [(1.1)](#nonmember-1.1)

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

- [(1.2)](#nonmember-1.2)

!m1.empty() && !m2.empty(), and the following conditions are satisfied:
  * [(1.2.1)](#nonmember-1.2.1)

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

  * [(1.2.2)](#nonmember-1.2.2)

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

  * [(1.2.3)](#nonmember-1.2.3)

m1.suffix() == m2.suffix()[.](#nonmember-1.sentence-2)

[*Note [1](#nonmember-note-1)*:

The algorithm equal is defined in [[algorithms]](algorithms "26 Algorithms library")[.](#nonmember-1.sentence-3)

— *end note*]