Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

4751 lines (4032 sloc) 138.141 kb
\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 guaranteed by 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>;
}
\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} shall not be a null pointer and
\tcode{n < npos}.
\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} shall not be a null pointer.
\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
\requires
\tcode{pos < size()}
\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}). After
constructing a \tcode{sentry} object,
if this object returns \tcode{true} when converted to a value of type
\tcode{bool},
determines padding as described
in~\ref{facet.num.put.virtuals}, then inserts the resulting sequence of
characters \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