31 Regular expressions library [re]

31.11 Regular expression algorithms [re.alg]

31.11.1 Exceptions [re.except]

The algorithms described in this subclause 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.

31.11.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);

Requires: The type BidirectionalIterator shall satisfy the requirements of a Bidirectional Iterator ([bidirectional.iterators]).

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

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

Table 130 — Effects of regex_match algorithm

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 of match_results<BidirectionalIterator> what, and then returning the result of regex_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<charT>::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<charT>::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).

31.11.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);

Requires: Type BidirectionalIterator shall satisfy the requirements of a Bidirectional Iterator ([bidirectional.iterators]).

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

Table 131 — Effects of regex_search algorithm

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<charT>::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<BidirectionalIterator> and returning regex_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<charT>::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).

31.11.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 by

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

If no such matches are found and !(flags & regex_constants::format_no_copy), then calls

out = copy(first, last, out)

If any matches are found then, for each such match:

(1.1)
If !(flags & regex_constants::format_no_copy), calls
```
out = copy(m.prefix().first, m.prefix().second, out)
```

(1.2)

Then calls

out = m.format(out, fmt, flags)

for the first form of the function and

out = 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), calls

out = 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<charT> and calls:

regex_replace(back_inserter(result), s, s + char_traits<charT>::length(s), e, fmt, flags);