depish/cppdraft_translate
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Init

Browse Source
This commit is contained in:
Leonov Artur (Depish)
2025-10-25 03:02:53 +03:00
commit 043225d523
3416 changed files with 681196 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

629
cppdraft/re/results.md Normal file
View File

@@ -0,0 +1,629 @@
[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*]