\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\iref{strings.general} template arguments,

two specializations of this class template that handle sequences of \tcode{char} and \keyword{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 summarized in \tref{re.summary}.

\begin{libsumtab}{Regular expressions library summary}{re.summary}

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

\ref{re.const} & Constants & \tcode{<regex>} \\

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

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

\ref{re.regex} & Regular expression template & \\

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

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

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

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

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

\end{libsumtab}

The ECMAScript Language Specification described in Standard Ecma-262

is called \defn{ECMA-262} in this Clause.

\rSec1[re.req]{Requirements}

This subclause defines requirements on classes representing regular

expression traits.

\begin{note}

The class template

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

meets these requirements.

\end{note}

The class template \tcode{basic_regex}, defined in

\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 the following requirements,

\begin{itemize}

\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\iref{input.iterators};

\tcode{F1} and \tcode{F2} are forward iterators\iref{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}.

\end{itemize}

A traits class \tcode{X} meets the regular expression traits requirements

if the following types and expressions are well-formed and have the specified

semantics.

\begin{itemdecl}

typename X::char_type

\end{itemdecl}

\begin{itemdescr}

\tcode{charT},

the character container type used in the implementation of class

template \tcode{basic_regex}.

\end{itemdescr}

\begin{itemdecl}

typename X::string_type

\end{itemdecl}

\begin{itemdescr}

\tcode{basic_string<charT>}

\end{itemdescr}

\begin{itemdecl}

typename X::locale_type

\end{itemdecl}

\begin{itemdescr}

A copy constructible type

that represents the locale used by the traits class.

\end{itemdescr}

\begin{itemdecl}

typename X::char_class_type

\end{itemdecl}

\begin{itemdescr}

A bitmask type\iref{bitmask.types}

representing a particular character classification.

\end{itemdescr}

\begin{itemdecl}

X::length(p)

\end{itemdecl}

\begin{itemdescr}

\tcode{size_t}

The smallest \tcode{i} such that \tcode{p[i] == 0}.

Linear in \tcode{i}.

\end{itemdescr}

\begin{itemdecl}

v.translate(c)

\end{itemdecl}

\begin{itemdescr}

\tcode{X::char_type}

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

\end{itemdescr}

\begin{itemdecl}

v.translate_nocase(c)

\end{itemdecl}

\begin{itemdescr}

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

\end{itemdescr}

\begin{itemdecl}

v.transform(F1, F2)

\end{itemdecl}

\begin{itemdescr}

\tcode{X::string_type}

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

\end{itemdescr}

\begin{itemdecl}

v.transform_primary(F1, F2)

\end{itemdecl}

\begin{itemdescr}

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

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

\tcode{X::string_type}

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

\end{itemdescr}

\begin{itemdecl}

v.lookup_collatename(F1, F2)

\end{itemdecl}

\begin{itemdescr}

\tcode{X::string_type}

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.

\end{itemdescr}

\begin{itemdecl}

v.lookup_classname(F1, F2, b)

\end{itemdecl}

\begin{itemdescr}

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

\end{itemdescr}

\begin{itemdecl}

v.isctype(c, cl)

\end{itemdecl}

\begin{itemdescr}

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

\end{itemdescr}

\begin{itemdecl}

v.value(c, I)

\end{itemdecl}

\begin{itemdescr}

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

\end{itemdescr}

\begin{itemdecl}

u.imbue(loc)

\end{itemdecl}

\begin{itemdescr}

\tcode{X::locale_type}

\indextext{locale}%

Imbues \tcode{u} with the locale \tcode{loc} and

returns the previous locale used by \tcode{u} if any.

\end{itemdescr}

\begin{itemdecl}

v.getloc()

\end{itemdecl}

\begin{itemdescr}

\tcode{X::locale_type}

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

\end{itemdescr}

\begin{note}

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

regular expression traits class when it is specialized for

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

the header \libheader{regex}, and is described in \ref{re.traits}.

\end{note}

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

\indexheader{regex}%

\indexlibraryglobal{basic_regex}%

\indexlibraryglobal{regex}%

\indexlibraryglobal{wregex}%

\begin{codeblock}

#include <compare> // see \ref{compare.syn}

#include <initializer_list> // see \ref{initializer.list.syn}

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>

auto operator<=>(const sub_match<BiIter>& 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>

auto operator<=>(

const sub_match<BiIter>& lhs,

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

template<class BiIter>

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

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

template<class BiIter>

auto 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>

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

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

\rSec2[re.const.general]{General}

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

\indexlibraryglobal{syntax_option_type}%

\indexlibrarymember{regex_constants}{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}

\indexlibraryglobal{syntax_option_type}%

\indexlibrarymember{syntax_option_type}{icase}%

\indexlibrarymember{syntax_option_type}{nosubs}%

\indexlibrarymember{syntax_option_type}{optimize}%

\indexlibrarymember{syntax_option_type}{collate}%

\indexlibrarymember{syntax_option_type}{ECMAScript}%

\indexlibrarymember{syntax_option_type}{basic}%

\indexlibrarymember{syntax_option_type}{extended}%

\indexlibrarymember{syntax_option_type}{awk}%

\indexlibrarymember{syntax_option_type}{grep}%

\indexlibrarymember{syntax_option_type}{egrep}%

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

type\iref{bitmask.types}. Setting its elements has the effects listed in

\tref{re.synopt}. 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}

{re.synopt}

\tcode{icase} &

Specifies that matching of regular expressions against a character

container sequence shall be performed without regard to case.

\indexlibrarymember{syntax_option_type}{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} object.

\indexlibrarymember{syntax_option_type}{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.

\indexlibrarymember{syntax_option_type}{optimize}%

\\ \rowsep

\tcode{collate} &

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

sensitive.%

\indexlibrarymember{syntax_option_type}{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}.

\newline \xref ECMA-262 15.10

\indextext{ECMAScript}%

\indexlibrarymember{syntax_option_type}{ECMAScript}%

\\ \rowsep

\tcode{basic} &

Specifies that the grammar recognized by the regular expression engine

shall be that used by basic regular expressions in POSIX.

\newline \xref POSIX, Base Definitions and Headers, Section 9.3

\indextext{POSIX!regular expressions}%

\indexlibrarymember{syntax_option_type}{basic}%

\\ \rowsep

\tcode{extended} &

Specifies that the grammar recognized by the regular expression engine

shall be that used by extended regular expressions in POSIX.

\newline \xref POSIX, Base Definitions and Headers, Section 9.4

\indextext{POSIX!extended regular expressions}%

\indexlibrarymember{syntax_option_type}{extended}%

\\ \rowsep

\tcode{awk} &

Specifies that the grammar recognized by the regular expression engine

shall be that used by the utility awk in POSIX.

\indexlibrarymember{syntax_option_type}{awk}%

\\ \rowsep

\tcode{grep} &

Specifies that the grammar recognized by the regular expression engine

shall be that used by the utility grep in POSIX.

\indexlibrarymember{syntax_option_type}{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.

\indexlibrarymember{syntax_option_type}{egrep}%

\\ \rowsep

\tcode{multiline} &

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

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

if the \tcode{ECMAScript} engine is selected.

\indexlibrarymember{syntax_option_type}{multiline}%

\end{libefftab}

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

\indexlibraryglobal{match_flag_type}%

\indexlibrarymember{regex_constants}{match_flag_type}%

\indexlibraryglobal{match_default}%

\indexlibraryglobal{match_not_bol}%

\indexlibraryglobal{match_not_eol}%

\indexlibraryglobal{match_not_bow}%

\indexlibraryglobal{match_not_eow}%

\indexlibraryglobal{match_any}%

\indexlibraryglobal{match_not_null}%

\indexlibraryglobal{match_continuous}%

\indexlibraryglobal{match_prev_avail}%

\indexlibraryglobal{format_default}%

\indexlibraryglobal{format_sed}%

\indexlibraryglobal{format_no_copy}%

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

\indexlibraryglobal{match_flag_type}%

The type \tcode{match_flag_type} is an

\impldef{type of \tcode{regex_constants::match_flag_type}} bitmask type\iref{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 \tref{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}.}

{re.matchflag}

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

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

\indexlibraryglobal{match_not_bow}%

\tcode{match_not_bow} &

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

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

\\ \rowsep

\indexlibraryglobal{match_not_eow}%

\tcode{match_not_eow} &

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

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

\\ \rowsep

\indexlibraryglobal{match_any}%

\tcode{match_any} &

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

acceptable result.

\\ \rowsep

\indexlibraryglobal{match_not_null}%

\tcode{match_not_null} &

The expression shall not match an empty

sequence.

\\ \rowsep

\indexlibraryglobal{match_continuous}%

\tcode{match_continuous} &

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

\tcode{first}.

\\ \rowsep

\indexlibraryglobal{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\iref{re.alg} and iterators\iref{re.iter}.

\\ \rowsep

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

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

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

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

\indexlibraryglobal{error_type}%

\indexlibrarymember{regex_constants}{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}

\indexlibraryglobal{error_type}%

\indexlibrarymember{regex_constants}{error_type}%

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

\tcode{regex_constants::error_type}} enumerated type\iref{enumerated.types}.

Values of type \tcode{error_type} represent the error

conditions described in \tref{re.err}:

\begin{longliberrtab}

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

{re.err}

\tcode{error_collate}

&

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

\tcode{error_ctype}

&

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

\tcode{error_escape}

&

The expression contains an invalid escaped character, or a trailing

escape. \\ \rowsep

\tcode{error_backref}

&

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

\tcode{error_brack}

&

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

\tcode{error_paren}

&

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

\tcode{error_brace}

&

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

\tcode{error_badbrace}

&

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

\tcode{error_range}

&

The expression contains an invalid character range, such as

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

\tcode{error_space}

&

There is insufficient memory to convert the expression into a finite

state machine. \\ \rowsep

\tcode{error_badrepeat}

&

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

\tcode{error_complexity}

&

The complexity of an attempted match against a regular expression

exceeds a pre-set level. \\ \rowsep

\tcode{error_stack}

&

There is insufficient memory to determine whether the regular

expression matches the specified character sequence. \\

\end{longliberrtab}

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

\indexlibraryglobal{regex_error}%

\begin{codeblock}

namespace std {

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.

\indexlibraryctor{regex_error}%

\begin{itemdecl}

regex_error(regex_constants::error_type ecode);

\end{itemdecl}

\begin{itemdescr}

\tcode{ecode == code()}.

\end{itemdescr}

\indexlibraryglobal{error_type}%

\indexlibrarymember{regex_constants}{error_type}%

\begin{itemdecl}

regex_constants::error_type code() const;

\end{itemdecl}

\begin{itemdescr}