\rSec0[re]{Regular expressions library}

\indextext{regular expression|(}

\rSec1[re.general]{General}

This Clause describes components that \Cpp programs may use to

perform operations involving regular expression matching and

searching.

The following subclauses describe a basic regular expression class template and its

traits that can handle char-like~(\ref{strings.general}) template arguments,

two specializations of this class template that handle sequences of \tcode{char} and \tcode{wchar_t},

a class template that holds the

result of a regular expression match, a series of algorithms that allow a character

sequence to be operated upon by a regular expression,

and two iterator types for

enumerating regular expression matches, as described in Table~\ref{tab:re.lib.summary}.

\begin{libsumtab}{Regular expressions library summary}{tab:re.lib.summary}

\ref{re.def} & Definitions & \\

\ref{re.req} & Requirements & \\ \rowsep

\ref{re.const} & Constants & \\

\ref{re.badexp} & Exception type & \\

\ref{re.traits} & Traits & \\

\ref{re.regex} & Regular expression template & \tcode{<regex>} \\

\ref{re.submatch} & Submatches & \\

\ref{re.results} & Match results & \\

\ref{re.alg} & Algorithms & \\

\ref{re.iter} & Iterators & \\ \rowsep

\ref{re.grammar} & Grammar & \\

\end{libsumtab}

\rSec1[re.def]{Definitions}

The following definitions shall apply to this Clause:

\indextext{collating element}%

\indextext{locale}%

\definition{collating element}{defns.regex.collating.element}

a sequence of one or more characters within the

current locale that collate as if they were a single character.

\indextext{finite state machine}%

\definition{finite state machine}{defns.regex.finite.state.machine}

an unspecified data structure that is used to

represent a regular expression, and which permits efficient matches

against the regular expression to be obtained.

\indextext{format specifier}%

\definition{format specifier}{defns.regex.format.specifier}

a sequence of one or more characters that is to be

replaced with some part of a regular expression match.

\indextext{matched}%

\indextext{regular expression!matched}%

\definition{matched}{defns.regex.matched}

a sequence of zero or more characters is matched by

a regular expression when the characters in the sequence

correspond to a sequence of characters defined by the pattern.

\indextext{primary equivalence class}%

\indextext{locale}%

\definition{primary equivalence class}{defns.regex.primary.equivalence.class}

a set of one or more characters which

share the same primary sort key: that is the sort key weighting that

depends only upon character shape, and not accents, case, or

locale specific tailorings.

\definition{regular expression}{defns.regex.regular.expression}

a pattern that selects specific strings

from a set of character strings.

\indextext{sub-expression}%

\definition{sub-expression}{defns.regex.subexpression}

a subset of a regular expression that has

been marked by parenthesis.

\rSec1[re.req]{Requirements}

This subclause defines requirements on classes representing regular

expression traits. \begin{note} The class template

\tcode{regex_traits}, defined in Clause~\ref{re.traits},

satisfies these requirements. \end{note}

The class template \tcode{basic_regex}, defined in

Clause~\ref{re.regex}, needs a set of related types and

functions to complete the definition of its semantics. These types

and functions are provided as a set of member \grammarterm{typedef-name}{s} and functions

in the template parameter \tcode{traits} used by the \tcode{basic_regex} class

template. This subclause defines the semantics of these

members.

To specialize class template \tcode{basic_regex} for a character

container \tcode{CharT} and its related regular

expression traits class \tcode{Traits}, use \tcode{basic_regex<CharT, Traits>}.

\indextext{regular expression traits!requirements}%

\indextext{requirements!regular expression traits}%

\indextext{regular expression!requirements}%

\indextext{locale}%

In Table~\ref{tab:re:RegexpTraits} \tcode{X} denotes a traits class

defining types and functions for the character container

type \tcode{charT}; \tcode{u} is an object of

type \tcode{X}; \tcode{v} is an object of type \tcode{const

X}; \tcode{p} is a value of type \tcode{const charT*}; \tcode{I1}

and \tcode{I2} are input iterators~(\ref{input.iterators});

\tcode{F1} and \tcode{F2} are forward iterators~(\ref{forward.iterators});

\tcode{c} is a value of type \tcode{const charT};

\tcode{s} is an object of type \tcode{X::string_type};

\tcode{cs} is an object of type \tcode{const X::string_type};

\tcode{b} is a value of type \tcode{bool};

\tcode{I} is a value of type \tcode{int};

\tcode{cl} is an object of type \tcode{X::char_class_type},

and \tcode{loc} is an object of type \tcode{X::locale_type}.

\begin{libreqtab3}

{Regular expression traits class requirements}

{tab:re:RegexpTraits}

\\ \topline

\lhdr{Expression} & \chdr{Return type} & \rhdr{Assertion/note pre-/post-condition } \\ \capsep

\lhdr{Expression} & \chdr{Return type} & \rhdr{Assertion/note pre-/post-condition } \\ \capsep

\tcode{X::char_type}

& \tcode{charT}

& The character container type used in the implementation of class

template \tcode{basic_regex}.

\\ \rowsep

\tcode{X::string_type}

& \tcode{basic_string<charT>}

&

\\ \rowsep

\tcode{X::locale_type}

& A copy constructible type

& A type that represents the locale used by the traits class. \indextext{locale}

\\ \rowsep

\tcode{X::char_class_type}

& A bitmask type~(\ref{bitmask.types}).

& A bitmask type representing a particular character classification.

\indextext{regular expression traits!\idxcode{char_class_type}}%

\indextext{\idxcode{char_class_type}!regular expression traits}%

\\ \rowsep

\tcode{X::length(p)}

& \tcode{size_t}

& Yields the smallest \tcode{i} such that \tcode{p[i] == 0}. Complexity is

linear in \tcode{i} .

\\ \rowsep

\tcode{v.translate(c)}

& \tcode{X::char_type}

& Returns a character such that for any character \tcode{d} that is to

be considered equivalent to \tcode{c} then \tcode{v.translate(c) == v.translate(d)}.

\indextext{regular expression traits!\idxcode{translate}}%

\indextext{\idxcode{translate}!regular expression traits}%

\\ \rowsep

\tcode{v.translate_nocase(c)}

& \tcode{X::char_type}

& For all characters \tcode{C} that are to be considered equivalent

to \tcode{c} when comparisons are to be performed without regard to

case, then \tcode{v.translate_nocase(c) == v.translate_nocase(C)}.

\indextext{regular expression traits!\idxcode{translate_nocase}}%

\indextext{\idxcode{translate_nocase}!regular expression traits}%

\\ \rowsep

\tcode{v.transform(F1, F2)}

& \tcode{X::string_type}

& Returns a sort key for the character sequence designated by the

iterator range \range{F1}{F2} such that if the character sequence

\range{G1}{G2} sorts before the character sequence \range{H1}{H2}

then \tcode{v.transform(G1, G2) < v.transform(H1, H2)}.

\indextext{regular expression traits!\idxcode{transform}}%

\indextext{\idxcode{transform}!regular expression traits}%

\\ \rowsep

\tcode{v.transform_primary(F1, F2)}

& \tcode{X::string_type}

& Returns a sort key for the character sequence designated by the

iterator range \range{F1}{F2} such that if the character sequence

\range{G1}{G2} sorts before the character sequence \range{H1}{H2}

when character case is not considered

then \tcode{v.transform_primary(G1, G2) < v.transform_primary(H1, H2)}.

\indextext{regular expression traits!\idxcode{transform_primary}}%

\indextext{transform_primary@\tcode{transform_primary}!regular expression traits}%

\\ \rowsep

\tcode{v.lookup_collatename(F1, F2)}

& \tcode{X::string_type}

& Returns a sequence of characters that represents the collating element

consisting of the character sequence designated by the iterator range

\range{F1}{F2}. Returns an empty string if the character sequence is not

a valid collating element.

\indextext{regular expression traits!\idxcode{lookup_collatename}}%

\indextext{\idxcode{lookup_collatename}!regular expression traits}%

\\ \rowsep

\tcode{v.lookup_classname(F1, F2, b)}

& \tcode{X::char_class_type}

& Converts the character sequence designated by the iterator range

\range{F1}{F2} into a value of a bitmask type that can

subsequently be passed to \tcode{isctype}. Values returned from

\tcode{lookup_classname} can be bitwise or'ed together; the

resulting value represents membership in either of the

corresponding character classes.

If \tcode{b} is \tcode{true}, the returned bitmask is suitable for

matching characters without regard to their case.

Returns \tcode{0} if the character

sequence is not the name of a character class recognized by

\tcode{X}. The value returned shall be independent of the case of

the characters in the sequence.

\indextext{regular expression traits!\idxcode{lookup_classname}}%

\indextext{\idxcode{lookup_classname}!regular expression traits}%

\\ \rowsep

\tcode{v.isctype(c, cl)}

& \tcode{bool}

& Returns \tcode{true} if character \tcode{c} is a member of

one of the character classes designated by \tcode{cl},

\tcode{false} otherwise.

\indextext{regular expression traits!\idxcode{isctype}}%

\indextext{\idxcode{isctype}!regular expression traits}%

\\ \rowsep

\tcode{v.value(c, I)}

& \tcode{int}

& Returns the value represented by the digit \textit{c} in base

\textit{I} if the character \textit{c} is a valid digit in base \textit{I};

otherwise returns \tcode{-1}. \begin{note} The value of \textit{I} will only

be 8, 10, or 16. \end{note}

\\ \rowsep

\tcode{u.imbue(loc)}

& \tcode{X::locale_type}

& Imbues \tcode{u} with the locale \tcode{loc} and returns the previous locale

used by \tcode{u} if any. \indextext{locale}%

\\ \rowsep

\tcode{v.getloc()}

& \tcode{X::locale_type}

& Returns the current locale used by \tcode{v}, if any. \indextext{locale}%

\\

\end{libreqtab3}

\begin{note}

Class template \tcode{regex_traits} satisfies the requirements for a

regular expression traits class when it is specialized for

\tcode{char} or \tcode{wchar_t}. This class template is described in

the header \tcode{<regex>}, and is described in Clause~\ref{re.traits}.

\end{note}

\rSec1[re.syn]{Header \tcode{<regex>} synopsis}

\indexlibrary{\idxhdr{regex}}%

\indexlibrary{\idxcode{basic_regex}}%

\indexlibrary{\idxcode{regex}}%

\indexlibrary{\idxcode{wregex}}%

\begin{codeblock}

#include <initializer_list>

namespace std {

// \ref{re.const}, regex constants

namespace regex_constants {

using syntax_option_type = @\placeholder{T1}@;

using match_flag_type = @\placeholder{T2}@;

using error_type = @\placeholder{T3}@;

}

// \ref{re.badexp}, class \tcode{regex_error}

class regex_error;

// \ref{re.traits}, class template \tcode{regex_traits}

template <class charT> struct regex_traits;

// \ref{re.regex}, class template \tcode{basic_regex}

template <class charT, class traits = regex_traits<charT>> class basic_regex;

using regex = basic_regex<char>;

using wregex = basic_regex<wchar_t>;

// \ref{re.regex.swap}, \tcode{basic_regex} swap

template <class charT, class traits>

void swap(basic_regex<charT, traits>& e1, basic_regex<charT, traits>& e2);

// \ref{re.submatch}, class template \tcode{sub_match}

template <class BidirectionalIterator>

class sub_match;

using csub_match = sub_match<const char*>;

using wcsub_match = sub_match<const wchar_t*>;

using ssub_match = sub_match<string::const_iterator>;

using wssub_match = sub_match<wstring::const_iterator>;

// \ref{re.submatch.op}, \tcode{sub_match} non-member operators

template <class BiIter>

bool operator==(const sub_match<BiIter>& lhs, const sub_match<BiIter>& rhs);

template <class BiIter>

bool operator!=(const sub_match<BiIter>& lhs, const sub_match<BiIter>& rhs);

template <class BiIter>

bool operator<(const sub_match<BiIter>& lhs, const sub_match<BiIter>& rhs);

template <class BiIter>

bool operator<=(const sub_match<BiIter>& lhs, const sub_match<BiIter>& rhs);

template <class BiIter>

bool operator>=(const sub_match<BiIter>& lhs, const sub_match<BiIter>& rhs);

template <class BiIter>

bool operator>(const sub_match<BiIter>& lhs, const sub_match<BiIter>& rhs);

template <class BiIter, class ST, class SA>

bool operator==(

const basic_string<typename iterator_traits<BiIter>::value_type, ST, SA>& lhs,

const sub_match<BiIter>& rhs);

template <class BiIter, class ST, class SA>

bool operator!=(

const basic_string<typename iterator_traits<BiIter>::value_type, ST, SA>& lhs,

const sub_match<BiIter>& rhs);

template <class BiIter, class ST, class SA>

bool operator<(

const basic_string<typename iterator_traits<BiIter>::value_type, ST, SA>& lhs,

const sub_match<BiIter>& rhs);

template <class BiIter, class ST, class SA>

bool operator>(

const basic_string<typename iterator_traits<BiIter>::value_type, ST, SA>& lhs,

const sub_match<BiIter>& rhs);

template <class BiIter, class ST, class SA>

bool operator>=(

const basic_string<typename iterator_traits<BiIter>::value_type, ST, SA>& lhs,

const sub_match<BiIter>& rhs);

template <class BiIter, class ST, class SA>

bool operator<=(

const basic_string<typename iterator_traits<BiIter>::value_type, ST, SA>& lhs,

const sub_match<BiIter>& rhs);

template <class BiIter, class ST, class SA>

bool operator==(

const sub_match<BiIter>& lhs,

const basic_string<typename iterator_traits<BiIter>::value_type, ST, SA>& rhs);

template <class BiIter, class ST, class SA>

bool operator!=(

const sub_match<BiIter>& lhs,

const basic_string<typename iterator_traits<BiIter>::value_type, ST, SA>& rhs);

template <class BiIter, class ST, class SA>

bool operator<(

const sub_match<BiIter>& lhs,

const basic_string<typename iterator_traits<BiIter>::value_type, ST, SA>& rhs);

template <class BiIter, class ST, class SA>

bool operator>(

const sub_match<BiIter>& lhs,

const basic_string<typename iterator_traits<BiIter>::value_type, ST, SA>& rhs);

template <class BiIter, class ST, class SA>

bool operator>=(

const sub_match<BiIter>& lhs,

const basic_string<typename iterator_traits<BiIter>::value_type, ST, SA>& rhs);

template <class BiIter, class ST, class SA>

bool operator<=(

const sub_match<BiIter>& lhs,

const basic_string<typename iterator_traits<BiIter>::value_type, ST, SA>& rhs);

template <class BiIter>

bool operator==(const typename iterator_traits<BiIter>::value_type* lhs,

const sub_match<BiIter>& rhs);

template <class BiIter>

bool operator!=(const typename iterator_traits<BiIter>::value_type* lhs,

const sub_match<BiIter>& rhs);

template <class BiIter>

bool operator<(const typename iterator_traits<BiIter>::value_type* lhs,

const sub_match<BiIter>& rhs);

template <class BiIter>

bool operator>(const typename iterator_traits<BiIter>::value_type* lhs,

const sub_match<BiIter>& rhs);

template <class BiIter>

bool operator>=(const typename iterator_traits<BiIter>::value_type* lhs,

const sub_match<BiIter>& rhs);

template <class BiIter>

bool operator<=(const typename iterator_traits<BiIter>::value_type* lhs,

const sub_match<BiIter>& rhs);

template <class BiIter>

bool operator==(const sub_match<BiIter>& lhs,

const typename iterator_traits<BiIter>::value_type* rhs);

template <class BiIter>

bool operator!=(const sub_match<BiIter>& lhs,

const typename iterator_traits<BiIter>::value_type* rhs);

template <class BiIter>

bool operator<(const sub_match<BiIter>& lhs,

const typename iterator_traits<BiIter>::value_type* rhs);

template <class BiIter>

bool operator>(const sub_match<BiIter>& lhs,

const typename iterator_traits<BiIter>::value_type* rhs);

template <class BiIter>

bool operator>=(const sub_match<BiIter>& lhs,

const typename iterator_traits<BiIter>::value_type* rhs);

template <class BiIter>

bool operator<=(const sub_match<BiIter>& lhs,

const typename iterator_traits<BiIter>::value_type* rhs);

template <class BiIter>

bool operator==(const typename iterator_traits<BiIter>::value_type& lhs,

const sub_match<BiIter>& rhs);

template <class BiIter>

bool operator!=(const typename iterator_traits<BiIter>::value_type& lhs,

const sub_match<BiIter>& rhs);

template <class BiIter>

bool operator<(const typename iterator_traits<BiIter>::value_type& lhs,

const sub_match<BiIter>& rhs);

template <class BiIter>

bool operator>(const typename iterator_traits<BiIter>::value_type& lhs,

const sub_match<BiIter>& rhs);

template <class BiIter>

bool operator>=(const typename iterator_traits<BiIter>::value_type& lhs,

const sub_match<BiIter>& rhs);

template <class BiIter>

bool operator<=(const typename iterator_traits<BiIter>::value_type& lhs,

const sub_match<BiIter>& rhs);

template <class BiIter>

bool operator==(const sub_match<BiIter>& lhs,

const typename iterator_traits<BiIter>::value_type& rhs);

template <class BiIter>

bool operator!=(const sub_match<BiIter>& lhs,

const typename iterator_traits<BiIter>::value_type& rhs);

template <class BiIter>

bool operator<(const sub_match<BiIter>& lhs,

const typename iterator_traits<BiIter>::value_type& rhs);

template <class BiIter>

bool operator>(const sub_match<BiIter>& lhs,

const typename iterator_traits<BiIter>::value_type& rhs);

template <class BiIter>

bool operator>=(const sub_match<BiIter>& lhs,

const typename iterator_traits<BiIter>::value_type& rhs);

template <class BiIter>

bool operator<=(const sub_match<BiIter>& lhs,

const typename iterator_traits<BiIter>::value_type& rhs);

template <class charT, class ST, class BiIter>

basic_ostream<charT, ST>&

operator<<(basic_ostream<charT, ST>& os, const sub_match<BiIter>& m);

// \ref{re.results}, class template \tcode{match_results}

template <class BidirectionalIterator,

class Allocator = allocator<sub_match<BidirectionalIterator>>>

class match_results;

using cmatch = match_results<const char*>;

using wcmatch = match_results<const wchar_t*>;

using smatch = match_results<string::const_iterator>;

using wsmatch = match_results<wstring::const_iterator>;

// \tcode{match_results} comparisons

template <class BidirectionalIterator, class Allocator>

bool operator==(const match_results<BidirectionalIterator, Allocator>& m1,

const match_results<BidirectionalIterator, Allocator>& m2);

template <class BidirectionalIterator, class Allocator>

bool operator!=(const match_results<BidirectionalIterator, Allocator>& m1,

const match_results<BidirectionalIterator, Allocator>& m2);

// \ref{re.results.swap}, \tcode{match_results} swap

template <class BidirectionalIterator, class Allocator>

void swap(match_results<BidirectionalIterator, Allocator>& m1,

match_results<BidirectionalIterator, Allocator>& m2);

// \ref{re.alg.match}, function template \tcode{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);

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

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

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

template <class ST, class SA, class Allocator, class charT, class traits>

bool regex_match(const basic_string<charT, ST, SA>&&,

match_results<typename basic_string<charT, ST, SA>::const_iterator,

Allocator>&,

const basic_regex<charT, traits>&,

regex_constants::match_flag_type = regex_constants::match_default) = delete;

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

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

// \ref{re.alg.search}, function template \tcode{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);

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

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

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

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

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

template <class ST, class SA, class Allocator, class charT, class traits>

bool regex_search(const basic_string<charT, ST, SA>&&,

match_results<typename basic_string<charT, ST, SA>::const_iterator,

Allocator>&,

const basic_regex<charT, traits>&,

regex_constants::match_flag_type

= regex_constants::match_default) = delete;

// \ref{re.alg.replace}, function template \tcode{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);

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

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

// \ref{re.regiter}, class template \tcode{regex_iterator}

template <class BidirectionalIterator,

class charT = typename iterator_traits<BidirectionalIterator>::value_type,

class traits = regex_traits<charT>>

class regex_iterator;

using cregex_iterator = regex_iterator<const char*>;

using wcregex_iterator = regex_iterator<const wchar_t*>;

using sregex_iterator = regex_iterator<string::const_iterator>;

using wsregex_iterator = regex_iterator<wstring::const_iterator>;

// \ref{re.tokiter}, class template \tcode{regex_token_iterator}

template <class BidirectionalIterator,

class charT = typename iterator_traits<BidirectionalIterator>::value_type,

class traits = regex_traits<charT>>

class regex_token_iterator;

using cregex_token_iterator = regex_token_iterator<const char*>;

using wcregex_token_iterator = regex_token_iterator<const wchar_t*>;

using sregex_token_iterator = regex_token_iterator<string::const_iterator>;

using wsregex_token_iterator = regex_token_iterator<wstring::const_iterator>;

namespace pmr {

template <class BidirectionalIterator>

using match_results =

std::match_results<BidirectionalIterator,

polymorphic_allocator<sub_match<BidirectionalIterator>>>;

using cmatch = match_results<const char*>;

using wcmatch = match_results<const wchar_t*>;

using smatch = match_results<string::const_iterator>;

using wsmatch = match_results<wstring::const_iterator>;

}

}

\end{codeblock}

\rSec1[re.const]{Namespace \tcode{std::regex_constants}}

\indexlibrary{\idxcode{regex_constants}}%

The namespace \tcode{std::regex_constants} holds

symbolic constants used by the regular expression library. This

namespace provides three types, \tcode{syntax_option_type},

\tcode{match_flag_type}, and \tcode{error_type}, along with several

constants of these types.

\rSec2[re.synopt]{Bitmask type \tcode{syntax_option_type}}

\indexlibrary{\idxcode{syntax_option_type}}%

\indexlibrary{\idxcode{regex_constants}!\idxcode{syntax_option_type}}%

\begin{codeblock}

namespace std::regex_constants {

using syntax_option_type = @\textit{T1}@;

inline constexpr syntax_option_type icase = @\unspec@;

inline constexpr syntax_option_type nosubs = @\unspec@;

inline constexpr syntax_option_type optimize = @\unspec@;

inline constexpr syntax_option_type collate = @\unspec@;

inline constexpr syntax_option_type ECMAScript = @\unspec@;

inline constexpr syntax_option_type basic = @\unspec@;

inline constexpr syntax_option_type extended = @\unspec@;

inline constexpr syntax_option_type awk = @\unspec@;

inline constexpr syntax_option_type grep = @\unspec@;

inline constexpr syntax_option_type egrep = @\unspec@;

inline constexpr syntax_option_type multiline = @\unspec@;

}

\end{codeblock}

\indexlibrary{\idxcode{syntax_option_type}}%

\indexlibrary{\idxcode{syntax_option_type}!\idxcode{icase}}%

\indexlibrary{\idxcode{syntax_option_type}!\idxcode{nosubs}}%

\indexlibrary{\idxcode{syntax_option_type}!\idxcode{optimize}}%

\indexlibrary{\idxcode{syntax_option_type}!\idxcode{collate}}%

\indexlibrary{\idxcode{syntax_option_type}!\idxcode{ECMAScript}}%

\indexlibrary{\idxcode{syntax_option_type}!\idxcode{basic}}%

\indexlibrary{\idxcode{syntax_option_type}!\idxcode{extended}}%

\indexlibrary{\idxcode{syntax_option_type}!\idxcode{awk}}%

\indexlibrary{\idxcode{syntax_option_type}!\idxcode{grep}}%

\indexlibrary{\idxcode{syntax_option_type}!\idxcode{egrep}}%

The type \tcode{syntax_option_type} is an \impldef{type of \tcode{syntax_option_type}} bitmask

type~(\ref{bitmask.types}). Setting its elements has the effects listed in

Table~\ref{tab:re:syntaxoption}. A valid value of type

\tcode{syntax_option_type} shall have at most one of the grammar elements

\tcode{ECMAScript}, \tcode{basic}, \tcode{extended}, \tcode{awk}, \tcode{grep}, \tcode{egrep}, set.

If no grammar element is set, the default grammar is \tcode{ECMAScript}.

\begin{libefftab}

{\tcode{syntax_option_type} effects}

{tab:re:syntaxoption}

\tcode{icase} &

Specifies that matching of regular expressions against a character

container sequence shall be performed without regard to case.

\indexlibrary{\idxcode{syntax_option_type}!\idxcode{icase}}%

\\ \rowsep

\tcode{nosubs} &

Specifies that no sub-expressions shall be considered to be marked, so that

when a regular expression is matched against a

character container sequence, no sub-expression matches shall be

stored in the supplied \tcode{match_results} structure.

\indexlibrary{\idxcode{syntax_option_type}!\idxcode{nosubs}}%

\\ \rowsep

\tcode{optimize} &

Specifies that the regular expression engine should pay more attention

to the speed with which regular expressions are matched, and less to

the speed with which regular expression objects are

constructed. Otherwise it has no detectable effect on the program

output.

\indexlibrary{\idxcode{syntax_option_type}!\idxcode{optimize}}%

\\ \rowsep

\tcode{collate} &

Specifies that character ranges of the form \tcode{"[a-b]"} shall be locale

sensitive.

\indexlibrary{\idxcode{syntax_option_type}!\idxcode{collate}}%

\indextext{locale}%

\\ \rowsep

\tcode{ECMAScript} &

Specifies that the grammar recognized by the regular expression engine

shall be that used by ECMAScript in ECMA-262, as modified in~\ref{re.grammar}.

\indextext{ECMAScript}%

\indexlibrary{\idxcode{syntax_option_type}!\idxcode{ECMAScript}}%

\\ \rowsep

\tcode{basic} &

Specifies that the grammar recognized by the regular expression engine

shall be that used by basic regular expressions in POSIX, Base Definitions and

Headers, Section 9, Regular Expressions.

\indextext{POSIX!regular expressions}%

\indexlibrary{\idxcode{syntax_option_type}!\idxcode{basic}}%

\\ \rowsep

\tcode{extended} &

Specifies that the grammar recognized by the regular expression engine

shall be that used by extended regular expressions in POSIX, Base Definitions and

Headers, Section 9, Regular Expressions.

\indextext{POSIX!extended regular expressions}%

\indexlibrary{\idxcode{syntax_option_type}!\idxcode{extended}}%

\\ \rowsep

\tcode{awk} &

Specifies that the grammar recognized by the regular expression engine

shall be that used by the utility awk in POSIX.

\indextext{\idxcode{awk}}%

\indexlibrary{\idxcode{syntax_option_type}!\idxcode{awk}}%

\\ \rowsep

\tcode{grep} &

Specifies that the grammar recognized by the regular expression engine

shall be that used by the utility grep in POSIX.

\indextext{\idxcode{grep}}%

\indexlibrary{\idxcode{syntax_option_type}!\idxcode{grep}}%

\\ \rowsep

\tcode{egrep} &

Specifies that the grammar recognized by the regular expression engine

shall be that used by the utility grep when given the -E

option in POSIX.

\indextext{\idxcode{egrep}}%

\indexlibrary{\idxcode{syntax_option_type}!\idxcode{egrep}}%

\\ \rowsep

\tcode{multiline} &

Specifies that \tcode{\^} shall match the beginning of a line and

\tcode{\$} shall match the end of a line,

if the \tcode{ECMAScript} engine is selected.

\indextext{\idxcode{multiline}}%

\indexlibrary{\idxcode{syntax_option_type}!\idxcode{multiline}}%

\end{libefftab}

\rSec2[re.matchflag]{Bitmask type \tcode{match_flag_type}}

\indexlibrary{\idxcode{match_flag_type}}%

\indexlibrary{\idxcode{regex_constants}!\idxcode{match_flag_type}}%

\indexlibrary{\idxcode{match_default}}%

\indexlibrary{\idxcode{match_not_bol}}%

\indexlibrary{\idxcode{match_not_eol}}%

\indexlibrary{\idxcode{match_not_bow}}%

\indexlibrary{\idxcode{match_not_eow}}%

\indexlibrary{\idxcode{match_any}}%

\indexlibrary{\idxcode{match_not_null}}%

\indexlibrary{\idxcode{match_continuous}}%

\indexlibrary{\idxcode{match_prev_avail}}%

\indexlibrary{\idxcode{format_default}}%

\indexlibrary{\idxcode{format_sed}}%

\indexlibrary{\idxcode{format_no_copy}}%

\indexlibrary{\idxcode{format_first_only}}%

\begin{codeblock}

namespace std::regex_constants {

using match_flag_type = @\textit{T2}@;

inline constexpr match_flag_type match_default = {};

inline constexpr match_flag_type match_not_bol = @\unspec@;

inline constexpr match_flag_type match_not_eol = @\unspec@;

inline constexpr match_flag_type match_not_bow = @\unspec@;

inline constexpr match_flag_type match_not_eow = @\unspec@;

inline constexpr match_flag_type match_any = @\unspec@;

inline constexpr match_flag_type match_not_null = @\unspec@;

inline constexpr match_flag_type match_continuous = @\unspec@;

inline constexpr match_flag_type match_prev_avail = @\unspec@;

inline constexpr match_flag_type format_default = {};

inline constexpr match_flag_type format_sed = @\unspec@;

inline constexpr match_flag_type format_no_copy = @\unspec@;

inline constexpr match_flag_type format_first_only = @\unspec@;

}

\end{codeblock}

\indexlibrary{\idxcode{match_flag_type}}%

The type \tcode{match_flag_type} is an

\impldef{type of \tcode{regex_constants::match_flag_type}} bitmask type~(\ref{bitmask.types}).

The constants of that type, except for \tcode{match_default} and

\tcode{format_default}, are bitmask elements. The \tcode{match_default} and

\tcode{format_default} constants are empty bitmasks.

Matching a regular expression against a sequence of characters

\range{first}{last} proceeds according to the rules of the grammar specified for the regular

expression object, modified according to the effects listed in Table~\ref{tab:re:matchflag} for

any bitmask elements set.

\begin{longlibefftab}

{\tcode{regex_constants::match_flag_type} effects when obtaining a match against a

character container sequence \range{first}{last}.}

{tab:re:matchflag}

\indexlibrary{\idxcode{match_not_bol}}%

\tcode{match_not_bol} &

The first character in the sequence \range{first}{last} shall be treated

as though it is not at the beginning of a line, so the character

\verb|^| in the regular expression shall not match \range{first}{first}.

\\ \rowsep

\indexlibrary{\idxcode{match_not_eol}}%

\tcode{match_not_eol} &

The last character in the sequence \range{first}{last} shall be treated

as though it is not at the end of a line, so the character

\verb|"$"| in the regular expression shall not match \range{last}{last}.

\\ \rowsep

\indexlibrary{\idxcode{match_not_bow}}%

\tcode{match_not_bow} &

The expression \verb|"\\b"| shall not match the

sub-sequence \range{first}{first}.

\\ \rowsep

\indexlibrary{\idxcode{match_not_eow}}%

\tcode{match_not_eow} &

The expression \verb|"\\b"| shall not match the

sub-sequence \range{last}{last}.

\\ \rowsep

\indexlibrary{\idxcode{match_any}}%

\tcode{match_any} &

If more than one match is possible then any match is an

acceptable result.

\\ \rowsep

\indexlibrary{\idxcode{match_not_null}}%

\tcode{match_not_null} &

The expression shall not match an empty

sequence.

\\ \rowsep

\indexlibrary{\idxcode{match_continuous}}%

\tcode{match_continuous} &

The expression shall only match a sub-sequence that begins at

\tcode{first}.

\\ \rowsep

\indexlibrary{\idxcode{match_prev_avail}}%

\tcode{match_prev_avail} &

\verb!--first! is a valid iterator position. When this flag is

set the flags \tcode{match_not_bol} and \tcode{match_not_bow} shall be ignored by the

regular expression algorithms~(\ref{re.alg}) and iterators~(\ref{re.iter}).

\\ \rowsep

\indexlibrary{\idxcode{format_default}}%

\tcode{format_default} &

When a regular expression match is to be replaced by a

new string, the new string shall be constructed using the rules used by

the ECMAScript replace function in ECMA-262,

part 15.5.4.11 String.prototype.replace. In

addition, during search and replace operations all non-overlapping

occurrences of the regular expression shall be located and replaced, and

sections of the input that did not match the expression shall be copied

unchanged to the output string.

\\ \rowsep

\indexlibrary{\idxcode{format_sed}}%

\tcode{format_sed} &

When a regular expression match is to be replaced by a

new string, the new string shall be constructed using the rules used by

the sed utility in POSIX.

\\ \rowsep

\indexlibrary{\idxcode{format_no_copy}}%

\tcode{format_no_copy} &

During a search and replace operation, sections of

the character container sequence being searched that do not match the

regular expression shall not be copied to the output string. \\ \rowsep

\indexlibrary{\idxcode{format_first_only}}%

\tcode{format_first_only} &

When specified during a search and replace operation, only the

first occurrence of the regular expression shall be replaced.

\end{longlibefftab}

\rSec2[re.err]{Implementation-defined \tcode{error_type}}

\indexlibrary{\idxcode{error_type}}%

\indexlibrary{\idxcode{regex_constants}!\idxcode{error_type}}%

\begin{codeblock}

namespace std::regex_constants {

using error_type = @\textit{T3}@;

inline constexpr error_type error_collate = @\unspec@;

inline constexpr error_type error_ctype = @\unspec@;

inline constexpr error_type error_escape = @\unspec@;

inline constexpr error_type error_backref = @\unspec@;

inline constexpr error_type error_brack = @\unspec@;

inline constexpr error_type error_paren = @\unspec@;

inline constexpr error_type error_brace = @\unspec@;

inline constexpr error_type error_badbrace = @\unspec@;

inline constexpr error_type error_range = @\unspec@;

inline constexpr error_type error_space = @\unspec@;

inline constexpr error_type error_badrepeat = @\unspec@;

inline constexpr error_type error_complexity = @\unspec@;

inline constexpr error_type error_stack = @\unspec@;

}

\end{codeblock}

\indexlibrary{\idxcode{error_type}}%

\indexlibrary{\idxcode{regex_constants}!\idxcode{error_type}}%

The type \tcode{error_type} is an \impldef{type of

\tcode{regex_constants::error_type}} enumerated type~(\ref{enumerated.types}).

Values of type \tcode{error_type} represent the error

conditions described in Table~\ref{tab:re:errortype}:

\begin{longliberrtab}

{\tcode{error_type} values in the C locale}

{tab:re:errortype}

\tcode{error_collate}

&

The expression contained an invalid collating element name. \\ \rowsep

\tcode{error_ctype}

&

The expression contained an invalid character class name. \\ \rowsep

\tcode{error_escape}

&

The expression contained an invalid escaped character, or a trailing

escape. \\ \rowsep

\tcode{error_backref}

&

The expression contained an invalid back reference. \\ \rowsep

\tcode{error_brack}

&

The expression contained mismatched \verb|[| and \verb|]|. \\ \rowsep

\tcode{error_paren}

&

The expression contained mismatched \verb|(| and \verb|)|. \\ \rowsep

\tcode{error_brace}

&

The expression contained mismatched \verb|{| and \verb|}| \\ \rowsep

\tcode{error_badbrace}

&

The expression contained an invalid range in a \verb|{}| expression. \\

\tcode{error_range}

&

The expression contained an invalid character range, such as

\verb|[b-a]| in most encodings. \\ \rowsep

\tcode{error_space}

&

There was insufficient memory to convert the expression into a finite

state machine. \\ \rowsep

\tcode{error_badrepeat}

&

One of \verb|*?+{| was not preceded by a valid regular expression. \\ \rowsep

\tcode{error_complexity}

&

The complexity of an attempted match against a regular expression

exceeded a pre-set level. \\ \rowsep

\tcode{error_stack}

&

There was insufficient memory to determine whether the regular

expression could match the specified character sequence. \\

\end{longliberrtab}

\rSec1[re.badexp]{Class \tcode{regex_error}}

\indexlibrary{\idxcode{regex_error}}%

\begin{codeblock}

class regex_error : public runtime_error {

public:

explicit regex_error(regex_constants::error_type ecode);

regex_constants::error_type code() const;

};

\end{codeblock}

The class \tcode{regex_error} defines the type of objects thrown as

exceptions to report errors from the regular expression library.

\indexlibrary{\idxcode{regex_error}!constructor}%

\begin{itemdecl}

regex_error(regex_constants::error_type ecode);

\end{itemdecl}

\begin{itemdescr}

\pnum\effects Constructs an object of class \tcode{regex_error}.