\rSec0[strings]{Strings library}

\rSec1[strings.general]{General}

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

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}

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.

Most classes specified in Clauses~\ref{string.classes}

and~\ref{input.output} need a set of related types and functions

to complete the definition of their semantics.

These types and functions are provided as a set of member typedefs

and functions in the template parameter `traits' used by each such

template.

This subclause defines the semantics of these

members.

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

parameters

\tcode{charT}

and

\tcode{traits}.

\tcode{Traits::char_type}

shall be the same as

\tcode{CharT}.

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}

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

\lhdr{Expression} & \chdr{Return type} & \chdr{Assertion/note} & \rhdr{Complexity}\\

& & \chdr{pre-/post-condition} & \\ \capsep

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

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}

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}

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}

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}

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

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

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}

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.

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

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

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.

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

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}

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

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.

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}

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

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.

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}

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.

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

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.

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.

The member

\tcode{eof()}

shall return

\tcode{WEOF}.

\rSec1[string.classes]{String classes}

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)

noexcept(noexcept(lhs.swap(rhs)));

// \ref{string.io}, inserters and extractors:

template<class charT, class traits, class Allocator>

basic_istream<charT,traits>&

operator>>(basic_istream<charT,traits>& is,

basic_string<charT,traits,Allocator>& str);

template<class charT, class traits, class Allocator>

basic_ostream<charT, traits>&

operator<<(basic_ostream<charT, traits>& os,

const basic_string<charT,traits,Allocator>& str);

template<class charT, class traits, class Allocator>

basic_istream<charT,traits>&

getline(basic_istream<charT,traits>& is,

basic_string<charT,traits,Allocator>& str,

charT delim);

template<class charT, class traits, class Allocator>

basic_istream<charT,traits>&

getline(basic_istream<charT,traits>&& is,

basic_string<charT,traits,Allocator>& str,

charT delim);

template<class charT, class traits, class Allocator>

basic_istream<charT,traits>&

getline(basic_istream<charT,traits>& is,

basic_string<charT,traits,Allocator>& str);

template<class charT, class traits, class Allocator>

basic_istream<charT,traits>&

getline(basic_istream<charT,traits>&& is,

basic_string<charT,traits,Allocator>& str);

// \tcode{basic_string} typedef names

typedef basic_string<char> string;

typedef basic_string<char16_t> u16string;

typedef basic_string<char32_t> u32string;

typedef basic_string<wchar_t> wstring;

// \ref{string.conversions}, numeric conversions:

int stoi(const string& str, size_t* idx = 0, int base = 10);

long stol(const string& str, size_t* idx = 0, int base = 10);

unsigned long stoul(const string& str, size_t* idx = 0, int base = 10);

long long stoll(const string& str, size_t* idx = 0, int base = 10);

unsigned long long stoull(const string& str, size_t* idx = 0, int base = 10);

float stof(const string& str, size_t* idx = 0);

double stod(const string& str, size_t* idx = 0);

long double stold(const string& str, size_t* idx = 0);

string to_string(int val);

string to_string(unsigned val);

string to_string(long val);

string to_string(unsigned long val);

string to_string(long long val);

string to_string(unsigned long long val);

string to_string(float val);

string to_string(double val);

string to_string(long double val);

int stoi(const wstring& str, size_t* idx = 0, int base = 10);

long stol(const wstring& str, size_t* idx = 0, int base = 10);

unsigned long stoul(const wstring& str, size_t* idx = 0, int base = 10);

long long stoll(const wstring& str, size_t* idx = 0, int base = 10);

unsigned long long stoull(const wstring& str, size_t* idx = 0, int base = 10);

float stof(const wstring& str, size_t* idx = 0);

double stod(const wstring& str, size_t* idx = 0);

long double stold(const wstring& str, size_t* idx = 0);

wstring to_wstring(int val);

wstring to_wstring(unsigned val);

wstring to_wstring(long val);

wstring to_wstring(unsigned long val);

wstring to_wstring(long long val);

wstring to_wstring(unsigned long long val);

wstring to_wstring(float val);

wstring to_wstring(double val);

wstring to_wstring(long double val);

// \ref{basic.string.hash}, hash support:

template <class T> struct hash;

template <> struct hash<string>;

template <> struct hash<u16string>;

template <> struct hash<u32string>;

template <> struct hash<wstring>;

inline namespace literals {

inline namespace string_literals {

// \ref{basic.string.literals}, suffix for basic_string literals:

string operator "" s(const char* str, size_t len);

u16string operator "" s(const char16_t* str, size_t len);

u32string operator "" s(const char32_t* str, size_t len);

wstring operator "" s(const wchar_t* str, size_t len);

}

}

}

\end{codeblock}

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

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

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

A \tcode{basic_string} is a contiguous container~(\ref{container.requirements.general}).

In all cases,

\tcode{size() <= capacity()}.

The functions described in this Clause can report two

kinds of errors, each associated with an exception type:

\begin{itemize}

a

\term{length}

error is associated with exceptions of type

\tcode{length_error}~(\ref{length.error});

\indexlibrary{\idxcode{length_error}}%

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:

basic_string() noexcept : basic_string(Allocator()) { }

explicit basic_string(const Allocator& a) noexcept;

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(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||

allocator_traits<Allocator>::is_always_equal::value);

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 = npos);

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 = npos);

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 = npos);

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