%!TEX root = std.tex
\rSec0[re]{Regular expressions library}
\indextext{regular expression|(}

\rSec1[re.general]{General}


\pnum
This Clause describes components that \Cpp programs may use to 
perform operations involving regular expression matching and
searching.

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

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

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

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

\pnum
\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
\endfirsthead
\continuedcaption\\
\hline
\lhdr{Expression} & \chdr{Return type} & \rhdr{Assertion/note pre-/post-condition } \\ \capsep
\endhead
%%
\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}

\pnum
\enternote
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}.
\exitnote

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

\pnum
\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 {
  namespace 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}

\pnum
\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}
%
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
%
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
%
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
%
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
%
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
%
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
%
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
%
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
%
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
%
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 {
  namespace 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}

\pnum
\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}}%
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}}%
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}}%
match_not_bow &
The expression \verb|"\\b"| shall not match the
sub-sequence \range{first}{first}. 
\\ \rowsep
%
\indexlibrary{\idxcode{match_not_eow}}%
match_not_eow &
The expression \verb|"\\b"| shall not match the
sub-sequence \range{last}{last}.
\\ \rowsep
%
\indexlibrary{\idxcode{match_any}}%
match_any &
If more than one match is possible then any match is an
acceptable result. 
\\ \rowsep
%
\indexlibrary{\idxcode{match_not_null}}%
match_not_null &
The expression shall not match an empty
sequence. 
\\ \rowsep
%
\indexlibrary{\idxcode{match_continuous}}%
match_continuous &
The expression shall only match a sub-sequence that begins at
\tcode{first}.
\\ \rowsep
%
\indexlibrary{\idxcode{match_prev_avail}}%
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}}%
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}}%
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}}%
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}}%
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 {
  namespace 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}

\pnum
\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.  \\
\rowsep
%
\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 std::runtime_error {
  public:
    explicit regex_error(regex_constants::error_type ecode);
    regex_constants::error_type code() const;
}; 
\end{codeblock}

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

\pnum\postcondition:  \tcode{ecode == code()}
\end{itemdescr}

\indexlibrary{\idxcode{error_type}}%
\indexlibrary{\idxcode{regex_constants}!\idxcode{error_type}}%
\begin{itemdecl}
regex_constants::error_type code() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  The error code that was passed to the constructor.
\end{itemdescr}

\rSec1[re.traits]{Class template \tcode{regex_traits}}
\indexlibrary{\idxcode{regex_traits}}%
\begin{codeblock}
namespace std {
  template <class charT>
  struct regex_traits {
  public:
     typedef charT                        char_type;
     typedef std::basic_string<char_type> string_type;
     typedef std::locale                  locale_type;
     typedef @{\itshape bitmask_type}@                 char_class_type;

     regex_traits();
     static std::size_t length(const char_type* p);
     charT translate(charT c) const;
     charT translate_nocase(charT c) const;
     template <class ForwardIterator>
       string_type transform(ForwardIterator first, ForwardIterator last) const;
     template <class ForwardIterator>
       string_type transform_primary(
         ForwardIterator first, ForwardIterator last) const;
     template <class ForwardIterator>
       string_type lookup_collatename(
         ForwardIterator first, ForwardIterator last) const;
     template <class ForwardIterator>
       char_class_type lookup_classname(
         ForwardIterator first, ForwardIterator last, bool icase = false) const;
     bool isctype(charT c, char_class_type f) const;
     int value(charT ch, int radix) const;
     locale_type imbue(locale_type l);
     locale_type getloc() const;
  };
}
\end{codeblock}

\pnum
\indextext{regular expression traits!requirements}%
\indextext{requirements!regular expression traits}%
\indextext{\idxcode{regex_traits}!specializations}%
The specializations \tcode{regex_traits<char>} and
\tcode{regex_traits<wchar_t>} shall be valid and shall satisfy the
requirements for a regular expression traits class~(\ref{re.req}).

\indexlibrary{\idxcode{regex_traits}!\idxcode{char_class_type}}%
\indexlibrary{\idxcode{char_class_type}!\idxcode{regex_traits}}%
\begin{itemdecl}
typedef @\textit{bitmask_type}@                 char_class_type; 
\end{itemdecl}

\begin{itemdescr}
\pnum
The type \tcode{char_class_type} is used to represent a character
classification and is capable of holding an implementation specific
set returned by \tcode{lookup_classname}.
\end{itemdescr}

\indexlibrary{\idxcode{length}!\idxcode{regex_traits}}%
\indexlibrary{\idxcode{regex_traits}!\idxcode{length}}%
\begin{itemdecl}
static std::size_t length(const char_type* p); 
\end{itemdecl}

\begin{itemdescr}
\pnum\returns \tcode{char_traits<charT>::length(p);}
\end{itemdescr}

\indexlibrary{\idxcode{regex_traits}!\idxcode{translate}}%
\indexlibrary{\idxcode{translate}!\idxcode{regex_traits}}%
\begin{itemdecl}
charT translate(charT c) const; 
\end{itemdecl}

\begin{itemdescr}
\pnum\returns \tcode{(c)}.
\end{itemdescr}

\indexlibrary{\idxcode{regex_traits}!\idxcode{translate_nocase}}%
\indexlibrary{\idxcode{translate_nocase}!\idxcode{regex_traits}}%
\begin{itemdecl}
charT translate_nocase(charT c) const; 
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{use_facet<ctype<charT> >(getloc()).tolower(c)}.
\end{itemdescr}

\indexlibrary{\idxcode{regex_traits}!\idxcode{transform}}%
\indexlibrary{\idxcode{transform}!\idxcode{regex_traits}}%
\begin{itemdecl}
template <class ForwardIterator>
  string_type transform(ForwardIterator first, ForwardIterator last) const; 
\end{itemdecl}

\begin{itemdescr}
\pnum\effects
\begin{codeblock}
string_type str(first, last);
return use_facet<collate<charT> >(
  getloc()).transform(&*str.begin(), &*str.begin() + str.length());
\end{codeblock}
\end{itemdescr}

\indexlibrary{\idxcode{regex_traits}!\idxcode{transform_primary}}%
\indexlibrary{\idxcode{transform_primary}!\idxcode{regex_traits}}%
\begin{itemdecl}
template <class ForwardIterator>
  string_type transform_primary(ForwardIterator first, ForwardIterator last) const; 
\end{itemdecl}

\begin{itemdescr}
\pnum\effects  if \tcode{typeid(use_facet<collate<charT> >) 
== typeid(collate_byname<charT>)}
and the form of the sort key returned
by \tcode{collate_byname<charT> \colcol transform(first, last)} is known and
can be converted into a primary sort key then returns that key,
otherwise returns an empty string.
\end{itemdescr}

\indexlibrary{\idxcode{regex_traits}!\idxcode{lookup_collatename}}%
\indexlibrary{\idxcode{lookup_collatename}!\idxcode{regex_traits}}%
\begin{itemdecl}
template <class ForwardIterator>
  string_type lookup_collatename(ForwardIterator first, ForwardIterator last) const; 
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  a sequence of one or more characters that
represents the collating element consisting of the character
sequence designated by the iterator range \range{first}{last}.
Returns an empty string if the character sequence is not a
valid collating element.
\end{itemdescr}

\indexlibrary{\idxcode{regex_traits}!\idxcode{lookup_classname}}%
\indexlibrary{\idxcode{lookup_classname}!\idxcode{regex_traits}}%
\begin{itemdecl}
template <class ForwardIterator>
  char_class_type lookup_classname(
    ForwardIterator first, ForwardIterator last, bool icase = false) const; 
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  an unspecified value that represents
the character classification named by the character sequence
designated by the iterator range \range{first}{last}.
If the parameter \tcode{icase} is true then the returned mask identifies the
character classification without regard to the case of the characters being
matched, otherwise it does honor the case of the characters being
matched.\footnote{For example, if the parameter \tcode{icase} is true then
\tcode{[[:lower:]]} is the same as \tcode{[[:alpha:]]}.}
The value
returned shall be independent of the case of the characters in
the character sequence. If the name
is not recognized then returns \tcode{char_class_type()}.

\pnum
\notes  For \tcode{regex_traits<char>}, at least the narrow character names
in Table~\ref{tab:re.traits.classnames} shall be recognized.
For \tcode{regex_traits<wchar_t>}, at least the wide character names
in Table~\ref{tab:re.traits.classnames} shall be recognized.
\end{itemdescr}

\indexlibrary{\idxcode{regex_traits}!\idxcode{isctype}}%
\indexlibrary{\idxcode{isctype}!\idxcode{regex_traits}}%
\begin{itemdecl}
bool isctype(charT c, char_class_type f) const; 
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects  Determines if the character \tcode{c} is a member of the character
classification represented by \tcode{f}.

\pnum
\returns Given the following function prototype:
\begin{codeblock}
// for exposition only
template<class C>
  ctype_base::mask convert(typename regex_traits<C>::char_class_type f);
\end{codeblock}
that returns a value in which each \tcode{ctype_base::mask} value corresponding to
a value in \tcode{f} named in Table~\ref{tab:re.traits.classnames} is set, then the
result is determined as if by:
\begin{codeblock}
ctype_base::mask m = convert<charT>(f);
const ctype<charT>& ct = use_facet<ctype<charT>>(getloc());
if (ct.is(m, c)) {
  return true;
} else if (c == ct.widen('_')) {
  charT w[1] = { ct.widen('w') };
  char_class_type x = lookup_classname(w, w+1);
  
  return (f&x) == x;
} else {
  return false;
} 
\end{codeblock}
\enterexample
\begin{codeblock}

regex_traits<char> t;
string d("d");
string u("upper");
regex_traits<char>::char_class_type f;
f = t.lookup_classname(d.begin(), d.end());
f |= t.lookup_classname(u.begin(), u.end());
ctype_base::mask m = convert<char>(f); // \tcode{m == ctype_base::digit|ctype_base::upper}
\end{codeblock}
\exitexample
\enterexample
\begin{codeblock}

regex_traits<char> t;
string w("w");
regex_traits<char>::char_class_type f;
f = t.lookup_classname(w.begin(), w.end());
t.isctype('A', f); // returns \tcode{true}
t.isctype('_', f); // returns \tcode{true}
t.isctype(' ', f); // returns \tcode{false}
\end{codeblock}
\exitexample

\end{itemdescr}

\indexlibrary{\idxcode{value}!\idxcode{regex_traits}}%
\indexlibrary{\idxcode{regex_traits}!\idxcode{value}}%
\begin{itemdecl}
int value(charT ch, int radix) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\precondition  The value of \textit{radix} shall be 8, 10, or 16.

\pnum
\returns  the value represented by the digit \textit{ch} in base
\textit{radix} if the character \textit{ch} is a valid digit in base
\textit{radix}; otherwise returns -1.
\end{itemdescr}

\indexlibrary{\idxcode{locale}}%
\indexlibrary{\idxcode{imbue}}%
\begin{itemdecl}
locale_type imbue(locale_type loc); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects  Imbues \tcode{this} with a copy of the
locale \tcode{loc}. \enternote Calling \tcode{imbue} with a
different locale than the one currently in use invalidates all cached
data held by \tcode{*this}. \exitnote

\pnum
\returns  if no locale has been previously imbued then a copy of the
global locale in effect at the time of construction of \tcode{*this},
otherwise a copy of the last argument passed to \tcode{imbue}.

\pnum
\postcondition  \tcode{getloc() == loc}.
\end{itemdescr}

\indexlibrary{\idxcode{locale}}%
\indexlibrary{\idxcode{getloc}}%
\begin{itemdecl}
locale_type getloc() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns  if no locale has been imbued then a copy of the global locale
in effect at the time of construction of \tcode{*this}, otherwise a copy of
the last argument passed to \tcode{imbue}.
\end{itemdescr}

\begin{floattable}{Character class names and corresponding \tcode{ctype} masks}{tab:re.traits.classnames}{lll}
\topline
\lhdr{Narrow character name} & \chdr{Wide character name} & \rhdr{Corresponding \tcode{ctype_base::mask} value} \\\capsep
\tcode{"alnum"}  & \tcode{L"alnum"}  & \tcode{ctype_base::alnum}  \\ \rowsep
\tcode{"alpha"}  & \tcode{L"alpha"}  & \tcode{ctype_base::alpha}  \\ \rowsep
\tcode{"blank"}  & \tcode{L"blank"}  & \tcode{ctype_base::blank}  \\ \rowsep
\tcode{"cntrl"}  & \tcode{L"cntrl"}  & \tcode{ctype_base::cntrl}  \\ \rowsep
\tcode{"digit"}  & \tcode{L"digit"}  & \tcode{ctype_base::digit}  \\ \rowsep
\tcode{"d"}      & \tcode{L"d"}      & \tcode{ctype_base::digit}  \\ \rowsep
\tcode{"graph"}  & \tcode{L"graph"}  & \tcode{ctype_base::graph}  \\ \rowsep
\tcode{"lower"}  & \tcode{L"lower"}  & \tcode{ctype_base::lower}  \\ \rowsep
\tcode{"print"}  & \tcode{L"print"}  & \tcode{ctype_base::print}  \\ \rowsep
\tcode{"punct"}  & \tcode{L"punct"}  & \tcode{ctype_base::punct}  \\ \rowsep
\tcode{"space"}  & \tcode{L"space"}  & \tcode{ctype_base::space}  \\ \rowsep
\tcode{"s"}      & \tcode{L"s"}      & \tcode{ctype_base::space}  \\ \rowsep
\tcode{"upper"}  & \tcode{L"upper"}  & \tcode{ctype_base::upper}  \\ \rowsep
\tcode{"w"}      & \tcode{L"w"}      & \tcode{ctype_base::alnum}  \\ \rowsep
\tcode{"xdigit"} & \tcode{L"xdigit"} & \tcode{ctype_base::xdigit} \\ \rowsep
\end{floattable}

\rSec1[re.regex]{Class template \tcode{basic_regex}}
\indexlibrary{\idxcode{basic_regex}}%

\pnum
For a char-like type \tcode{charT}, specializations of class
template \tcode{basic_regex} represent regular expressions constructed
from character sequences of \tcode{charT} characters.  In the rest
of~\ref{re.regex}, \tcode{charT} denotes a given char-like
type. Storage for a regular expression is allocated and freed as
necessary by the member functions of class \tcode{basic_regex}.

\pnum
Objects of type specialization of \tcode{basic_regex} are responsible for
converting the sequence of \tcode{charT} objects to an internal
representation. It is not specified what form this representation
takes, nor how it is accessed by algorithms that operate on regular
expressions. \enternote Implementations will typically declare
some function templates as friends of \tcode{basic_regex} to achieve
this \exitnote

\pnum
\indexlibrary{\idxcode{regex_error}}%
The functions described in this Clause report errors by throwing
exceptions of type \tcode{regex_error}.

\indexlibrary{\idxcode{basic_regex}}%
\begin{codeblock}
namespace std {
  template <class charT,
            class traits = regex_traits<charT> >
  class basic_regex {
  public:
    // types:
    typedef          charT                                value_type;
    typedef          traits                               traits_type;
    typedef typename traits::string_type                  string_type;
    typedef          regex_constants::syntax_option_type  flag_type;
    typedef typename traits::locale_type                  locale_type;

    // \ref{re.regex.const}, constants:
    static constexpr regex_constants::syntax_option_type
      icase = regex_constants::icase;
    static constexpr regex_constants::syntax_option_type
      nosubs = regex_constants::nosubs;
    static constexpr regex_constants::syntax_option_type
      optimize = regex_constants::optimize;
    static constexpr regex_constants::syntax_option_type
      collate = regex_constants::collate;
    static constexpr regex_constants::syntax_option_type
      ECMAScript = regex_constants::ECMAScript;
    static constexpr regex_constants::syntax_option_type
      basic = regex_constants::basic;
    static constexpr regex_constants::syntax_option_type
      extended = regex_constants::extended;
    static constexpr regex_constants::syntax_option_type
      awk = regex_constants::awk;
    static constexpr regex_constants::syntax_option_type
      grep = regex_constants::grep;
    static constexpr regex_constants::syntax_option_type
      egrep = regex_constants::egrep;

    // \ref{re.regex.construct}, construct/copy/destroy:
    basic_regex();
    explicit basic_regex(const charT* p,
      flag_type f = regex_constants::ECMAScript);
    basic_regex(const charT* p, size_t len, flag_type f = regex_constants::ECMAScript);
    basic_regex(const basic_regex&);
    basic_regex(basic_regex&&) noexcept;
    template <class ST, class SA>
      explicit basic_regex(const basic_string<charT, ST, SA>& p, 
                           flag_type f = regex_constants::ECMAScript);
    template <class ForwardIterator>
      basic_regex(ForwardIterator first, ForwardIterator last, 
                  flag_type f = regex_constants::ECMAScript);
    basic_regex(initializer_list<charT>,
      flag_type = regex_constants::ECMAScript);

    ~basic_regex();

    basic_regex& operator=(const basic_regex&);
    basic_regex& operator=(basic_regex&&) noexcept;
    basic_regex& operator=(const charT* ptr);
    basic_regex& operator=(initializer_list<charT> il);
    template <class ST, class SA>
      basic_regex& operator=(const basic_string<charT, ST, SA>& p);

    // \ref{re.regex.assign}, assign:
    basic_regex& assign(const basic_regex& that);
    basic_regex& assign(basic_regex&& that) noexcept;
    basic_regex& assign(const charT* ptr,
      flag_type f = regex_constants::ECMAScript);
    basic_regex& assign(const charT* p, size_t len, flag_type f);
    template <class string_traits, class A>
      basic_regex& assign(const basic_string<charT, string_traits, A>& s,
                          flag_type f = regex_constants::ECMAScript);
    template <class InputIterator>
      basic_regex& assign(InputIterator first, InputIterator last,
                          flag_type f = regex_constants::ECMAScript);
    basic_regex& assign(initializer_list<charT>,
                        flag_type = regex_constants::ECMAScript);

    // \ref{re.regex.operations}, const operations:
    unsigned mark_count() const;
    flag_type flags() const;

    // \ref{re.regex.locale}, locale:
    locale_type imbue(locale_type loc);
    locale_type getloc() const;

    // \ref{re.regex.swap}, swap:
    void swap(basic_regex&);
  }; 
}
\end{codeblock}

\rSec2[re.regex.const]{\tcode{basic_regex} constants}
\indexlibrary{\idxcode{basic_regex}!constants}%

\begin{codeblock}
static constexpr regex_constants::syntax_option_type
  icase = regex_constants::icase;
static constexpr regex_constants::syntax_option_type
  nosubs = regex_constants::nosubs;
static constexpr regex_constants::syntax_option_type
  optimize = regex_constants::optimize;
static constexpr regex_constants::syntax_option_type
  collate = regex_constants::collate;
static constexpr regex_constants::syntax_option_type
  ECMAScript = regex_constants::ECMAScript;
static constexpr regex_constants::syntax_option_type
  basic = regex_constants::basic;
static constexpr regex_constants::syntax_option_type
  extended = regex_constants::extended;
static constexpr regex_constants::syntax_option_type
  awk = regex_constants::awk;
static constexpr regex_constants::syntax_option_type
  grep = regex_constants::grep;
static constexpr regex_constants::syntax_option_type
  egrep = regex_constants::egrep;
\end{codeblock}

\pnum
\indexlibrary{\idxcode{basic_regex}!constants}%
The static constant members are provided as synonyms for the constants
declared in namespace \tcode{regex_constants}.

\rSec2[re.regex.construct]{\tcode{basic_regex} constructors}
\indexlibrary{\idxcode{basic_regex}!\idxcode{basic_regex}}%

\indexlibrary{\idxcode{basic_regex}!constructor}%
\begin{itemdecl}
basic_regex();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects  Constructs an object of class \tcode{basic_regex} that
does not match any character sequence.
\end{itemdescr}

\indexlibrary{\idxcode{basic_regex}!\idxcode{basic_regex}}%
\begin{itemdecl}
explicit basic_regex(const charT* p, flag_type f = regex_constants::ECMAScript);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires  \textit{p} shall not be a null pointer. 

\pnum
\throws  \tcode{regex_error} if \textit{p} is not a valid regular expression. 

\pnum
\effects  Constructs an object of class \tcode{basic_regex}; the object's
internal finite state machine is constructed from the regular
expression contained in the array of \tcode{charT} of length
\tcode{char_traits<charT>::\brk{}length(p)} whose first element is
designated by \textit{p}, and interpreted according to the flags \textit{f}.

\pnum\postconditions
\tcode{flags()} returns \tcode{f}.  
\tcode{mark_count()} returns the number of marked sub-expressions
within the expression.
\end{itemdescr}

\indexlibrary{\idxcode{basic_regex}!\idxcode{basic_regex}}%
\begin{itemdecl}
basic_regex(const charT* p, size_t len, flag_type f);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires  \textit{p} shall not be a null pointer.

\pnum
\throws  \tcode{regex_error} if \textit{p} is not a valid regular expression. 

\pnum
\effects  Constructs an object of class \tcode{basic_regex}; the object's
internal finite state machine is constructed from the regular
expression contained in the sequence of characters \range{p}{p+len}, and
interpreted according the flags specified in \textit{f}. 

\pnum\postconditions
\tcode{flags()} returns \tcode{f}.  
\tcode{mark_count()} returns the number of marked sub-expressions
within the expression.
\end{itemdescr}

\indexlibrary{\idxcode{basic_regex}!\idxcode{basic_regex}}%
\begin{itemdecl}
basic_regex(const basic_regex& e); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects  Constructs an object of class \tcode{basic_regex} as a copy of
the object \tcode{e}.

\pnum\postconditions
\tcode{flags()} and \tcode{mark_count()} return 
\tcode{e.flags()} and \tcode{e.mark_count()}, respectively.
\end{itemdescr}

\indexlibrary{\idxcode{basic_regex}!\idxcode{basic_regex}}%
\begin{itemdecl}
basic_regex(basic_regex&& e) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects  Move constructs an object of class \tcode{basic_regex} from \tcode{e}.

\pnum
\postconditions \tcode{flags()} and \tcode{mark_count()} return the values that
\tcode{e.flags()} and \tcode{e.mark_count()}, respectively, had before construction.
\tcode{e} is in a valid state with unspecified value.
\end{itemdescr}

\indexlibrary{\idxcode{basic_regex}!\idxcode{basic_regex}}%
\begin{itemdecl}
template <class ST, class SA>
  explicit basic_regex(const basic_string<charT, ST, SA>& s,
                       flag_type f = regex_constants::ECMAScript);
\end{itemdecl}

\begin{itemdescr}
\pnum
\throws  \tcode{regex_error} if \tcode{s} is not a valid regular expression. 

\pnum
\effects  Constructs an object of class \tcode{basic_regex}; the object's
internal finite state machine is constructed from the regular
expression contained in the string \tcode{s}, and interpreted according to the
flags specified in \tcode{f}.

\pnum\postconditions
\tcode{flags()} returns \tcode{f}.  
\tcode{mark_count()} returns the number of marked sub-expressions
within the expression.
\end{itemdescr}

\indexlibrary{\idxcode{basic_regex}!\idxcode{basic_regex}}%
\begin{itemdecl}
template <class ForwardIterator>
  basic_regex(ForwardIterator first, ForwardIterator last,
              flag_type f = regex_constants::ECMAScript);
\end{itemdecl}

\begin{itemdescr}
\pnum
\throws  \tcode{regex_error} if the sequence \range{first}{last} is not a
valid regular expression.

\pnum
\effects  Constructs an object of class \tcode{basic_regex}; the object's
internal finite state machine is constructed from the regular
expression contained in the sequence of characters \range{first}{last}, and
interpreted according to the flags specified in \tcode{f}.

\pnum\postconditions
\tcode{flags()} returns \tcode{f}.  
\tcode{mark_count()} returns the number of marked sub-expressions
within the expression.
\end{itemdescr}

\indexlibrary{\idxcode{basic_regex}!constructor}%
\begin{itemdecl}
basic_regex(initializer_list<charT> il,
            flag_type f = regex_constants::ECMAScript);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Same as \tcode{basic_regex(il.begin(), il.end(), f)}.
\end{itemdescr}

\rSec2[re.regex.assign]{\tcode{basic_regex} assign}

\indexlibrary{\idxcode{basic_regex}!\idxcode{operator=}}%
\indexlibrary{\idxcode{operator=}!\idxcode{basic_regex}}%
\begin{itemdecl}
basic_regex& operator=(const basic_regex& e); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects  returns \tcode{assign(e)}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_regex}!\idxcode{operator=}}%
\indexlibrary{\idxcode{operator=}!\idxcode{basic_regex}}%
\begin{itemdecl}
basic_regex& operator=(basic_regex&& e) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects  returns \tcode{assign(std::move(e))}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_regex}!\idxcode{operator=}}%
\indexlibrary{\idxcode{operator=}!\idxcode{basic_regex}}%
\begin{itemdecl}
basic_regex& operator=(const charT* ptr); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires  \tcode{ptr} shall not be a null pointer. 

\pnum
\effects  returns \tcode{assign(ptr)}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_regex}!\idxcode{operator=}}%
\indexlibrary{\idxcode{operator=}!\idxcode{basic_regex}}%
\begin{itemdecl}
basic_regex& operator=(initializer_list<charT> il);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects  returns \tcode{assign(il.begin(), il.end())}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_regex}!\idxcode{operator=}}%
\indexlibrary{\idxcode{operator=}!\idxcode{basic_regex}}%
\begin{itemdecl}
template <class ST, class SA>
  basic_regex& operator=(const basic_string<charT, ST, SA>& p); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects  returns \tcode{assign(p)}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_regex}!\idxcode{assign}}%
\indexlibrary{\idxcode{assign}!\idxcode{basic_regex}}%
\begin{itemdecl}
basic_regex& assign(const basic_regex& that); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects  copies \tcode{that} into \tcode{*this} and returns \tcode{*this}.

\pnum\postconditions
\tcode{flags()} and \tcode{mark_count()} return
\tcode{that.flags()} and \tcode{that.mark_count()}, respectively.
\end{itemdescr}

\indexlibrary{\idxcode{basic_regex}!\idxcode{assign}}%
\indexlibrary{\idxcode{assign}!\idxcode{basic_regex}}%
\begin{itemdecl}
basic_regex& assign(basic_regex&& that) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects  move assigns from \tcode{that} into \tcode{*this} and returns \tcode{*this}.

\pnum
\postconditions \tcode{flags()} and \tcode{mark_count()} return the values that
\tcode{that.flags()} and \tcode{that.mark_count()}, respectively, had before assignment.
\tcode{that} is in a valid state with unspecified value.
\end{itemdescr}

\indexlibrary{\idxcode{basic_regex}!\idxcode{assign}}%
\indexlibrary{\idxcode{assign}!\idxcode{basic_regex}}%
\begin{itemdecl}
basic_regex& assign(const charT* ptr, flag_type f = regex_constants::ECMAScript); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns  \tcode{assign(string_type(ptr), f)}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_regex}!\idxcode{assign}}%
\indexlibrary{\idxcode{assign}!\idxcode{basic_regex}}%
\begin{itemdecl}
basic_regex& assign(const charT* ptr, size_t len,
  flag_type f = regex_constants::ECMAScript);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns \tcode{assign(string_type(ptr, len), f)}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_regex}!\idxcode{assign}}%
\indexlibrary{\idxcode{assign}!\idxcode{basic_regex}}%
\begin{itemdecl}
template <class string_traits, class A>
  basic_regex& assign(const basic_string<charT, string_traits, A>& s,
                      flag_type f = regex_constants::ECMAScript); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\throws  \tcode{regex_error} if \tcode{s} is not a valid regular expression. 

\pnum
\returns  \tcode{*this}.

\pnum
\effects  Assigns the regular expression contained in the string
\tcode{s}, interpreted according the flags specified in \tcode{f}. 
If an exception is thrown, \tcode{*this} is unchanged.  

\pnum
\postconditions
If no exception is thrown,
\tcode{flags()} returns \tcode{f} and \tcode{mark_count()}
returns the number of marked sub-expressions within the expression.
\end{itemdescr}

\indexlibrary{\idxcode{basic_regex}!\idxcode{assign}}%
\indexlibrary{\idxcode{assign}!\idxcode{basic_regex}}%
\begin{itemdecl}
template <class InputIterator>
  basic_regex& assign(InputIterator first, InputIterator last,
                      flag_type f = regex_constants::ECMAScript);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires  The type \tcode{InputIterator} shall satisfy the requirements for an Input
Iterator~(\ref{input.iterators}).

\pnum
\returns  \tcode{assign(string_type(first, last), f)}.
\end{itemdescr}

\indexlibrary{\idxcode{assign}!\idxcode{basic_regex}}%
\indexlibrary{\idxcode{basic_regex}!\idxcode{assign}}%
\begin{itemdecl}
basic_regex& assign(initializer_list<charT> il,
                    flag_type f = regex_constants::ECMAScript);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Same as \tcode{assign(il.begin(), il.end(), f)}.

\pnum
\returns \tcode{*this}.
\end{itemdescr}


\rSec2[re.regex.operations]{\tcode{basic_regex} constant operations}

\indexlibrary{\idxcode{mark_count}!\idxcode{basic_regex}}%
\indexlibrary{\idxcode{basic_regex}!\idxcode{mark_count}}%
\begin{itemdecl}
unsigned mark_count() const; 
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects  Returns the number of marked sub-expressions within the
regular expression.
\end{itemdescr}

\indexlibrary{\idxcode{flag_type}!\idxcode{basic_regex}}%
\indexlibrary{\idxcode{basic_regex}!\idxcode{flag_type}}%
\begin{itemdecl}
flag_type flags() const; 
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects  Returns a copy of the regular expression syntax flags that
were passed to the object's constructor or to the last call
to \tcode{assign}.
\end{itemdescr}

\rSec2[re.regex.locale]{\tcode{basic_regex} locale}%
\indexlibrary{\idxcode{locale}}

\indexlibrary{\idxcode{imbue}!\idxcode{basic_regex}}%
\indexlibrary{\idxcode{basic_regex}!\idxcode{imbue}}%
\begin{itemdecl}
locale_type imbue(locale_type loc);
\end{itemdecl}

\begin{itemdescr}
\pnum\effects  Returns the result of \tcode{traits_inst.imbue(loc)} where
\tcode{traits_inst} is a (default initialized) instance of the template
type argument \tcode{traits} stored within the object.  After a call
to \tcode{imbue} the \tcode{basic_regex} object does not match any
character sequence.
\end{itemdescr}

\indexlibrary{\idxcode{getloc}!\idxcode{basic_regex}}%
\indexlibrary{\idxcode{basic_regex}!\idxcode{getloc}}%
\begin{itemdecl}
locale_type getloc() const; 
\end{itemdecl}

\begin{itemdescr}
\pnum\effects  Returns the result of \tcode{traits_inst.getloc()} where
\tcode{traits_inst} is a (default initialized) instance of the template
parameter \tcode{traits} stored within the object.
\end{itemdescr}

\rSec2[re.regex.swap]{\tcode{basic_regex} swap}
\indexlibrary{\idxcode{basic_regex}!\idxcode{swap}}%
\indexlibrary{\idxcode{swap}!\idxcode{basic_regex}}%

\indexlibrary{\idxcode{swap}!\idxcode{basic_regex}}%
\indexlibrary{\idxcode{basic_regex}!\idxcode{swap}}%
\begin{itemdecl}
void swap(basic_regex& e); 
\end{itemdecl}

\begin{itemdescr}
\pnum\effects  Swaps the contents of the two regular expressions. 

\pnum\postcondition  \tcode{*this} contains the regular expression
that was in \tcode{e}, \tcode{e} contains the regular expression that
was in \tcode{*this}. 

\pnum\complexity Constant time. 
\end{itemdescr}

\rSec2[re.regex.nonmemb]{\tcode{basic_regex} non-member functions}

\rSec3[re.regex.nmswap]{\tcode{basic_regex} non-member swap}
\indexlibrary{\idxcode{basic_regex}!\idxcode{swap}}%
\indexlibrary{\idxcode{swap}!\idxcode{basic_regex}}%
\begin{itemdecl}
template <class charT, class traits>
  void swap(basic_regex<charT, traits>& lhs, basic_regex<charT, traits>& rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum\effects  Calls \tcode{lhs.swap(rhs)}.
\end{itemdescr}

\rSec1[re.submatch]{Class template \tcode{sub_match}}
\pnum
\indexlibrary{\idxcode{sub_match}}%
Class template \tcode{sub_match} denotes the sequence of characters matched
by a particular marked sub-expression.

\begin{codeblock}
namespace std {
  template <class BidirectionalIterator>
  class sub_match : public std::pair<BidirectionalIterator, BidirectionalIterator> {
  public:
     typedef typename iterator_traits<BidirectionalIterator>::
       value_type                                               value_type;
     typedef typename iterator_traits<BidirectionalIterator>::
       difference_type                                          difference_type;
     typedef BidirectionalIterator                              iterator;
     typedef basic_string<value_type>                           string_type;

     bool matched;

     constexpr sub_match();

     difference_type length() const;
     operator string_type() const;
     string_type str() const;

     int compare(const sub_match& s) const;
     int compare(const string_type& s) const;
     int compare(const value_type* s) const;
  }; 
}
\end{codeblock}


\rSec2[re.submatch.members]{\tcode{sub_match} members}

\indexlibrary{\idxcode{sub_match}!constructor}%
\begin{itemdecl}
constexpr sub_match();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Value-initializes the \tcode{pair} base class subobject and the member
\tcode{matched}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{length}}%
\indexlibrary{\idxcode{length}!\idxcode{sub_match}}%
\begin{itemdecl}
difference_type length() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{(matched ? distance(first, second) : 0)}.
\end{itemdescr}

\indexlibrary{\idxcode{operator basic_string}!\idxcode{sub_match}}%
\indexlibrary{\idxcode{sub_match}!\idxcode{operator basic_string}}%
\begin{itemdecl}
operator string_type() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns \tcode{matched ? string_type(first, second) : string_type()}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{str}}%
\indexlibrary{\idxcode{str}!\idxcode{sub_match}}%
\begin{itemdecl}
string_type str() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{matched ? string_type(first, second) : string_type()}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{compare}}%
\indexlibrary{\idxcode{compare}!\idxcode{sub_match}}%
\begin{itemdecl}
int compare(const sub_match& s) const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{str().compare(s.str())}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{compare}}%
\indexlibrary{\idxcode{compare}!\idxcode{sub_match}}%
\begin{itemdecl}
int compare(const string_type& s) const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{str().compare(s)}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{compare}}%
\indexlibrary{\idxcode{compare}!\idxcode{sub_match}}%
\begin{itemdecl}
int compare(const value_type* s) const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{str().compare(s)}.
\end{itemdescr}

\rSec2[re.submatch.op]{\tcode{sub_match} non-member operators}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator==}}%
\indexlibrary{\idxcode{operator==}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter>
  bool operator==(const sub_match<BiIter>& lhs, const sub_match<BiIter>& rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{lhs.compare(rhs) == 0}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator"!=}}%
\indexlibrary{\idxcode{operator"!=}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter>
  bool operator!=(const sub_match<BiIter>& lhs, const sub_match<BiIter>& rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum\returns \tcode{lhs.compare(rhs) != 0}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator<}}%
\indexlibrary{\idxcode{operator<}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter>
  bool operator<(const sub_match<BiIter>& lhs, const sub_match<BiIter>& rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{lhs.compare(rhs) < 0}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator<=}}%
\indexlibrary{\idxcode{operator<=}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter>
  bool operator<=(const sub_match<BiIter>& lhs, const sub_match<BiIter>& rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{lhs.compare(rhs) <= 0}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator>=}}%
\indexlibrary{\idxcode{operator>=}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter>
  bool operator>=(const sub_match<BiIter>& lhs, const sub_match<BiIter>& rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{lhs.compare(rhs) >= 0}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator>}}%
\indexlibrary{\idxcode{operator>}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter>
  bool operator>(const sub_match<BiIter>& lhs, const sub_match<BiIter>& rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{lhs.compare(rhs) > 0}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator==}}%
\indexlibrary{\idxcode{operator==}!\idxcode{sub_match}}%
\begin{itemdecl}
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);
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{rhs.compare(lhs.c_str()) == 0}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator"!=}}%
\indexlibrary{\idxcode{operator"!=}!\idxcode{sub_match}}%
\begin{itemdecl}
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);
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{!(lhs == rhs)}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator<}}%
\indexlibrary{\idxcode{operator<}!\idxcode{sub_match}}%
\begin{itemdecl}
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);
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{rhs.compare(lhs.c_str()) > 0}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator>}}%
\indexlibrary{\idxcode{operator>}!\idxcode{sub_match}}%
\begin{itemdecl}
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);
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{rhs < lhs}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator>=}}%
\indexlibrary{\idxcode{operator>=}!\idxcode{sub_match}}%
\begin{itemdecl}
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);
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{!(lhs < rhs)}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator<=}}%
\indexlibrary{\idxcode{operator<=}!\idxcode{sub_match}}%
\begin{itemdecl}
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);
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{!(rhs < lhs)}.
\end{itemdescr}

\indexlibrary{\idxcode{operator==}!\idxcode{sub_match}}%
\indexlibrary{\idxcode{sub_match}!\idxcode{operator==}}%
\begin{itemdecl}
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);
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{lhs.compare(rhs.c_str()) == 0}.
\end{itemdescr}

\indexlibrary{\idxcode{operator"!=}!\idxcode{sub_match}}%
\indexlibrary{\idxcode{sub_match}!\idxcode{operator"!=}}%
\begin{itemdecl}
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);
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{!(lhs == rhs)}.
\end{itemdescr}

\indexlibrary{\idxcode{operator>}!\idxcode{sub_match}}%
\indexlibrary{\idxcode{sub_match}!\idxcode{operator<}}%
\begin{itemdecl}
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);
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{lhs.compare(rhs.c_str()) < 0}.
\end{itemdescr}

\indexlibrary{\idxcode{operator>}!\idxcode{sub_match}}%
\indexlibrary{\idxcode{sub_match}!\idxcode{operator>}}%
\begin{itemdecl}
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);
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{rhs < lhs}.
\end{itemdescr}

\indexlibrary{\idxcode{operator>=}!\idxcode{sub_match}}%
\indexlibrary{\idxcode{sub_match}!\idxcode{operator>=}}%
\begin{itemdecl}
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);
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{!(lhs < rhs)}.
\end{itemdescr}

\indexlibrary{\idxcode{operator<=}!\idxcode{sub_match}}%
\indexlibrary{\idxcode{sub_match}!\idxcode{operator<=}}%
\begin{itemdecl}
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);
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{!(rhs < lhs)}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator==}}%
\indexlibrary{\idxcode{operator==}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter> 
  bool operator==(typename iterator_traits<BiIter>::value_type const* lhs, 
                  const sub_match<BiIter>& rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{rhs.compare(lhs) == 0}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator"!=}}%
\indexlibrary{\idxcode{operator"!=}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter> 
  bool operator!=(typename iterator_traits<BiIter>::value_type const* lhs, 
                  const sub_match<BiIter>& rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{!(lhs == rhs)}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator<}}%
\indexlibrary{\idxcode{operator<}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter> 
  bool operator<(typename iterator_traits<BiIter>::value_type const* lhs, 
                 const sub_match<BiIter>& rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{rhs.compare(lhs) > 0}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator>}}%
\indexlibrary{\idxcode{operator>}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter> 
  bool operator>(typename iterator_traits<BiIter>::value_type const* lhs, 
                 const sub_match<BiIter>& rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{rhs < lhs}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator>=}}%
\indexlibrary{\idxcode{operator>=}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter> 
  bool operator>=(typename iterator_traits<BiIter>::value_type const* lhs, 
                  const sub_match<BiIter>& rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{!(lhs < rhs)}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator<=}}%
\indexlibrary{\idxcode{operator<=}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter> 
  bool operator<=(typename iterator_traits<BiIter>::value_type const* lhs, 
                  const sub_match<BiIter>& rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{!(rhs < lhs)}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator==}}%
\indexlibrary{\idxcode{operator==}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter> 
  bool operator==(const sub_match<BiIter>& lhs, 
                  typename iterator_traits<BiIter>::value_type const* rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{lhs.compare(rhs) == 0}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator"!=}}%
\indexlibrary{\idxcode{operator"!=}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter> 
  bool operator!=(const sub_match<BiIter>& lhs, 
                  typename iterator_traits<BiIter>::value_type const* rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{!(lhs == rhs)}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator<}}%
\indexlibrary{\idxcode{operator<}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter> 
  bool operator<(const sub_match<BiIter>& lhs, 
                 typename iterator_traits<BiIter>::value_type const* rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{lhs.compare(rhs) < 0}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator>}}%
\indexlibrary{\idxcode{operator>}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter> 
  bool operator>(const sub_match<BiIter>& lhs, 
                 typename iterator_traits<BiIter>::value_type const* rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{rhs < lhs}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator>=}}%
\indexlibrary{\idxcode{operator>=}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter> 
  bool operator>=(const sub_match<BiIter>& lhs, 
                  typename iterator_traits<BiIter>::value_type const* rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{!(lhs < rhs)}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator<=}}%
\indexlibrary{\idxcode{operator<=}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter> 
  bool operator<=(const sub_match<BiIter>& lhs, 
                  typename iterator_traits<BiIter>::value_type const* rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns  \tcode{!(rhs < lhs)}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator==}}%
\indexlibrary{\idxcode{operator==}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter> 
  bool operator==(typename iterator_traits<BiIter>::value_type const& lhs, 
                  const sub_match<BiIter>& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns \tcode{rhs.compare(typename sub_match<BiIter>::string_type(1, lhs)) == 0}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator"!=}}%
\indexlibrary{\idxcode{operator"!=}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter> 
  bool operator!=(typename iterator_traits<BiIter>::value_type const& lhs, 
                  const sub_match<BiIter>& rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns \tcode{!(lhs == rhs)}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator<}}%
\indexlibrary{\idxcode{operator<}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter> 
  bool operator<(typename iterator_traits<BiIter>::value_type const& lhs, 
                 const sub_match<BiIter>& rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns \tcode{rhs.compare(typename sub_match<BiIter>::string_type(1, lhs)) > 0}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator>}}%
\indexlibrary{\idxcode{operator>}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter> 
  bool operator>(typename iterator_traits<BiIter>::value_type const& lhs, 
                 const sub_match<BiIter>& rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns \tcode{rhs < lhs}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator>=}}%
\indexlibrary{\idxcode{operator>=}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter> 
  bool operator>=(typename iterator_traits<BiIter>::value_type const& lhs, 
                  const sub_match<BiIter>& rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns \tcode{!(lhs < rhs)}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator<=}}%
\indexlibrary{\idxcode{operator<=}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter> 
  bool operator<=(typename iterator_traits<BiIter>::value_type const& lhs, 
                  const sub_match<BiIter>& rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns \tcode{!(rhs < lhs)}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator==}}%
\indexlibrary{\idxcode{operator==}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter> 
  bool operator==(const sub_match<BiIter>& lhs, 
                  typename iterator_traits<BiIter>::value_type const& rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns \tcode{lhs.compare(typename sub_match<BiIter>::string_type(1, rhs)) == 0}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator"!=}}%
\indexlibrary{\idxcode{operator"!=}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter> 
  bool operator!=(const sub_match<BiIter>& lhs, 
                  typename iterator_traits<BiIter>::value_type const& rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns \tcode{!(lhs == rhs)}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator<}}%
\indexlibrary{\idxcode{operator<}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter> 
  bool operator<(const sub_match<BiIter>& lhs, 
                 typename iterator_traits<BiIter>::value_type const& rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns \tcode{lhs.compare(typename sub_match<BiIter>::string_type(1, rhs)) < 0}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator>}}%
\indexlibrary{\idxcode{operator>}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter> 
  bool operator>(const sub_match<BiIter>& lhs, 
                 typename iterator_traits<BiIter>::value_type const& rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns \tcode{rhs < lhs}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator>=}}%
\indexlibrary{\idxcode{operator>=}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter> 
  bool operator>=(const sub_match<BiIter>& lhs, 
                  typename iterator_traits<BiIter>::value_type const& rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns \tcode{!(lhs < rhs)}.
\end{itemdescr}

\indexlibrary{\idxcode{sub_match}!\idxcode{operator<=}}%
\indexlibrary{\idxcode{operator<=}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class BiIter> 
  bool operator<=(const sub_match<BiIter>& lhs, 
                  typename iterator_traits<BiIter>::value_type const& rhs); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns \tcode{!(rhs < lhs)}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_ostream}}%
\indexlibrary{\idxcode{sub_match}!\idxcode{operator<<}}%
\indexlibrary{\idxcode{operator<<}!\idxcode{sub_match}}%
\begin{itemdecl}
template <class charT, class ST, class BiIter>
  basic_ostream<charT, ST>&
  operator<<(basic_ostream<charT, ST>& os, const sub_match<BiIter>& m); 
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{(os <{}< m.str())}.
\end{itemdescr}

\rSec1[re.results]{Class template \tcode{match_results}}
\pnum
\indexlibrary{\idxcode{match_results}}%
Class template \tcode{match_results} denotes a collection of character
sequences representing the result of a regular expression
match. Storage for the collection is allocated and freed as necessary
by the member functions of class template \tcode{match_results}.

\pnum
\indextext{requirements!container}%
\indextext{requirements!sequence}%
\indextext{\idxcode{match_results}!as sequence}%
The class template \tcode{match_results} shall satisfy the requirements of an
allocator-aware container and of a sequence container, as specified
in~\ref{sequence.reqmts}, except that only operations defined for const-qualified
sequence containers are supported.

\pnum
A default-constructed \tcode{match_results} object has no fully established result state. A
match result is \defn{ready} when, as a consequence of a completed regular expression match
modifying such an object, its result state becomes fully established. The effects of calling
most member functions from a \tcode{match_results} object that is not ready are undefined.

\pnum
\indexlibrary{\idxcode{match_results}!\idxcode{matched}}%
The \tcode{sub_match} object stored at index 0 represents sub-expression 0,
i.e., the whole match. In this case the \tcode{sub_match} member
\tcode{matched} is always true. The \tcode{sub_match}
object stored at index \tcode{n} denotes what matched the marked
sub-expression \tcode{n} within the matched expression. If the
sub-expression \tcode{n} participated in a regular expression 
match then the \tcode{sub_match} member \tcode{matched} evaluates to true, and
members \tcode{first} and \tcode{second} denote the range of characters
\range{first}{second} which formed that
match. Otherwise \tcode{matched} is false, and members \tcode{first}
and \tcode{second} point to the end of the sequence 
that was searched. \enternote The \tcode{sub_match} objects representing
different sub-expressions that did not participate in a regular expression
match need not be distinct.\exitnote

\begin{codeblock}
namespace std {
  template <class BidirectionalIterator,
            class Allocator = allocator<sub_match<BidirectionalIterator>>>
  class match_results {
  public: 
     typedef sub_match<BidirectionalIterator>                       value_type;
     typedef const value_type&                                      const_reference;
     typedef value_type&                                            reference;
     typedef @{\impdef}@                                 const_iterator;
     typedef const_iterator                                         iterator;
     typedef typename
      iterator_traits<BidirectionalIterator>::difference_type       difference_type;
     typedef typename allocator_traits<Allocator>::size_type        size_type;
     typedef Allocator                                              allocator_type;
     typedef typename iterator_traits<BidirectionalIterator>::
       value_type                                                   char_type;
     typedef basic_string<char_type>                                string_type;

     // \ref{re.results.const}, construct/copy/destroy:
     explicit match_results(const Allocator& a = Allocator());
     match_results(const match_results& m);
     match_results(match_results&& m) noexcept;
     match_results& operator=(const match_results& m); 
     match_results& operator=(match_results&& m);
     ~match_results();

     // \ref{re.results.state}, state:
     bool ready() const;

     // \ref{re.results.size}, size:
     size_type size() const;
     size_type max_size() const;
     bool empty() const;

     // \ref{re.results.acc}, element access:
     difference_type length(size_type sub = 0) const;
     difference_type position(size_type sub = 0) const;
     string_type str(size_type sub = 0) const;
     const_reference operator[](size_type n) const;

     const_reference prefix() const;
     const_reference suffix() const;
     const_iterator begin() const;
     const_iterator end() const;
     const_iterator cbegin() const;
     const_iterator cend() const;

     // \ref{re.results.form}, format:
     template <class OutputIter>
      OutputIter
      format(OutputIter out,
             const char_type* fmt_first, const char_type* fmt_last,
             regex_constants::match_flag_type flags =
              regex_constants::format_default) const;
     template <class OutputIter, class ST, class SA>
       OutputIter
       format(OutputIter out,
              const basic_string<char_type, ST, SA>& fmt,
              regex_constants::match_flag_type flags =
                regex_constants::format_default) const;
     template <class ST, class SA>
      basic_string<char_type, ST, SA>
      format(const basic_string<char_type, ST, SA>& fmt,
             regex_constants::match_flag_type flags =
               regex_constants::format_default) const;
     string_type
     format(const char_type* fmt,
            regex_constants::match_flag_type flags =
              regex_constants::format_default) const;

     // \ref{re.results.all}, allocator:
     allocator_type get_allocator() const;

     // \ref{re.results.swap}, swap:
     void swap(match_results& that);
  }; 
}
\end{codeblock}

\rSec2[re.results.const]{\tcode{match_results} constructors}
\pnum
In all \tcode{match_results} constructors, a copy of the \tcode{Allocator} argument
shall be used for any memory allocation performed by the constructor
or member functions during the lifetime of the object.

\indexlibrary{\idxcode{match_results}!\idxcode{match_results}}%
\begin{itemdecl}
match_results(const Allocator& a = Allocator()); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects  Constructs an object of class \tcode{match_results}. 

\pnum
\postconditions
\tcode{ready()} returns \tcode{false}.
\tcode{size()} returns \tcode{0}.
\end{itemdescr}

\indexlibrary{\idxcode{match_results}!\idxcode{match_results}}%
\begin{itemdecl}
match_results(const match_results& m); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects  Constructs an object of class \tcode{match_results}, as a
copy of \tcode{m}.
\end{itemdescr}

\indexlibrary{\idxcode{match_results}!\idxcode{match_results}}%
\begin{itemdecl}
match_results(match_results&& m) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects\ Move-constructs an object of class \tcode{match_results} from \tcode{m}
satisfying the same postconditions as Table~\ref{tab:re:results:assign}. Additionally,
the stored \tcode{Allocator} value is move constructed from \tcode{m.get_allocator()}.

\pnum
\throws Nothing.
\end{itemdescr}

\indexlibrary{\idxcode{match_results}!\idxcode{operator=}}%
\indexlibrary{\idxcode{operator=}!\idxcode{match_results}}%
\begin{itemdecl}
match_results& operator=(const match_results& m); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects  Assigns \tcode{m} to \tcode{*this}. The postconditions of this
function are indicated in Table~\ref{tab:re:results:assign}.
\end{itemdescr}

\indexlibrary{\idxcode{match_results}!\idxcode{operator=}}%
\indexlibrary{\idxcode{operator=}!\idxcode{match_results}}%
\begin{itemdecl}
match_results& operator=(match_results&& m);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects\ Move-assigns \tcode{m} to \tcode{*this}. The postconditions of this function
are indicated in Table~\ref{tab:re:results:assign}.
\end{itemdescr}

\begin{libefftabvalue}
  {\tcode{match_results} assignment operator effects}
  {tab:re:results:assign}
\tcode{ready()}         & \tcode{m.ready()}       \\ \rowsep
\tcode{size()}          & \tcode{m.size()}        \\ \rowsep
\tcode{str(n)}          & \tcode{m.str(n)} for all integers \tcode{n < m.size()} \\ \rowsep
\tcode{prefix()}        & \tcode{m.prefix()} \\ \rowsep
\tcode{suffix()}        & \tcode{m.suffix()} \\ \rowsep
\tcode{(*this)[n]}      & \tcode{m[n]} for all integers \tcode{n < m.size()} \\ \rowsep
\tcode{length(n)}       & \tcode{m.length(n)} for all integers \tcode{n < m.size()} \\ \rowsep
\tcode{position(n)}     & \tcode{m.position(n)} for all integers \tcode{n < m.size()} \\ 
\end{libefftabvalue}

\rSec2[re.results.state]{\tcode{match_results} state}

\indexlibrary{\idxcode{match_results}!\idxcode{state}}%
\indexlibrary{\idxcode{state}!\idxcode{match_results}}%
\begin{itemdecl}
bool ready() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns \tcode{true} if \tcode{*this} has a fully established result state, otherwise 
\tcode{false}.
\end{itemdescr}

\rSec2[re.results.size]{\tcode{match_results} size}

\indexlibrary{\idxcode{match_results}!\idxcode{size}}%
\indexlibrary{\idxcode{size}!\idxcode{match_results}}%
\begin{itemdecl}
size_type size() const; 
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  One plus the number of marked sub-expressions in the
regular expression that was matched if \tcode{*this} represents the
result of a successful match.  Otherwise returns \tcode{0}.
\enternote The state of a \tcode{match_results} object can be modified
only by passing that object to \tcode{regex_match} or \tcode{regex_search}.
Sections~\ref{re.alg.match} and~\ref{re.alg.search} specify the
effects of those algorithms on their \tcode{match_results} arguments.
\exitnote
\end{itemdescr}

\indexlibrary{\idxcode{match_results}!\idxcode{max_size}}%
\indexlibrary{\idxcode{max_size}!\idxcode{match_results}}%
\begin{itemdecl}
size_type max_size() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  The maximum number of \tcode{sub_match} elements that can be
stored in \tcode{*this}.
\end{itemdescr} 

\indexlibrary{\idxcode{match_results}!\idxcode{empty}}%
\indexlibrary{\idxcode{empty}!\idxcode{match_results}}%
\begin{itemdecl}
bool empty() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{size() == 0}.
\end{itemdescr}

\rSec2[re.results.acc]{\tcode{match_results} element access}

\indexlibrary{\idxcode{length}!\idxcode{match_results}}%
\indexlibrary{\idxcode{match_results}!\idxcode{length}}%
\begin{itemdecl}
difference_type length(size_type sub = 0) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{ready() == true}.

\pnum
\returns  \tcode{(*this)[sub].length()}.
\end{itemdescr}

\indexlibrary{\idxcode{position}!\idxcode{match_results}}%
\indexlibrary{\idxcode{match_results}!\idxcode{position}}%
\begin{itemdecl}
difference_type position(size_type sub = 0) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{ready() == true}.

\pnum
\returns  The distance from the start of the target sequence
to \tcode{(*this)[sub].first}.
\end{itemdescr} 

\indexlibrary{\idxcode{match_results}!\idxcode{str}}%
\indexlibrary{\idxcode{str}!\idxcode{match_results}}%
\begin{itemdecl}
string_type str(size_type sub = 0) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{ready() == true}.

\pnum
\returns  \tcode{string_type((*this)[sub])}.
\end{itemdescr}

\indexlibrary{\idxcode{match_results}!\idxcode{operator[]}}%
\indexlibrary{\idxcode{operator[]}!\idxcode{match_results}}%
\begin{itemdecl}
const_reference operator[](size_type n) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{ready() == true}.

\pnum
\returns  A reference to the \tcode{sub_match} object representing the
character sequence that matched marked sub-expression \tcode{n}. If \tcode{n == 0}
then returns a reference to a \tcode{sub_match} object representing the
character sequence that matched the whole regular expression. If
\tcode{n >= size()} then returns a \tcode{sub_match} object representing an
unmatched sub-expression.
\end{itemdescr}

\indexlibrary{\idxcode{match_results}!\idxcode{prefix}}%
\indexlibrary{\idxcode{prefix}!\idxcode{match_results}}%
\begin{itemdecl}
const_reference prefix() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{ready() == true}.

\pnum
\returns  A reference to the \tcode{sub_match} object representing the
character sequence from the start of the string being
matched/searched to the start of the match found.  
\end{itemdescr}

\indexlibrary{\idxcode{match_results}!\idxcode{suffix}}%
\indexlibrary{\idxcode{suffix}!\idxcode{match_results}}%
\begin{itemdecl}
const_reference suffix() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{ready() == true}.

\pnum
\returns  A reference to the \tcode{sub_match} object representing the
character sequence from the end of the match found to the end of the
string being matched/searched.  
\end{itemdescr}

\indexlibrary{\idxcode{match_results}!\idxcode{begin}}%
\indexlibrary{\idxcode{begin}!\idxcode{match_results}}%
\begin{itemdecl}
const_iterator begin() const;
const_iterator cbegin() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  A starting iterator that enumerates over all the
sub-expressions stored in \tcode{*this}.
\end{itemdescr}  

\indexlibrary{\idxcode{match_results}!\idxcode{end}}%
\indexlibrary{\idxcode{end}!\idxcode{match_results}}%
\begin{itemdecl}
const_iterator end() const;
const_iterator cend() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  A terminating iterator that enumerates over all the
sub-expressions stored in \tcode{*this}.  
\end{itemdescr}

\rSec2[re.results.form]{\tcode{match_results} formatting}

\indexlibrary{\idxcode{match_results}!\idxcode{format}}%
\indexlibrary{\idxcode{format}!\idxcode{match_results}}%
\begin{itemdecl}
template <class OutputIter>
  OutputIter format(OutputIter out,
                    const char_type* fmt_first, const char_type* fmt_last,
                    regex_constants::match_flag_type flags =
                      regex_constants::format_default) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires\ ready() == true and \tcode{OutputIter} shall satisfy the requirements for an
Output Iterator~(\ref{output.iterators}).

\pnum
\effects Copies the character sequence \range{fmt_first}{fmt_last} to
OutputIter \tcode{out}.  Replaces each format specifier or escape
sequence in the copied range with either the character(s) it represents or
the sequence of characters within \tcode{*this} to which it refers.
The bitmasks specified in \tcode{flags} determine which format
specifiers and escape sequences are recognized.

\pnum
\returns\ \tcode{out}.
\end{itemdescr}

\indexlibrary{\idxcode{match_results}!\idxcode{format}}%
\indexlibrary{\idxcode{format}!\idxcode{match_results}}%
\begin{itemdecl}
template <class OutputIter, class ST, class SA>
  OutputIter format(OutputIter out,
                    const basic_string<char_type, ST, SA>& fmt,
                    regex_constants::match_flag_type flags =
                      regex_constants::format_default) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Equivalent to \tcode{return format(out, fmt.data(),}
\tcode{fmt.data() + fmt.size(), flags)}.
\end{itemdescr}

\indexlibrary{\idxcode{match_results}!\idxcode{format}}%
\indexlibrary{\idxcode{format}!\idxcode{match_results}}%
\begin{itemdecl}
template <class ST, class SA>
  basic_string<char_type, ST, SA>
  format(const basic_string<char_type, ST, SA>& fmt,
         regex_constants::match_flag_type flags =
           regex_constants::format_default) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{ready() == true}.

\pnum
\effects
Constructs an empty string \tcode{result} of type \tcode{basic_string<char_type, ST, SA>} and
calls \tcode{format(back_inserter(result), fmt, flags)}.

\pnum
\returns\ \tcode{result}.
\end{itemdescr}

\indexlibrary{\idxcode{match_results}!\idxcode{format}}%
\indexlibrary{\idxcode{format}!\idxcode{match_results}}%
\begin{itemdecl}
string_type
  format(const char_type* fmt,
         regex_constants::match_flag_type flags =
           regex_constants::format_default) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{ready() == true}.

\pnum
\effects\ Constructs an empty string \tcode{result} of type \tcode{string_type} and
calls\linebreak \tcode{format(back_inserter(result), fmt, fmt +
char_traits<char_type>::length(fmt), flags)}.

\pnum
\returns\ \tcode{result}.
\end{itemdescr}

\rSec2[re.results.all]{\tcode{match_results} allocator}%
\indexlibrary{allocator}

\indexlibrary{\idxcode{get_allocator}!\idxcode{match_results}}%
\indexlibrary{\idxcode{match_results}!\idxcode{get_allocator}}%
\begin{itemdecl}
allocator_type get_allocator() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns A copy of the Allocator that was passed to the object's constructor or, if that
allocator has been replaced, a copy of the most recent replacement.
\end{itemdescr}

\rSec2[re.results.swap]{\tcode{match_results} swap}

\indexlibrary{\idxcode{match_results}!\idxcode{swap}}%
\indexlibrary{\idxcode{swap}!\idxcode{match_results}}%
\begin{itemdecl}
void swap(match_results& that); 
\end{itemdecl}

\begin{itemdescr}
\pnum\effects  Swaps the contents of the two sequences. 

\pnum\postcondition  \tcode{*this} contains the sequence of matched
sub-expressions that were in \tcode{that}, \tcode{that} contains the
sequence of matched sub-expressions that were in \tcode{*this}.

\pnum\complexity Constant time. 
\end{itemdescr}

\indexlibrary{\idxcode{match_results}!\idxcode{swap}}%
\indexlibrary{\idxcode{swap}!\idxcode{match_results}}%
\begin{itemdecl}
template <class BidirectionalIterator, class Allocator>
  void swap(match_results<BidirectionalIterator, Allocator>& m1,
            match_results<BidirectionalIterator, Allocator>& m2);
\end{itemdecl}

\pnum\effects \tcode{m1.swap(m2)}.

\rSec2[re.results.nonmember]{\tcode{match_results} non-member functions}

\indexlibrary{\idxcode{operator==}!\idxcode{match_results}}%
\indexlibrary{\idxcode{match_results}!\idxcode{operator==}}%
\begin{itemdecl}
template <class BidirectionalIterator, class Allocator>
bool operator==(const match_results<BidirectionalIterator, Allocator>& m1,
                const match_results<BidirectionalIterator, Allocator>& m2);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{true} if neither match result is ready, \tcode{false} if one match result is ready and the
other is not. If both match results are ready, returns \tcode{true} only if:

\begin{itemize}
\item
\tcode{m1.empty() \&\& m2.empty()}, or

\item
\tcode{!m1.empty() \&\& !m2.empty()}, and the following conditions are satisfied:

\begin{itemize}
\item
\tcode{m1.prefix() == m2.prefix()},

\item
\tcode{m1.size() == m2.size() \&\& equal(m1.begin(), m1.end(), m2.begin())}, and

\item
\tcode{m1.suffix() == m2.suffix()}.
\end{itemize}
\end{itemize}
\enternote The algorithm \tcode{equal} is defined in Clause~\ref{algorithms}. \exitnote
\end{itemdescr}

\indexlibrary{\idxcode{operator"!=}!\idxcode{match_results}}%
\indexlibrary{\idxcode{match_results}!\idxcode{operator"!=}}%
\begin{itemdecl}
template <class BidirectionalIterator, class Allocator>
bool operator!=(const match_results<BidirectionalIterator, Allocator>& m1,
                const match_results<BidirectionalIterator, Allocator>& m2);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns \tcode{!(m1 == m2)}.
\end{itemdescr}

\rSec1[re.alg]{Regular expression algorithms}

\rSec2[re.except]{exceptions}
\pnum
The algorithms described in this subclause may throw an exception
of type \tcode{regex_error}. If such an exception \tcode{e} is thrown,
\tcode{e.code()} shall return either \tcode{regex_constants::error_complexity}
or \tcode{regex_constants::error_stack}.

\rSec2[re.alg.match]{\tcode{regex_match}}
\indexlibrary{\idxcode{regex_match}}%
\begin{itemdecl}
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);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires  The type \tcode{BidirectionalIterator} shall satisfy the requirements
of a Bidirectional Iterator ~(\ref{bidirectional.iterators}).

\pnum
\effects  Determines whether there is a match between the
regular expression \tcode{e}, and all of the character
sequence \range{first}{last}. The parameter \tcode{flags} is
used to control how the expression is matched against the character
sequence. Returns \tcode{true} if such a match exists, \tcode{false}
otherwise.

\pnum
\postconditions
\tcode{m.ready() == true} in all cases.
If the function returns \tcode{false}, then the effect
on parameter \tcode{m} is unspecified except that \tcode{m.size()}
returns \tcode{0} and \tcode{m.empty()} returns \tcode{true}.
Otherwise the effects on parameter \tcode{m} are given in
Table~\ref{tab:re:alg:match}.
\end{itemdescr}

\begin{longlibefftabvalue}
  {Effects of \tcode{regex_match} algorithm}
  {tab:re:alg:match}
\tcode{m.size()}
&
\tcode{1 + e.mark_count()} 
\\ \rowsep
\tcode{m.empty()}
&
false 
\\ \rowsep
\tcode{m.prefix().first}
&
first 
\\ \rowsep
\tcode{m.prefix().second}
&
first 
\\ \rowsep
\tcode{m.prefix().matched}
&
false 
\\ \rowsep
\tcode{m.suffix().first}
&
last 
\\ \rowsep
\tcode{m.suffix().second}
&
last 
\\ \rowsep
\tcode{m.suffix().matched}
&
false 
\\ \rowsep
\tcode{m[0].first}
&
first 
\\ \rowsep
\tcode{m[0].second}
&
last 
\\ \rowsep
\tcode{m[0].matched}
&
\tcode{true}
\\ \rowsep
\tcode{m[n].first}
&
For all integers \tcode{0 < n < m.size()}, the start of the sequence that matched
sub-expression \tcode{n}. Alternatively, if sub-expression \tcode{n} did not participate
in the match, then \tcode{last}.
\\ \rowsep
\tcode{m[n].second}
&
For all integers \tcode{0 < n < m.size()}, the end of the sequence that matched
sub-expression \tcode{n}. Alternatively, if sub-expression \tcode{n} did not participate
in the match, then \tcode{last}.
\\ \rowsep
\tcode{m[n].matched}
&
For all integers \tcode{0 < n < m.size()}, \tcode{true} if sub-expression \tcode{n} participated in
the match, \tcode{false} otherwise. 
\\ 
\end{longlibefftabvalue}

\indexlibrary{\idxcode{regex_match}}%
\begin{itemdecl}
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); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects  Behaves ``as if'' by constructing an instance of
\tcode{match_results<BidirectionalIterator> what}, and then 
returning the result of \tcode{regex_match(first, last, what, e,
flags)}.
\end{itemdescr}

\indexlibrary{\idxcode{regex_match}}%
\begin{itemdecl}
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); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns  \tcode{regex_match(str, str + char_traits<charT>::length(str), m, e, flags)}.
\end{itemdescr}

\indexlibrary{\idxcode{regex_match}}%
\begin{itemdecl}
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); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns  \tcode{regex_match(s.begin(), s.end(), m, e, flags)}.
\end{itemdescr}

\indexlibrary{\idxcode{regex_match}}%
\begin{itemdecl}
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); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns  \tcode{regex_match(str, str + char_traits<charT>::length(str), e, flags)}
\end{itemdescr}

\indexlibrary{\idxcode{regex_match}}%
\begin{itemdecl}
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); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns  \tcode{regex_match(s.begin(), s.end(), e, flags)}.
\end{itemdescr}

\rSec2[re.alg.search]{\tcode{regex_search}}

\indexlibrary{\idxcode{regex_search}}%
\begin{itemdecl}
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); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires Type \tcode{BidirectionalIterator} shall satisfy the requirements of a Bidirectional
Iterator (\ref{bidirectional.iterators}).

\pnum
\effects Determines whether there is some sub-sequence within \range{first}{last} that matches
the regular expression \tcode{e}. The parameter \tcode{flags} is used to control how the
expression is matched against the character sequence. Returns \tcode{true} if such a sequence
exists, \tcode{false} otherwise.

\pnum
\postconditions
\tcode{m.ready() == true} in all cases.
If the function returns \tcode{false}, then the effect
on parameter \tcode{m} is unspecified except that \tcode{m.size()}
returns \tcode{0} and \tcode{m.empty()} returns \tcode{true}.  Otherwise 
the effects on parameter \tcode{m} are given in Table~\ref{tab:re:alg:search}.
\end{itemdescr}

\begin{longlibefftabvalue}
  {Effects of \tcode{regex_search} algorithm}
  {tab:re:alg:search}
\tcode{m.size()}
&
\tcode{1 + e.mark_count()}
\\ \rowsep
\tcode{m.empty()}
&
\tcode{false}
\\ \rowsep
\tcode{m.prefix().first}
&
\tcode{first}
\\ \rowsep
\tcode{m.prefix().second}
&
\tcode{m[0].first}
\\ \rowsep
\tcode{m.prefix().matched}
&
\tcode{m.prefix().first != m.prefix().second}
\\ \rowsep
\tcode{m.suffix().first}
&
\tcode{m[0].second}
\\ \rowsep
\tcode{m.suffix().second}
&
\tcode{last}
\\ \rowsep
\tcode{m.suffix().matched}
&
\tcode{m.suffix().first != m.suffix().second}
\\ \rowsep
\tcode{m[0].first}
&
The start of the sequence of characters that matched the regular expression
\\ \rowsep
\tcode{m[0].second}
&
The end of the sequence of characters that matched the regular expression
\\ \rowsep
\tcode{m[0].matched}
&
\tcode{true}
\\ \rowsep
\tcode{m[n].first}
&
For all integers \tcode{0 < n < m.size()}, the start of the sequence that
matched sub-expression \tcode{n}. Alternatively, if sub-expression \tcode{n}
did not participate in the match, then \tcode{last}. 
\\ \rowsep
\tcode{m[n].second}
&
For all integers \tcode{0 < n < m.size()}, the end of the sequence that matched
sub-expression \tcode{n}. Alternatively, if sub-expression \tcode{n} did not
participate in the match, then \tcode{last} .
\\ \rowsep
\tcode{m[n].matched}
&
For all integers \tcode{0 < n < m.size()}, \tcode{true} if sub-expression \tcode{n}
participated in the match, \tcode{false} otherwise.
\\ 
\end{longlibefftabvalue}

\indexlibrary{\idxcode{regex_search}}%
\begin{itemdecl}
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); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns  The result of \tcode{regex_search(str, 
str + char_traits<charT>::length(str), m, e, flags)}. 
\end{itemdescr}

\indexlibrary{\idxcode{regex_search}}%
\begin{itemdecl}
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); 
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  The result of \tcode{regex_search(s.begin(), s.end(), m,
e, flags)}.
\end{itemdescr}

\indexlibrary{\idxcode{regex_search}}%
\begin{itemdecl}
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); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects  Behaves ``as if'' by constructing an object \tcode{what}
of type \tcode{match_results<BidirectionalIterator>} and then returning
the result of \tcode{regex_search(first, last, what, e, flags)}.
\end{itemdescr}

\indexlibrary{\idxcode{regex_search}}%
\begin{itemdecl}
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); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns  \tcode{regex_search(str, str + char_traits<charT>::length(str), 
e, flags)}
\end{itemdescr}

\indexlibrary{\idxcode{regex_search}}%
\begin{itemdecl}
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); 
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{regex_search(s.begin(), s.end(), e, flags)}.
\end{itemdescr}

\rSec2[re.alg.replace]{\tcode{regex_replace}}

\indexlibrary{\idxcode{regex_replace}}%
\begin{itemdecl}
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);
\end{itemdecl}

\begin{itemdescr}
\pnum
\indexlibrary{\idxcode{format_no_copy}}%
\indexlibrary{\idxcode{format_first_only}}%
\effects  Constructs a \tcode{regex_iterator} object \tcode{i}
as if by \tcode{regex_iterator<BidirectionalIterator, charT, traits>
i(first, last, e, flags)}, and uses \tcode{i} to enumerate through all
of the matches \tcode{m} of type \tcode{match_results<BidirectionalIterator>} 
that occur within the sequence \range{first}{last}. If no such
matches are found and \tcode{!(flags \&
regex_constants \colcol format_no_copy)} then calls \tcode{out = std::copy(first,
last, out)}.  If any matches are found then, for each such match,
if \tcode{!(flags \& regex_constants::format_no_copy)}, calls 
\tcode{out = std\colcol{}copy(m.prefix().first, m.prefix().second, \brk{}out)}, and
then calls \tcode{out = m.format(out, fmt, flags)}
for the first form of the function and
\tcode{out = m.format(out,} \tcode{fmt, fmt + char_traits<charT>::length(fmt), flags)} for the second. Finally, if such a match
is found and \tcode{!(flags \& regex_constants \colcol format_no_copy)},
calls \tcode{out = std::\brk{}copy(last_m.suffix().first, last_m.suffix().second,
out)} where \tcode{last_m} is a copy of the last match
found. If \tcode{flags \& regex_constants::format_first_only} 
is non-zero then only the first match found is replaced.

\pnum\returns  \tcode{out}.
\end{itemdescr}

\indexlibrary{\idxcode{regex_replace}}%
\begin{itemdecl}
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);
\end{itemdecl}

\begin{itemdescr}
\pnum\effects  Constructs an empty string \tcode{result} of
type \tcode{basic_string<charT, ST, SA>} and calls 
\tcode{regex_replace(back_inserter(result), s.begin(), s.end(), e, fmt,
flags)}.

\pnum
\returns\ \tcode{result}.
\end{itemdescr}

\indexlibrary{\idxcode{regex_replace}}%
\begin{itemdecl}
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);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects  Constructs an empty string \tcode{result} of
type \tcode{basic_string<charT>} and calls 
\tcode{regex_replace(}
\tcode{back_inserter(result), s, s + char_traits<charT>::length(s), e, fmt,
flags)}.

\pnum
\returns\ \tcode{result}.
\end{itemdescr}

\rSec1[re.iter]{Regular expression iterators}

\rSec2[re.regiter]{Class template \tcode{regex_iterator}}
\pnum
\indexlibrary{\idxcode{regex_iterator}}%
\indexlibrary{\idxcode{match_results}}%
The class template \tcode{regex_iterator} is an iterator adaptor.
It represents a new view of an existing iterator sequence, by
enumerating all the occurrences of a regular expression within that
sequence. A \tcode{regex_iterator} uses  \tcode{regex_search} to find successive
regular expression matches within the sequence from which it was
constructed.  After the iterator is constructed, and every time \tcode{operator++} is
used, the iterator finds and stores a value of
\tcode{match_results<BidirectionalIterator>}. If the end of the sequence is
reached (\tcode{regex_search} returns \tcode{false}), the iterator becomes equal to
the end-of-sequence iterator value. The default constructor
constructs an end-of-sequence iterator object,
which is the only legitimate iterator to be used for the end
condition. The result of \tcode{operator*} on an end-of-sequence iterator is not
defined. For any other iterator value a const
\tcode{match_results<BidirectionalIterator>\&} is returned. The result of
\tcode{operator->} on an end-of-sequence iterator is not defined. For any other
iterator value a \tcode{const match_results<BidirectionalIterator>*} is
returned. It is impossible to store things into \tcode{regex_iterator}s. Two
end-of-sequence iterators are always equal. An end-of-sequence
iterator is not equal to a non-end-of-sequence iterator. Two
non-end-of-sequence iterators are equal when they are constructed from
the same arguments.  

\begin{codeblock}
namespace std {
  template <class BidirectionalIterator, 
            class charT = typename iterator_traits<
              BidirectionalIterator>::value_type,
              class traits = regex_traits<charT> >
  class regex_iterator {
  public:
     typedef basic_regex<charT, traits>           regex_type;
     typedef match_results<BidirectionalIterator> value_type;
     typedef std::ptrdiff_t                       difference_type;
     typedef const value_type*                    pointer;
     typedef const value_type&                    reference;
     typedef std::forward_iterator_tag            iterator_category;
   
     regex_iterator();
     regex_iterator(BidirectionalIterator a, BidirectionalIterator b, 
                    const regex_type& re, 
                    regex_constants::match_flag_type m =
                      regex_constants::match_default);
     regex_iterator(BidirectionalIterator a, BidirectionalIterator b,
                    const regex_type&& re,
                    regex_constants::match_flag_type m =
                      regex_constants::match_default) = delete;
     regex_iterator(const regex_iterator&);
     regex_iterator& operator=(const regex_iterator&);
     bool operator==(const regex_iterator&) const;
     bool operator!=(const regex_iterator&) const;
     const value_type& operator*() const;
     const value_type* operator->() const;
     regex_iterator& operator++();
     regex_iterator operator++(int);
  private:
     BidirectionalIterator                begin;  // \expos
     BidirectionalIterator                end;    // \expos
     const regex_type*                    pregex; // \expos
     regex_constants::match_flag_type     flags;  // \expos
     match_results<BidirectionalIterator> match;  // \expos
  }; 
}
\end{codeblock}

\pnum
\indextext{\idxcode{regex_iterator}!end-of-sequence}%
An object of type \tcode{regex_iterator} that is not an end-of-sequence iterator
holds a \textit{zero-length match} if \tcode{match[0].matched == true} and
\tcode{match[0].first == match[0].second}. \enternote For
example, this can occur when the part of the regular expression that
matched consists only of an assertion (such as \verb|'^'|, \verb|'$'|, 
\tcode{'$\backslash$b'}, \tcode{'$\backslash$B'}). \exitnote

\rSec3[re.regiter.cnstr]{\tcode{regex_iterator} constructors}

\indexlibrary{\idxcode{regex_iterator}!\idxcode{regex_iterator}}%
\begin{itemdecl}
regex_iterator(); 
\end{itemdecl}

\begin{itemdescr}
\pnum\effects  Constructs an end-of-sequence iterator.
\end{itemdescr}

\indexlibrary{\idxcode{regex_iterator}!\idxcode{regex_iterator}}%
\begin{itemdecl}
regex_iterator(BidirectionalIterator a, BidirectionalIterator b, 
               const regex_type& re, 
               regex_constants::match_flag_type m = regex_constants::match_default); 
\end{itemdecl}

\begin{itemdescr}
\pnum\effects  Initializes \tcode{begin} and \tcode{end} to
\tcode{a} and \tcode{b}, respectively, sets
\tcode{pregex} to \tcode{\&re}, sets \tcode{flags} to
\tcode{m}, then calls \tcode{regex_search(begin, end, match, *pregex, flags)}. If this
call returns \tcode{false} the constructor sets \tcode{*this} to the end-of-sequence
iterator.
\end{itemdescr}

\rSec3[re.regiter.comp]{\tcode{regex_iterator} comparisons}

\indexlibrary{\idxcode{regex_iterator}!\idxcode{operator==}}%
\indexlibrary{\idxcode{operator==}!\idxcode{regex_iterator}}%
\begin{itemdecl}
bool operator==(const regex_iterator& right) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns  \tcode{true} if \tcode{*this} and \tcode{right} are both end-of-sequence
iterators or if the following conditions all hold:
\begin{itemize}
\item \tcode{begin == right.begin},
\item \tcode{end == right.end},
\item \tcode{pregex == right.pregex},
\item \tcode{flags == right.flags}, and
\item \tcode{match[0] == right.match[0]};
\end{itemize}
otherwise \tcode{false}.
\end{itemdescr}

\indexlibrary{\idxcode{regex_iterator}!\idxcode{operator"!=}}%
\indexlibrary{\idxcode{operator"!=}!\idxcode{regex_iterator}}%
\begin{itemdecl}
bool operator!=(const regex_iterator& right) const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns \tcode{!(*this == right)}.
\end{itemdescr}

\rSec3[re.regiter.deref]{\tcode{regex_iterator} indirection}

\indexlibrary{\idxcode{regex_iterator}!\idxcode{operator*}}%
\indexlibrary{\idxcode{operator*}!\idxcode{regex_iterator}}%
\begin{itemdecl}
const value_type& operator*() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{match}.
\end{itemdescr}

\indexlibrary{\idxcode{operator->}!\idxcode{regex_iterator}}%
\indexlibrary{\idxcode{regex_iterator}!\idxcode{operator->}}%
\begin{itemdecl}
const value_type* operator->() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{\&match}.
\end{itemdescr}

\rSec3[re.regiter.incr]{\tcode{regex_iterator} increment}

\indexlibrary{\idxcode{regex_iterator}!\idxcode{operator++}}%
\indexlibrary{\idxcode{operator++}!\idxcode{regex_iterator}}%
\indexlibrary{\idxcode{regex_iterator}!increment}%
\begin{itemdecl}
regex_iterator& operator++(); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects  Constructs a local variable \tcode{start} of type \tcode{BidirectionalIterator} and
initializes it with the value of \tcode{match[0].second}.

\pnum
If the iterator holds a zero-length match and \tcode{start == end} the operator
sets \tcode{*this} to the end-of-sequence iterator and returns \tcode{*this}.

\pnum
\indexlibrary{\idxcode{match_not_null}}%
\indexlibrary{\idxcode{match_continuous}}%
Otherwise, if the iterator holds a zero-length match the operator calls
\tcode{regex_search(start, end, match, *pregex, flags $|$ regex_constants::match_not_null
$|$ regex_constants::match_}\\\tcode{continuous)}. If the call returns \tcode{true} the operator
returns \tcode{*this}. Otherwise the operator increments \tcode{start} and continues as if
the most recent match was not a zero-length match.

\pnum
\indexlibrary{\idxcode{match_prev_avail}}%
If the most recent match was not a zero-length match, the operator sets
\tcode{flags} to \tcode{flags $|$ regex_constants \colcol match_prev_avail} and 
calls \tcode{regex_search(start, end, match, *pregex, flags)}. If the call returns
\tcode{false} the iterator sets \tcode{*this} to the end-of-sequence iterator. The
iterator then returns \tcode{*this}.

\pnum
In all cases in which the call to \tcode{regex_search} returns \tcode{true},
\tcode{match.prefix().first} shall be equal to the previous value of
\tcode{match[0].second}, and for each index \tcode{i} in the half-open range
\tcode{[0, match.size())} for which \tcode{match[i].matched} is true,
\tcode{match[i].position()}
shall return \tcode{distance(begin, match[i].\brk{}first)}.

\pnum
\enternote This means that \tcode{match[i].position()} gives the
offset from the beginning of the target sequence, which is often not
the same as the offset from the sequence passed in the call
to \tcode{regex_search}. \exitnote

\pnum
It is unspecified how the implementation makes these adjustments.

\pnum
\enternote This means that a compiler may call an
implementation-specific search function, in which case a user-defined
specialization of \tcode{regex_search} will not be
called. \exitnote
\end{itemdescr}

\indexlibrary{\idxcode{regex_iterator}!\idxcode{operator++}}%
\indexlibrary{\idxcode{operator++}!\idxcode{regex_iterator}}%
\begin{itemdecl}
regex_iterator operator++(int); 
\end{itemdecl}

\begin{itemdescr}
\pnum\effects
\begin{codeblock}
regex_iterator tmp = *this;
++(*this);
return tmp;
\end{codeblock}
\end{itemdescr}

\rSec2[re.tokiter]{Class template \tcode{regex_token_iterator}}

\pnum
\indexlibrary{\idxcode{regex_token_iterator}}%
The class template \tcode{regex_token_iterator} is an iterator adaptor; that
is to say it represents a new view of an existing iterator sequence,
by enumerating all the occurrences of a regular expression within that
sequence, and presenting one or more sub-expressions for each match
found. Each position enumerated by the iterator is a \tcode{sub_match} class
template instance that represents what matched a particular sub-expression
within the regular expression.

\pnum
When class \tcode{regex_token_iterator} is used to enumerate a
single sub-expression with index -1 the iterator performs field
splitting: that is to say it enumerates one sub-expression for each section of
the character container sequence that does not match the regular
expression specified.

\pnum
\indexlibrary{\idxcode{match_results}}%
After it is constructed, the iterator finds and stores a value
\tcode{regex_iterator<BidirectionalIterator> position} 
and sets the internal count \tcode{N} to zero. It also maintains a sequence
\tcode{subs} which contains a list of the sub-expressions which will be
enumerated. Every time \tcode{operator++} is used
the count \tcode{N} is incremented; if \tcode{N} exceeds or equals \tcode{subs.size()},
then the iterator increments member \tcode{position}
and sets count \tcode{N} to zero.

\pnum
\indextext{\idxcode{regex_token_iterator}!end-of-sequence}%
If the end of sequence is reached (\tcode{position} is equal to the end of
sequence iterator), the iterator becomes equal to the end-of-sequence
iterator value, unless the sub-expression being enumerated has index -1,
in which case the iterator enumerates one last sub-expression that contains
all the characters from the end of the last regular expression match to the
end of the input sequence being enumerated, provided that this would not be an
empty sub-expression.

\pnum
\indexlibrary{\idxcode{regex_token_iterator}!end-of-sequence}%
The default constructor constructs
an end-of-sequence iterator object, which is the only legitimate
iterator to be used for the end condition. The result of \tcode{operator*} on
an end-of-sequence iterator is not defined. For any other iterator value a
\tcode{const sub_match<BidirectionalIterator>\&} is returned.
The result of \tcode{operator->} on an end-of-sequence iterator
is not defined. For any other iterator value a \tcode{const
sub_match<BidirectionalIterator>*} is returned.

\pnum
\indexlibrary{\idxcode{regex_token_iterator}!\idxcode{operator==}}%
\indexlibrary{\idxcode{operator==}!\idxcode{regex_token_iterator}}%
It is impossible to store things
into \tcode{regex_token_iterator}s. Two end-of-sequence iterators are always
equal. An end-of-sequence iterator is not equal to a
non-end-of-sequence iterator. Two non-end-of-sequence iterators are
equal when they are constructed from the same arguments.

\begin{codeblock}
namespace std {
  template <class BidirectionalIterator, 
            class charT = typename iterator_traits<
              BidirectionalIterator>::value_type,
              class traits = regex_traits<charT> >
  class regex_token_iterator  {
  public:
    typedef basic_regex<charT, traits>       regex_type;
    typedef sub_match<BidirectionalIterator> value_type;
    typedef std::ptrdiff_t                   difference_type;
    typedef const value_type*                pointer;
    typedef const value_type&                reference;
    typedef std::forward_iterator_tag        iterator_category;

    regex_token_iterator();
    regex_token_iterator(BidirectionalIterator a, BidirectionalIterator b, 
                        const regex_type& re, 
                        int submatch = 0, 
                        regex_constants::match_flag_type m =
                          regex_constants::match_default);
    regex_token_iterator(BidirectionalIterator a, BidirectionalIterator b, 
                        const regex_type& re, 
                        const std::vector<int>& submatches, 
                        regex_constants::match_flag_type m =
                          regex_constants::match_default);
    regex_token_iterator(BidirectionalIterator a, BidirectionalIterator b,
                        const regex_type& re,
                        initializer_list<int> submatches,
                        regex_constants::match_flag_type m =
                          regex_constants::match_default);
    template <std::size_t N>
      regex_token_iterator(BidirectionalIterator a, BidirectionalIterator b, 
                        const regex_type& re, 
                        const int (&submatches)[N], 
                        regex_constants::match_flag_type m =
                          regex_constants::match_default);
    regex_token_iterator(BidirectionalIterator a, BidirectionalIterator b,
                         const regex_type&& re,
                         int submatch = 0,
                         regex_constants::match_flag_type m =
                           regex_constants::match_default) = delete;
    regex_token_iterator(BidirectionalIterator a, BidirectionalIterator b,
                         const regex_type&& re,
                         const std::vector<int>& submatches,
                         regex_constants::match_flag_type m =
                           regex_constants::match_default) = delete;
    regex_token_iterator(BidirectionalIterator a, BidirectionalIterator b,
                         const regex_type&& re,
                         initializer_list<int> submatches,
                         regex_constants::match_flag_type m =
                           regex_constants::match_default) = delete;
    template <std::size_t N>
    regex_token_iterator(BidirectionalIterator a, BidirectionalIterator b,
                         const regex_type&& re,
                         const int (&submatches)[N],
                         regex_constants::match_flag_type m =
                           regex_constants::match_default) = delete;                          
    regex_token_iterator(const regex_token_iterator&);
    regex_token_iterator& operator=(const regex_token_iterator&);
    bool operator==(const regex_token_iterator&) const;
    bool operator!=(const regex_token_iterator&) const;
    const value_type& operator*() const;
    const value_type* operator->() const;
    regex_token_iterator& operator++();
    regex_token_iterator operator++(int);
  private:
    typedef
      regex_iterator<BidirectionalIterator, charT, traits> position_iterator; // \expos
    position_iterator position;                                               // \expos
    const value_type* result;                                                 // \expos
    value_type suffix;                                                        // \expos
    std::size_t N;                                                            // \expos
    std::vector<int> subs;                                                    // \expos
  };
}
\end{codeblock}

\pnum
A \textit{suffix iterator} is a \tcode{regex_token_iterator} object
that points to a final sequence of characters at
the end of the target sequence. In a suffix iterator the
member \tcode{result} holds a pointer to the data
member \tcode{suffix}, the value of the member \tcode{suffix.match}
is \tcode{true}, \tcode{suffix.first} points to the beginning of the
final sequence, and \tcode{suffix.second} points to the end of the
final sequence. 

\pnum
\enternote For a suffix iterator, data
member \tcode{suffix.first} is the same as the end of the last match
found, and \tcode{suffix\brk.second} is the same as the end of the target
sequence \exitnote

\pnum
The \textit{current match} is \tcode{(*position).prefix()} if \tcode{subs[N] == -1}, or
\tcode{(*position)[subs[N]]} for any other value of \tcode{subs[N]}.

\rSec3[re.tokiter.cnstr]{\tcode{regex_token_iterator} constructors}

\indexlibrary{\idxcode{regex_token_iterator}!\idxcode{regex_token_iterator}}%
\begin{itemdecl}
regex_token_iterator(); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects  Constructs the end-of-sequence iterator.
\end{itemdescr}

\indexlibrary{\idxcode{regex_token_iterator}!\idxcode{regex_token_iterator}}%
\begin{itemdecl}
regex_token_iterator(BidirectionalIterator a, BidirectionalIterator b, 
                    const regex_type& re, 
                    int submatch = 0, 
                    regex_constants::match_flag_type m =
                     regex_constants::match_default); 

regex_token_iterator(BidirectionalIterator a, BidirectionalIterator b, 
                    const regex_type& re, 
                    const std::vector<int>& submatches, 
                    regex_constants::match_flag_type m =
                     regex_constants::match_default); 

regex_token_iterator(BidirectionalIterator a, BidirectionalIterator b,
                    const regex_type& re, 
                    initializer_list<int> submatches,
                    regex_constants::match_flag_type m =
                      regex_constants::match_default);

template <std::size_t N>
  regex_token_iterator(BidirectionalIterator a, BidirectionalIterator b, 
                    const regex_type& re, 
                    const int (&submatches)[N],
                    regex_constants::match_flag_type m =
                     regex_constants::match_default); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires Each of the initialization values of \tcode{submatches} shall be \tcode{>=
-1}.

\pnum
\effects The first constructor initializes the member \tcode{subs} to hold the single
value \tcode{submatch}. The second constructor initializes the member \tcode{subs} to
hold a copy of the argument \tcode{submatches}. The third and fourth constructors
initialize the member \tcode{subs} to hold a copy of the sequence of integer values
pointed to by the iterator range \range{submatches.begin()}{submatches.end()} and
\range{\&submatches}{\&submatches + N}, respectively.

\pnum
Each constructor then sets \tcode{N} to 0, and \tcode{position} to
\tcode{position_iterator(a, b, re, m)}. If \tcode{position} is not an
end-of-sequence iterator the constructor sets \tcode{result} to the
address of the current match. Otherwise if any of the values stored
in \tcode{subs} is equal to -1 the constructor sets \tcode{*this} to a suffix
iterator that points to the range \range{a}{b}, otherwise the constructor
sets \tcode{*this} to an end-of-sequence iterator.
\end{itemdescr}

\rSec3[re.tokiter.comp]{\tcode{regex_token_iterator} comparisons}

\indexlibrary{\idxcode{regex_token_iterator}!\idxcode{operator==}}%
\indexlibrary{\idxcode{operator==}!\idxcode{regex_token_iterator}}%
\begin{itemdecl}
bool operator==(const regex_token_iterator& right) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns  \tcode{true} if \tcode{*this} and \tcode{right} are both end-of-sequence iterators,
or if \tcode{*this} and \tcode{right} are both suffix iterators and \tcode{suffix == right.suffix};
otherwise returns \tcode{false} if \tcode{*this} or \tcode{right} is an end-of-sequence
iterator or a suffix iterator. Otherwise returns \tcode{true} if \tcode{position == right.position},
\tcode{N == right.N}, and \tcode{subs == right.subs}. Otherwise returns \tcode{false}.
\end{itemdescr}

\indexlibrary{\idxcode{regex_token_iterator}!\idxcode{operator"!=}}%
\indexlibrary{\idxcode{operator"!=}!\idxcode{regex_token_iterator}}%
\begin{itemdecl}
bool operator!=(const regex_token_iterator& right) const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{!(*this == right)}.
\end{itemdescr}

\rSec3[re.tokiter.deref]{\tcode{regex_token_iterator} indirection}

\indexlibrary{\idxcode{regex_token_iterator}!\idxcode{operator*}}%
\indexlibrary{\idxcode{operator*}!\idxcode{regex_token_iterator}}%
\begin{itemdecl}
const value_type& operator*() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{*result}.
\end{itemdescr}


\indexlibrary{\idxcode{operator->}!\idxcode{regex_token_iterator}}%
\indexlibrary{\idxcode{regex_token_iterator}!\idxcode{operator->}}%
\begin{itemdecl}
const value_type* operator->() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns  \tcode{result}.
\end{itemdescr}


\rSec3[re.tokiter.incr]{\tcode{regex_token_iterator} increment}

\indexlibrary{\idxcode{regex_token_iterator}!\idxcode{operator++}}%
\indexlibrary{\idxcode{operator++}!\idxcode{regex_token_iterator}}%
\begin{itemdecl}
regex_token_iterator& operator++(); 
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects  Constructs a local variable \tcode{prev} of
type \tcode{position_iterator}, initialized with the value
of \tcode{position}.

\pnum
If \tcode{*this} is a suffix iterator, sets \tcode{*this} to an
end-of-sequence iterator. 

\pnum
Otherwise, if \tcode{N + 1 < subs.size()}, increments \tcode{N} and
sets \tcode{result} to the address of the current match.

\pnum
Otherwise, sets \tcode{N} to 0 and
increments \tcode{position}. If \tcode{position} is not an
end-of-sequence iterator the operator sets \tcode{result} to the
address of the current match. 

\pnum
Otherwise, if any of the values stored in \tcode{subs} is equal to -1 and
\tcode{prev->suffix().length()} is not 0 the operator sets \tcode{*this} to a
suffix iterator that points to the range \range{prev->suffix().first}{prev->suffix().second}.

\pnum
Otherwise, sets \tcode{*this} to an end-of-sequence iterator.

\returns  \tcode{*this}
\end{itemdescr}

\indexlibrary{\idxcode{regex_token_iterator}!\idxcode{operator++}}%
\indexlibrary{\idxcode{operator++}!\idxcode{regex_token_iterator}}%
\begin{itemdecl}
regex_token_iterator& operator++(int); 
\end{itemdecl}

\begin{itemdescr}
\pnum\effects  Constructs a copy \tcode{tmp} of \tcode{*this}, then calls \tcode{++(*this)}.

\pnum\returns  \tcode{tmp}.
\end{itemdescr}

\rSec1[re.grammar]{Modified ECMAScript regular expression grammar}
\indextext{regular expression!grammar}%
\indextext{grammar!regular expression}%

\pnum
\indexlibrary{\idxcode{basic_regex}}%
\indextext{ECMAScript}%
The regular expression grammar recognized by 
\tcode{basic_regex} objects constructed with the ECMAScript 
flag is that specified by ECMA-262, except as specified below.

\pnum
\indexlibrary{\idxcode{locale}}%
\indextext{regular expression traits}%
Objects of type specialization of \tcode{basic_regex} store within themselves a
default-constructed instance of their \tcode{traits} template parameter, henceforth
referred to as \tcode{traits_inst}. This \tcode{traits_inst} object is used to support localization
of the regular expression; \tcode{basic_regex} member functions shall not call
any locale dependent C or C++ API, including the formatted string input functions.
Instead they shall call the appropriate traits member function to achieve the required effect.

\pnum
The following productions within the ECMAScript grammar are modified as follows:

\begin{codeblock}
ClassAtom ::
  -
  ClassAtomNoDash
  ClassAtomExClass
  ClassAtomCollatingElement
  ClassAtomEquivalence
\end{codeblock}

\pnum
The following new productions are then added:

\begin{codeblock}
ClassAtomExClass ::
  [: ClassName :]

ClassAtomCollatingElement ::
  [. ClassName .]

ClassAtomEquivalence ::
  [= ClassName =]

ClassName ::
  ClassNameCharacter
  ClassNameCharacter ClassName

ClassNameCharacter ::
  SourceCharacter but not one of "." "=" ":"
\end{codeblock}

\pnum
The productions \tcode{ClassAtomExClass}, \tcode{ClassAtomCollatingElement}
and \tcode{ClassAtomEquivalence} provide functionality
equivalent to that of the same features in regular expressions in POSIX.

\pnum
The regular expression grammar may be modified by
any \tcode{regex_constants::syntax_option_type} flags specified when
constructing an object of type specialization of \tcode{basic_regex}
according to the rules in Table \ref{tab:re:syntaxoption}.

\pnum
A \tcode{ClassName} production, when used in \tcode{ClassAtomExClass},
is not valid if \tcode{traits_inst.lookup_classname} returns zero for
that name.  The names recognized as valid \tcode{ClassName}s are
determined by the type of the traits class, but at least the following
names shall be recognized: 
\tcode{alnum}, \tcode{alpha}, \tcode{blank}, \tcode{cntrl}, \tcode{digit}, 
\tcode{graph}, \tcode{lower}, \tcode{print}, \tcode{punct}, \tcode{space}, 
\tcode{upper}, \tcode{xdigit}, \tcode{d}, \tcode{s}, \tcode{w}.
In addition the following expressions shall be equivalent:

\begin{codeblock}
\d and [[:digit:]]

\D and [^[:digit:]]

\s and [[:space:]]

\S and [^[:space:]]

\w and [_[:alnum:]]

\W and [^_[:alnum:]]
\end{codeblock}

\pnum
\indexlibrary{regular expression traits!\idxcode{lookup_collatename}}%
\indexlibrary{\idxcode{lookup_collatename}!regular expression traits}%
A \tcode{ClassName} production when used in
a \tcode{ClassAtomCollatingElement} production is not valid 
if the value returned by \tcode{traits_inst.lookup_collatename} for
that name is an empty string. 

\pnum
\indexlibrary{regular expression traits!\idxcode{isctype}}%
\indexlibrary{\idxcode{isctype}!regular expression traits}%
\indexlibrary{regular expression traits!\idxcode{lookup_classname}}%
\indexlibrary{\idxcode{lookup_classname}!regular expression traits}%
The results from multiple calls
to \tcode{traits_inst.lookup_classname} can be bitwise OR'ed 
together and subsequently passed to \tcode{traits_inst.isctype}.

\pnum
\indexlibrary{regular expression traits!\idxcode{transform_primary}}%
\indextext{\idxcode{transform_primary}!regular expression traits}%
A \tcode{ClassName} production when used in
a \tcode{ClassAtomEquivalence} production is not valid if the value
returned by \tcode{traits_inst.lookup_collatename} for that name is an
empty string or if the value returned by \tcode{traits_inst\brk.transform_primary} 
for the result of the call to \tcode{traits_inst.lookup_collatename}
is an empty string. 

\pnum
\indexlibrary{\idxcode{regex_error}}%
When the sequence of characters being transformed to a finite state
machine contains an invalid class name the translator shall throw an
exception object of type \tcode{regex_error}. 

\pnum
\indexlibrary{\idxcode{regex_error}}%
If the \textit{CV} of a \textit{UnicodeEscapeSequence} is greater than the largest
value that can be held in an object of type \tcode{charT} the translator shall
throw an exception object of type \tcode{regex_error}. \enternote
This means that values of the form \tcode{"uxxxx"} that do not fit in
a character are invalid.  \exitnote

\pnum
Where the regular expression grammar requires the conversion of a sequence of characters
to an integral value, this is accomplished by calling \tcode{traits_inst.value}.

\pnum
\indexlibrary{\idxcode{match_flag_type}}%
The behavior of the internal finite state machine representation when used to match a
sequence of characters is as described in ECMA-262.
The behavior is modified according
to any match_flag_type flags~\ref{re.matchflag} specified when using the regular expression
object in one of the regular expression algorithms~\ref{re.alg}. The behavior is also
localized by interaction with the traits class template parameter as follows:

\begin{itemize}
\item During matching of a regular expression finite state machine
against a sequence of characters, two characters \tcode{c}
and \tcode{d} are compared using the following rules: 
\begin{enumerate}
\item if \tcode{(flags() \& regex_constants::icase)} the two characters are equal
if \tcode{traits_inst.trans\-late_nocase(c) == traits_inst.translate_nocase(d)};
\indextext{regular expression traits!\idxcode{translate_nocase}}%
\indextext{\idxcode{translate_nocase}!regular expression traits}%
\item otherwise, if \tcode{flags() \& regex_constants::collate} the
two characters are equal if 
\tcode{traits_inst\brk.translate(c) == traits_inst\brk.translate(d)};
\indexlibrary{\idxcode{syntax_option_type}!\idxcode{collate}}%
\indextext{regular expression traits!\idxcode{translate}}%
\indextext{\idxcode{translate}!regular expression traits}%
\item otherwise, the two characters are equal if \tcode{c == d}.
\end{enumerate}

\item During matching of a regular expression finite state machine
against a sequence of characters, comparison of a collating element
range \tcode{c1-c2} against a character \tcode{c} is 
conducted as follows: if \tcode{flags() \& regex_constants \colcol
collate} is false then the character \tcode{c} is matched if \tcode{c1
<= c \&\& c <= c2}, otherwise \tcode{c} is matched in 
accordance with the following algorithm:

\indextext{regular expression traits!\idxcode{translate}}%
\indextext{\idxcode{translate}!regular expression traits}%
\indextext{regular expression traits!\idxcode{translate_nocase}}%
\indextext{\idxcode{translate_nocase}!regular expression traits}%
\indextext{regular expression traits!\idxcode{transform}}%
\indextext{\idxcode{transform}!regular expression traits}%
\begin{codeblock}
string_type str1 = string_type(1,
  flags() & icase ?
    traits_inst.translate_nocase(c1) : traits_inst.translate(c1);
string_type str2 = string_type(1,
  flags() & icase ?
    traits_inst.translate_nocase(c2) : traits_inst.translate(c2);
string_type str = string_type(1,
  flags() & icase ?
    traits_inst.translate_nocase(c) : traits_inst.translate(c);
return traits_inst.transform(str1.begin(), str1.end())
      <= traits_inst.transform(str.begin(), str.end())
  && traits_inst.transform(str.begin(), str.end())
      <= traits_inst.transform(str2.begin(), str2.end());
\end{codeblock}

\item During matching of a regular expression finite state machine against a sequence of
characters, testing whether a collating element is a member of a primary equivalence
class is conducted by first converting the collating element and the equivalence
class to sort keys using \tcode{traits::transform_primary}, and then comparing the sort
keys for equality.
\indextext{regular expression traits!\idxcode{transform_primary}}%
\indextext{transform_primary@\tcode{transform_primaryl}!regular expression traits}%

\item During matching of a regular expression finite state machine against a sequence
of characters, a character \tcode{c} is a member of a character class designated by an
iterator range \range{first}{last} if
\tcode{traits_inst.isctype(c, traits_inst.lookup_classname(first, last, flags() \& icase))} is \tcode{true}.
\indextext{regular expression traits!\idxcode{lookup_classname}}%
\indextext{\idxcode{lookup_classname}!regular expression traits}%
\end{itemize}
\indextext{regular expression|)}
