[re.alg]

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

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

### 28.6.10 Regular expression algorithms [re.alg]

#### [28.6.10.1](#re.except) Exceptions [[re.except]](re.except)

[1](#re.except-1)

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

The algorithms described in subclause [re.alg] may throw an exception
of type regex_error[.](#re.except-1.sentence-1)

If such an exception e is thrown,e.code() shall return either regex_constants​::​error_complexity or regex_constants​::​error_stack[.](#re.except-1.sentence-2)

#### [28.6.10.2](#match) regex_match [[re.alg.match]](re.alg.match)

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

[1](#match-1)

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

*Preconditions*: BidirectionalIterator models[bidirectional_iterator](iterator.concept.bidir#concept:bidirectional_iterator "24.3.4.12 Concept bidirectional_­iterator [iterator.concept.bidir]") ([[iterator.concept.bidir]](iterator.concept.bidir "24.3.4.12 Concept bidirectional_­iterator"))[.](#match-1.sentence-1)

[2](#match-2)

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

*Effects*: Determines whether there is a match between the
regular expression e, and all of the character
sequence [first, last)[.](#match-2.sentence-1)

The parameter flags is
used to control how the expression is matched against the character
sequence[.](#match-2.sentence-2)

When determining if there is a match, only potential matches
that match the entire character sequence are considered[.](#match-2.sentence-3)

Returns true if such a match exists, false otherwise[.](#match-2.sentence-4)

[*Example [1](#match-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*]

[3](#match-3)

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

*Postconditions*: m.ready() == true in all cases[.](#match-3.sentence-1)

If the function returns false, then the effect
on parameter m is unspecified except that m.size() returns 0 and m.empty() returns true[.](#match-3.sentence-2)

Otherwise the effects on parameter m are given in
Table [123](#tab:re.alg.match "Table 123: Effects of regex_­match algorithm")[.](#match-3.sentence-3)

Table [123](#tab:re.alg.match) — Effects of regex_match algorithm [[tab:re.alg.match]](./tab:re.alg.match)  

| [🔗](#tab:re.alg.match-row-1)<br>**Element** | **Value** |
| --- | --- |
| [🔗](#tab:re.alg.match-row-2)<br>m.size() | 1 + e.mark_count() |
| [🔗](#tab:re.alg.match-row-3)<br>m.empty() | false |
| [🔗](#tab:re.alg.match-row-4)<br>m.prefix().first | first |
| [🔗](#tab:re.alg.match-row-5)<br>m.prefix().second | first |
| [🔗](#tab:re.alg.match-row-6)<br>m.prefix().matched | false |
| [🔗](#tab:re.alg.match-row-7)<br>m.suffix().first | last |
| [🔗](#tab:re.alg.match-row-8)<br>m.suffix().second | last |
| [🔗](#tab:re.alg.match-row-9)<br>m.suffix().matched | false |
| [🔗](#tab:re.alg.match-row-10)<br>m[0].first | first |
| [🔗](#tab:re.alg.match-row-11)<br>m[0].second | last |
| [🔗](#tab:re.alg.match-row-12)<br>m[0].matched | true |
| [🔗](#tab:re.alg.match-row-13)<br>m[n].first | For all integers 0 < n < m.size(), the start of the sequence that matched sub-expression n[.](#tab:re.alg.match-row-13-column-2-sentence-1)<br>Alternatively, if sub-expression n did not participate in the match, then last[.](#tab:re.alg.match-row-13-column-2-sentence-2) |
| [🔗](#tab:re.alg.match-row-14)<br>m[n].second | For all integers 0 < n < m.size(), the end of the sequence that matched sub-expression n[.](#tab:re.alg.match-row-14-column-2-sentence-1)<br>Alternatively, if sub-expression n did not participate in the match, then last[.](#tab:re.alg.match-row-14-column-2-sentence-2) |
| [🔗](#tab:re.alg.match-row-15)<br>m[n].matched | For all integers 0 < n < m.size(), true if sub-expression n participated in the match, false otherwise[.](#tab:re.alg.match-row-15-column-2-sentence-1) |

[🔗](#lib:regex_match_)

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

[4](#match-4)

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

*Effects*: Behaves “as if” by constructing an instance ofmatch_results<BidirectionalIterator> what, and then
returning the result ofregex_match(first, last, what, e, flags)[.](#match-4.sentence-1)

[🔗](#lib:regex_match__)

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

[5](#match-5)

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

*Returns*: regex_match(str, str + char_traits<charT>​::​length(str), m, e, flags)[.](#match-5.sentence-1)

[🔗](#lib:regex_match___)

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

[6](#match-6)

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

*Returns*: regex_match(s.begin(), s.end(), m, e, flags)[.](#match-6.sentence-1)

[🔗](#lib:regex_match____)

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

[7](#match-7)

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

*Returns*: regex_match(str, str + char_traits<charT>​::​length(str), e, flags)[.](#match-7.sentence-1)

[🔗](#lib:regex_match_____)

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

[8](#match-8)

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

*Returns*: regex_match(s.begin(), s.end(), e, flags)[.](#match-8.sentence-1)

#### [28.6.10.3](#search) regex_search [[re.alg.search]](re.alg.search)

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

[1](#search-1)

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

*Preconditions*: BidirectionalIterator models[bidirectional_iterator](iterator.concept.bidir#concept:bidirectional_iterator "24.3.4.12 Concept bidirectional_­iterator [iterator.concept.bidir]") ([[iterator.concept.bidir]](iterator.concept.bidir "24.3.4.12 Concept bidirectional_­iterator"))[.](#search-1.sentence-1)

[2](#search-2)

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

*Effects*: Determines whether there is some sub-sequence within [first, last) that matches
the regular expression e[.](#search-2.sentence-1)

The parameter flags is used to control how the
expression is matched against the character sequence[.](#search-2.sentence-2)

Returns true if such a sequence
exists, false otherwise[.](#search-2.sentence-3)

[3](#search-3)

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

*Postconditions*: m.ready() == true in all cases[.](#search-3.sentence-1)

If the function returns false, then the effect
on parameter m is unspecified except that m.size() returns 0 and m.empty() returns true[.](#search-3.sentence-2)

Otherwise
the effects on parameter m are given in Table [124](#tab:re.alg.search "Table 124: Effects of regex_­search algorithm")[.](#search-3.sentence-3)

Table [124](#tab:re.alg.search) — Effects of regex_search algorithm [[tab:re.alg.search]](./tab:re.alg.search)  

| [🔗](#tab:re.alg.search-row-1)<br>**Element** | **Value** |
| --- | --- |
| [🔗](#tab:re.alg.search-row-2)<br>m.size() | 1 + e.mark_count() |
| [🔗](#tab:re.alg.search-row-3)<br>m.empty() | false |
| [🔗](#tab:re.alg.search-row-4)<br>m.prefix().first | first |
| [🔗](#tab:re.alg.search-row-5)<br>m.prefix().second | m[0].first |
| [🔗](#tab:re.alg.search-row-6)<br>m.prefix().matched | m.prefix().first != m.prefix().second |
| [🔗](#tab:re.alg.search-row-7)<br>m.suffix().first | m[0].second |
| [🔗](#tab:re.alg.search-row-8)<br>m.suffix().second | last |
| [🔗](#tab:re.alg.search-row-9)<br>m.suffix().matched | m.suffix().first != m.suffix().second |
| [🔗](#tab:re.alg.search-row-10)<br>m[0].first | The start of the sequence of characters that matched the regular expression |
| [🔗](#tab:re.alg.search-row-11)<br>m[0].second | The end of the sequence of characters that matched the regular expression |
| [🔗](#tab:re.alg.search-row-12)<br>m[0].matched | true |
| [🔗](#tab:re.alg.search-row-13)<br>m[n].first | For all integers 0 < n < m.size(), the start of the sequence that matched sub-expression n[.](#tab:re.alg.search-row-13-column-2-sentence-1)<br>Alternatively, if sub-expression n did not participate in the match, then last[.](#tab:re.alg.search-row-13-column-2-sentence-2) |
| [🔗](#tab:re.alg.search-row-14)<br>m[n].second | For all integers 0 < n < m.size(), the end of the sequence that matched sub-expression n[.](#tab:re.alg.search-row-14-column-2-sentence-1)<br>Alternatively, if sub-expression n did not participate in the match, then last[.](#tab:re.alg.search-row-14-column-2-sentence-2) |
| [🔗](#tab:re.alg.search-row-15)<br>m[n].matched | For all integers 0 < n < m.size(), true if sub-expression n participated in the match, false otherwise[.](#tab:re.alg.search-row-15-column-2-sentence-1) |

[🔗](#lib:regex_search_)

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

[4](#search-4)

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

*Returns*: regex_search(str, str + char_traits<charT>​::​length(str), m, e, flags)[.](#search-4.sentence-1)

[🔗](#lib:regex_search__)

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

[5](#search-5)

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

*Returns*: regex_search(s.begin(), s.end(), m, e, flags)[.](#search-5.sentence-1)

[🔗](#lib:regex_search___)

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

[6](#search-6)

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

*Effects*: Behaves “as if” by constructing an object what of type match_results<BidirectionalIterator> and returningregex_search(first, last, what, e, flags)[.](#search-6.sentence-1)

[🔗](#lib:regex_search____)

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

[7](#search-7)

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

*Returns*: regex_search(str, str + char_traits<charT>​::​length(str), e, flags)[.](#search-7.sentence-1)

[🔗](#lib:regex_search_____)

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

[8](#search-8)

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

*Returns*: regex_search(s.begin(), s.end(), e, flags)[.](#search-8.sentence-1)

#### [28.6.10.4](#replace) regex_replace [[re.alg.replace]](re.alg.replace)

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

[1](#replace-1)

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

*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<BidirectionalIterator> that occur within the sequence [first, last)[.](#replace-1.sentence-1)

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:

- [(1.1)](#replace-1.1)

If !(flags & regex_constants​::​format_no_copy), callsout = copy(m.prefix().first, m.prefix().second, out)

- [(1.2)](#replace-1.2)

Then callsout = m.format(out, fmt, flags) for the first form of the function andout = m.format(out, fmt, fmt + char_traits<charT>::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[.](#replace-1.sentence-3)

If flags & regex_constants​::​format_first_only is nonzero, then only the first match found is replaced[.](#replace-1.sentence-4)

[2](#replace-2)

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

*Returns*: out[.](#replace-2.sentence-1)

[🔗](#lib:regex_replace_)

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

[3](#replace-3)

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

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

[4](#replace-4)

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

*Returns*: result[.](#replace-4.sentence-1)

[🔗](#lib:regex_replace__)

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

[5](#replace-5)

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

*Effects*: Constructs an empty string result of
type basic_string<charT> and calls:regex_replace(back_inserter(result), s, s + char_traits<charT>::length(s), e, fmt, flags);

[6](#replace-6)

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

*Returns*: result[.](#replace-6.sentence-1)