%!TEX root = std.tex

\rSec0[strings]{Strings library}

\rSec1[strings.general]{General}

\pnum

This Clause describes components for manipulating sequences of

any non-array trivially copyable standard-layout\iref{term.standard.layout.type} type \tcode{T}

where \tcode{is_trivially_default_constructible_v<T>} is \tcode{true}.

Such types are called \defnx{char-like types}{char-like type},

and objects of

char-like types are called \defnx{char-like objects}{char-like object} or

simply \term{characters}.

\pnum

The following subclauses describe a

character traits class, string classes, and

null-terminated sequence utilities,

as summarized in \tref{strings.summary}.

\begin{libsumtab}[x{2.1in}]{Strings library summary}{strings.summary}

\ref{char.traits} & Character traits & \tcode{<string>} \\

\ref{string.view} & String view classes & \tcode{<string_view>} \\ \rowsep

\ref{string.classes} & String classes & \tcode{<string>} \\ \rowsep

\ref{c.strings} & Null-terminated sequence utilities & \tcode{<cstring>} \\

\end{libsumtab}

\rSec1[char.traits]{Character traits}

\rSec2[char.traits.general]{General}

\pnum

Subclause \ref{char.traits} defines requirements on classes representing

\term{character traits},

and defines a class template

\tcode{char_traits<charT>},

along with five specializations,

\tcode{char_traits<char>},

\tcode{char_traits<char8_t>},

\tcode{char_traits<char16_t>},

\tcode{char_traits<char32_t>},

and

\tcode{char_traits<wchar_t>},

that meet those requirements.

\pnum

Most classes specified in \ref{string.classes}, \ref{string.view},

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.

Subclause \ref{char.traits} defines the semantics of these members.

\pnum

To specialize those templates to generate a string, string view, or

iostream class to handle a particular character container type\iref{defns.character.container}

\tcode{C},

that and its related character traits class

\tcode{X}

are passed as a pair of parameters to the string, string view, or iostream template as

parameters

\tcode{charT}

and

\tcode{traits}.

If

\tcode{X::char_type}

is not the same type as

\tcode{C}, the program is ill-formed.

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

\pnum

In \tref{char.traits.req},

\tcode{X}

denotes a traits class defining types and functions for the

character container type

\tcode{C};

\tcode{c}

and

\tcode{d}

denote values of type

\tcode{C};

\tcode{p}

and

\tcode{q}

denote values of type

\tcode{const C*};

\tcode{s}

denotes a value of type

\tcode{C*};

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

and

\tcode{r}

denotes an lvalue of type

\tcode{C}.

No expression which is part of the character traits requirements

specified in \ref{char.traits.require}

shall exit via an exception.

\begin{libreqtab4d}

{Character traits requirements}

{char.traits.req}

\\ \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{C} &

& \\ \rowsep

\tcode{X::int_type} & &

(described in~\ref{char.traits.typedefs}) & \\ \rowsep

\tcode{X::off_type} & &

(described in~\ref{iostreams.limits.pos} and \ref{iostream.forward}) & \\ \rowsep

\tcode{X::pos_type} & &

(described in~\ref{iostreams.limits.pos} and \ref{iostream.forward}) & \\ \rowsep

\tcode{X::state_type} & &

(described in~\ref{char.traits.typedefs}) & \\ \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 \range{0}{n}, \tcode{X::eq(p[i],q[i])}

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

\tcode{X::lt(p[j],q[j])} is \tcode{true} and for each \tcode{i} in \range{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 \range{p}{p+n} such that

\tcode{X::eq(*q,c)} is \tcode{true}, \tcode{nullptr} otherwise. & linear \\ \rowsep

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

for each \tcode{i} in \range{0}{n}, performs \tcode{X::assign(s[i],p[i])}.

Copies correctly even where the ranges \range{p}{p+n} and \range{s}{s+n} overlap.\br \returns \tcode{s}. & linear \\ \rowsep

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

\expects

The ranges \range{p}{p+n} and \range{s}{s+n} do not overlap.\par

\returns

\tcode{s}.\br

for each \tcode{i} in

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

\pnum

The class template

\indexlibraryglobal{char_traits}%

\begin{codeblock}

template<class charT> struct char_traits;

\end{codeblock}

is provided in the header \libheaderref{string}

as a basis for explicit specializations.

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

\indexlibrarymember{char_type}{char_traits}%

\indexlibrarymember{int_type}{char_traits}%

\begin{itemdecl}

using int_type = @\seebelow@;

\end{itemdecl}

\begin{itemdescr}

\pnum

\expects

\tcode{int_type}

shall be able to represent all of the

valid characters converted from the corresponding

\tcode{char_type}

values, as well as an end-of-file value,

\tcode{eof()}.

\begin{footnote}

If

\tcode{eof()}

can be held in

\tcode{char_type}

then some iostreams operations can give surprising results.

\end{footnote}

\end{itemdescr}

\indexlibrarymember{state_type}{char_traits}%

\begin{itemdecl}

using state_type = @\seebelow@;

\end{itemdecl}

\begin{itemdescr}

\pnum

\expects

\tcode{state_type} meets the

\oldconcept{Destructible} (\tref{cpp17.destructible}),

\oldconcept{CopyAssignable} (\tref{cpp17.copyassignable}),

\oldconcept{CopyConstructible} (\tref{cpp17.copyconstructible}), and

\oldconcept{DefaultConstructible} (\tref{cpp17.defaultconstructible}) requirements.

\end{itemdescr}

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

\rSec3[char.traits.specializations.general]{General}

\indexlibraryglobal{char_traits}%

\begin{codeblock}

namespace std {

template<> struct char_traits<char>;

template<> struct char_traits<char8_t>;

template<> struct char_traits<char16_t>;

template<> struct char_traits<char32_t>;

template<> struct char_traits<wchar_t>;

}

\end{codeblock}

\pnum

The header \libheader{string}

defines five specializations of the class template

\tcode{char_traits}:

\tcode{char_traits<\brk{}char>},

\tcode{char_traits<char8_t>},

\tcode{char_traits<char16_t>},

\tcode{char_traits<char32_t>},

and

\tcode{char_traits<wchar_t>}.

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

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

using comparison_category = strong_ordering;

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

static constexpr char_type* copy(char_type* s1, const char_type* s2, size_t n);

static constexpr 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{mbstate_t} is defined in \libheaderref{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} is defined identically to the

built-in operator \tcode{=}. The two-argument members \tcode{eq}

and \tcode{lt} are defined identically to the built-in operators

\tcode{==} and \tcode{<} for type \tcode{unsigned char}.

\pnum

The member

\tcode{eof()}

returns

\tcode{EOF}.

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

\indexlibraryglobal{char_traits}%

\begin{codeblock}

namespace std {

template<> struct char_traits<char8_t> {

using char_type = char8_t;

using int_type = unsigned int;

using off_type = streamoff;

using pos_type = u8streampos;

using state_type = mbstate_t;

using comparison_category = strong_ordering;

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

static constexpr char_type* copy(char_type* s1, const char_type* s2, size_t n);

static constexpr 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 two-argument members \tcode{assign}, \tcode{eq}, and \tcode{lt}

are defined identically to

the built-in operators \tcode{=}, \tcode{==}, and \tcode{<} respectively.

\pnum

\indextext{UTF-8}%

The member \tcode{eof()} returns an

\impldef{return value of \tcode{char_traits<char8_t>::eof}} constant

that cannot appear as a valid UTF-8 code unit.

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

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

using comparison_category = strong_ordering;

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

static constexpr char_type* copy(char_type* s1, const char_type* s2, size_t n);

static constexpr 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 two-argument members \tcode{assign},

\tcode{eq}, and \tcode{lt} are defined identically to

the built-in operators \tcode{=}, \tcode{==}, and

\tcode{<}, respectively.

\pnum

The member \tcode{eof()} returns 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>}}

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

using comparison_category = strong_ordering;

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

static constexpr char_type* copy(char_type* s1, const char_type* s2, size_t n);

static constexpr 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 two-argument members \tcode{assign},

\tcode{eq}, and \tcode{lt} are defined identically to

the built-in operators \tcode{=}, \tcode{==}, and

\tcode{<}, respectively.

\pnum

The member \tcode{eof()} returns 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>}}

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

using comparison_category = strong_ordering;

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

static constexpr char_type* copy(char_type* s1, const char_type* s2, size_t n);

static constexpr 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 two-argument members

\tcode{assign},

\tcode{eq},

and

\tcode{lt}

are defined identically

to the built-in operators

\tcode{=},

\tcode{==},

and

\tcode{<},

respectively.

\pnum

The member

\tcode{eof()}

returns

\tcode{WEOF}.

\rSec1[string.view]{String view classes}

\rSec2[string.view.general]{General}

\pnum

The class template \tcode{basic_string_view} describes an object that can refer to a constant contiguous sequence of char-like\iref{strings.general} objects with the first element of the sequence at position zero.

In the rest of \ref{string.view}, the type of the char-like objects held in a \tcode{basic_string_view} object is designated by \tcode{charT}.

\pnum

\begin{note}

The library provides implicit conversions from \tcode{const charT*} and \tcode{std::basic_string<charT, ...>} to \tcode{std::basic_string_view<charT, ...>} so that user code can accept just \tcode{std::basic_string_view<charT>} as a non-templated parameter wherever a sequence of characters is expected.

User-defined types can define their own implicit conversions to \tcode{std::basic_string_view<charT>} in order to interoperate with these functions.

\end{note}

\rSec2[string.view.synop]{Header \tcode{<string_view>} synopsis}

\indexheader{string_view}%

\begin{codeblock}

// mostly freestanding

#include <compare> // see \ref{compare.syn}

namespace std {

// \ref{string.view.template}, class template \tcode{basic_string_view}

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

class basic_string_view; // partially freestanding

template<class charT, class traits>

constexpr bool ranges::@\libspec{enable_view}{basic_string_view}@<basic_string_view<charT, traits>> = true;

template<class charT, class traits>

constexpr bool ranges::@\libspec{enable_borrowed_range}{basic_string_view}@<basic_string_view<charT, traits>> = true;

// \ref{string.view.comparison}, non-member comparison functions

template<class charT, class traits>

constexpr bool operator==(basic_string_view<charT, traits> x,

type_identity_t<basic_string_view<charT, traits>> y) noexcept;

template<class charT, class traits>

constexpr @\seebelow@ operator<=>(basic_string_view<charT, traits> x,

@\itcorr@ type_identity_t<basic_string_view<charT,

@\itcorr@ traits>> y) noexcept;

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

template<class charT, class traits>

basic_ostream<charT, traits>&

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

basic_string_view<charT, traits> str); // hosted

// \tcode{basic_string_view} \grammarterm{typedef-name}s

using @\libglobal{string_view}@ = basic_string_view<char>;

using @\libglobal{u8string_view}@ = basic_string_view<char8_t>;

using @\libglobal{u16string_view}@ = basic_string_view<char16_t>;

using @\libglobal{u32string_view}@ = basic_string_view<char32_t>;

using @\libglobal{wstring_view}@ = basic_string_view<wchar_t>;

// \ref{string.view.hash}, hash support

template<class T> struct hash;

template<> struct hash<string_view>;

template<> struct hash<u8string_view>;

template<> struct hash<u16string_view>;

template<> struct hash<u32string_view>;

template<> struct hash<wstring_view>;

inline namespace literals {

inline namespace string_view_literals {

// \ref{string.view.literals}, suffix for \tcode{basic_string_view} literals

constexpr string_view operator""sv(const char* str, size_t len) noexcept;

constexpr u8string_view operator""sv(const char8_t* str, size_t len) noexcept;

constexpr u16string_view operator""sv(const char16_t* str, size_t len) noexcept;

constexpr u32string_view operator""sv(const char32_t* str, size_t len) noexcept;

constexpr wstring_view operator""sv(const wchar_t* str, size_t len) noexcept;

}

}

}

\end{codeblock}

\pnum

The function templates defined in \ref{utility.swap} and \ref{iterator.range}

are available when \tcode{<string_view>} is included.

\rSec2[string.view.template]{Class template \tcode{basic_string_view}}

\rSec3[string.view.template.general]{General}

\indexlibraryglobal{basic_string_view}%

\indexlibrarymember{traits_type}{basic_string_view}%

\indexlibrarymember{value_type}{basic_string_view}%

\indexlibrarymember{pointer}{basic_string_view}%

\indexlibrarymember{const_pointer}{basic_string_view}%

\indexlibrarymember{reference}{basic_string_view}%

\indexlibrarymember{const_reference}{basic_string_view}%

\indexlibrarymember{const_iterator}{basic_string_view}%

\indexlibrarymember{iterator}{basic_string_view}%

\indexlibrarymember{const_reverse_iterator}{basic_string_view}%

\indexlibrarymember{reverse_iterator}{basic_string_view}%

\indexlibrarymember{size_type}{basic_string_view}%

\indexlibrarymember{difference_type}{basic_string_view}%

\begin{codeblock}

namespace std {

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

class basic_string_view {

public:

// types

using traits_type = traits;

using value_type = charT;

using pointer = value_type*;

using const_pointer = const value_type*;

using reference = value_type&;

using const_reference = const value_type&;

using const_iterator = @\impdefx{type of \tcode{basic_string_view::const_iterator}}@; // see \ref{string.view.iterators}

using iterator = const_iterator;@

\begin{footnote}

Because \tcode{basic_string_view} refers to a constant sequence, \tcode{iterator} and \tcode{const_iterator} are the same type.

\end{footnote}@

using const_reverse_iterator = reverse_iterator<const_iterator>;

using reverse_iterator = const_reverse_iterator;

using size_type = size_t;

using difference_type = ptrdiff_t;

static constexpr size_type npos = size_type(-1);

// \ref{string.view.cons}, construction and assignment

constexpr basic_string_view() noexcept;

constexpr basic_string_view(const basic_string_view&) noexcept = default;

constexpr basic_string_view& operator=(const basic_string_view&) noexcept = default;

constexpr basic_string_view(const charT* str);

basic_string_view(nullptr_t) = delete;

constexpr basic_string_view(const charT* str, size_type len);

template<class It, class End>

constexpr basic_string_view(It begin, End end);

template<class R>

constexpr explicit basic_string_view(R&& r);

// \ref{string.view.iterators}, iterator support

constexpr const_iterator begin() const noexcept;

constexpr const_iterator end() const noexcept;

constexpr const_iterator cbegin() const noexcept;

constexpr const_iterator cend() const noexcept;

constexpr const_reverse_iterator rbegin() const noexcept;

constexpr const_reverse_iterator rend() const noexcept;

constexpr const_reverse_iterator crbegin() const noexcept;

constexpr const_reverse_iterator crend() const noexcept;

// \ref{string.view.capacity}, capacity

constexpr size_type size() const noexcept;

constexpr size_type length() const noexcept;

constexpr size_type max_size() const noexcept;

constexpr bool empty() const noexcept;

// \ref{string.view.access}, element access

constexpr const_reference operator[](size_type pos) const;

constexpr const_reference at(size_type pos) const; // freestanding-deleted

constexpr const_reference front() const;

constexpr const_reference back() const;

constexpr const charT* data() const noexcept;

// \ref{string.view.modifiers}, modifiers

constexpr void remove_prefix(size_type n);

constexpr void remove_suffix(size_type n);

constexpr void swap(basic_string_view& s) noexcept;

// \ref{string.view.ops}, string operations

constexpr size_type copy(charT* s, size_type n,

size_type pos = 0) const; // freestanding-deleted

constexpr basic_string_view substr(size_type pos = 0,

size_type n = npos) const; // freestanding-deleted

constexpr basic_string_view subview(size_type pos = 0,

size_type n = npos) const; // freestanding-deleted

constexpr int compare(basic_string_view s) const noexcept;

constexpr int compare(size_type pos1, size_type n1,

basic_string_view s) const; // freestanding-deleted

constexpr int compare(size_type pos1, size_type n1, basic_string_view s,

size_type pos2, size_type n2) const; // freestanding-deleted

constexpr int compare(const charT* s) const;

constexpr int compare(size_type pos1, size_type n1,

const charT* s) const; // freestanding-deleted

constexpr int compare(size_type pos1, size_type n1, const charT* s,

size_type n2) const; // freestanding-deleted

constexpr bool starts_with(basic_string_view x) const noexcept;

constexpr bool starts_with(charT x) const noexcept;

constexpr bool starts_with(const charT* x) const;

constexpr bool ends_with(basic_string_view x) const noexcept;

constexpr bool ends_with(charT x) const noexcept;

constexpr bool ends_with(const charT* x) const;

constexpr bool contains(basic_string_view x) const noexcept;

constexpr bool contains(charT x) const noexcept;

constexpr bool contains(const charT* x) const;

// \ref{string.view.find}, searching

constexpr size_type find(basic_string_view s, size_type pos = 0) const noexcept;

constexpr size_type find(charT c, size_type pos = 0) const noexcept;

constexpr size_type find(const charT* s, size_type pos, size_type n) const;

constexpr size_type find(const charT* s, size_type pos = 0) const;

constexpr size_type rfind(basic_string_view s, size_type pos = npos) const noexcept;

constexpr size_type rfind(charT c, size_type pos = npos) const noexcept;

constexpr size_type rfind(const charT* s, size_type pos, size_type n) const;

constexpr size_type rfind(const charT* s, size_type pos = npos) const;

constexpr size_type find_first_of(basic_string_view s, size_type pos = 0) const noexcept;

constexpr size_type find_first_of(charT c, size_type pos = 0) const noexcept;

constexpr size_type find_first_of(const charT* s, size_type pos, size_type n) const;

constexpr size_type find_first_of(const charT* s, size_type pos = 0) const;

constexpr size_type find_last_of(basic_string_view s, size_type pos = npos) const noexcept;

constexpr size_type find_last_of(charT c, size_type pos = npos) const noexcept;

constexpr size_type find_last_of(const charT* s, size_type pos, size_type n) const;

constexpr size_type find_last_of(const charT* s, size_type pos = npos) const;

constexpr size_type find_first_not_of(basic_string_view s, size_type pos = 0) const noexcept;

constexpr size_type find_first_not_of(charT c, size_type pos = 0) const noexcept;

constexpr size_type find_first_not_of(const charT* s, size_type pos,

size_type n) const;

constexpr size_type find_first_not_of(const charT* s, size_type pos = 0) const;

constexpr size_type find_last_not_of(basic_string_view s,

size_type pos = npos) const noexcept;

constexpr size_type find_last_not_of(charT c, size_type pos = npos) const noexcept;

constexpr size_type find_last_not_of(const charT* s, size_type pos,

size_type n) const;

constexpr size_type find_last_not_of(const charT* s, size_type pos = npos) const;

private:

const charT* @\exposid{data_}@; // \expos

size_type @\exposid{size_}@; // \expos

};

// \ref{string.view.deduct}, deduction guides

template<class It, class End>

basic_string_view(It, End) -> basic_string_view<iter_value_t<It>>;

template<class R>

basic_string_view(R&&) -> basic_string_view<ranges::range_value_t<R>>;

}

\end{codeblock}

\pnum

In every specialization \tcode{basic_string_view<charT, traits>}, the type \tcode{traits} shall meet the character traits requirements\iref{char.traits}.

\begin{note}

The program is ill-formed if \tcode{traits::char_type} is not the same type as \tcode{charT}.

\end{note}

\pnum

For a \tcode{basic_string_view str},

any operation that invalidates a pointer

in the range

\begin{codeblock}

@\range{str.data()}{str.data() + str.size()}@

\end{codeblock}

invalidates pointers, iterators, and references

to elements of \tcode{str}.

\pnum

The complexity of \tcode{basic_string_view} member functions is \bigoh{1}

unless otherwise specified.

\pnum

\tcode{basic_string_view<charT, traits>} is

a trivially copyable type\iref{term.trivially.copyable.type}.

\rSec3[string.view.cons]{Construction and assignment}

\indexlibraryctor{basic_string_view}%

\begin{itemdecl}

constexpr basic_string_view() noexcept;

\end{itemdecl}

\begin{itemdescr}

\pnum

\ensures

\tcode{\exposid{size_} == 0} and \tcode{\exposid{data_} == nullptr}.

\end{itemdescr}

\indexlibraryctor{basic_string_view}%

\begin{itemdecl}

constexpr basic_string_view(const charT* str);

\end{itemdecl}

\begin{itemdescr}

\pnum

\expects

\range{str}{str + traits::length(str)} is a valid range.

\pnum

\effects

Constructs a \tcode{basic_string_view}, initializing \exposid{data_} with \tcode{str}

and initializing \exposid{size_} with \tcode{traits::length(str)}.

\pnum

\complexity

\bigoh{\tcode{traits::length(str)}}.

\end{itemdescr}

\indexlibraryctor{basic_string_view}%

\begin{itemdecl}

constexpr basic_string_view(const charT* str, size_type len);

\end{itemdecl}

\begin{itemdescr}

\pnum

\expects

\range{str}{str + len} is a valid range.

\pnum

\effects

Constructs a \tcode{basic_string_view}, initializing \exposid{data_} with \tcode{str}

and initializing \exposid{size_} with \tcode{len}.

\end{itemdescr}

\indexlibraryctor{basic_string_view}%

\begin{itemdecl}

template<class It, class End>

constexpr basic_string_view(It begin, End end);

\end{itemdecl}

\begin{itemdescr}

\pnum

\constraints

\begin{itemize}

\item \tcode{It} satisfies \libconcept{contiguous_iterator}.

\item \tcode{End} satisfies \tcode{\libconcept{sized_sentinel_for}<It>}.

\item \tcode{is_same_v<iter_value_t<It>, charT>} is \tcode{true}.

\item \tcode{is_convertible_v<End, size_type>} is \tcode{false}.

\end{itemize}

\pnum

\expects

\begin{itemize}

\item \range{begin}{end} is a valid range.

\item \tcode{It} models \libconcept{contiguous_iterator}.

\item \tcode{End} models \tcode{\libconcept{sized_sentinel_for}<It>}.

\end{itemize}

\pnum

\effects

Initializes \exposid{data_} with \tcode{to_address(begin)} and

initializes \exposid{size_} with \tcode{end - begin}.

\pnum

\throws

When and what \tcode{end - begin} throws.

\end{itemdescr}

\indexlibraryctor{basic_string_view}%

\begin{itemdecl}

template<class R>

constexpr explicit basic_string_view(R&& r);

\end{itemdecl}

\begin{itemdescr}

\pnum

Let \tcode{d} be an lvalue of type \tcode{remove_cvref_t<R>}.

\pnum

\constraints

\begin{itemize}

\item

\tcode{remove_cvref_t<R>} is not the same type as \tcode{basic_string_view},

\item

\tcode{R} models

\tcode{ranges::\libconcept{contiguous_range}} and \tcode{ranges::\libconcept{sized_range}},

\item

\tcode{is_same_v<ranges::range_value_t<R>, charT>} is \tcode{true},

\item

\tcode{is_convertible_v<R, const charT*>} is \tcode{false}, and

\item

\tcode{d.operator ::std::basic_string_view<charT, traits>()}

is not a valid expression.

\end{itemize}

\pnum

\effects

Initializes \exposid{data_} with \tcode{ranges::data(r)} and

\exposid{size_} with \tcode{ranges::size(r)}.

\pnum

\throws

Any exception thrown by \tcode{ranges::data(r)} and \tcode{ranges::size(r)}.

\end{itemdescr}

\rSec3[string.view.deduct]{Deduction guides}

\begin{itemdecl}

template<class It, class End>

basic_string_view(It, End) -> basic_string_view<iter_value_t<It>>;

\end{itemdecl}

\begin{itemdescr}

\pnum

\constraints

\begin{itemize}

\item \tcode{It} satisfies \libconcept{contiguous_iterator}.

\item \tcode{End} satisfies \tcode{\libconcept{sized_sentinel_for}<It>}.

\end{itemize}

\end{itemdescr}

\begin{itemdecl}

template<class R>

basic_string_view(R&&) -> basic_string_view<ranges::range_value_t<R>>;

\end{itemdecl}

\begin{itemdescr}

\pnum

\constraints

\tcode{R} satisfies \tcode{ranges::\libconcept{contiguous_range}}.

\end{itemdescr}

\rSec3[string.view.iterators]{Iterator support}

\indexlibrarymember{const_iterator}{basic_string_view}%

\begin{itemdecl}

using const_iterator = @\impdefx{type of \tcode{basic_string_view::const_iterator}}@;

\end{itemdecl}

\begin{itemdescr}

\pnum

A type that meets the requirements

of a constant

\oldconcept{RandomAccessIterator}\iref{random.access.iterators},

models \libconcept{contiguous_iterator}\iref{iterator.concept.contiguous}, and

meets the constexpr iterator requirements\iref{iterator.requirements.general},

whose \tcode{value_type} is the template parameter \tcode{charT}.

\pnum

All requirements on container iterators\iref{container.requirements} apply to \tcode{basic_string_view::const_iterator} as well.

\end{itemdescr}

\indexlibrarymember{begin}{basic_string_view}%

\indexlibrarymember{cbegin}{basic_string_view}%

\begin{itemdecl}

constexpr const_iterator begin() const noexcept;

constexpr const_iterator cbegin() const noexcept;

\end{itemdecl}

\begin{itemdescr}

\pnum

\returns

An iterator such that

\begin{itemize}

\item if \tcode{!empty()}, \tcode{addressof(*begin()) == \exposid{data_}},

\item otherwise, an unspecified value such that \range{begin()}{end()} is a valid range.

\end{itemize}

\end{itemdescr}

\indexlibrarymember{end}{basic_string_view}%

\indexlibrarymember{cend}{basic_string_view}%

\begin{itemdecl}

constexpr const_iterator end() const noexcept;

constexpr const_iterator cend() const noexcept;

\end{itemdecl}

\begin{itemdescr}

\pnum

\returns

\tcode{begin() + size()}.

\end{itemdescr}

\indexlibrarymember{rbegin}{basic_string_view}%

\indexlibrarymember{crbegin}{basic_string_view}%

\begin{itemdecl}

constexpr const_reverse_iterator rbegin() const noexcept;

constexpr const_reverse_iterator crbegin() const noexcept;

\end{itemdecl}

\begin{itemdescr}

\pnum

\returns

\tcode{const_reverse_iterator(end())}.

\end{itemdescr}

\indexlibrarymember{rend}{basic_string_view}%

\indexlibrarymember{crend}{basic_string_view}%

\begin{itemdecl}

constexpr const_reverse_iterator rend() const noexcept;

constexpr const_reverse_iterator crend() const noexcept;

\end{itemdecl}

\begin{itemdescr}

\pnum

\returns

\tcode{const_reverse_iterator(begin())}.

\end{itemdescr}

\rSec3[string.view.capacity]{Capacity}

\indexlibrarymember{size}{basic_string_view}%

\indexlibrarymember{length}{basic_string_view}%

\begin{itemdecl}