19 KiB
[re.alg]
28 Text processing library [text]
28.6 Regular expressions library [re]
28.6.10 Regular expression algorithms [re.alg]
28.6.10.1 Exceptions [re.except]
The algorithms described in subclause [re.alg] may throw an exception of type regex_error.
If such an exception e is thrown,e.code() shall return either regex_constants::error_complexity or regex_constants::error_stack.
28.6.10.2 regex_match [re.alg.match]
template<class BidirectionalIterator, class Allocator, class charT, class traits> bool regex_match(BidirectionalIterator first, BidirectionalIterator last, match_results<BidirectionalIterator, Allocator>& m, const basic_regex<charT, traits>& e, regex_constants::match_flag_type flags = regex_constants::match_default);
Preconditions: BidirectionalIterator modelsbidirectional_iterator ([iterator.concept.bidir]).
Effects: Determines whether there is a match between the regular expression e, and all of the character sequence [first, last).
The parameter flags is used to control how the expression is matched against the character sequence.
When determining if there is a match, only potential matches that match the entire character sequence are considered.
Returns true if such a match exists, false otherwise.
[Example 1: std::regex re("Get|GetValue"); std::cmatch m; regex_search("GetValue", m, re); // returns true, and m[0] contains "Get" regex_match ("GetValue", m, re); // returns true, and m[0] contains "GetValue" regex_search("GetValues", m, re); // returns true, and m[0] contains "Get" regex_match ("GetValues", m, re); // returns false â end example]
Postconditions: m.ready() == true in all cases.
If the function returns false, then the effect on parameter m is unspecified except that m.size() returns 0 and m.empty() returns true.
Otherwise the effects on parameter m are given in Table 123.
Table 123 — Effects of regex_match algorithm [tab:re.alg.match]
| ð Element |
Value |
|---|---|
| ð m.size() |
1 + e.mark_count() |
| ð m.empty() |
false |
| ð m.prefix().first |
first |
| ð m.prefix().second |
first |
| ð m.prefix().matched |
false |
| ð m.suffix().first |
last |
| ð m.suffix().second |
last |
| ð m.suffix().matched |
false |
| ð m[0].first |
first |
| ð m[0].second |
last |
| ð m[0].matched |
true |
| ð m[n].first |
For all integers 0 < n < m.size(), the start of the sequence that matched sub-expression n. Alternatively, if sub-expression n did not participate in the match, then last. |
| ð m[n].second |
For all integers 0 < n < m.size(), the end of the sequence that matched sub-expression n. Alternatively, if sub-expression n did not participate in the match, then last. |
| ð m[n].matched |
For all integers 0 < n < m.size(), true if sub-expression n participated in the match, false otherwise. |
template<class BidirectionalIterator, class charT, class traits> bool regex_match(BidirectionalIterator first, BidirectionalIterator last, const basic_regex<charT, traits>& e, regex_constants::match_flag_type flags = regex_constants::match_default);
Effects: Behaves âas ifâ by constructing an instance ofmatch_results what, and then returning the result ofregex_match(first, last, what, e, flags).
template<class charT, class Allocator, class traits> bool regex_match(const charT* str, match_results<const charT*, Allocator>& m, const basic_regex<charT, traits>& e, regex_constants::match_flag_type flags = regex_constants::match_default);
Returns: regex_match(str, str + char_traits::length(str), m, e, flags).
template<class ST, class SA, class Allocator, class charT, class traits> bool regex_match(const basic_string<charT, ST, SA>& s, match_results<typename basic_string<charT, ST, SA>::const_iterator, Allocator>& m, const basic_regex<charT, traits>& e, regex_constants::match_flag_type flags = regex_constants::match_default);
Returns: regex_match(s.begin(), s.end(), m, e, flags).
template<class charT, class traits> bool regex_match(const charT* str, const basic_regex<charT, traits>& e, regex_constants::match_flag_type flags = regex_constants::match_default);
Returns: regex_match(str, str + char_traits::length(str), e, flags).
template<class ST, class SA, class charT, class traits> bool regex_match(const basic_string<charT, ST, SA>& s, const basic_regex<charT, traits>& e, regex_constants::match_flag_type flags = regex_constants::match_default);
Returns: regex_match(s.begin(), s.end(), e, flags).
28.6.10.3 regex_search [re.alg.search]
template<class BidirectionalIterator, class Allocator, class charT, class traits> bool regex_search(BidirectionalIterator first, BidirectionalIterator last, match_results<BidirectionalIterator, Allocator>& m, const basic_regex<charT, traits>& e, regex_constants::match_flag_type flags = regex_constants::match_default);
Preconditions: BidirectionalIterator modelsbidirectional_iterator ([iterator.concept.bidir]).
Effects: Determines whether there is some sub-sequence within [first, last) that matches the regular expression e.
The parameter flags is used to control how the expression is matched against the character sequence.
Returns true if such a sequence exists, false otherwise.
Postconditions: m.ready() == true in all cases.
If the function returns false, then the effect on parameter m is unspecified except that m.size() returns 0 and m.empty() returns true.
Otherwise the effects on parameter m are given in Table 124.
Table 124 — Effects of regex_search algorithm [tab:re.alg.search]
| ð Element |
Value |
|---|---|
| ð m.size() |
1 + e.mark_count() |
| ð m.empty() |
false |
| ð m.prefix().first |
first |
| ð m.prefix().second |
m[0].first |
| ð m.prefix().matched |
m.prefix().first != m.prefix().second |
| ð m.suffix().first |
m[0].second |
| ð m.suffix().second |
last |
| ð m.suffix().matched |
m.suffix().first != m.suffix().second |
| ð m[0].first |
The start of the sequence of characters that matched the regular expression |
| ð m[0].second |
The end of the sequence of characters that matched the regular expression |
| ð m[0].matched |
true |
| ð m[n].first |
For all integers 0 < n < m.size(), the start of the sequence that matched sub-expression n. Alternatively, if sub-expression n did not participate in the match, then last. |
| ð m[n].second |
For all integers 0 < n < m.size(), the end of the sequence that matched sub-expression n. Alternatively, if sub-expression n did not participate in the match, then last. |
| ð m[n].matched |
For all integers 0 < n < m.size(), true if sub-expression n participated in the match, false otherwise. |
template<class charT, class Allocator, class traits> bool regex_search(const charT* str, match_results<const charT*, Allocator>& m, const basic_regex<charT, traits>& e, regex_constants::match_flag_type flags = regex_constants::match_default);
Returns: regex_search(str, str + char_traits::length(str), m, e, flags).
template<class ST, class SA, class Allocator, class charT, class traits> bool regex_search(const basic_string<charT, ST, SA>& s, match_results<typename basic_string<charT, ST, SA>::const_iterator, Allocator>& m, const basic_regex<charT, traits>& e, regex_constants::match_flag_type flags = regex_constants::match_default);
Returns: regex_search(s.begin(), s.end(), m, e, flags).
template<class BidirectionalIterator, class charT, class traits> bool regex_search(BidirectionalIterator first, BidirectionalIterator last, const basic_regex<charT, traits>& e, regex_constants::match_flag_type flags = regex_constants::match_default);
Effects: Behaves âas ifâ by constructing an object what of type match_results and returningregex_search(first, last, what, e, flags).
template<class charT, class traits> bool regex_search(const charT* str, const basic_regex<charT, traits>& e, regex_constants::match_flag_type flags = regex_constants::match_default);
Returns: regex_search(str, str + char_traits::length(str), e, flags).
template<class ST, class SA, class charT, class traits> bool regex_search(const basic_string<charT, ST, SA>& s, const basic_regex<charT, traits>& e, regex_constants::match_flag_type flags = regex_constants::match_default);
Returns: regex_search(s.begin(), s.end(), e, flags).
28.6.10.4 regex_replace [re.alg.replace]
template<class OutputIterator, class BidirectionalIterator, class traits, class charT, class ST, class SA> OutputIterator regex_replace(OutputIterator out, BidirectionalIterator first, BidirectionalIterator last, const basic_regex<charT, traits>& e, const basic_string<charT, ST, SA>& fmt, regex_constants::match_flag_type flags = regex_constants::match_default); template<class OutputIterator, class BidirectionalIterator, class traits, class charT> OutputIterator regex_replace(OutputIterator out, BidirectionalIterator first, BidirectionalIterator last, const basic_regex<charT, traits>& e, const charT* fmt, regex_constants::match_flag_type flags = regex_constants::match_default);
Effects: Constructs a regex_iterator object i as if byregex_iterator<BidirectionalIterator, charT, traits> i(first, last, e, flags) and uses i to enumerate through all of the matches m of type match_results that occur within the sequence [first, last).
If no such matches are found and!(flags & regex_constants::format_no_copy), then callsout = copy(first, last, out)
If any matches are found then, for each such match:
If !(flags & regex_constants::format_no_copy), callsout = copy(m.prefix().first, m.prefix().second, out)
Then callsout = m.format(out, fmt, flags) for the first form of the function andout = m.format(out, fmt, fmt + char_traits::length(fmt), flags) for the second.
Finally, if such a match is found and !(flags & regex_constants::format_no_copy), callsout = copy(last_m.suffix().first, last_m.suffix().second, out) where last_m is a copy of the last match found.
If flags & regex_constants::format_first_only is nonzero, then only the first match found is replaced.
Returns: out.
template<class traits, class charT, class ST, class SA, class FST, class FSA> basic_string<charT, ST, SA> regex_replace(const basic_string<charT, ST, SA>& s, const basic_regex<charT, traits>& e, const basic_string<charT, FST, FSA>& fmt, regex_constants::match_flag_type flags = regex_constants::match_default); template<class traits, class charT, class ST, class SA> basic_string<charT, ST, SA> regex_replace(const basic_string<charT, ST, SA>& s, const basic_regex<charT, traits>& e, const charT* fmt, regex_constants::match_flag_type flags = regex_constants::match_default);
Effects: Constructs an empty string result of type basic_string<charT, ST, SA> and calls:regex_replace(back_inserter(result), s.begin(), s.end(), e, fmt, flags);
Returns: result.
template<class traits, class charT, class ST, class SA> basic_string<charT> regex_replace(const charT* s, const basic_regex<charT, traits>& e, const basic_string<charT, ST, SA>& fmt, regex_constants::match_flag_type flags = regex_constants::match_default); template<class traits, class charT> basic_string<charT> regex_replace(const charT* s, const basic_regex<charT, traits>& e, const charT* fmt, regex_constants::match_flag_type flags = regex_constants::match_default);
Effects: Constructs an empty string result of type basic_string and calls:regex_replace(back_inserter(result), s, s + char_traits::length(s), e, fmt, flags);
Returns: result.