\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 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. \enternote The class template

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

satisfies these requirements. \exitnote

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 typedefs 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{std::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{std::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_primaryl}!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 true, the returned bitmask is suitable for

matching characters without regard to their case.

Returns 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}. \enternote The value of \textit{I} will only

be 8, 10, or 16. \exitnote

\\ \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}

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

\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 {

enum error_type;

} // namespace regex_constants

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

class regex_error;

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

template <class charT> struct regex_traits;

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

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

typedef basic_regex<char> regex;

typedef basic_regex<wchar_t> wregex;

// \ref{re.regex.swap}, 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 sub_match:

template <class BidirectionalIterator>

class sub_match;

typedef sub_match<const char*> csub_match;

typedef sub_match<const wchar_t*> wcsub_match;

typedef sub_match<string::const_iterator> ssub_match;

typedef sub_match<wstring::const_iterator> wssub_match;

// \ref{re.submatch.op}, 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==(typename iterator_traits<BiIter>::value_type const* lhs,

const sub_match<BiIter>& rhs);

template <class BiIter>

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

const sub_match<BiIter>& rhs);

template <class BiIter>

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

const sub_match<BiIter>& rhs);

template <class BiIter>

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

const sub_match<BiIter>& rhs);

template <class BiIter>

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

const sub_match<BiIter>& rhs);

template <class BiIter>

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

const sub_match<BiIter>& rhs);

template <class BiIter>

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

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

template <class BiIter>

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

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

template <class BiIter>

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

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

template <class BiIter>

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

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

template <class BiIter>

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

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

template <class BiIter>

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

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

template <class BiIter>

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

const sub_match<BiIter>& rhs);

template <class BiIter>

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

const sub_match<BiIter>& rhs);

template <class BiIter>

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

const sub_match<BiIter>& rhs);

template <class BiIter>

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

const sub_match<BiIter>& rhs);

template <class BiIter>

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

const sub_match<BiIter>& rhs);

template <class BiIter>

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

const sub_match<BiIter>& rhs);

template <class BiIter>

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

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

template <class BiIter>

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

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

template <class BiIter>

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

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

template <class BiIter>

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

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

template <class BiIter>

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

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

template <class BiIter>

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

typename iterator_traits<BiIter>::value_type const& 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 match_results:

template <class BidirectionalIterator,

class Allocator = allocator<sub_match<BidirectionalIterator> > >

class match_results;

typedef match_results<const char*> cmatch;

typedef match_results<const wchar_t*> wcmatch;

typedef match_results<string::const_iterator> smatch;

typedef match_results<wstring::const_iterator> wsmatch;

// 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}, 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 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 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 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 regex_iterator:

template <class BidirectionalIterator,

class charT = typename iterator_traits<

BidirectionalIterator>::value_type,

class traits = regex_traits<charT> >

class regex_iterator;

typedef regex_iterator<const char*> cregex_iterator;

typedef regex_iterator<const wchar_t*> wcregex_iterator;

typedef regex_iterator<string::const_iterator> sregex_iterator;

typedef regex_iterator<wstring::const_iterator> wsregex_iterator;

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

template <class BidirectionalIterator,

class charT = typename iterator_traits<

BidirectionalIterator>::value_type,

class traits = regex_traits<charT> >

class regex_token_iterator;

typedef regex_token_iterator<const char*> cregex_token_iterator;

typedef regex_token_iterator<const wchar_t*> wcregex_token_iterator;

typedef regex_token_iterator<string::const_iterator> sregex_token_iterator;

typedef regex_token_iterator<wstring::const_iterator> wsregex_token_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 {

typedef @\textit{T1}@ syntax_option_type;

constexpr syntax_option_type icase = @\unspec@;

constexpr syntax_option_type nosubs = @\unspec@;

constexpr syntax_option_type optimize = @\unspec@;

constexpr syntax_option_type collate = @\unspec@;

constexpr syntax_option_type ECMAScript = @\unspec@;

constexpr syntax_option_type basic = @\unspec@;

constexpr syntax_option_type extended = @\unspec@;

constexpr syntax_option_type awk = @\unspec@;

constexpr syntax_option_type grep = @\unspec@;

constexpr syntax_option_type egrep = @\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 implementation-defined 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}}%

\\

\end{libefftab}

\rSec2[re.matchflag]{Bitmask type \tcode{regex_constants::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 {

typedef @\textit{T2}@ match_flag_type;

constexpr match_flag_type match_default = {};

constexpr match_flag_type match_not_bol = @\unspec@;

constexpr match_flag_type match_not_eol = @\unspec@;

constexpr match_flag_type match_not_bow = @\unspec@;

constexpr match_flag_type match_not_eow = @\unspec@;

constexpr match_flag_type match_any = @\unspec@;

constexpr match_flag_type match_not_null = @\unspec@;

constexpr match_flag_type match_continuous = @\unspec@;

constexpr match_flag_type match_prev_avail = @\unspec@;

constexpr match_flag_type format_default = {};

constexpr match_flag_type format_sed = @\unspec@;

constexpr match_flag_type format_no_copy = @\unspec@;

constexpr match_flag_type format_first_only = @\unspec@;

}

\end{codeblock}

\indexlibrary{\idxcode{match_flag_type}}%

The type \tcode{regex_constants::match_flag_type} is an implementation-defined 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 match_not_bol and 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 {

typedef @\textit{T3}@ error_type;

constexpr error_type error_collate = @\unspec@;

constexpr error_type error_ctype = @\unspec@;

constexpr error_type error_escape = @\unspec@;

constexpr error_type error_backref = @\unspec@;

constexpr error_type error_brack = @\unspec@;

constexpr error_type error_paren = @\unspec@;

constexpr error_type error_brace = @\unspec@;

constexpr error_type error_badbrace = @\unspec@;

constexpr error_type error_range = @\unspec@;

constexpr error_type error_space = @\unspec@;

constexpr error_type error_badrepeat = @\unspec@;

constexpr error_type error_complexity = @\unspec@;

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}}%