strings.tex

\rSec0[strings]{Strings library}

\rSec1[strings.general]{General}

\pnum
This Clause describes components for manipulating sequences of
any non-array POD~(\ref{basic.types}) type.
In this Clause such types are called \term{char-like types}\indextext{char-like type},
and objects of
char-like types are called \term{char-like objects}\indextext{char-like object} or
simply \term{characters}.

\pnum
The following subclauses describe a
character traits class, a string class, and
null-terminated sequence utilities,
as summarized in Table~\ref{tab:strings.lib.summary}.

\begin{libsumtab}{Strings library summary}{tab:strings.lib.summary}
\ref{char.traits}     & Character traits                    & \tcode{<string>}  \\ \rowsep
\ref{string.classes}  & String classes                      & \tcode{<string>}  \\ \rowsep
                      &                                     & \tcode{<cctype>}  \\
                      &                                     & \tcode{<cwctype>} \\
\ref{c.strings}       & Null-terminated sequence utilities  & \tcode{<cstring>} \\
                      &                                     & \tcode{<cwchar>}  \\
                      &                                     & \tcode{<cstdlib>} \\
                      &                                     & \tcode{<cuchar>}  \\
\end{libsumtab}

\rSec1[char.traits]{Character traits}

\pnum
This subclause defines requirements on classes representing
\term{character traits},
and defines a class template
\tcode{char_traits<charT>},
along with four specializations,
\tcode{char_traits<char>},
\tcode{char_traits<char16_t>},\\
\tcode{char_traits<char32_t>},
and
\tcode{char_traits<wchar_t>},
that satisfy those requirements.

\pnum
Most classes specified in Clauses~\ref{string.classes}
and~\ref{input.output} need a set of related types and functions
to complete the definition of their semantics.
These types and functions are provided as a set of member typedefs
and functions in the template parameter `traits' used by each such
template.
This subclause defines the semantics of these
members.

\pnum
To specialize those templates to generate a string or
iostream class to handle a particular character container type
\tcode{CharT},
that and its related character traits class
\tcode{Traits}
are passed as a pair of parameters to the string or iostream template as
formal parameters
\tcode{charT}
and
\tcode{traits}.
\tcode{Traits::char_type}
shall be the same as
\tcode{CharT}.

\pnum
This subclause specifies a struct template,
\tcode{char_traits<charT>},
and four explicit specializations of it,
\tcode{char_traits<\brk{}char>},
\tcode{char_traits<char16_t>},
\tcode{char_traits<char32_t>},
and
\tcode{char_traits<wchar_t>},
all of which appear in the header
\tcode{<string>}
and satisfy the requirements below.

\rSec2[char.traits.require]{Character traits requirements}

\pnum
In Table~\ref{tab:char.traits.require},
\tcode{X}
denotes a Traits class defining types and functions for the
character container type
\tcode{CharT};
\tcode{c}
and
\tcode{d}
denote values of type
\tcode{CharT};
\tcode{p}
and
\tcode{q}
denote values of type
\tcode{const CharT*};
\tcode{s}
denotes a value of type
\tcode{CharT*};
\tcode{n},
\tcode{i}
and
\tcode{j}
denote values of type
\tcode{std::size_t};
\tcode{e}
and
\tcode{f}
denote values of type
\tcode{X::int_type};
\tcode{pos}
denotes a value of type
\tcode{X::pos_type};
\tcode{state}
denotes a value of type
\tcode{X::state_type};
and
\tcode{r}
denotes an lvalue of type
\tcode{CharT}.
Operations on Traits shall not throw exceptions.

\begin{libreqtab4d}
{Character traits requirements}
{tab:char.traits.require}
\\ \topline
\lhdr{Expression}       &   \chdr{Return type}  &   \chdr{Assertion/note}   &   \rhdr{Complexity}\\
                        &                       &   \chdr{pre-/post-condition}   &               \\ \capsep
\endfirsthead
\continuedcaption\\
\topline
\lhdr{Expression}       &   \chdr{Return type}  &   \chdr{Assertion/note}   &   \rhdr{Complexity}\\
                        &                       &   \chdr{pre-/post-condition}   &               \\ \capsep
\endhead
\tcode{X::char_type}    &   \tcode{charT}       &
(described in~\ref{char.traits.typedefs})   &   compile-time    \\ \rowsep
\tcode{X::int_type} &                       &
(described in~\ref{char.traits.typedefs})   &   compile-time    \\ \rowsep
\tcode{X::off_type} &                       &
(described in~\ref{char.traits.typedefs})   &   compile-time    \\ \rowsep
\tcode{X::pos_type} &                       &
(described in~\ref{char.traits.typedefs})   &   compile-time    \\ \rowsep
\tcode{X::state_type}   &                       &
(described in~\ref{char.traits.typedefs})   &   compile-time    \\ \rowsep
\tcode{X::eq(c,d)}      &   \tcode{bool}        &
yields: whether \tcode{c} is to be treated as equal to \tcode{d}.   &   constant    \\ \rowsep
\tcode{X::lt(c,d)}      &   \tcode{bool}        &
yields: whether \tcode{c} is to be treated as less than \tcode{d}.  &   constant    \\ \rowsep
\tcode{X::compare(p,q,n)}   &   \tcode{int}     &
yields: \tcode{0} if for each \tcode{i} in \tcode{[0,n)}, \tcode{X::eq(p[i],q[i])}
is true; else, a negative value if, for some \tcode{j} in \tcode{[0,n)},
\tcode{X::lt(p[j],q[j])} is true and for each \tcode{i} in \tcode{[0,j)}
\tcode{X::eq(p[i],q[i])} is true; else a positive value.            &   linear      \\ \rowsep
\tcode{X::length(p)}    &   \tcode{std::size_t}     &
yields: the smallest \tcode{i} such that \tcode{X::eq(p[i],charT())} is true.  &   linear  \\ \rowsep
\tcode{X::find(p,n,c)}  &   \tcode{const X::char_type*} &
yields: the smallest \tcode{q} in \tcode{[p,p+n)} such that
\tcode{X::eq(*q,c)} is true, zero otherwise.                        &   linear      \\ \rowsep
\tcode{X::move(s,p,n)}  &   \tcode{X::char_type*}   &
for each \tcode{i} in \tcode{[0,n)}, performs \tcode{X::assign(s[i],p[i])}.
Copies correctly even where the ranges \tcode{[p,p+n)} and \tcode{[s,s+n)} overlap. yields: \tcode{s}.    &   linear  \\ \rowsep
\tcode{X::copy(s,p,n)}  &   \tcode{X::char_type*}   &
pre: \tcode{p} not in \tcode{[s,s+n)}. yields: \tcode{s}. for each \tcode{i} in
\tcode{[0,n)}, performs \tcode{X::assign(s[i],p[i])}.               &   linear      \\ \rowsep
\tcode{X::assign(r,d)}  &   (not used)          &
assigns \tcode{r=d}.                            &   constant        \\ \rowsep
\tcode{X::assign\-(s,n,c)}  &   \tcode{X::char_type*}   &
for each \tcode{i} in \tcode{[0,n)}, performs
\tcode{X::assign(s[i],c)}. yields: \tcode{s}.                       &   linear      \\ \rowsep
\tcode{X::not_eof(e)}   &   \tcode{int_type}        &
yields: \tcode{e} if \tcode{X::eq_int_type(e,X::eof())} is false,
otherwise a value \tcode{f} such that
\tcode{X::eq_int_type(f,X::eof())} is false.                       &   constant    \\ \rowsep
\tcode{X::to_char_type\-(e)}    &   \tcode{X::char_type}    &
yields: if for some \tcode{c}, \tcode{X::eq_int_type(e,X::to_int_type(c))}
is true, \tcode{c}; else some unspecified value.                    &   constant    \\ \rowsep
\tcode{X::to_int_type\-(c)} &   \tcode{X::int_type} &
yields: some value \tcode{e}, constrained by the definitions of
\tcode{to_char_type} and \tcode{eq_int_type}.                  &   constant    \\ \rowsep
\tcode{X::eq_int_type\-(e,f)}   &   \tcode{bool}            &
yields: for all \tcode{c} and \tcode{d}, \tcode{X::eq(c,d)} is equal to
\tcode{X::eq_int_type(X::to_int_type(c), X::to_int_type(d))}; otherwise, yields true
if \tcode{e} and \tcode{f} are both copies of \tcode{X::eof()}; otherwise, yields false if
one of \tcode{e} and \tcode{f} is a copy of \tcode{X::eof()} and the other is not; otherwise
the value is unspecified.                                           &   constant    \\ \rowsep
\tcode{X::eof()}                &   \tcode{X::int_type} &
yields: a value \tcode{e} such that \tcode{X::eq_int_type(e,X::to_int_type(c))}
is false for all values \tcode{c}.                                  &   constant    \\
\end{libreqtab4d}

\pnum
The struct template

\indexlibrary{\idxcode{char_traits}}%
\begin{codeblock}
template<class charT> struct char_traits;
\end{codeblock}

shall be provided in the header
\tcode{<string>}
as a basis for explicit specializations.

\rSec2[char.traits.typedefs]{traits typedefs}

\indexlibrary{\idxcode{char_type}!\idxcode{char_traits}}%
\indexlibrary{\idxcode{char_traits}!\idxcode{char_type}}%
\begin{itemdecl}
typedef CHAR_T char_type;
\end{itemdecl}

\begin{itemdescr}
\pnum
The type
\tcode{char_type}
is used to refer to the character container type
in the implementation of the library classes defined in~\ref{string.classes} and Clause~\ref{input.output}.
\end{itemdescr}

\indexlibrary{\idxcode{int_type}!\idxcode{char_traits}}%
\indexlibrary{\idxcode{char_traits}!\idxcode{int_type}}%
\begin{itemdecl}
typedef INT_T int_type;
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
For a certain character container type
\tcode{char_type},
a related container type
\tcode{INT_T}
shall be a type or class which can represent all of the
valid characters converted from the corresponding
\tcode{char_type}
values, as well as an end-of-file value,
\tcode{eof()}.
The type
\tcode{int_type}
represents a character container type
which can hold end-of-file to be used as a return type
of the iostream class member functions.\footnote{If
\tcode{eof()}
can be held in
\tcode{char_type}
then some iostreams operations may give surprising results.}
\end{itemdescr}

\indexlibrary{\idxcode{off_type}!\idxcode{char_traits}}%
\indexlibrary{\idxcode{char_traits}!\idxcode{off_type}}%
\indexlibrary{\idxcode{pos_type}!\idxcode{char_traits}}%
\indexlibrary{\idxcode{char_traits}!\idxcode{pos_type}}%
\begin{itemdecl}
typedef @\impdef@ off_type;
typedef @\impdef@ pos_type;
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
Requirements for
\tcode{off_type}
and
\tcode{pos_type}
are described in~\ref{iostreams.limits.pos} and \ref{iostream.forward}.
\end{itemdescr}

\indexlibrary{\idxcode{state_type}!\idxcode{char_traits}}%
\indexlibrary{\idxcode{char_traits}!\idxcode{state_type}}%
\begin{itemdecl}
typedef STATE_T state_type;
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{state_type}
shall meet the requirements of
\tcode{CopyAssignable} (Table~\ref{copyassignable}),
\tcode{CopyConstructible} (Table~\ref{copyconstructible}), and
\tcode{DefaultConstructible} (Table~\ref{defaultconstructible}) types.
\end{itemdescr}

\rSec2[char.traits.specializations]{\tcode{char_traits} specializations}

\indexlibrary{\idxcode{char_traits}}%
\begin{codeblock}
namespace std {
  template<> struct char_traits<char>;
  template<> struct char_traits<char16_t>;
  template<> struct char_traits<char32_t>;
  template<> struct char_traits<wchar_t>;
}
\end{codeblock}

\pnum
The header
\tcode{<string>}
shall define four
specializations of the template struct
\tcode{char_traits}:
\tcode{char_traits<\brk{}char>},
\tcode{char_traits<char16_t>},
\tcode{char_traits<char32_t>},
and
\tcode{char_traits<wchar_t>}.

\pnum
The requirements for the members of these specializations are given in
Clause~\ref{char.traits.require}.

\rSec3[char.traits.specializations.char]{\tcode{struct char_traits<char>}}

\indexlibrary{\idxcode{char_traits}}%
\begin{codeblock}
namespace std {
  template<> struct char_traits<char> {
    typedef char        char_type;
    typedef int         int_type;
    typedef streamoff   off_type;
    typedef streampos   pos_type;
    typedef mbstate_t   state_type;

    static void assign(char_type& c1, const char_type& c2) noexcept;
    static constexpr bool eq(char_type c1, char_type c2) noexcept;
    static constexpr bool lt(char_type c1, char_type c2) noexcept;

    static int compare(const char_type* s1, const char_type* s2, size_t n);
    static size_t length(const char_type* s);
    static const char_type* find(const char_type* s, size_t n,
                 const char_type& a);
    static char_type* move(char_type* s1, const char_type* s2, size_t n);
    static char_type* copy(char_type* s1, const char_type* s2, size_t n);
    static char_type* assign(char_type* s, size_t n, char_type a);

    static constexpr int_type not_eof(int_type c) noexcept;
    static constexpr char_type to_char_type(int_type c) noexcept;
    static constexpr int_type to_int_type(char_type c) noexcept;
    static constexpr bool eq_int_type(int_type c1, int_type c2) noexcept;
    static constexpr int_type eof() noexcept;
  };
}
\end{codeblock}

\pnum
The defined types for
\tcode{int_type},
\tcode{pos_type},
\tcode{off_type},
and
\tcode{state_type}
shall be
\tcode{int},
\tcode{streampos},
\tcode{streamoff},
and
\tcode{mbstate_t}
respectively.

\pnum
The type
\tcode{streampos}
shall be an \impldef{type of \tcode{streampos}} type that satisfies the requirements for
\tcode{pos_type}
in~\ref{iostreams.limits.pos} and \ref{iostream.forward}.

\pnum
The type
\tcode{streamoff}
shall be an \impldef{type of \tcode{streamoff}} type that satisfies the requirements for
\tcode{off_type}
in~\ref{iostreams.limits.pos} and \ref{iostream.forward}.

\pnum
The type
\tcode{mbstate_t}
is defined in
\tcode{<cwchar>}
and can represent any of the conversion states that can occur in an
\impldef{supported multibyte character encoding rules} set of supported multibyte
character encoding rules.

\pnum
The two-argument member \tcode{assign} shall be defined identically to the
built-in operator \tcode{=}. The two-argument members \tcode{eq}
and \tcode{lt} shall be defined identically to the built-in operators
\tcode{==} and \tcode{<} for type \tcode{unsigned}
\tcode{char}.

\pnum
The member
\tcode{eof()}
shall return
\tcode{EOF}.

\rSec3[char.traits.specializations.char16_t]{\tcode{struct char_traits<char16_t>}}

\indexlibrary{\idxcode{char_traits}}%
\begin{codeblock}
namespace std {
  template<> struct char_traits<char16_t> {
    typedef char16_t        char_type;
    typedef uint_least16_t  int_type;
    typedef streamoff       off_type;
    typedef u16streampos    pos_type;
    typedef mbstate_t       state_type;

    static void assign(char_type& c1, const char_type& c2) noexcept;
    static constexpr bool eq(char_type c1, char_type c2) noexcept;
    static constexpr bool lt(char_type c1, char_type c2) noexcept;

    static int compare(const char_type* s1, const char_type* s2, size_t n);
    static size_t length(const char_type* s);
    static const char_type* find(const char_type* s, size_t n,
                                 const char_type& a);
    static char_type* move(char_type* s1, const char_type* s2, size_t n);
    static char_type* copy(char_type* s1, const char_type* s2, size_t n);
    static char_type* assign(char_type* s, size_t n, char_type a);

    static constexpr int_type not_eof(int_type c) noexcept;
    static constexpr char_type to_char_type(int_type c) noexcept;
    static constexpr int_type to_int_type(char_type c) noexcept;
    static constexpr bool eq_int_type(int_type c1, int_type c2) noexcept;
    static constexpr int_type eof() noexcept;
  };
}
\end{codeblock}

\pnum
The type
\tcode{u16streampos}
shall be an \impldef{type of \tcode{u16streampos}} type that satisfies the requirements
for pos_type in~\ref{iostreams.limits.pos} and \ref{iostream.forward}.

\pnum
The two-argument members \tcode{assign},
\tcode{eq}, and \tcode{lt} shall be defined identically to
the built-in operators \tcode{=}, \tcode{==}, and
\tcode{<} respectively.

\pnum
The member \tcode{eof()} shall return an
\impldef{return value of \tcode{char_traits<char16_t>::eof}} constant that cannot appear
as a valid UTF-16 code unit.

\rSec3[char.traits.specializations.char32_t]{\tcode{struct char_traits<char32_t>}}

\indexlibrary{\idxcode{char_traits}}%
\begin{codeblock}
namespace std {
  template<> struct char_traits<char32_t> {
    typedef char32_t        char_type;
    typedef uint_least32_t  int_type;
    typedef streamoff       off_type;
    typedef u32streampos    pos_type;
    typedef mbstate_t       state_type;

    static void assign(char_type& c1, const char_type& c2) noexcept;
    static constexpr bool eq(char_type c1, char_type c2) noexcept;
    static constexpr bool lt(char_type c1, char_type c2) noexcept;

    static int compare(const char_type* s1, const char_type* s2, size_t n);
    static size_t length(const char_type* s);
    static const char_type* find(const char_type* s, size_t n,
                 const char_type& a);
    static char_type* move(char_type* s1, const char_type* s2, size_t n);
    static char_type* copy(char_type* s1, const char_type* s2, size_t n);
    static char_type* assign(char_type* s, size_t n, char_type a);

    static constexpr int_type not_eof(int_type c) noexcept;
    static constexpr char_type to_char_type(int_type c) noexcept;
    static constexpr int_type to_int_type(char_type c) noexcept;
    static constexpr bool eq_int_type(int_type c1, int_type c2) noexcept;
    static constexpr int_type eof() noexcept;
  };
}
\end{codeblock}

\pnum
The type
\tcode{u32streampos}
shall be an \impldef{type of \tcode{u32streampos}} type that satisfies the requirements
for pos_type in~\ref{iostreams.limits.pos} and \ref{iostream.forward}.

\pnum
The two-argument members \tcode{assign},
\tcode{eq}, and \tcode{lt} shall be defined identically to
the built-in operators \tcode{=}, \tcode{==}, and
\tcode{<} respectively.

\pnum
The member \tcode{eof()} shall return an
\impldef{return value of \tcode{char_traits<char32_t>::eof}} constant that cannot appear as a Unicode
code point.

\rSec3[char.traits.specializations.wchar.t]{\tcode{struct char_traits<wchar_t>}}

\indexlibrary{\idxcode{char_traits}}%
\begin{codeblock}
namespace std {
  template<> struct char_traits<wchar_t> {
    typedef wchar_t      char_type;
    typedef wint_t       int_type;
    typedef streamoff    off_type;
    typedef wstreampos   pos_type;
    typedef mbstate_t    state_type;

    static void assign(char_type& c1, const char_type& c2) noexcept;
    static constexpr bool eq(char_type c1, char_type c2) noexcept;
    static constexpr bool lt(char_type c1, char_type c2) noexcept;

    static int compare(const char_type* s1, const char_type* s2, size_t n);
    static size_t length(const char_type* s);
    static const char_type* find(const char_type* s, size_t n,
                 const char_type& a);
    static char_type* move(char_type* s1, const char_type* s2, size_t n);
    static char_type* copy(char_type* s1, const char_type* s2, size_t n);
    static char_type* assign(char_type* s, size_t n, char_type a);

    static constexpr int_type not_eof(int_type c) noexcept;
    static constexpr char_type to_char_type(int_type c) noexcept;
    static constexpr int_type to_int_type(char_type c) noexcept;
    static constexpr bool eq_int_type(int_type c1, int_type c2) noexcept;
    static constexpr int_type eof() noexcept;
  };
}
\end{codeblock}

\pnum
The defined types for
\tcode{int_type},
\tcode{pos_type},
and
\tcode{state_type}
shall be
\tcode{wint_t},
\tcode{wstreampos},
and
\tcode{mbstate_t}
respectively.

\pnum
The type
\tcode{wstreampos}
shall be an \impldef{type of \tcode{wstreampos}} type that satisfies the requirements
for pos_type in~\ref{iostreams.limits.pos} and \ref{iostream.forward}.

\pnum
The type
\tcode{mbstate_t}
is defined in
\tcode{<cwchar>}
and can represent any of the conversion states that can occur in an \impldef{supported
multibyte character encoding rules} set of supported multibyte character encoding rules.

\pnum
The two-argument members
\tcode{assign},
\tcode{eq},
and
\tcode{lt}
shall be defined identically
to the built-in operators
\tcode{=},
\tcode{==},
and
\tcode{<}
respectively.

\pnum
The member
\tcode{eof()}
shall return
\tcode{WEOF}.

\rSec1[string.classes]{String classes}

\pnum
The header \tcode{<string>} defines the
\tcode{basic_string} class template for manipulating
varying-length sequences of char-like objects and four
typedefs, \tcode{string},
\tcode{u16string},
\tcode{u32string},
and \tcode{wstring}, that name
the specializations
\tcode{basic_string<char>},
\tcode{basic_string<char16_t>},
\tcode{basic_string<char32_t>},
and
\tcode{basic_string<\brk{}wchar_t>}, respectively.

\synopsis{Header \tcode{<string>} synopsis}

\indexlibrary{\idxhdr{string}}%
\begin{codeblock}
#include <initializer_list>

namespace std {

  // \ref{char.traits}, character traits:
  template<class charT> struct char_traits;
  template <> struct char_traits<char>;
  template <> struct char_traits<char16_t>;
  template <> struct char_traits<char32_t>;
  template <> struct char_traits<wchar_t>;

  // \ref{basic.string}, basic_string:
  template<class charT, class traits = char_traits<charT>,
    class Allocator = allocator<charT> >
      class basic_string;

  template<class charT, class traits, class Allocator>
    basic_string<charT,traits,Allocator>
      operator+(const basic_string<charT,traits,Allocator>& lhs,
                const basic_string<charT,traits,Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    basic_string<charT,traits,Allocator>
      operator+(basic_string<charT,traits,Allocator>&& lhs,
                const basic_string<charT,traits,Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    basic_string<charT,traits,Allocator>
      operator+(const basic_string<charT,traits,Allocator>& lhs,
                basic_string<charT,traits,Allocator>&& rhs);
  template<class charT, class traits, class Allocator>
    basic_string<charT,traits,Allocator>
      operator+(basic_string<charT,traits,Allocator>&& lhs,
                basic_string<charT,traits,Allocator>&& rhs);
  template<class charT, class traits, class Allocator>
    basic_string<charT,traits,Allocator>
      operator+(const charT* lhs,
                const basic_string<charT,traits,Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    basic_string<charT,traits,Allocator>
      operator+(const charT* lhs,
                basic_string<charT,traits,Allocator>&& rhs);
  template<class charT, class traits, class Allocator>
    basic_string<charT,traits,Allocator>
      operator+(charT lhs, const basic_string<charT,traits,Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    basic_string<charT,traits,Allocator>
      operator+(charT lhs, basic_string<charT,traits,Allocator>&& rhs);
  template<class charT, class traits, class Allocator>
    basic_string<charT,traits,Allocator>
      operator+(const basic_string<charT,traits,Allocator>& lhs,
                const charT* rhs);
  template<class charT, class traits, class Allocator>
    basic_string<charT,traits,Allocator>
      operator+(basic_string<charT,traits,Allocator>&& lhs,
                const charT* rhs);
  template<class charT, class traits, class Allocator>
    basic_string<charT,traits,Allocator>
      operator+(const basic_string<charT,traits,Allocator>& lhs, charT rhs);
  template<class charT, class traits, class Allocator>
    basic_string<charT,traits,Allocator>
      operator+(basic_string<charT,traits,Allocator>&& lhs, charT rhs);

  template<class charT, class traits, class Allocator>
    bool operator==(const basic_string<charT,traits,Allocator>& lhs,
                    const basic_string<charT,traits,Allocator>& rhs) noexcept;
  template<class charT, class traits, class Allocator>
    bool operator==(const charT* lhs,
                    const basic_string<charT,traits,Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    bool operator==(const basic_string<charT,traits,Allocator>& lhs,
                    const charT* rhs);
  template<class charT, class traits, class Allocator>
    bool operator!=(const basic_string<charT,traits,Allocator>& lhs,
                    const basic_string<charT,traits,Allocator>& rhs) noexcept;
  template<class charT, class traits, class Allocator>
    bool operator!=(const charT* lhs,
                    const basic_string<charT,traits,Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    bool operator!=(const basic_string<charT,traits,Allocator>& lhs,
                    const charT* rhs);

  template<class charT, class traits, class Allocator>
    bool operator< (const basic_string<charT,traits,Allocator>& lhs,
                    const basic_string<charT,traits,Allocator>& rhs) noexcept;
  template<class charT, class traits, class Allocator>
    bool operator< (const basic_string<charT,traits,Allocator>& lhs,
                    const charT* rhs);
  template<class charT, class traits, class Allocator>
    bool operator< (const charT* lhs,
                    const basic_string<charT,traits,Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    bool operator> (const basic_string<charT,traits,Allocator>& lhs,
                    const basic_string<charT,traits,Allocator>& rhs) noexcept;
  template<class charT, class traits, class Allocator>
    bool operator> (const basic_string<charT,traits,Allocator>& lhs,
                    const charT* rhs);
  template<class charT, class traits, class Allocator>
    bool operator> (const charT* lhs,
                    const basic_string<charT,traits,Allocator>& rhs);

  template<class charT, class traits, class Allocator>
    bool operator<=(const basic_string<charT,traits,Allocator>& lhs,
                    const basic_string<charT,traits,Allocator>& rhs) noexcept;
  template<class charT, class traits, class Allocator>
    bool operator<=(const basic_string<charT,traits,Allocator>& lhs,
                    const charT* rhs);
  template<class charT, class traits, class Allocator>
    bool operator<=(const charT* lhs,
                    const basic_string<charT,traits,Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    bool operator>=(const basic_string<charT,traits,Allocator>& lhs,
                    const basic_string<charT,traits,Allocator>& rhs) noexcept;
  template<class charT, class traits, class Allocator>
    bool operator>=(const basic_string<charT,traits,Allocator>& lhs,
                    const charT* rhs);
  template<class charT, class traits, class Allocator>
    bool operator>=(const charT* lhs,
                    const basic_string<charT,traits,Allocator>& rhs);

  // \ref{string.special}, swap:
  template<class charT, class traits, class Allocator>
    void swap(basic_string<charT,traits,Allocator>& lhs,
      basic_string<charT,traits,Allocator>& rhs);

  // \ref{string.io}, inserters and extractors:
  template<class charT, class traits, class Allocator>
    basic_istream<charT,traits>&
      operator>>(basic_istream<charT,traits>& is,
                 basic_string<charT,traits,Allocator>& str);
  template<class charT, class traits, class Allocator>
    basic_ostream<charT, traits>&
      operator<<(basic_ostream<charT, traits>& os,
                 const basic_string<charT,traits,Allocator>& str);
  template<class charT, class traits, class Allocator>
    basic_istream<charT,traits>&
      getline(basic_istream<charT,traits>& is,
              basic_string<charT,traits,Allocator>& str,
              charT delim);
  template<class charT, class traits, class Allocator>
    basic_istream<charT,traits>&
      getline(basic_istream<charT,traits>&& is,
              basic_string<charT,traits,Allocator>& str,
              charT delim);
  template<class charT, class traits, class Allocator>
    basic_istream<charT,traits>&
      getline(basic_istream<charT,traits>& is,
              basic_string<charT,traits,Allocator>& str);
  template<class charT, class traits, class Allocator>
    basic_istream<charT,traits>&
      getline(basic_istream<charT,traits>&& is,
              basic_string<charT,traits,Allocator>& str);

  // \tcode{basic_string} typedef names
  typedef basic_string<char> string;
  typedef basic_string<char16_t> u16string;
  typedef basic_string<char32_t> u32string;
  typedef basic_string<wchar_t> wstring;

  // \ref{string.conversions}, numeric conversions:
  int stoi(const string& str, size_t *idx = 0, int base = 10);
  long stol(const string& str, size_t *idx = 0, int base = 10);
  unsigned long stoul(const string& str, size_t *idx = 0, int base = 10);
  long long stoll(const string& str, size_t *idx = 0, int base = 10);
  unsigned long long stoull(const string& str, size_t *idx = 0, int base = 10);
  float stof(const string& str, size_t *idx = 0);
  double stod(const string& str, size_t *idx = 0);
  long double stold(const string& str, size_t *idx = 0);
  string to_string(int val);
  string to_string(unsigned val);
  string to_string(long val);
  string to_string(unsigned long val);
  string to_string(long long val);
  string to_string(unsigned long long val);
  string to_string(float val);
  string to_string(double val);
  string to_string(long double val);

  int stoi(const wstring& str, size_t *idx = 0, int base = 10);
  long stol(const wstring& str, size_t *idx = 0, int base = 10);
  unsigned long stoul(const wstring& str, size_t *idx = 0, int base = 10);
  long long stoll(const wstring& str, size_t *idx = 0, int base = 10);
  unsigned long long stoull(const wstring& str, size_t *idx = 0, int base = 10);
  float stof(const wstring& str, size_t *idx = 0);
  double stod(const wstring& str, size_t *idx = 0);
  long double stold(const wstring& str, size_t *idx = 0);
  wstring to_wstring(int val);
  wstring to_wstring(unsigned val);
  wstring to_wstring(long val);
  wstring to_wstring(unsigned long val);
  wstring to_wstring(long long val);
  wstring to_wstring(unsigned long long val);
  wstring to_wstring(float val);
  wstring to_wstring(double val);
  wstring to_wstring(long double val);

  // \ref{basic.string.hash}, hash support:
  template <class T> struct hash;
  template <> struct hash<string>;
  template <> struct hash<u16string>;
  template <> struct hash<u32string>;
  template <> struct hash<wstring>;

inline namespace literals {
inline namespace string_literals {

  // \ref{basic.string.literals}, suffix for basic_string literals:
  string    operator "" s(const char *str, size_t len);
  u16string operator "" s(const char16_t *str, size_t len);
  u32string operator "" s(const char32_t *str, size_t len);
  wstring   operator "" s(const wchar_t *str, size_t len);

}
}
}
\end{codeblock}

\rSec1[basic.string]{Class template \tcode{basic_string}}

\pnum
\indexlibrary{\idxcode{basic_string}}%
The
class template
\tcode{basic_string}
describes objects that can store a sequence consisting of a varying number of
arbitrary char-like objects with the first element of the sequence at position zero.
Such a sequence is also called a ``string'' if the type of the
char-like objects that it holds
is clear from context.
In the rest of this Clause,
the type of the char-like objects held in a \tcode{basic_string} object
is designated by \tcode{charT}.

\pnum
The
member functions of
\tcode{basic_string} use an object of the
\tcode{Allocator}
class passed as a template parameter to allocate and free storage for the
contained char-like objects.\footnote{\tcode{Allocator::value_type} must name the same type
as \tcode{charT}~(\ref{string.require}).}

\pnum
The iterators supported by
\tcode{basic_string} are random access iterators~(\ref{random.access.iterators}).

\pnum
In all cases,
\tcode{size() <= capacity()}.

\pnum
The functions described in this Clause can report two
kinds of errors, each associated with an exception type:

\begin{itemize}
\item
a
\term{length}
error is associated with exceptions of type
\tcode{length_error}~(\ref{length.error});
\indexlibrary{\idxcode{length_error}}%
\item
an
\term{out-of-range}
error is associated with exceptions of type
\tcode{out_of_range}~(\ref{out.of.range}).
\indexlibrary{\idxcode{out_of_range}}%
\end{itemize}

\indexlibrary{\idxcode{basic_string}}%
\begin{codeblock}
namespace std {
  template<class charT, class traits = char_traits<charT>,
    class Allocator = allocator<charT> >
  class basic_string {
  public:
    // types:
    typedef          traits                                         traits_type;
    typedef typename traits::char_type                              value_type;
    typedef          Allocator                                      allocator_type;
    typedef typename allocator_traits<Allocator>::size_type         size_type;
    typedef typename allocator_traits<Allocator>::difference_type   difference_type;

    typedef value_type& reference;
    typedef const value_type&   const_reference;
    typedef typename allocator_traits<Allocator>::pointer           pointer;
    typedef typename allocator_traits<Allocator>::const_pointer     const_pointer;

    typedef @\impdef@              iterator;       // See \ref{container.requirements}
    typedef @\impdef@              const_iterator; // See \ref{container.requirements}
    typedef std::reverse_iterator<iterator> reverse_iterator;
    typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
    static const size_type npos = -1;

    // \ref{string.cons}, construct/copy/destroy:
    explicit basic_string(const Allocator& a = Allocator());
    basic_string(const basic_string& str);
    basic_string(basic_string&& str) noexcept;
    basic_string(const basic_string& str, size_type pos, size_type n = npos,
                 const Allocator& a = Allocator());
    basic_string(const charT* s,
                 size_type n, const Allocator& a = Allocator());
    basic_string(const charT* s, const Allocator& a = Allocator());
    basic_string(size_type n, charT c, const Allocator& a = Allocator());
    template<class InputIterator>
      basic_string(InputIterator begin, InputIterator end,
                   const Allocator& a = Allocator());
    basic_string(initializer_list<charT>, const Allocator& = Allocator());
    basic_string(const basic_string&, const Allocator&);
    basic_string(basic_string&&, const Allocator&);

   ~basic_string();
    basic_string& operator=(const basic_string& str);
    basic_string& operator=(basic_string&& str) noexcept;
    basic_string& operator=(const charT* s);
    basic_string& operator=(charT c);
    basic_string& operator=(initializer_list<charT>);

    // \ref{string.iterators}, iterators:
    iterator       begin() noexcept;
    const_iterator begin() const noexcept;
    iterator       end() noexcept;
    const_iterator end() const noexcept;

    reverse_iterator       rbegin() noexcept;
    const_reverse_iterator rbegin() const noexcept;
    reverse_iterator       rend() noexcept;
    const_reverse_iterator rend() const noexcept;

    const_iterator         cbegin() const noexcept;
    const_iterator         cend() const noexcept;
    const_reverse_iterator crbegin() const noexcept;
    const_reverse_iterator crend() const noexcept;

    // \ref{string.capacity}, capacity:
    size_type size() const noexcept;
    size_type length() const noexcept;
    size_type max_size() const noexcept;
    void resize(size_type n, charT c);
    void resize(size_type n);
    size_type capacity() const noexcept;
    void reserve(size_type res_arg = 0);
    void shrink_to_fit();
    void clear() noexcept;
    bool empty() const noexcept;

    // \ref{string.access}, element access:
    const_reference operator[](size_type pos) const;
    reference       operator[](size_type pos);
    const_reference at(size_type n) const;
    reference       at(size_type n);

    const charT& front() const;
    charT& front();
    const charT& back() const;
    charT& back();

    // \ref{string.modifiers}, modifiers:
    basic_string& operator+=(const basic_string& str);
    basic_string& operator+=(const charT* s);
    basic_string& operator+=(charT c);
    basic_string& operator+=(initializer_list<charT>);
    basic_string& append(const basic_string& str);
    basic_string& append(const basic_string& str, size_type pos,
                         size_type n);
    basic_string& append(const charT* s, size_type n);
    basic_string& append(const charT* s);
    basic_string& append(size_type n, charT c);
    template<class InputIterator>
      basic_string& append(InputIterator first, InputIterator last);
    basic_string& append(initializer_list<charT>);
    void push_back(charT c);

    basic_string& assign(const basic_string& str);
    basic_string& assign(basic_string&& str) noexcept;
    basic_string& assign(const basic_string& str, size_type pos,
                         size_type n);
    basic_string& assign(const charT* s, size_type n);
    basic_string& assign(const charT* s);
    basic_string& assign(size_type n, charT c);
    template<class InputIterator>
      basic_string& assign(InputIterator first, InputIterator last);
    basic_string& assign(initializer_list<charT>);

    basic_string& insert(size_type pos1, const basic_string& str);
    basic_string& insert(size_type pos1, const basic_string& str,
                         size_type pos2, size_type n);
    basic_string& insert(size_type pos, const charT* s, size_type n);
    basic_string& insert(size_type pos, const charT* s);
    basic_string& insert(size_type pos, size_type n, charT c);
    iterator insert(const_iterator p, charT c);
    iterator insert(const_iterator p, size_type n, charT c);
    template<class InputIterator>
      iterator insert(const_iterator p, InputIterator first, InputIterator last);
    iterator insert(const_iterator p, initializer_list<charT>);

    basic_string& erase(size_type pos = 0, size_type n = npos);
    iterator erase(const_iterator p);
    iterator erase(const_iterator first, const_iterator last);

    void pop_back();

    basic_string& replace(size_type pos1, size_type n1,
                          const basic_string& str);
    basic_string& replace(size_type pos1, size_type n1,
                          const basic_string& str,
                          size_type pos2, size_type n2);
    basic_string& replace(size_type pos, size_type n1, const charT* s,
                          size_type n2);
    basic_string& replace(size_type pos, size_type n1, const charT* s);
    basic_string& replace(size_type pos, size_type n1, size_type n2,
                          charT c);

    basic_string& replace(const_iterator i1, const_iterator i2,
              const basic_string& str);
    basic_string& replace(const_iterator i1, const_iterator i2, const charT* s,
                          size_type n);
    basic_string& replace(const_iterator i1, const_iterator i2, const charT* s);
    basic_string& replace(const_iterator i1, const_iterator i2,
                          size_type n, charT c);
    template<class InputIterator>
      basic_string& replace(const_iterator i1, const_iterator i2,
                            InputIterator j1, InputIterator j2);
    basic_string& replace(const_iterator, const_iterator, initializer_list<charT>);

    size_type copy(charT* s, size_type n, size_type pos = 0) const;
    void swap(basic_string& str);

    // \ref{string.ops}, string operations:
    const charT* c_str() const noexcept;
    const charT* data() const noexcept;
    allocator_type get_allocator() const noexcept;

    size_type find (const basic_string& str, size_type pos = 0) const noexcept;
    size_type find (const charT* s, size_type pos, size_type n) const;
    size_type find (const charT* s, size_type pos = 0) const;
    size_type find (charT c, size_type pos = 0) const;
    size_type rfind(const basic_string& str, size_type pos = npos) const noexcept;
    size_type rfind(const charT* s, size_type pos, size_type n) const;
    size_type rfind(const charT* s, size_type pos = npos) const;
    size_type rfind(charT c, size_type pos = npos) const;

    size_type find_first_of(const basic_string& str,
                            size_type pos = 0) const noexcept;
    size_type find_first_of(const charT* s,
                            size_type pos, size_type n) const;
    size_type find_first_of(const charT* s, size_type pos = 0) const;
    size_type find_first_of(charT c, size_type pos = 0) const;
    size_type find_last_of (const basic_string& str,
                            size_type pos = npos) const noexcept;
    size_type find_last_of (const charT* s,
                            size_type pos, size_type n) const;
    size_type find_last_of (const charT* s, size_type pos = npos) const;
    size_type find_last_of (charT c, size_type pos = npos) const;

    size_type find_first_not_of(const basic_string& str,
                size_type pos = 0) const noexcept;
    size_type find_first_not_of(const charT* s, size_type pos,
                                size_type n) const;
    size_type find_first_not_of(const charT* s, size_type pos = 0) const;
    size_type find_first_not_of(charT c, size_type pos = 0) const;
    size_type find_last_not_of (const basic_string& str,
                                size_type pos = npos) const noexcept;
    size_type find_last_not_of (const charT* s, size_type pos,
                                size_type n) const;
    size_type find_last_not_of (const charT* s,
                                size_type pos = npos) const;
    size_type find_last_not_of (charT c, size_type pos = npos) const;

    basic_string substr(size_type pos = 0, size_type n = npos) const;
    int compare(const basic_string& str) const noexcept;
    int compare(size_type pos1, size_type n1,
                const basic_string& str) const;
    int compare(size_type pos1, size_type n1,
                const basic_string& str,
                size_type pos2, size_type n2) const;
    int compare(const charT* s) const;
    int compare(size_type pos1, size_type n1,
                const charT* s) const;
    int compare(size_type pos1, size_type n1,
                const charT* s, size_type n2) const;
  };
}
\end{codeblock}

\rSec2[string.require]{\tcode{basic_string} general requirements}

\pnum
If any operation would cause \tcode{size()} to
exceed \tcode{max_size()}, that operation shall throw an
exception object of type \tcode{length_error}.

\pnum
If any member function or operator of \tcode{basic_string} throws an exception, that
function or operator shall have no other effect.

\pnum
No \tcode{erase()} or \tcode{pop_back()} member function shall throw any exceptions.

\pnum
In every specialization \tcode{basic_string<charT, traits, Allocator>},
the type \tcode{allocator_traits<All\-ocator>::value_type} shall name the same type
as \tcode{charT}. Every object of type
\tcode{basic_string<charT, traits, Allocator>} shall use an object of type
\tcode{Allocator} to allocate and free storage for the contained \tcode{charT}
objects as needed. The \tcode{Allocator} object used shall be
obtained as described in \ref{container.requirements.general}.

\pnum
The char-like objects in a \tcode{basic_string} object shall be
stored contiguously. That is, for any \tcode{basic_string} object \tcode{s},
the identity \tcode{\&*(s.begin() + n) == \&*s.begin() + n} shall hold for all
values of \tcode{n} such that \tcode{0 <= n < s.size()}.

\pnum
References, pointers, and iterators referring to the elements of a
\tcode{basic_string} sequence may be
invalidated by the following uses of that \tcode{basic_string} object:

\begin{itemize}
\item as an argument to any standard library function taking a reference to non-const
\tcode{basic_string} as an argument.\footnote{For example, as an argument to non-member
functions \tcode{swap()}~(\ref{string.special}),
\tcode{operator>{}>()}~(\ref{string.io}), and \tcode{getline()}~(\ref{string.io}), or as
an argument to \tcode{basic_string::swap()}}

\item Calling non-const member functions, except
\tcode{operator[]},
\tcode{at},
\tcode{front},
\tcode{back},
\tcode{begin},
\tcode{rbegin},
\tcode{end},
and
\tcode{rend}.
\end{itemize}

\rSec2[string.cons]{\tcode{basic_string} constructors and assignment operators}

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

\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{basic_string}.
The postconditions of this function are indicated in Table~\ref{tab:strings.ctr.1}.

\begin{libefftabvalue}{\tcode{basic_string(const Allocator\&)} effects}{tab:strings.ctr.1}
\tcode{data()}      &   a non-null pointer that is copyable and can have 0 added to it  \\ \rowsep
\tcode{size()}      &   0                                                               \\ \rowsep
\tcode{capacity()}  &   an unspecified value                                            \\
\end{libefftabvalue}
\end{itemdescr}

\indexlibrary{\idxcode{basic_string}!constructor}%
\begin{itemdecl}
basic_string(const basic_string& str);
basic_string(basic_string&& str) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{basic_string}
as indicated in Table~\ref{tab:strings.ctr.cpy}.
In the second form, \tcode{str}
is left in a valid state with an unspecified value.

\begin{libefftabvalue}
{\tcode{basic_string(const basic_string\&)} effects}
{tab:strings.ctr.cpy}
\tcode{data()}      &
points at the first element of an allocated copy of the array
whose first element is pointed at by \tcode{str.data()} \\
\tcode{size()}      &   \tcode{str.size()}                                                  \\
\tcode{capacity()}  &   a value at least as large as \tcode{size()}                     \\
\end{libefftabvalue}
\end{itemdescr}

\indexlibrary{\idxcode{basic_string}!constructor}%
\begin{itemdecl}
basic_string(const basic_string& str,
             size_type pos, size_type n = npos,
             const Allocator& a = Allocator());
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{pos <= str.size()}

\pnum
\throws
\tcode{out_of_range}
if
\tcode{pos > str.size()}.

\pnum
\effects
Constructs an object of class
\tcode{basic_string}
and determines the effective length \tcode{rlen} of the initial string
value as the smaller of \tcode{n} and
\tcode{str.size() - pos},
as indicated in Table~\ref{tab:strings.ctr.2}.

\begin{libefftabvalue}
{\tcode{basic_string(const basic_string\&, size_type, size_type, const Allocator\&)} effects}
{tab:strings.ctr.2}
\tcode{data()}      &
points at the first element of an allocated copy of \tcode{rlen} consecutive elements
of the string controlled by \tcode{str} beginning at position \tcode{pos}              \\
\tcode{size()}      &   \tcode{rlen}                                                    \\
\tcode{capacity()}  &   a value at least as large as \tcode{size()}                     \\
\end{libefftabvalue}
\end{itemdescr}

\indexlibrary{\idxcode{basic_string}!constructor}%
\begin{itemdecl}
basic_string(const charT* s, size_type n,
             const Allocator& a = Allocator());
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{s} points to an array of at least \tcode{n} elements of \tcode{charT}.

\pnum
\effects
Constructs an object of class
\tcode{basic_string}
and determines its initial string value from the array of
\tcode{charT}
of length \tcode{n} whose first element is designated by \tcode{s},
as indicated in Table~\ref{tab:strings.ctr.3}.

\begin{libefftabvalue}
{\tcode{basic_string(const charT*, size_type, const Allocator\&)} effects}
{tab:strings.ctr.3}
\tcode{data()}      &
points at the first element of an allocated copy of the array whose first element
is pointed at by \tcode{s}                                                              \\
\tcode{size()}      &   \tcode{n}                                                       \\
\tcode{capacity()}  &   a value at least as large as \tcode{size()}                     \\
\end{libefftabvalue}
\end{itemdescr}

\indexlibrary{\idxcode{basic_string}!constructor}%
\begin{itemdecl}
basic_string(const charT* s, const Allocator& a = Allocator());
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{s} points to an array of at least \tcode{traits::length(s) + 1} elements
of \tcode{charT}.

\pnum
\effects
Constructs an object of class
\tcode{basic_string}
and determines its initial string value from the array of
\tcode{charT}
of length
\tcode{traits::length(s)}
whose first element is designated
by \tcode{s},
as indicated in Table~\ref{tab:strings.ctr.4}.

\begin{libefftabvalue}
{\tcode{basic_string(const charT*, const Allocator\&)} effects}
{tab:strings.ctr.4}
\tcode{data()}      &
points at the first element of an allocated copy of the array whose first element
is pointed at by \tcode{s}                                                              \\
\tcode{size()}      &   \tcode{traits::length(s)}                                       \\
\tcode{capacity()}  &   a value at least as large as \tcode{size()}                     \\
\end{libefftabvalue}

\pnum
\notes
Uses
\tcode{traits::length()}.
\indexlibrary{\idxcode{length}!\tcode{char_traits}}%
\end{itemdescr}

\indexlibrary{\idxcode{basic_string}!constructor}%
\begin{itemdecl}
basic_string(size_type n, charT c, const Allocator& a = Allocator());
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{n < npos}

\pnum
\effects
Constructs an object of class
\tcode{basic_string}
and determines its initial string value by repeating the char-like
object \tcode{c} for all \tcode{n} elements,
as indicated in Table~\ref{tab:strings.ctr.5}.

\begin{libefftabvalue}
{\tcode{basic_string(size_t, charT, const Allocator\&)} effects}
{tab:strings.ctr.5}
\tcode{data()}      &
points at the first element of an allocated array of \tcode{n} elements, each
storing the initial value \tcode{c}                                                     \\
\tcode{size()}      &   \tcode{n}                                                       \\
\tcode{capacity()}  &   a value at least as large as \tcode{size()}                     \\
\end{libefftabvalue}
\end{itemdescr}

\indexlibrary{\idxcode{basic_string}!constructor}%
\begin{itemdecl}
template<class InputIterator>
  basic_string(InputIterator begin, InputIterator end,
               const Allocator& a = Allocator());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If \tcode{InputIterator} is an integral type,
equivalent to

\begin{codeblock}
basic_string(static_cast<size_type>(begin), static_cast<value_type>(end), a)
\end{codeblock}

\pnum
Otherwise constructs a string from the values in the range [\tcode{begin}, \tcode{end}),
as indicated in the Sequence Requirements table
(see~\ref{sequence.reqmts}).
%
\end{itemdescr}

\indexlibrary{\idxcode{basic_string}!constructor}%
\begin{itemdecl}
basic_string(initializer_list<charT> il, const Allocator& a = Allocator());
\end{itemdecl}

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

\indexlibrary{\idxcode{basic_string}!constructor}%
\begin{itemdecl}
basic_string(const basic_string& str, const Allocator& alloc);
basic_string(basic_string&& str, const Allocator& alloc);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Constructs an object of class \tcode{basic_string} as indicated in
Table~\ref{tab:strings.ctr.6}. The stored allocator is constructed from
\tcode{alloc}. In the second form, \tcode{str} is left in a valid state with an
unspecified value.

\begin{libefftabvalue}
{\tcode{basic_string(const basic_string\&, const Allocator\&)} and
\tcode{basic_string(basic_string\&\&, const Allocator\&)} effects}
{tab:strings.ctr.6}
\tcode{data()}      &
points at the first element of an allocated copy of the array whose first
element is pointed at by the original value of \tcode{str.data()}. \\
\tcode{size()}      &   the original value of \tcode{str.size()}   \\
\tcode{capacity()}  &   a value at least as large as \tcode{size()}                     \\
\tcode{get_allocator()} &	\tcode{alloc} \\
\end{libefftabvalue}

\pnum
\throws The second form throws nothing if \tcode{alloc == str.get_allocator()}.
\end{itemdescr}


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

\begin{itemdescr}
\pnum
\effects
If
\tcode{*this}
and \tcode{str} are not the same object,
modifies
\tcode{*this}
as shown in Table~\ref{tab:strings.op=}.

\pnum
If
\tcode{*this}
and \tcode{str} are the same object,
the member has no effect.

\pnum
\returns
\tcode{*this}

\begin{libefftabvalue}
{\tcode{operator=(const basic_string\&)} effects}
{tab:strings.op=}
\tcode{data()}      &
points at the first element of an allocated copy of the array whose first
element is pointed at by \tcode{str.data()}                                             \\
\tcode{size()}      &   \tcode{str.size()}                                              \\
\tcode{capacity()}  &   a value at least as large as \tcode{size()}                     \\
\end{libefftabvalue}
\end{itemdescr}

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

\begin{itemdescr}
\pnum
\effects
If
\tcode{*this}
and \tcode{str} are not the same object,
modifies
\tcode{*this}
as shown in Table~\ref{tab:strings.op=rv}.
\enternote A valid implementation is
\tcode{swap(str)}. \exitnote

\pnum
If
\tcode{*this}
and \tcode{str} are the same object,
the member has no effect.

\pnum
\returns
\tcode{*this}

\begin{libefftabvalue}
{\tcode{operator=(basic_string\&\&)} effects}
{tab:strings.op=rv}
\tcode{data()}      &
points at the array whose first
element was pointed at by \tcode{str.data()}                                            \\
\tcode{size()}      &   previous value of \tcode{str.size()}                            \\
\tcode{capacity()}  &   a value at least as large as \tcode{size()}                     \\
\end{libefftabvalue}
\end{itemdescr}

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

\begin{itemdescr}
\pnum
\returns
\tcode{*this = basic_string(s)}.

\pnum
\notes
Uses
\indexlibrary{\idxcode{length}!\tcode{char_traits}}%
\tcode{traits::length()}.
\end{itemdescr}

\indexlibrary{\idxcode{operator=}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{operator=}}%
\begin{itemdecl}
basic_string& operator=(charT c);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{*this = basic_string(1,c)}.
\end{itemdescr}

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

\begin{itemdescr}
\pnum
\effects \tcode{*this = basic_string(il)}.

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

\rSec2[string.iterators]{\tcode{basic_string} iterator support}

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

\begin{itemdescr}
\pnum
\returns
An iterator referring to the first character in the string.
\end{itemdescr}

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

\begin{itemdescr}
\pnum
\returns
An iterator which is the past-the-end value.
\end{itemdescr}

\indexlibrary{\idxcode{rbegin}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{rbegin}}%
\indexlibrary{\idxcode{crbegin}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{crbegin}}%
\begin{itemdecl}
reverse_iterator       rbegin() noexcept;
const_reverse_iterator rbegin() const noexcept;
const_reverse_iterator crbegin() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
An iterator which is semantically equivalent to
\tcode{reverse_iterator(end())}.
\end{itemdescr}

\indexlibrary{\idxcode{rend}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{rend}}%
\indexlibrary{\idxcode{crend}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{crend}}%
\begin{itemdecl}
reverse_iterator       rend() noexcept;
const_reverse_iterator rend() const noexcept;
const_reverse_iterator crend() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
An iterator which is semantically equivalent to
\tcode{reverse_iterator(begin())}.
\end{itemdescr}

\rSec2[string.capacity]{\tcode{basic_string} capacity}

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

\begin{itemdescr}
\pnum
\returns
A count of the number of char-like objects currently in the string.

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

\indexlibrary{\idxcode{length}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{length}}%
\begin{itemdecl}
size_type length() const noexcept;
\end{itemdecl}

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

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

\begin{itemdescr}
\pnum
\returns
The size of the largest possible string.

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

\indexlibrary{\idxcode{basic_string}!\idxcode{resize}}%
\indexlibrary{\idxcode{resize}!\idxcode{basic_string}}%
\begin{itemdecl}
void resize(size_type n, charT c);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{n <= max_size()}

\pnum
\throws
\tcode{length_error}
if
\tcode{n > max_size()}.

\pnum
\effects
Alters the length of the string designated by
\tcode{*this}
as follows:

\begin{itemize}
\item
If
\tcode{n <= size()},
the function replaces the string designated by
\tcode{*this}
with a string of length \tcode{n} whose elements are a
copy of the initial elements of the original string designated by
\tcode{*this}.
\item
If
\tcode{n > size()},
the function replaces the string designated by
\tcode{*this}
with a string of length \tcode{n} whose first
\tcode{size()}
elements are a copy of the original string designated by
\tcode{*this},
and whose remaining elements are all initialized to \tcode{c}.
\end{itemize}
\end{itemdescr}

\indexlibrary{\idxcode{resize}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{resize}}%
\begin{itemdecl}
void resize(size_type n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
\tcode{resize(n,charT())}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_string}!\idxcode{capacity}}%
\indexlibrary{\idxcode{capacity}!\idxcode{basic_string}}%
\begin{itemdecl}
size_type capacity() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The size of the allocated storage in the string.
\end{itemdescr}

\indexlibrary{\idxcode{basic_string}!\idxcode{reserve}}%
\indexlibrary{\idxcode{reserve}!\idxcode{basic_string}}%
\begin{itemdecl}
void reserve(size_type res_arg=0);
\end{itemdecl}

\begin{itemdescr}
\pnum
The member function
\tcode{reserve()}
is a directive that informs a
\tcode{basic_string}
object of a planned change in size,
so that it can manage the storage allocation accordingly.

\pnum
\effects
After
\tcode{reserve()},
\tcode{capacity()}
is greater or equal to the argument of
\tcode{reserve}.
\enternote
Calling
\tcode{reserve()}
with a \tcode{res_arg} argument less than
\tcode{capacity()}
is in effect a non-binding shrink request.
A call with
\tcode{res_arg <= size()}
is in effect a non-binding shrink-to-fit request.
\exitnote

\pnum
\throws
\tcode{length_error}
if
\tcode{res_arg > max_size()}.\footnote{\tcode{reserve()}
uses
\tcode{allocator_traits<Allocator>::allocate()}
which may throw an appropriate exception.}
\end{itemdescr}

\indexlibrary{\idxcode{basic_string}!\idxcode{shrink_to_fit}}%
\indexlibrary{\idxcode{shrink_to_fit}!\idxcode{basic_string}}%
\begin{itemdecl}
void shrink_to_fit();
\end{itemdecl}

\begin{itemdescr}
\pnum
\notes \tcode{shrink_to_fit} is a non-binding request to reduce
\tcode{capacity()} to \tcode{size()}. \enternote The request is non-binding to
allow latitude for implementation-specific optimizations. \exitnote
\end{itemdescr}

\indexlibrary{\idxcode{basic_string}!\idxcode{clear}}%
\indexlibrary{\idxcode{clear}!\idxcode{basic_string}}%
\begin{itemdecl}
void clear() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves as if the function calls:

\begin{codeblock}
erase(begin(), end());
\end{codeblock}
\end{itemdescr}

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

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

\rSec2[string.access]{\tcode{basic_string} element access}

\indexlibrary{\idxcode{basic_string}!\idxcode{operator[]}}%
\indexlibrary{\idxcode{operator[]}!\idxcode{basic_string}}%
\begin{itemdecl}
const_reference operator[](size_type pos) const;
reference       operator[](size_type pos);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{pos <= size()}.

\pnum
\returns \tcode{*(begin() + pos)} if \tcode{pos < size()}. Otherwise,
returns a reference to an object of type \tcode{charT} with value
\tcode{charT()}, where modifying the object leads to
undefined behavior.

\pnum
\throws Nothing.

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

\indexlibrary{\idxcode{basic_string}!\idxcode{at}}%
\indexlibrary{\idxcode{at}!\idxcode{basic_string}}%
\begin{itemdecl}
const_reference at(size_type pos) const;
reference       at(size_type pos);
\end{itemdecl}

\begin{itemdescr}
\pnum
\throws
\tcode{out_of_range}
if
\tcode{pos >= size()}.

\pnum
\returns
\tcode{operator[](pos)}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_string}!\idxcode{front}}%
\indexlibrary{\idxcode{front}!\idxcode{basic_string}}%
\begin{itemdecl}
const charT& front() const;
charT& front();
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{!empty()}

\pnum
\effects
Equivalent to \tcode{operator[](0)}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_string}!\idxcode{back}}%
\indexlibrary{\idxcode{back}!\idxcode{basic_string}}%
\begin{itemdecl}
const charT& back() const;
charT& back();
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{!empty()}

\pnum
\effects
Equivalent to \tcode{operator[](size() - 1)}.
\end{itemdescr}

\rSec2[string.modifiers]{\tcode{basic_string} modifiers}

\rSec3[string::op+=]{\tcode{basic_string::operator+=}}

\indexlibrary{\idxcode{basic_string}!\idxcode{operator+=}}%
\indexlibrary{\idxcode{operator+=}!\idxcode{basic_string}}%
\begin{itemdecl}
basic_string&
  operator+=(const basic_string& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Calls \tcode{append(str)}.

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

\indexlibrary{\idxcode{operator+=}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{operator+=}}%
\begin{itemdecl}
basic_string& operator+=(const charT* s);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Calls \tcode{append(s)}.

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

\indexlibrary{\idxcode{basic_string}!\idxcode{operator+=}}%
\indexlibrary{\idxcode{operator+=}!\idxcode{basic_string}}%
\begin{itemdecl}
basic_string& operator+=(charT c);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Calls \tcode{push_back(c)};

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

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

\begin{itemdescr}
\pnum
\effects Calls \tcode{append(il)}.

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


\rSec3[string::append]{\tcode{basic_string::append}}

\indexlibrary{\idxcode{basic_string}!\idxcode{append}}%
\indexlibrary{\idxcode{append}!\idxcode{basic_string}}%
\begin{itemdecl}
basic_string&
  append(const basic_string& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Calls \tcode{append(str.data(), str.size())}.

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

\indexlibrary{\idxcode{append}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{append}}%
\begin{itemdecl}
basic_string&
  append(const basic_string& str, size_type pos, size_type n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{pos <= str.size()}

\pnum
\throws
\tcode{out_of_range}
if
\tcode{pos > str.size()}.

\pnum
\effects
Determines the effective length \tcode{rlen}
of the string to append as the smaller of \tcode{n} and
\tcode{\tcode{str}.size() - \tcode{pos}} and calls \tcode{append(str.data() + pos, rlen)}.

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

\indexlibrary{\idxcode{append}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{append}}%
\begin{itemdecl}
basic_string&
  append(const charT* s, size_type n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{s} points to an array of at least \tcode{n} elements
of \tcode{charT}.

\pnum
\throws \tcode{length_error} if \tcode{size() + n > max_size()}.

\pnum
\effects The function replaces the string controlled by \tcode{*this}
with a string of length \tcode{size() + n} whose first \tcode{size()}
elements are a copy of the original string controlled by \tcode{*this}
and whose remaining elements are a copy of the initial \tcode{n} elements
of \tcode{s}.

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

\indexlibrary{\idxcode{append}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{append}}%
\begin{itemdecl}
basic_string& append(const charT* s);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{s} points to an array of at least \tcode{traits::length(s) + 1}
elements of \tcode{charT}.

\pnum
\effects Calls \tcode{append(s, traits::length(s))}.

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

\indexlibrary{\idxcode{basic_string}!\idxcode{append}}%
\indexlibrary{\idxcode{append}!\idxcode{basic_string}}%
\begin{itemdecl}
basic_string& append(size_type n, charT c);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Equivalent to \tcode{append(basic_string(n, c))}.

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

\indexlibrary{\idxcode{append}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{append}}%
\begin{itemdecl}
template<class InputIterator>
  basic_string& append(InputIterator first, InputIterator last);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \range{first}{last} is a valid range.

\pnum
\effects Equivalent to \tcode{append(basic_string(first, last))}.

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

\indexlibrary{\idxcode{append}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{append}}%
\begin{itemdecl}
basic_string& append(initializer_list<charT> il);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Calls \tcode{append(il.begin(), il.size())}.

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

\indexlibrary{\idxcode{push_back}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{push_back}}%
\begin{itemdecl}
void push_back(charT c)
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to
\tcode{append(static_cast<size_type>(1), c)}.
\end{itemdescr}

\rSec3[string::assign]{\tcode{basic_string::assign}}

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

\begin{itemdescr}
\pnum
\effects Equivalent to \tcode{assign(str, 0, npos)}.

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

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

\begin{itemdescr}
\effects The function replaces the string controlled by
\tcode{*this}
with a string of length \tcode{str.size()} whose elements are a copy of the
string controlled by \tcode{str}.
\enternote A valid implementation is
\tcode{swap(str)}. \exitnote

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


\indexlibrary{\idxcode{assign}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{assign}}%
\begin{itemdecl}
basic_string&
  assign(const basic_string& str, size_type pos,
         size_type n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{pos <= str.size()}

\pnum
\throws
\tcode{out_of_range}
if
\tcode{pos > str.size()}.

\pnum
\effects
Determines the effective length \tcode{rlen}
of the string to assign as the smaller of \tcode{n} and
\tcode{\tcode{str}.size() - \tcode{pos}} and calls
\tcode{assign(str.data() + pos rlen)}.

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

\indexlibrary{\idxcode{assign}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{assign}}%
\begin{itemdecl}
basic_string& assign(const charT* s, size_type n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{s} points to an array of at least \tcode{n} elements of \tcode{charT}.

\pnum
\throws \tcode{length_error} if \tcode{n > max_size()}.

\pnum
\effects Replaces the string controlled by \tcode{*this} with a string
of length \tcode{n} whose elements are a copy of those pointed to by \tcode{s}.

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

\indexlibrary{\idxcode{assign}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{assign}}%
\begin{itemdecl}
basic_string& assign(const charT* s);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{s} points to an array of at least \tcode{traits::length(s) + 1}
elements of \tcode{charT}.

\pnum
\effects Calls \tcode{assign(s, traits::length(s))}.

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

\indexlibrary{\idxcode{assign}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{assign}}%
\begin{itemdecl}
basic_string& assign(initializer_list<charT> il);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Calls \tcode{assign(il.begin(), il.size())}.

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


\indexlibrary{\idxcode{length}!\tcode{char_traits}}%
\begin{itemdecl}
basic_string& assign(size_type n, charT c);
\end{itemdecl}

\begin{itemdescr}
\pnum
\pnum
\effects Equivalent to \tcode{assign(basic_string(n, c))}.

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

\indexlibrary{\idxcode{assign}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{assign}}%
\begin{itemdecl}
template<class InputIterator>
  basic_string& assign(InputIterator first, InputIterator last);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Equivalent to \tcode{assign(basic_string(first, last))}.

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

\rSec3[string::insert]{\tcode{basic_string::insert}}

\indexlibrary{\idxcode{basic_string}!\idxcode{insert}}%
\indexlibrary{\idxcode{insert}!\idxcode{basic_string}}%
\begin{itemdecl}
basic_string&
  insert(size_type pos1,
         const basic_string& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{pos <= size()}.

\pnum
\throws \tcode{out_of_range} if \tcode{pos > size()}.

\pnum
\effects Calls \tcode{insert(pos, str.data(), str.size())}.

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

\indexlibrary{\idxcode{insert}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{insert}}%
\begin{itemdecl}
basic_string&
  insert(size_type pos1,
         const basic_string& str,
         size_type pos2, size_type n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{pos1 <= size()}
and
\tcode{pos2 <= str.size()}

\pnum
\throws
\tcode{out_of_range}
if
\tcode{pos1 > size()}
or
\tcode{pos2 > str.size()}.

\pnum
\effects
Determines the effective length \tcode{rlen} of the string to insert as the smaller
of \tcode{n} and
\tcode{str.size() - pos2} and calls \tcode{insert(pos1, str.data() + pos2, rlen)}.

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

\indexlibrary{\idxcode{insert}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{insert}}%
\begin{itemdecl}
basic_string&
  insert(size_type pos, const charT* s, size_type n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{s} points to an array of at least \tcode{n}
elements of \tcode{charT} and \tcode{pos <= size()}.

\pnum
\throws \tcode{out_of_range} if \tcode{pos > size()} or \tcode{length_error}
if \tcode{size() + n > max_size()}.

\pnum
\effects Replaces the string controlled by \tcode{*this} with a string of
length \tcode{size() + n} whose first \tcode{pos} elements are a copy of
the initial elements of the original string controlled by \tcode{*this} and
whose next \tcode{n} elements are a copy of the elements in \tcode{s} and
whose remaining elements are a copy of the remaining elements of the original
string controlled by \tcode{*this}.

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

\indexlibrary{\idxcode{insert}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{insert}}%
\begin{itemdecl}
basic_string&
  insert(size_type pos, const charT* s);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{pos <= size()} and \tcode{s} points to an array of at least
\tcode{traits::length(s) + 1} elements of \tcode{charT}.

\pnum
\effects Equivalent to \tcode{insert(pos, s, traits::length(s))}.

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

\indexlibrary{\idxcode{basic_string}!\idxcode{insert}}%
\indexlibrary{\idxcode{insert}!\idxcode{basic_string}}%
\begin{itemdecl}
basic_string&
  insert(size_type pos, size_type n, charT c);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Equivalent to \tcode{insert(pos, basic_string(n, c))}.

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

\indexlibrary{\idxcode{insert}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{insert}}%
\begin{itemdecl}
iterator insert(const_iterator p, charT c);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{p} is a valid iterator on
\tcode{*this}.

\pnum
\effects
inserts a copy of \tcode{c} before the character referred to by \tcode{p}.

\pnum
\returns
An iterator which refers to the copy of the inserted character.
\end{itemdescr}

\indexlibrary{\idxcode{insert}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{insert}}%
\begin{itemdecl}
iterator insert(const_iterator p, size_type n, charT c);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{p} is a valid iterator on
\tcode{*this}.

\pnum
\effects
inserts \tcode{n} copies of \tcode{c} before the character referred to by \tcode{p}.

\pnum
\returns An iterator which refers to the copy of the first inserted character, or
\tcode{p} if \tcode{n == 0}.
\end{itemdescr}

\indexlibrary{\idxcode{insert}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{insert}}%
\begin{itemdecl}
template<class InputIterator>
  iterator insert(const_iterator p, InputIterator first, InputIterator last);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{p} is a valid iterator on
\tcode{*this}.
\tcode{[first,last)}
is a valid range.

\pnum
\effects
Equivalent to
\tcode{insert(p - begin(), basic_string(first, last))}.

\pnum
\returns An iterator which refers to the copy of the first inserted character, or
\tcode{p} if \tcode{first == last}.
\end{itemdescr}

\indexlibrary{\idxcode{insert}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{insert}}%
\begin{itemdecl}
iterator insert(const_iterator p, initializer_list<charT> il);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects \tcode{insert(p, il.begin(), il.end())}.

\pnum
\returns An iterator which refers to the copy of the first inserted character, or
\tcode{p} if \tcode{i1} is empty.
\end{itemdescr}

\rSec3[string::erase]{\tcode{basic_string::erase}}

\indexlibrary{\idxcode{basic_string}!\idxcode{erase}}%
\indexlibrary{\idxcode{erase}!\idxcode{basic_string}}%
\begin{itemdecl}
basic_string& erase(size_type pos = 0, size_type n = npos);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{pos}
\tcode{ <= size()}

\pnum
\throws
\tcode{out_of_range}
if \tcode{pos}
\tcode{> size()}.

\pnum
\effects
Determines the effective length \tcode{xlen}
of the string to be removed as the smaller of \tcode{n} and
\tcode{size() - pos}.

\pnum
The function then replaces the string controlled by
\tcode{*this}
with a string of length
\tcode{size() - xlen}
whose first \tcode{pos} elements are a copy of the initial elements of the original string controlled by
\tcode{*this},
and whose remaining elements are a copy of the elements of the original string controlled by
\tcode{*this}
beginning at position
\tcode{pos + xlen}.

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

\indexlibrary{\idxcode{erase}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{erase}}%
\begin{itemdecl}
iterator erase(const_iterator p);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
removes the character referred to by \tcode{p}.

\pnum
\returns
An iterator which points to the element immediately following \tcode{p} prior to
the element being erased.
If no such element exists,
\tcode{end()}
is returned.
\end{itemdescr}

\indexlibrary{\idxcode{erase}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{erase}}%
\begin{itemdecl}
iterator erase(const_iterator first, const_iterator last);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{first} and \tcode{last} are valid iterators on
\tcode{*this},
defining a range
\tcode{[first,last)}.

\pnum
\effects
removes the characters in the range
\tcode{[first,last)}.

\pnum
\returns
An iterator which points to the element pointed to by \tcode{last} prior to
the other elements being erased.
If no such element exists,
\tcode{end()}
is returned.
\end{itemdescr}

\indexlibrary{\idxcode{basic_string}!\idxcode{pop_back}}%
\indexlibrary{\idxcode{pop_back}!\idxcode{basic_string}}%
\begin{itemdecl}
void pop_back();
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{!empty()}

\pnum
\effects
Equivalent to \tcode{erase(size() - 1, 1)}.
\end{itemdescr}

\rSec3[string::replace]{\tcode{basic_string::replace}}

\indexlibrary{\idxcode{basic_string}!\idxcode{replace}}%
\indexlibrary{\idxcode{replace}!\idxcode{basic_string}}%
\begin{itemdecl}
basic_string&
  replace(size_type pos1, size_type n1,
          const basic_string& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{pos1 <= size()}.

\pnum
\throws \tcode{out_of_range} if \tcode{pos1 > size()}.

\pnum
\effects Calls \tcode{replace(pos1, n1, str.data(), str.size())}.

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

\indexlibrary{\idxcode{replace}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{replace}}%
\begin{itemdecl}
basic_string&
  replace(size_type pos1, size_type n1,
          const basic_string& str,
          size_type pos2, size_type n2);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{pos1 <= size()} and \tcode{pos2 <= str.size()}.

\pnum
\throws
\tcode{out_of_range}
if
\tcode{pos1 > size()}
or
\tcode{pos2 > str.size()}.

\pnum
\effects
Determines the effective length \tcode{rlen} of the string to be inserted
as the smaller of \tcode{n2} and \tcode{str.size() - pos2} and calls
\tcode{replace(pos1, n1, str.data() + pos2, rlen)}.

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

\indexlibrary{\idxcode{replace}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{replace}}%
\begin{itemdecl}
basic_string&
  replace(size_type pos1, size_type n1, const charT* s, size_type n2);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{pos1 <= size()} and \tcode{s} points to an array of at
least \tcode{n2} elements of \tcode{charT}.

\pnum
\throws \tcode{out_of_range} if \tcode{pos1 > size()} or \tcode{length_error}
if the length of the resulting string would exceed \tcode{max_size()} (see below).

\pnum
\effects Determines the effective length \tcode{xlen} of the string to be
removed as the smaller of \tcode{n1} and \tcode{size() - pos1}. If
\tcode{size() - xlen >= max_size() - n2} throws \tcode{length_error}. Otherwise,
the function replaces the string controlled by *\tcode{this} with a string of
length \tcode{size() - xlen + n2} whose first \tcode{pos1} elements are a copy
of the initial elements of the original string controlled by \tcode{*this},
whose next \tcode{n2} elements are a copy of the initial \tcode{n2} elements
of \tcode{s}, and whose remaining elements are a copy of the elements of the
original string controlled by \tcode{*this} beginning at position
\tcode{pos + xlen}.

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

\indexlibrary{\idxcode{replace}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{replace}}%
\begin{itemdecl}
basic_string&
  replace(size_type pos, size_type n, const charT* s);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{pos <= size()} and \tcode{s} points to an array of at least
\tcode{traits::length(s) + 1} elements of \tcode{charT}.

\pnum
\effects Calls \tcode{replace(pos, n, s, traits::length(s))}.

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

\indexlibrary{\idxcode{basic_string}!\idxcode{replace}}%
\indexlibrary{\idxcode{replace}!\idxcode{basic_string}}%
\begin{itemdecl}
basic_string&
  replace(size_type pos1, size_type n1,
          size_type n2, charT c);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Equivalent to \tcode{replace(pos1, n1, basic_string(n2, c))}.

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

\indexlibrary{\idxcode{replace}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{replace}}%
\begin{itemdecl}
basic_string& replace(const_iterator i1, const_iterator i2, const basic_string& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\range{begin()}{i1} and \range{i1}{i2} are valid ranges.

\pnum
\effects
Calls \tcode{replace(i1 - begin(), i2 - i1, str)}.

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

\indexlibrary{\idxcode{replace}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{replace}}%
\begin{itemdecl}
basic_string&
  replace(const_iterator i1, const_iterator i2, const charT* s, size_type n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \range{begin()}{i1} and \range{i1}{i2} are valid ranges and
\tcode{s} points to an array of at least \tcode{n} elements of \tcode{charT}.

\pnum
\effects Calls \tcode{replace(i1 - begin(), i2 - i1, s, n)}.

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

\indexlibrary{\idxcode{replace}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{replace}}%
\begin{itemdecl}
basic_string& replace(const_iterator i1, const_iterator i2, const charT* s);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \range{begin()}{i1} and \range{i1}{i2} are valid ranges and
\tcode{s} points to an array of at least \tcode{traits::\brk{}length(s) + 1}
elements of \tcode{charT}.

\pnum
\effects Calls \tcode{replace(i1 - begin(), i2 - i1, s, traits::length(s))}.

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

\indexlibrary{\idxcode{replace}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{replace}}%
\begin{itemdecl}
basic_string& replace(const_iterator i1, const_iterator i2, size_type n,
                      charT c);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \range{begin()}{i1} and \range{i1}{i2} are valid ranges.

\pnum
\effects Calls \tcode{replace(i1 - begin(), i2 - i1, basic_string(n, c))}.

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

\indexlibrary{\idxcode{replace}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{replace}}%
\begin{itemdecl}
template<class InputIterator>
  basic_string& replace(const_iterator i1, const_iterator i2,
                        InputIterator j1, InputIterator j2);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \range{begin()}{i1}, \range{i1}{i2} and \range{j1}{j2} are valid ranges.

\pnum
\effects Calls \tcode{replace(i1 - begin(), i2 - i1, basic_string(j1, j2))}.

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

\indexlibrary{\idxcode{replace}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{replace}}%
\begin{itemdecl}
basic_string& replace(const_iterator i1, const_iterator i2,
                      initializer_list<charT> il);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \range{begin()}{i1} and \range{i1}{i2} are valid ranges.

\pnum
\effects Calls \tcode{replace(i1 - begin(), i2 - i1, il.begin(), il.size())}.

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


\rSec3[string::copy]{\tcode{basic_string::copy}}

\indexlibrary{\idxcode{basic_string}!\idxcode{copy}}%
\indexlibrary{\idxcode{copy}!\idxcode{basic_string}}%
\begin{itemdecl}
size_type copy(charT* s, size_type n, size_type pos = 0) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{pos <= size()}

\pnum
\throws
\tcode{out_of_range}
if
\tcode{pos > size()}.

\pnum
\effects
Determines the effective length \tcode{rlen}
of the string to copy as the smaller of \tcode{n} and
\tcode{size() - pos}.
\tcode{s} shall designate an array of at least \tcode{rlen} elements.

The function then replaces the string designated by \tcode{s}
with a string of length \tcode{rlen} whose elements are a copy of the
string controlled by
\tcode{*this}
beginning at position \tcode{pos}.

The function does not append a null object to the string designated
by \tcode{s}.

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

\rSec3[string::swap]{\tcode{basic_string::swap}}

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

\begin{itemdescr}
\pnum
\postcondition
\tcode{*this}
contains the same sequence of characters that was in \tcode{s},
\tcode{s} contains the same sequence of characters that was in
\tcode{*this}.

\pnum
\throws Nothing.

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

\rSec2[string.ops]{\tcode{basic_string} string operations}

\rSec3[string.accessors]{\tcode{basic_string} accessors}

\indexlibrary{\idxcode{c_str}!\tcode{basic_string}}%
\indexlibrary{\idxcode{data}!\tcode{basic_string}}%
\begin{itemdecl}
const charT* c_str() const noexcept;
const charT* data() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns A pointer \tcode{p} such that \tcode{p + i == \&operator[](i)} for each
\tcode{i} in \crange{0}{size()}.

\pnum
\complexity constant time.

\pnum
\requires
The program shall not alter any of the values stored in the character array.
\end{itemdescr}

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

\begin{itemdescr}
\pnum
\returns
A copy of the
\tcode{Allocator}
object used to construct the string or, if that allocator has been replaced, a
copy of the most recent replacement.
\end{itemdescr}

\rSec3[string::find]{\tcode{basic_string::find}}

\indexlibrary{\idxcode{basic_string}!\idxcode{find}}%
\indexlibrary{\idxcode{find}!\idxcode{basic_string}}%
\begin{itemdecl}
size_type find(const basic_string& str,
               size_type pos = 0) const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Determines the lowest position \tcode{xpos}, if possible, such that both of
the following conditions obtain:

\begin{itemize}
\item
\tcode{pos <= xpos} and
\tcode{xpos + str.size() <= size()};
\item
\indexlibrary{\idxcode{eq}!\tcode{char_traits}}%
\tcode{traits::eq(at(xpos+I), str.at(I))}
for all elements \tcode{I} of the string controlled by \tcode{str}.
\end{itemize}

\pnum
\returns
\tcode{xpos} if the function can determine such a value for \tcode{xpos}.
Otherwise, returns
\tcode{npos}.

\pnum
\notes
Uses
\tcode{traits::eq()}.
\end{itemdescr}

\indexlibrary{\idxcode{find}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{find}}%
\begin{itemdecl}
size_type find(const charT* s, size_type pos, size_type n) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{find(basic_string(s,n),pos)}.
\end{itemdescr}

\indexlibrary{\idxcode{find}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{find}}%
\begin{itemdecl}
size_type find(const charT* s, size_type pos = 0) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{s} points to an array of at least \tcode{traits::length(s) + 1}
elements of \tcode{charT}.

\pnum
\returns
\tcode{find(basic_string(s), pos)}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_string}!\idxcode{find}}%
\indexlibrary{\idxcode{find}!\idxcode{basic_string}}%
\begin{itemdecl}
size_type find(charT c, size_type pos = 0) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{find(basic_string(1,c), pos)}.
\end{itemdescr}

\rSec3[string::rfind]{\tcode{basic_string::rfind}}

\indexlibrary{\idxcode{basic_string}!\idxcode{rfind}}%
\indexlibrary{\idxcode{rfind}!\idxcode{basic_string}}%
\begin{itemdecl}
size_type rfind(const basic_string& str,
                size_type pos = npos) const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Determines the highest position \tcode{xpos}, if possible, such that both of
the following conditions obtain:

\begin{itemize}
\item
\tcode{xpos <= pos}
and
\tcode{xpos + str.size() <= size()};
\item
\indexlibrary{\idxcode{eq}!\tcode{char_traits}}%
\tcode{traits::eq(at(xpos+I), str.at(I))}
for all elements \tcode{I} of the string controlled by \tcode{str}.
\end{itemize}

\pnum
\returns
\tcode{xpos} if the function can determine such a value for \tcode{xpos}.
Otherwise, returns
\tcode{npos}.

\pnum
\notes
Uses
\tcode{traits::eq()}.
\end{itemdescr}

\indexlibrary{\idxcode{rfind}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{rfind}}%
\begin{itemdecl}
size_type rfind(const charT* s, size_type pos, size_type n) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{rfind(basic_string(s, n), pos)}.
\end{itemdescr}

\indexlibrary{\idxcode{rfind}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{rfind}}%
\begin{itemdecl}
size_type rfind(const charT* s, size_type pos = npos) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires s points to an array of at least \tcode{traits::length(s) + 1}
elements of \tcode{charT}.

\pnum
\returns
\tcode{rfind(basic_string(s), pos)}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_string}!\idxcode{rfind}}%
\indexlibrary{\idxcode{rfind}!\idxcode{basic_string}}%
\begin{itemdecl}
size_type rfind(charT c, size_type pos = npos) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{rfind(basic_string(1,c),pos)}.
\end{itemdescr}

\rSec3[string::find.first.of]{\tcode{basic_string::find_first_of}}

\indexlibrary{\idxcode{basic_string}!\idxcode{find_first_of}}%
\indexlibrary{\idxcode{find_first_of}!\idxcode{basic_string}}%
\begin{itemdecl}
size_type
  find_first_of(const basic_string& str,
                size_type pos = 0) const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Determines the lowest position \tcode{xpos}, if possible, such that both of
the following conditions obtain:

\begin{itemize}
\item
\tcode{pos <= xpos}
and
\tcode{xpos < size()};
\item
\indexlibrary{\idxcode{eq}!\tcode{char_traits}}%
\tcode{traits::eq(at(xpos), str.at(I))}
for some element \tcode{I} of the string controlled by \tcode{str}.
\end{itemize}

\pnum
\returns
\tcode{xpos} if the function can determine such a value for \tcode{xpos}.
Otherwise, returns
\tcode{npos}.

\pnum
\notes
Uses
\tcode{traits::eq()}.
\end{itemdescr}

\indexlibrary{\idxcode{find_first_of}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{find_first_of}}%
\begin{itemdecl}
size_type
  find_first_of(const charT* s, size_type pos, size_type n) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{find_first_of(basic_string(s, n), pos)}.
\end{itemdescr}

\indexlibrary{\idxcode{find_first_of}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{find_first_of}}%
\begin{itemdecl}
size_type find_first_of(const charT* s, size_type pos = 0) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{s} points to an array of at least \tcode{traits::length(s) + 1}
elements of \tcode{charT}.

\pnum
\returns
\tcode{find_first_of(basic_string(s), pos)}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_string}!\idxcode{find_first_of}}%
\indexlibrary{\idxcode{find_first_of}!\idxcode{basic_string}}%
\begin{itemdecl}
size_type find_first_of(charT c, size_type pos = 0) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{find_first_of(basic_string(1,c), pos)}.
\end{itemdescr}

\rSec3[string::find.last.of]{\tcode{basic_string::find_last_of}}

\indexlibrary{\idxcode{basic_string}!\idxcode{find_last_of}}%
\indexlibrary{\idxcode{find_last_of}!\idxcode{basic_string}}%
\begin{itemdecl}
size_type
  find_last_of(const basic_string& str,
               size_type pos = npos) const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Determines the highest position \tcode{xpos}, if possible, such that both of
the following conditions obtain:

\begin{itemize}
\item
\tcode{xpos <= pos}
and
\tcode{xpos < size()};
\item
\indexlibrary{\idxcode{eq}!\tcode{char_traits}}%
\tcode{traits::eq(at(xpos), str.at(I))}
for some element \tcode{I} of the string controlled by \tcode{str}.
\end{itemize}

\pnum
\returns
\tcode{xpos} if the function can determine such a value for \tcode{xpos}.
Otherwise, returns
\tcode{npos}.

\pnum
\notes
Uses
\tcode{traits::eq()}.
\end{itemdescr}

\indexlibrary{\idxcode{find_last_of}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{find_last_of}}%
\begin{itemdecl}
size_type find_last_of(const charT* s, size_type pos, size_type n) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{find_last_of(basic_string(s, n), pos)}.
\end{itemdescr}

\indexlibrary{\idxcode{find_last_of}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{find_last_of}}%
\begin{itemdecl}
size_type find_last_of(const charT* s, size_type pos = npos) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{s} points to an array of at least \tcode{traits::length(s) + 1}
elements of \tcode{charT}.

\pnum
\returns
\tcode{find_last_of(basic_string(s), pos)}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_string}!\idxcode{find_last_of}}%
\indexlibrary{\idxcode{find_last_of}!\idxcode{basic_string}}%
\begin{itemdecl}
size_type find_last_of(charT c, size_type pos = npos) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{find_last_of(basic_string(1,c),pos)}.
\end{itemdescr}

\rSec3[string::find.first.not.of]{\tcode{basic_string::find_first_not_of}}

\indexlibrary{\idxcode{basic_string}!\idxcode{find_first_not_of}}%
\indexlibrary{\idxcode{find_first_not_of}!\idxcode{basic_string}}%
\begin{itemdecl}
size_type
  find_first_not_of(const basic_string& str,
                    size_type pos = 0) const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Determines the lowest position \tcode{xpos}, if possible, such that both of
the following conditions obtain:

\begin{itemize}
\item
\tcode{pos <= xpos}
and
\tcode{xpos < size()};
\item
\indexlibrary{\idxcode{eq}!\tcode{char_traits}}%
\tcode{traits::eq(at(xpos), str.at(I))}
for no element \tcode{I} of the string controlled by \tcode{str}.
\end{itemize}

\pnum
\returns
\tcode{xpos} if the function can determine such a value for \tcode{xpos}.
Otherwise, returns
\tcode{npos}.

\pnum
\notes
Uses
\tcode{traits::eq()}.
\end{itemdescr}

\indexlibrary{\idxcode{find_first_not_of}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{find_first_not_of}}%
\begin{itemdecl}
size_type
  find_first_not_of(const charT* s, size_type pos, size_type n) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{find_first_not_of(basic_string(s, n), pos)}.
\end{itemdescr}

\indexlibrary{\idxcode{find_first_not_of}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{find_first_not_of}}%
\begin{itemdecl}
size_type find_first_not_of(const charT* s, size_type pos = 0) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{s} points to an array of at least \tcode{traits::length(s) + 1}
elements of \tcode{charT}.

\pnum
\returns
\tcode{find_first_not_of(basic_string(s), pos)}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_string}!\idxcode{find_first_not_of}}%
\indexlibrary{\idxcode{find_first_not_of}!\idxcode{basic_string}}%
\begin{itemdecl}
size_type find_first_not_of(charT c, size_type pos = 0) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{find_first_not_of(basic_string(1, c), pos)}.
\end{itemdescr}

\rSec3[string::find.last.not.of]{\tcode{basic_string::find_last_not_of}}

\indexlibrary{\idxcode{basic_string}!\idxcode{find_last_not_of}}%
\indexlibrary{\idxcode{find_last_not_of}!\idxcode{basic_string}}%
\begin{itemdecl}
size_type
  find_last_not_of(const basic_string& str,
                   size_type pos = npos) const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Determines the highest position \tcode{xpos}, if possible, such that both of
the following conditions obtain:

\begin{itemize}
\item
\tcode{xpos <= pos}
and
\tcode{xpos < size()};
\item
\indexlibrary{\idxcode{eq}!\tcode{char_traits}}%
\tcode{traits::eq(at(xpos), str.at(I))}
for no element \tcode{I} of the string
controlled by \tcode{str}.
\end{itemize}

\pnum
\returns
\tcode{xpos} if the function can determine such a value for \tcode{xpos}.
Otherwise, returns
\tcode{npos}.

\pnum
\notes
Uses
\tcode{traits::eq()}.
\end{itemdescr}

\indexlibrary{\idxcode{find_last_not_of}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{find_last_not_of}}%
\begin{itemdecl}
size_type find_last_not_of(const charT* s, size_type pos,
                           size_type n) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{find_last_not_of(basic_string(s, n), pos)}.
\end{itemdescr}

\indexlibrary{\idxcode{find_last_not_of}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{find_last_not_of}}%
\begin{itemdecl}
size_type find_last_not_of(const charT* s, size_type pos = npos) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{s} points to an array of at least \tcode{traits::length(s) + 1}
elements of \tcode{charT}.

\pnum
\returns
\tcode{find_last_not_of(basic_string(s), pos)}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_string}!\idxcode{find_last_not_of}}%
\indexlibrary{\idxcode{find_last_not_of}!\idxcode{basic_string}}%
\begin{itemdecl}
size_type find_last_not_of(charT c, size_type pos = npos) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{find_last_not_of(basic_string(1, c), pos)}.
\end{itemdescr}

\rSec3[string::substr]{\tcode{basic_string::substr}}

\indexlibrary{\idxcode{basic_string}!\idxcode{substr}}%
\indexlibrary{\idxcode{substr}!\idxcode{basic_string}}%
\begin{itemdecl}
basic_string substr(size_type pos = 0, size_type n = npos) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{pos <= size()}

\pnum
\throws
\tcode{out_of_range}
if
\tcode{pos > size()}.

\pnum
\effects
Determines the effective length \tcode{rlen} of the string to copy as the smaller of \tcode{n} and
\tcode{size() - pos}.

\pnum
\returns
\tcode{basic_string(data()+pos,rlen)}.
\end{itemdescr}

\rSec3[string::compare]{\tcode{basic_string::compare}}

\indexlibrary{\idxcode{basic_string}!\idxcode{compare}}%
\indexlibrary{\idxcode{compare}!\idxcode{basic_string}}%
\begin{itemdecl}
int compare(const basic_string& str) const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Determines the effective length
\textit{rlen}
of the strings to compare as the smallest of
\tcode{size()}
and
\tcode{str.size()}.
The function then compares the two strings by calling
\tcode{traits::compare(data(), str.data(), rlen)}.

\pnum
\returns
The nonzero result if the result of the comparison is nonzero.
Otherwise, returns a value as indicated in Table~\ref{tab:strings.compare}.

\begin{floattable}{\tcode{compare()} results}{tab:strings.compare}
{lc}
\topline
\lhdr{Condition}                &   \rhdr{Return Value} \\ \capsep
\tcode{size() < \ str.size()}  &   \tcode{< 0}         \\
\tcode{size() == str.size()}    &   \tcode{ \ 0}       \\
\tcode{size() > \ str.size()}  &   \tcode{> 0}         \\
\end{floattable}
\end{itemdescr}

\indexlibrary{\idxcode{compare}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{compare}}%
\begin{itemdecl}
int compare(size_type pos1, size_type n1,
            const basic_string& str) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns \tcode{basic_string(*this,pos1,n1).compare(str)}.
\end{itemdescr}

\indexlibrary{\idxcode{compare}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{compare}}%
\begin{itemdecl}
int compare(size_type pos1, size_type n1,
            const basic_string& str,
            size_type pos2, size_type n2 ) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns \tcode{basic_string(*this, pos1, n1).compare(basic_string(str, pos2, n2))}.
\end{itemdescr}

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

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

\indexlibrary{\idxcode{compare}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{compare}}%
\begin{itemdecl}
int compare(size_type pos, size_type n1,
            const charT *s) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns \tcode{basic_string(*this, pos, n1).compare(basic_string(s))}.
\end{itemdescr}

\indexlibrary{\idxcode{compare}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{compare}}%
\begin{itemdecl}
int compare(size_type pos, size_type n1,
            const charT *s, size_type n2) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns \tcode{basic_string(*this, pos, n1).compare(basic_string(s, n2))}.
\end{itemdescr}

\rSec2[string.nonmembers]{\tcode{basic_string} non-member functions}

\indexlibrary{\idxcode{basic_string}}

\rSec3[string::op+]{\tcode{operator+}}

\indexlibrary{\idxcode{basic_string}!\idxcode{operator+}}%
\indexlibrary{\idxcode{operator+}!\idxcode{basic_string}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  basic_string<charT,traits,Allocator>
    operator+(const basic_string<charT,traits,Allocator>& lhs,
              const basic_string<charT,traits,Allocator>& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{basic_string<charT,traits,Allocator>(lhs).append(rhs)}
\end{itemdescr}

\indexlibrary{\idxcode{basic_string}!\idxcode{operator+}}%
\indexlibrary{\idxcode{operator+}!\idxcode{basic_string}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  basic_string<charT,traits,Allocator>
    operator+(basic_string<charT,traits,Allocator>&& lhs,
              const basic_string<charT,traits,Allocator>& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{std::move(lhs.append(rhs))}
\end{itemdescr}

\indexlibrary{\idxcode{basic_string}!\idxcode{operator+}}%
\indexlibrary{\idxcode{operator+}!\idxcode{basic_string}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  basic_string<charT,traits,Allocator>
    operator+(const basic_string<charT,traits,Allocator>& lhs,
              basic_string<charT,traits,Allocator>&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{std::move(rhs.insert(0, lhs))}
\end{itemdescr}

\indexlibrary{\idxcode{basic_string}!\idxcode{operator+}}%
\indexlibrary{\idxcode{operator+}!\idxcode{basic_string}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  basic_string<charT,traits,Allocator>
    operator+(basic_string<charT,traits,Allocator>&& lhs,
              basic_string<charT,traits,Allocator>&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{std::move(lhs.append(rhs))}
\enternote Or equivalently
\tcode{std::move(rhs.insert(0, lhs))} \exitnote
\end{itemdescr}

\indexlibrary{\idxcode{operator+}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{operator+}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  basic_string<charT,traits,Allocator>
    operator+(const charT* lhs,
              const basic_string<charT,traits,Allocator>& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{basic_string<charT,traits,Allocator>(lhs) + rhs}.

\pnum
\notes
Uses
\tcode{traits::length()}.
\end{itemdescr}

\indexlibrary{\idxcode{operator+}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{operator+}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  basic_string<charT,traits,Allocator>
    operator+(const charT* lhs,
              basic_string<charT,traits,Allocator>&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{std::move(rhs.insert(0, lhs))}.

\pnum
\notes
Uses
\tcode{traits::length()}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_string}!\idxcode{operator+}}%
\indexlibrary{\idxcode{operator+}!\idxcode{basic_string}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  basic_string<charT,traits,Allocator>
    operator+(charT lhs,
              const basic_string<charT,traits,Allocator>& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{basic_string<charT,traits,Allocator>(1,lhs) + rhs}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_string}!\idxcode{operator+}}%
\indexlibrary{\idxcode{operator+}!\idxcode{basic_string}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  basic_string<charT,traits,Allocator>
    operator+(charT lhs,
              basic_string<charT,traits,Allocator>&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{std::move(rhs.insert(0, 1, lhs))}.
\end{itemdescr}

\indexlibrary{\idxcode{operator+}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{operator+}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  basic_string<charT,traits,Allocator>
    operator+(const basic_string<charT,traits,Allocator>& lhs,
              const charT* rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{lhs + basic_string<charT,traits,Allocator>(rhs)}.

\pnum
\notes
Uses
\tcode{traits::length()}.
\end{itemdescr}

\indexlibrary{\idxcode{operator+}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{operator+}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  basic_string<charT,traits,Allocator>
    operator+(basic_string<charT,traits,Allocator>&& lhs,
              const charT* rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{std::move(lhs.append(rhs))}.

\pnum
\notes
Uses
\tcode{traits::length()}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_string}!\idxcode{operator+}}%
\indexlibrary{\idxcode{operator+}!\idxcode{basic_string}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  basic_string<charT,traits,Allocator>
    operator+(const basic_string<charT,traits,Allocator>& lhs,
              charT rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{lhs + basic_string<charT,traits,Allocator>(1,rhs)}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_string}!\idxcode{operator+}}%
\indexlibrary{\idxcode{operator+}!\idxcode{basic_string}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  basic_string<charT,traits,Allocator>
    operator+(basic_string<charT,traits,Allocator>&& lhs,
              charT rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{std::move(lhs.append(1, rhs))}.
\end{itemdescr}

\rSec3[string::operator==]{\tcode{operator==}}

\indexlibrary{\idxcode{basic_string}!\idxcode{operator==}}%
\indexlibrary{\idxcode{operator==}!\idxcode{basic_string}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  bool operator==(const basic_string<charT,traits,Allocator>& lhs,
                  const basic_string<charT,traits,Allocator>& rhs) noexcept;
\end{itemdecl}

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

\indexlibrary{\idxcode{operator==}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{operator==}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  bool operator==(const charT* lhs,
                  const basic_string<charT,traits,Allocator>& rhs);
\end{itemdecl}

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

\indexlibrary{\idxcode{operator==}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{operator==}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  bool operator==(const basic_string<charT,traits,Allocator>& lhs,
                  const charT* rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{rhs} points to an array of at least \tcode{traits::length(rhs) + 1}
elements of \tcode{charT}.

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

\indexlibrary{\idxcode{length}!\tcode{char_traits}}%
\rSec3[string::op!=]{\tcode{operator!=}}

\indexlibrary{\idxcode{basic_string}!\idxcode{operator"!=}}%
\indexlibrary{\idxcode{operator"!=}!\idxcode{basic_string}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  bool operator!=(const basic_string<charT,traits,Allocator>& lhs,
                  const basic_string<charT,traits,Allocator>& rhs) noexcept;
\end{itemdecl}

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

\indexlibrary{\idxcode{operator"!=}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{operator"!=}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  bool operator!=(const charT* lhs,
                  const basic_string<charT,traits,Allocator>& rhs);
\end{itemdecl}

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

\indexlibrary{\idxcode{operator"!=}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{operator"!=}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  bool operator!=(const basic_string<charT,traits,Allocator>& lhs,
                  const charT* rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{rhs} points to an array of at least \tcode{traits::length(rhs) + 1}
elements of \tcode{charT}.

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

\rSec3[string::op<]{\tcode{operator<}}

\indexlibrary{\idxcode{basic_string}!\idxcode{operator<}}%
\indexlibrary{\idxcode{operator<}!\idxcode{basic_string}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  bool operator< (const basic_string<charT,traits,Allocator>& lhs,
                  const basic_string<charT,traits,Allocator>& rhs) noexcept;
\end{itemdecl}

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

\indexlibrary{\idxcode{operator<}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{operator<}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  bool operator< (const charT* lhs,
                  const basic_string<charT,traits,Allocator>& rhs);
\end{itemdecl}

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

\indexlibrary{\idxcode{operator<}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{operator<}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  bool operator< (const basic_string<charT,traits,Allocator>& lhs,
                  const charT* rhs);
\end{itemdecl}

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

\rSec3[string::op>]{\tcode{operator>}}

\indexlibrary{\idxcode{operator>}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{operator>}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  bool operator> (const basic_string<charT,traits,Allocator>& lhs,
                  const basic_string<charT,traits,Allocator>& rhs) noexcept;
\end{itemdecl}

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

\indexlibrary{\idxcode{operator>}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{operator>}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  bool operator> (const charT* lhs,
                  const basic_string<charT,traits,Allocator>& rhs);
\end{itemdecl}

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

\indexlibrary{\idxcode{operator>}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{operator>}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  bool operator> (const basic_string<charT,traits,Allocator>& lhs,
                  const charT* rhs);
\end{itemdecl}

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

\rSec3[string::op<=]{\tcode{operator<=}}

\indexlibrary{\idxcode{operator<=}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{operator<=}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  bool operator<=(const basic_string<charT,traits,Allocator>& lhs,
                  const basic_string<charT,traits,Allocator>& rhs) noexcept;
\end{itemdecl}

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

\indexlibrary{\idxcode{operator<=}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{operator<=}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  bool operator<=(const charT* lhs,
                  const basic_string<charT,traits,Allocator>& rhs);
\end{itemdecl}

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

\indexlibrary{\idxcode{operator<=}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{operator<=}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  bool operator<=(const basic_string<charT,traits,Allocator>& lhs,
                  const charT* rhs);
\end{itemdecl}

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

\rSec3[string::op>=]{\tcode{operator>=}}

\indexlibrary{\idxcode{operator>=}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{operator>=}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  bool operator>=(const basic_string<charT,traits,Allocator>& lhs,
                  const basic_string<charT,traits,Allocator>& rhs) noexcept;
\end{itemdecl}

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

\indexlibrary{\idxcode{operator>=}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{operator>=}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  bool operator>=(const charT* lhs,
                  const basic_string<charT,traits,Allocator>& rhs);
\end{itemdecl}

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

\indexlibrary{\idxcode{operator>=}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{operator>=}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  bool operator>=(const basic_string<charT,traits,Allocator>& lhs,
                  const charT* rhs);
\end{itemdecl}

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

\rSec3[string.special]{\tcode{swap}}

\indexlibrary{\idxcode{basic_string}!\idxcode{swap}}%
\indexlibrary{\idxcode{swap}!\idxcode{basic_string}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  void swap(basic_string<charT,traits,Allocator>& lhs,
    basic_string<charT,traits,Allocator>& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to \tcode{lhs.swap(rhs);}
\end{itemdescr}

\rSec3[string.io]{Inserters and extractors}

\indexlibrary{\idxcode{operator\shr}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{operator\shr}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  basic_istream<charT,traits>&
    operator>>(basic_istream<charT,traits>& is,
               basic_string<charT,traits,Allocator>& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves as a formatted input function~(\ref{istream.formatted.reqmts}).
After constructing a
\tcode{sentry}
object, if the sentry converts to true, calls
\tcode{str.erase()}
and then extracts characters from \tcode{is} and appends them
to \tcode{str} as if by calling
\tcode{str.append(1,c)}.
If
\tcode{is.width()}
is greater than zero, the maximum
number \tcode{n} of characters appended is
\tcode{is.width()};
otherwise \tcode{n} is
\tcode{str.max_size()}.
Characters are extracted and appended until any of the following
occurs:

\begin{itemize}
\item
\textit{n}
characters are stored;
\item
end-of-file occurs on the input sequence;
\item
\tcode{isspace(c,is.getloc())}
is true for the next available input character
\textit{c}.
\end{itemize}

\pnum
After the last character (if any) is extracted,
\tcode{is.width(0)}
is called and the
\tcode{sentry}
object \tcode{k} is destroyed.

\pnum
If the function extracts no characters, it calls
\tcode{is.setstate(ios::failbit)},
which may throw
\tcode{ios_base\colcol{}fail\-ure}~(\ref{iostate.flags}).

\pnum
\returns
\tcode{is}
\end{itemdescr}

\indexlibrary{\idxcode{operator\shl}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{operator\shl}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  basic_ostream<charT, traits>&
    operator<<(basic_ostream<charT, traits>& os,
               const basic_string<charT,traits,Allocator>& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves as a formatted output
function~(\ref{ostream.formatted.reqmts}) of \tcode{os}. Forms a character sequence
\tcode{seq}, initially consisting of the elements defined by the range
[\tcode{str.begin(), str.end()}). Determines padding for \tcode{seq}
as described in~\ref{ostream.formatted.reqmts}.
Then inserts \tcode{seq} as if by calling
\tcode{os.rdbuf()->sputn(\brk{}seq, n)}, where \tcode{n} is the larger
of \tcode{os.width()} and \tcode{str.size()};
then calls \tcode{os.\brk{}width(0)}.

\pnum
\returns
\tcode{os}
\end{itemdescr}

\indexlibrary{\idxcode{getline}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{getline}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  basic_istream<charT,traits>&
    getline(basic_istream<charT,traits>& is,
            basic_string<charT,traits,Allocator>& str,
            charT delim);
template<class charT, class traits, class Allocator>
  basic_istream<charT,traits>&
    getline(basic_istream<charT,traits>&& is,
            basic_string<charT,traits,Allocator>& str,
            charT delim);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves as an unformatted input function~(\ref{istream.unformatted}),
except that it does not affect the value returned by subsequent calls to
\tcode{basic_istream<>::gcount()}.
After constructing a
\tcode{sentry}
object, if the sentry converts to true, calls
\tcode{str.erase()}
and then extracts characters from \tcode{is} and appends them
to \tcode{str} as if by calling
\tcode{str.append(1, c)}
until any of the following occurs:

\begin{itemize}
\item
end-of-file occurs on the input sequence
(in which case, the
\tcode{getline}
function calls
\tcode{is.setstate(\brk{}ios_base\colcol{}eofbit)}).
\item
\tcode{traits::eq(c, delim)}
for the next available input character
\textit{c}
(in which case,
\textit{c}
is extracted but not appended)~(\ref{iostate.flags})
\item
\tcode{str.max_size()}
characters are stored
(in which case,
the function calls
\tcode{is.setstate(ios_base\colcol{}fail\-bit))}~(\ref{iostate.flags})
\end{itemize}

\pnum
The conditions are tested in the order shown.
In any case,
after the last character is extracted, the
\tcode{sentry}
object \tcode{k}
is destroyed.

\pnum
If the function extracts no characters, it calls
\tcode{is.setstate(ios_base\colcol{}fail\-bit)}
which may throw
\tcode{ios_base\colcol{}fail\-ure}~(\ref{iostate.flags}).

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

\indexlibrary{\idxcode{getline}!\idxcode{basic_string}}%
\indexlibrary{\idxcode{basic_string}!\idxcode{getline}}%
\begin{itemdecl}
template<class charT, class traits, class Allocator>
  basic_istream<charT,traits>&
    getline(basic_istream<charT,traits>& is,
            basic_string<charT,traits,Allocator>& str);
template<class charT, class traits, class Allocator>
  basic_istream<charT,traits>&
    getline(basic_istream<charT,traits>&& is,
            basic_string<charT,traits,Allocator>& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{getline(is,str,is.widen('\textbackslash n'))}
\end{itemdescr}

\rSec1[string.conversions]{Numeric conversions}

\indexlibrary{\idxcode{stoi}}%
\indexlibrary{\idxcode{stol}}%
\indexlibrary{\idxcode{stoul}}%
\indexlibrary{\idxcode{stoll}}%
\indexlibrary{\idxcode{stoull}}%
\begin{itemdecl}
int stoi(const string& str, size_t *idx = 0, int base = 10);
long stol(const string& str, size_t *idx = 0, int base = 10);
unsigned long stoul(const string& str, size_t *idx = 0, int base = 10);
long long stoll(const string& str, size_t *idx = 0, int base = 10);
unsigned long long stoull(const string& str, size_t *idx = 0, int base = 10);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects the first two functions call \tcode{strtol(str.c_str(), ptr, base)},
and the last three functions call \tcode{strtoul(str.c_str(), ptr, base)},
\tcode{strtoll(str.c_str(), ptr, base)}, and \tcode{strtoull(\brk{}str.c_str(), ptr,
base)}, respectively. Each function returns the converted result, if any. The
argument \tcode{ptr} designates a pointer to an object internal to the function
that is used to determine what to store at \tcode{*idx}. If the function does
not throw an exception and \tcode{idx != 0}, the function stores in \tcode{*idx}
the index of the first unconverted element of \tcode{str}.

\pnum
\returns The converted result.

\pnum
\throws \tcode{invalid_argument} if \tcode{strtol}, \tcode{strtoul},
\tcode{strtoll}, or \tcode{strtoull} reports that no conversion could be
performed. Throws \tcode{out_of_range} if \tcode{strtol}, \tcode{strtoul},
\tcode{strtoll} or \tcode{strtoull} sets \tcode{errno} to \tcode{ERANGE},
or if the converted value is outside the range of representable values
for the return type.
\end{itemdescr}

\indexlibrary{\idxcode{stof}}%
\indexlibrary{\idxcode{stol}}%
\indexlibrary{\idxcode{stold}}%
\begin{itemdecl}
float stof(const string& str, size_t *idx = 0);
double stod(const string& str, size_t *idx = 0);
long double stold(const string& str, size_t *idx = 0);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects the first two functions call \tcode{strtod(str.c_str(), ptr)} and the
third function calls \tcode{strtold(\brk{}str.c_str(), ptr)}. Each function returns
the converted result, if any. The argument \tcode{ptr} designates a pointer to
an object internal to the function that is used to determine what to store at
\tcode{*idx}. If the function does not throw an exception and \tcode{idx != 0},
the function stores in \tcode{*idx} the index of the first unconverted element
of \tcode{str}.

\pnum
\returns The converted result.

\pnum
\throws \tcode{invalid_argument} if \tcode{strtod} or \tcode{strtold} reports
that no conversion could be performed. Throws \tcode{out_of_range} if
\tcode{strtod} or \tcode{strtold} sets \tcode{errno} to \tcode{ERANGE}
or if the converted value is outside the range of representable
values for the return type.
\end{itemdescr}

\indexlibrary{\idxcode{to_string}}%
\begin{itemdecl}
string to_string(int val);
string to_string(unsigned val);
string to_string(long val);
string to_string(unsigned long val);
string to_string(long long val);
string to_string(unsigned long long val);
string to_string(float val);
string to_string(double val);
string to_string(long double val);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns Each function returns a \tcode{string} object holding the character
representation of the value of its argument that would be generated by calling
\tcode{sprintf(buf, fmt, val)} with a format specifier of
\tcode{"\%d"},
\tcode{"\%u"},
\tcode{"\%ld"},
\tcode{"\%lu"},
\tcode{"\%lld"},  \tcode{"\%llu"},
\tcode{"\%f"},
\tcode{"\%f"},
or \tcode{"\%Lf"}, respectively, where \tcode{buf} designates an internal
character buffer of sufficient size.
\end{itemdescr}

\indexlibrary{\idxcode{stoi}}%
\indexlibrary{\idxcode{stol}}%
\indexlibrary{\idxcode{stoul}}%
\indexlibrary{\idxcode{stoll}}%
\indexlibrary{\idxcode{stoull}}%
\begin{itemdecl}
int stoi(const wstring& str, size_t *idx = 0, int base = 10);
long stol(const wstring& str, size_t *idx = 0, int base = 10);
unsigned long stoul(const wstring& str, size_t *idx = 0, int base = 10);
long long stoll(const wstring& str, size_t *idx = 0, int base = 10);
unsigned long long stoull(const wstring& str, size_t *idx = 0, int base = 10);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects the first two functions call \tcode{wcstol(str.c_str(), ptr, base)},
and the last three functions call \tcode{wcstoul(str.c_str(), ptr, base)},
\tcode{wcstoll(str.c_str(), ptr, base)}, and \tcode{wcstoull(\brk{}str.c_str(), ptr,
base)}, respectively. Each function returns the converted result, if any. The
argument \tcode{ptr} designates a pointer to an object internal to the function
that is used to determine what to store at \tcode{*idx}. If the function does
not throw an exception and \tcode{idx != 0}, the function stores in \tcode{*idx}
the index of the first unconverted element of \tcode{str}.

\pnum
\returns The converted result.

\pnum
\throws \tcode{invalid_argument} if \tcode{wcstol}, \tcode{wcstoul}, \tcode{wcstoll}, or
\tcode{wcstoull} reports that no conversion could be performed. Throws
\tcode{out_of_range} if the converted value is outside the range of representable values
for the return type.
\end{itemdescr}

\indexlibrary{\idxcode{stof}}%
\indexlibrary{\idxcode{stod}}%
\indexlibrary{\idxcode{stold}}%
\begin{itemdecl}
float stof(const wstring& str, size_t *idx = 0);
double stod(const wstring& str, size_t *idx = 0);
long double stold(const wstring& str, size_t *idx = 0);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects the first two functions call \tcode{wcstod(str.c_str(), ptr)} and the third
function calls \tcode{wcstold(\brk{}str.c_str(), ptr)}. Each function returns the converted
result, if any. The argument \tcode{ptr} designates a pointer to an object internal to
the function that is used to determine what to store at \tcode{*idx}. If the function
does not throw an exception and \tcode{idx != 0}, the function stores in \tcode{*idx}
the index of the first unconverted element of \tcode{str}.

\pnum
\returns The converted result.

\pnum
\throws \tcode{invalid_argument} if \tcode{wcstod} or \tcode{wcstold} reports that no
conversion could be performed. Throws \tcode{out_of_range} if \tcode{wcstod} or
\tcode{wcstold} sets \tcode{errno} to \tcode{ERANGE}.
\end{itemdescr}

\indexlibrary{\idxcode{to_wstring}}%
\begin{itemdecl}
wstring to_wstring(int val);
wstring to_wstring(unsigned val);
wstring to_wstring(long val);
wstring to_wstring(unsigned long val);
wstring to_wstring(long long val);
wstring to_wstring(unsigned long long val);
wstring to_wstring(float val);
wstring to_wstring(double val);
wstring to_wstring(long double val);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns Each function returns a \tcode{wstring} object holding the character
representation of the value of its argument that would be generated by calling
\tcode{swprintf(buf, buffsz, fmt, val)} with a format specifier of
\tcode{L"\%d"},
\tcode{L"\%u"},
\tcode{L"\%ld"},
\tcode{L"\%lu"},
\tcode{L"\%lld"},
\tcode{L"\%llu"},
\tcode{L"\%f"},
\tcode{L"\%f"},
or \tcode{L"\%Lf"}, respectively, where \tcode{buf} designates an
internal character buffer of sufficient size \tcode{buffsz}.
\end{itemdescr}

\rSec1[basic.string.hash]{Hash support}

\indexlibrary{\idxcode{hash}}%
\begin{itemdecl}
template <> struct hash<string>;
template <> struct hash<u16string>;
template <> struct hash<u32string>;
template <> struct hash<wstring>;
\end{itemdecl}

\begin{itemdescr}
\pnum The template specializations shall meet the requirements of class template
\tcode{hash}~(\ref{unord.hash}).
\end{itemdescr}

\rSec1[basic.string.literals]{Suffix for \tcode{basic_string} literals}

\begin{itemdecl}
string operator "" s(const char* str, size_t len);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{string\{str,len\}}
\end{itemdescr}

\begin{itemdecl}
u16string operator "" s(const char16_t* str, size_t len);
\end{itemdecl}
\begin{itemdescr}
\pnum
\returns
\tcode{u16string\{str,len\}}
\end{itemdescr}

\begin{itemdecl}
u32string operator "" s(const char32_t* str, size_t len);
\end{itemdecl}
\begin{itemdescr}
\pnum
\returns
\tcode{u32string\{str,len\}}
\end{itemdescr}

\begin{itemdecl}
wstring operator "" s(const wchar_t* str, size_t len);
\end{itemdecl}
\begin{itemdescr}
\pnum
\returns
\tcode{wstring\{str,len\}}
\end{itemdescr}

\pnum \enternote
The same suffix \tcode{s} is used for \tcode{chrono::duration} literals denoting seconds but there is no conflict, since duration suffixes apply to numbers and string literal suffixes apply to character array literals.
\exitnote

\rSec1[c.strings]{Null-terminated sequence utilities}

\pnum
Tables~\ref{tab:strings.hdr.cctype},
\ref{tab:strings.hdr.cwctype}, \ref{tab:strings.hdr.cstring},
\ref{tab:strings.hdr.cwchar},
\ref{tab:strings.hdr.cstdlib},
and \ref{tab:strings.hdr.cuchar}
describe headers
\tcode{<cctype>},
\tcode{<cwctype>},
\tcode{<cstring>},
\tcode{<cwchar>},
\tcode{<cstdlib>}
(character conversions),
 and
\tcode{<cuchar>},
respectively.

\pnum
The contents of these headers shall be the same as the Standard C Library headers
\tcode{<ctype.h>},
\tcode{<wctype.h>},
\tcode{<string.h>},
\tcode{<wchar.h>},
and
\tcode{<stdlib.h>}
and the C Unicode TR header \tcode{<uchar.h>},
respectively, with the following modifications:

\pnum
\indextext{\idxcode{wchar_t}}%
The headers shall not define the types
\tcode{char16_t}, \tcode{char32_t}, and
\tcode{wchar_t}~(\ref{lex.key}).

\pnum
\indexlibrary{\idxcode{strchr}}%
The function signature
\tcode{strchr(const char*, int)}
shall be replaced by the two declarations:

\begin{codeblock}
const char* strchr(const char* s, int c);
      char* strchr(      char* s, int c);
\end{codeblock}

both of which shall have the same behavior as the original declaration.

\pnum
\indexlibrary{\idxcode{strpbrk}}%
The function signature
\tcode{strpbrk(const char*, const char*)}
shall be replaced by the two declarations:

\begin{codeblock}
const char* strpbrk(const char* s1, const char* s2);
      char* strpbrk(      char* s1, const char* s2);
\end{codeblock}

both of which shall have the same behavior as the original declaration.

\pnum
\indexlibrary{\idxcode{strrchr}}%
The function signature
\tcode{strrchr(const char*, int)}
shall be replaced by the two declarations:

\begin{codeblock}
const char* strrchr(const char* s, int c);
      char* strrchr(      char* s, int c);
\end{codeblock}

both of which shall have the same behavior as the original declaration.

\pnum
\indexlibrary{\idxcode{strstr}}%
The function signature
\tcode{strstr(const char*, const char*)}
shall be replaced by the two declarations:

\begin{codeblock}
const char* strstr(const char* s1, const char* s2);
      char* strstr(      char* s1, const char* s2);
\end{codeblock}

both of which shall have the same behavior as the original declaration.

\pnum
\indexlibrary{\idxcode{memchr}}%
The function signature
\tcode{memchr(const void*, int, size_t)}
shall be replaced by the two declarations:

\begin{codeblock}
const void* memchr(const void* s, int c, size_t n);
      void* memchr(      void* s, int c, size_t n);
\end{codeblock}

both of which shall have the same behavior as the original declaration.

\pnum
\indexlibrary{\idxcode{wcschr}}%
The function signature
\tcode{wcschr(const wchar_t*, wchar_t)}
shall be replaced by the two declarations:

\begin{codeblock}
const wchar_t* wcschr(const wchar_t* s, wchar_t c);
      wchar_t* wcschr(      wchar_t* s, wchar_t c);
\end{codeblock}

both of which shall have the same behavior as the original declaration.

\pnum
\indexlibrary{\idxcode{wcspbrk}}%
The function signature
\tcode{wcspbrk(const wchar_t*, const wchar_t*)}
shall be replaced by the two declarations:

\begin{codeblock}
const wchar_t* wcspbrk(const wchar_t* s1, const wchar_t* s2);
      wchar_t* wcspbrk(      wchar_t* s1, const wchar_t* s2);
\end{codeblock}

both of which shall have the same behavior as the original declaration.

\pnum
\indexlibrary{\idxcode{wcsrchr}}%
The function signature
\tcode{wcsrchr(const wchar_t*, wchar_t)}
shall be replaced by the two declarations:

\begin{codeblock}
const wchar_t* wcsrchr(const wchar_t* s, wchar_t c);
      wchar_t* wcsrchr(      wchar_t* s, wchar_t c);
\end{codeblock}

both of which shall have the same behavior as the original declaration.

\pnum
\indexlibrary{\idxcode{wcsstr}}%
The function signature
\tcode{wcsstr(const wchar_t*, const wchar_t*)}
shall be replaced by the two declarations:

\begin{codeblock}
const wchar_t* wcsstr(const wchar_t* s1, const wchar_t* s2);
      wchar_t* wcsstr(      wchar_t* s1, const wchar_t* s2);
\end{codeblock}

both of which shall have the same behavior as the original declaration.

\pnum
\indexlibrary{\idxcode{wmemchr}}%
The function signature
\tcode{wmemchr(const wwchar_t*, int, size_t)}
shall be replaced by the two declarations:

\begin{codeblock}
const wchar_t* wmemchr(const wchar_t* s, wchar_t c, size_t n);
      wchar_t* wmemchr(      wchar_t* s, wchar_t c, size_t n);
\end{codeblock}

both of which shall have the same behavior as the original declaration.

\pnum
The functions \tcode{strerror} and \tcode{strtok} are not required to avoid data
races~(\ref{res.on.data.races}).

\pnum
Calling the functions listed in Table~\ref{tab:mbstate.data.races} with an \tcode{mbstate_t*} argument of
\tcode{NULL} may introduce a data race~(\ref{res.on.data.races}) with other calls to
these functions with an \tcode{mbstate_t*} argument of \tcode{NULL}.

\begin{floattable}
{Potential \tcode{mbstate_t} data races}
{tab:mbstate.data.races}
{lllll}
\topline

\tcode{mbrlen}    &
\tcode{mbrtowc}   &
\tcode{mbsrtowc}  &
\tcode{mbtowc}    &
\tcode{wcrtomb}   \\

\tcode{wcsrtomb}  &
\tcode{wctomb}    &&&\\

\end{floattable}

\xref
ISO C 7.3, 7.10.7, 7.10.8, and  7.11.
Amendment 1 4.4, 4.5, and 4.6.

\begin{libsyntabf5}{cctype}{tab:strings.hdr.cctype}

\cspan{\functions}  \\
\tcode{isalnum}     &
 \tcode{isblank}    &
 \tcode{isdigit}    &
 \tcode{isprint}    &
 \tcode{isupper}    \\
 \tcode{tolower}    &
\tcode{isalpha}     &
 \tcode{isgraph}    &
 \tcode{ispunct}    &
 \tcode{isxdigit}   \\
 \tcode{toupper}    &
\tcode{iscntrl}     &
 \tcode{islower}    &
 \tcode{isspace}    &
                    \\
\end{libsyntabf5}

\begin{libsyntabf5}{cwctype}{tab:strings.hdr.cwctype}
\macro              &   \multicolumn{4}{l|}{\tcode{WEOF}} \\ \rowsep
\types              &
 \tcode{wctrans_t}  &
 \tcode{wctype_t}   &
 \multicolumn{2}{l|}{\tcode{wint_t}}  \\ \rowsep
\cspan{\functions}  \\

\tcode{iswalnum}    &
\tcode{iswctype}    &
\tcode{iswprint}    &
\tcode{iswxdigit}   &
\tcode{wctrans}     \\

\tcode{iswalpha}    &
\tcode{iswdigit}    &
\tcode{iswpunct}    &
\tcode{towctrans}   &
\tcode{wctype}      \\

\tcode{iswblank}    &
\tcode{iswgraph}    &
\tcode{iswspace}    &
\tcode{towlower}    & \\

\tcode{iswcntrl}    &
\tcode{iswlower}    &
\tcode{iswupper}    &
\tcode{towupper}    & \\


\end{libsyntabf5}

\begin{libsyntabf5}{cstring}{tab:strings.hdr.cstring}
\macro              &
 \multicolumn{4}{l|}{\tcode{NULL <cstring>}}    \\ \rowsep
\type               &
 \multicolumn{4}{l|}{\tcode{size_t <cstring>}}  \\ \rowsep
\cspan{\functions}  \\
\tcode{memchr}      &
 \tcode{strcat}     &
 \tcode{strcspn}    &
 \tcode{strncpy}    &
 \tcode{strtok}     \\
\tcode{memcmp}      &
 \tcode{strchr}     &
 \tcode{strerror}   &
 \tcode{strpbrk}    &
 \tcode{strxfrm}    \\
\tcode{memcpy}      &
 \tcode{strcmp}     &
 \tcode{strlen}     &
 \tcode{strrchr}    &
                    \\
\tcode{memmove}     &
 \tcode{strcoll}    &
 \tcode{strncat}    &
 \tcode{strspn}     &
                    \\
\tcode{memset}      &
 \tcode{strcpy}     &
 \tcode{strncmp}    &
 \tcode{strstr}     &
                    \\
\end{libsyntabf5}

\begin{libsyntabf5}{cwchar}{tab:strings.hdr.cwchar}
\macros                 &
 \tcode{NULL}           &
 \tcode{WCHAR_MAX}      &
 \tcode{WCHAR_MIN}      &
 \tcode{WEOF}           \\ \rowsep
\types                  &
 \tcode{mbstate_t}      &
 \tcode{wint_t}         &
 \tcode{size_t}         &
 \tcode{tm}             \\ \rowsep
\cspan{\functions}      \\

\tcode{btowc}           &
\tcode{mbsinit}         &
\tcode{vwscanf}         &
\tcode{wcsncpy}         &
\tcode{wcstoull}        \\

\tcode{fgetwc}          &
\tcode{mbsrtowcs}       &
\tcode{wcrtomb}         &
\tcode{wcspbrk}         &
\tcode{wcstoul}         \\

\tcode{fgetws}          &
\tcode{putwchar}        &
\tcode{wcscat}          &
\tcode{wcsrchr}         &
\tcode{wcsxfrm}         \\

\tcode{fputwc}          &
\tcode{putwc}           &
\tcode{wcschr}          &
\tcode{wcsrtombs}       &
\tcode{wctob}           \\

\tcode{fputws}          &
\tcode{swprintf}        &
\tcode{wcscmp}          &
\tcode{wcsspn}          &
\tcode{wmemchr}         \\

\tcode{fwide}           &
\tcode{swscanf}         &
\tcode{wcscoll}         &
\tcode{wcsstr}          &
\tcode{wmemcmp}         \\

\tcode{fwprintf}        &
\tcode{ungetwc}         &
\tcode{wcscpy}          &
\tcode{wcstod}          &
\tcode{wmemcpy}         \\

\tcode{fwscanf}         &
\tcode{vfwprintf}       &
\tcode{wcscspn}         &
\tcode{wcstof}          &
\tcode{wmemmove}        \\

\tcode{getwchar}        &
\tcode{vfwscanf}        &
\tcode{wcsftime}        &
\tcode{wcstok}          &
\tcode{wmemset}         \\

\tcode{getwc}           &
\tcode{vswprintf}       &
\tcode{wcslen}          &
\tcode{wcstold}         &
\tcode{wprintf}         \\

\tcode{mbrlen}          &
\tcode{vswscanf}        &
\tcode{wcsncat}         &
\tcode{wcstoll}         &
\tcode{wscanf}          \\

\tcode{mbrtowc}         &
\tcode{vwprintf}        &
\tcode{wcsncmp}         &
\tcode{wcstol}          & \\

\end{libsyntabf5}

\begin{libsyntabf4}{cstdlib}{tab:strings.hdr.cstdlib}
\macros             &
 \tcode{MB_CUR_MAX} &
                    &
                    \\ \rowsep
\cspan{\functions}  \\
\tcode{atof}        & \tcode{mblen}     & \tcode{strtof} & \tcode{strtoul}   \\
\tcode{atoi}        & \tcode{mbtowc}    & \tcode{strtol}    & \tcode{strtoull}\\
\tcode{atol}        & \tcode{mbstowcs}& \tcode{strtold}     & \tcode{wctomb}\\
\tcode{atoll}       & \tcode{strtod}    & \tcode{strtoll}   &  \tcode{wcstombs}\\
\end{libsyntabf4}

\begin{libsyntabf3}{cuchar}{tab:strings.hdr.cuchar}
\macros             &
 \mbox{\tcode{__STDC_UTF_16__}}    & \\
 & \mbox{\tcode{__STDC_UTF_32__}}  & \\ \rowsep
\functions          &
 \tcode{mbrtoc16}   &
 \tcode{c16rtomb}   \\
                    &
 \tcode{mbrtoc32}   &
 \tcode{c32rtomb}   \\
\end{libsyntabf3}