\rSec0[strings]{Strings library}

\rSec1[strings.general]{General}

This Clause describes components for manipulating sequences of

any non-array POD~(\ref{basic.types}) type.

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

\ref{string.view} & String view classes & \tcode{<string_view>} \\ \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 \grammarterm{typedef-name}{s} and functions in the template

parameter \tcode{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 class 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{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} &

\returns whether \tcode{c} is to be treated as equal to \tcode{d}. & constant \\ \rowsep

\tcode{X::lt(c,d)} & \tcode{bool} &

\returns whether \tcode{c} is to be treated as less than \tcode{d}. & constant \\ \rowsep

\tcode{X::compare(p,q,n)} & \tcode{int} &

\returns \tcode{0} if for each \tcode{i} in \tcode{[0,n)}, \tcode{X::eq(p[i],q[i])}

is \tcode{true}; else, a negative value if, for some \tcode{j} in \tcode{[0,n)},

\tcode{X::lt(p[j],q[j])} is \tcode{true} and for each \tcode{i} in \tcode{[0,j)}

\tcode{X::eq(p[i],q[i])} is \tcode{true}; else a positive value. & linear \\ \rowsep

\tcode{X::length(p)} & \tcode{size_t} &

\returns the smallest \tcode{i} such that \tcode{X::eq(p[i],charT())} is \tcode{true}. & linear \\ \rowsep

\tcode{X::find(p,n,c)} & \tcode{const X::char_type*} &

\returns the smallest \tcode{q} in \tcode{[p,p+n)} such that

\tcode{X::eq(*q,c)} is \tcode{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.\br \returns \tcode{s}. & linear \\ \rowsep

\tcode{X::copy(s,p,n)} & \tcode{X::char_type*} &

\requires \tcode{p} not in \tcode{[s,s+n)}. \returns \tcode{s}.\br

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

\returns \tcode{s}. & linear \\ \rowsep

\tcode{X::not_eof(e)} & \tcode{int_type} &

\returns \tcode{e} if \tcode{X::eq_int_type(e,X::eof())} is \tcode{false},

otherwise a value \tcode{f} such that

\tcode{X::eq_int_type(f,X::eof())} is \tcode{false}. & constant \\ \rowsep

\tcode{X::to_char_type\-(e)} & \tcode{X::char_type} &

\returns if for some \tcode{c}, \tcode{X::eq_int_type(e,X::to_int_type(c))}

is \tcode{true}, \tcode{c}; else some unspecified value. & constant \\ \rowsep

\tcode{X::to_int_type\-(c)} & \tcode{X::int_type} &

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

\returns 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 \tcode{true}

if \tcode{e} and \tcode{f} are both copies of \tcode{X::eof()}; otherwise, yields \tcode{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} &

\returns a value \tcode{e} such that \tcode{X::eq_int_type(e,X::to_int_type(c))}

is \tcode{false} for all values \tcode{c}. & constant \\

\end{libreqtab4d}

The class 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}

\indexlibrarymember{char_type}{char_traits}%

\begin{itemdecl}

using char_type = CHAR_T;

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

\indexlibrarymember{int_type}{char_traits}%

\begin{itemdecl}

using int_type = INT_T;

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

\indexlibrarymember{off_type}{char_traits}%

\indexlibrarymember{pos_type}{char_traits}%

\begin{itemdecl}

using off_type = @\impdef@;

using pos_type = @\impdef@;

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

\indexlibrarymember{state_type}{char_traits}%

\begin{itemdecl}

using state_type = STATE_T;

\end{itemdecl}

\begin{itemdescr}

\tcode{state_type}

shall meet the requirements of

\tcode{CopyAssignable} (Table~\ref{tab:copyassignable}),

\tcode{CopyConstructible} (Table~\ref{tab:copyconstructible}), and

\tcode{DefaultConstructible} (Table~\ref{tab: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 class template

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

using char_type = char;

using int_type = int;

using off_type = streamoff;

using pos_type = streampos;

using state_type = mbstate_t;

static constexpr 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 constexpr int compare(const char_type* s1, const char_type* s2, size_t n);

static constexpr size_t length(const char_type* s);

static constexpr 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 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> {

using char_type = char16_t;

using int_type = uint_least16_t;

using off_type = streamoff;

using pos_type = u16streampos;

using state_type = mbstate_t;

static constexpr 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 constexpr int compare(const char_type* s1, const char_type* s2, size_t n);

static constexpr size_t length(const char_type* s);

static constexpr 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 \tcode{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> {

using char_type = char32_t;

using int_type = uint_least32_t;

using off_type = streamoff;

using pos_type = u32streampos;

using state_type = mbstate_t;

static constexpr 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 constexpr int compare(const char_type* s1, const char_type* s2, size_t n);

static constexpr size_t length(const char_type* s);

static constexpr 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 \tcode{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> {

using char_type = wchar_t;

using int_type = wint_t;

using off_type = streamoff;

using pos_type = wstreampos;

using state_type = mbstate_t;

static constexpr 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 constexpr int compare(const char_type* s1, const char_type* s2, size_t n);

static constexpr size_t length(const char_type* s);

static constexpr 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 \tcode{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

\grammarterm{typedef-name}{s}, \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.

\rSec2[string.syn]{Header \tcode{<string>} synopsis}

\indextext{\idxhdr{string}}%

\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}, \tcode{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

using string = basic_string<char>;

using u16string = basic_string<char16_t>;

using u32string = basic_string<char32_t>;

using wstring = basic_string<wchar_t>;

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

namespace pmr {

template <class charT, class traits = char_traits<charT>>

using basic_string =

std::basic_string<charT, traits, polymorphic_allocator<charT>>;

using string = basic_string<char>;

using u16string = basic_string<char16_t>;

using u32string = basic_string<char32_t>;

using wstring = basic_string<wchar_t>;

}

inline namespace literals {

inline namespace string_literals {

// \ref{basic.string.literals}, suffix for \tcode{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}

\rSec2[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:

using traits_type = traits;

using value_type = charT;

using allocator_type = Allocator;

using size_type = typename allocator_traits<Allocator>::size_type;

using difference_type = typename allocator_traits<Allocator>::difference_type;

using pointer = typename allocator_traits<Allocator>::pointer;

using const_pointer = typename allocator_traits<Allocator>::const_pointer;

using reference = value_type&;

using const_reference = const value_type&;

using iterator = @\impdefx{type of \tcode{basic_string::iterator}}@; // see \ref{container.requirements}

using const_iterator = @\impdefx{type of \tcode{basic_string::const_iterator}}@; // see \ref{container.requirements}

using reverse_iterator = std::reverse_iterator<iterator>;

using const_reverse_iterator = std::reverse_iterator<const_iterator>;

static const size_type npos = -1;

// \ref{string.cons}, construct/copy/destroy

basic_string() noexcept(noexcept(Allocator())) : 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,

const Allocator& a = Allocator());

basic_string(const basic_string& str, size_type pos, size_type n,

const Allocator& a = Allocator());

template<class T>

basic_string(const T& t, size_type pos, size_type n,

const Allocator& a = Allocator());

explicit basic_string(basic_string_view<charT, traits> sv,

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=(basic_string_view<charT, traits> sv);

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+=(basic_string_view<charT, traits> sv);

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(basic_string_view<charT, traits> sv);

template<class T>

basic_string& append(const T& t, 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(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||

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

basic_string& assign(const basic_string& str, size_type pos,

size_type n = npos);

basic_string& assign(basic_string_view<charT, traits> sv);

template<class T>

basic_string& assign(const T& t, size_type pos, size_type n = npos);

basic_string& assign(const charT* s, size_type n);

basic_string& assign(const charT* s);