Working Draft, Standard for Programming Language C++ (N4713, 2017 year) - page 23
template<class ToDuration, class Clock, class Duration>
constexpr time_point<Clock, ToDuration> round(const time_point<Clock, Duration>& tp);
7
Remarks: This function shall not participate in overload resolution unless ToDuration is a specialization
of duration, and treat_as_floating_point_v<typename ToDuration::rep> is false.
8
Returns: time_point<Clock, ToDuration>(round<ToDuration>(tp.time_since_epoch())).
23.17.7
Clocks
[time.clock]
1
The types defined in this subclause shall satisfy the TrivialClock requirements (23.17.3).
23.17.7.1
Class system_clock
[time.clock.system]
1
Objects of class system_clock represent wall clock time from the system-wide realtime clock.
namespace std::chrono {
class system_clock {
public:
using rep
= see below ;
using period
= ratio<unspecified, unspecified >;
using duration
= chrono::duration<rep, period>;
using time_point = chrono::time_point<system_clock>;
static constexpr bool is_steady = unspecified ;
static time_point now() noexcept;
// map to C API
static time_t
to_time_t
(const time_point& t) noexcept;
static time_point
from_time_t(time_t t) noexcept;
};
}
using system_clock::rep = unspecified ;
2
Requires: system_clock::duration::min() < system_clock::duration::zero() shall be true.
[ Note: This implies that rep is a signed type.
— end note ]
static time_t to_time_t(const time_point& t) noexcept;
3
Returns: A time_t object that represents the same point in time as t when both values are restricted
to the coarser of the precisions of time_t and time_point. It is implementation-defined whether values
are rounded or truncated to the required precision.
static time_point from_time_t(time_t t) noexcept;
4
Returns: A time_point object that represents the same point in time as t when both values are
restricted to the coarser of the precisions of time_t and time_point. It is implementation-defined
whether values are rounded or truncated to the required precision.
23.17.7.2
Class steady_clock
[time.clock.steady]
1
Objects of class steady_clock represent clocks for which values of time_point never decrease as physical
time advances and for which values of time_point advance at a steady rate relative to real time. That is,
the clock may not be adjusted.
namespace std::chrono {
class steady_clock {
public:
using rep
= unspecified ;
using period
= ratio<unspecified, unspecified >;
using duration
= chrono::duration<rep, period>;
using time_point = chrono::time_point<unspecified, duration>;
static constexpr bool is_steady = true;
static time_point now() noexcept;
};
}
§ 23.17.7.2
652
23.17.7.3
Class high_resolution_clock
[time.clock.hires]
1
Objects of class high_resolution_clock represent clocks with the shortest tick period. high_resolution_-
clock may be a synonym for system_clock or steady_clock.
namespace std::chrono {
class high_resolution_clock {
public:
using rep
= unspecified ;
using period
= ratio<unspecified, unspecified >;
using duration
= chrono::duration<rep, period>;
using time_point = chrono::time_point<unspecified,
duration>;
static constexpr bool is_steady = unspecified ;
static time_point now() noexcept;
};
}
23.17.8
Header <ctime> synopsis
[ctime.syn]
#define NULL see 21.2.3
#define CLOCKS_PER_SEC see below
#define TIME_UTC see below
namespace std {
using size_t = see 21.2.4;
using clock_t = see below ;
using time_t = see below ;
struct timespec;
struct tm;
clock_t clock();
double difftime(time_t time1, time_t time0);
time_t mktime(struct tm* timeptr);
time_t time(time_t* timer);
int timespec_get(timespec* ts, int base);
char* asctime(const struct tm* timeptr);
char* ctime(const time_t* timer);
struct tm* gmtime(const time_t* timer);
struct tm* localtime(const time_t* timer);
size_t strftime(char* s, size_t maxsize, const char*
format,
const
struct
tm*
timeptr);
}
1
The contents of the header <ctime> are the same as the C standard library header <time.h>.227
2
The functions asctime, ctime, gmtime, and localtime are not required to avoid data races (20.5.5.9).
See also: ISO C 7.27
23.18
Class type_index
[type.index]
23.18.1
Header <typeindex> synopsis
[type.index.synopsis]
namespace std {
class type_index;
template<class T> struct hash;
template<> struct hash<type_index>;
}
23.18.2
type_index overview
[type.index.overview]
namespace std {
class type_index {
public:
type_index(const type_info& rhs) noexcept;
bool operator==(const type_index& rhs) const noexcept;
227) strftime supports the C conversion specifiers C, D, e, F, g, G, h, r, R, t, T, u, V, and z, and the modifiers E and O.
§ 23.18.2
653
bool operator!=(const type_index& rhs) const noexcept;
bool operator< (const type_index& rhs) const noexcept;
bool operator<= (const type_index& rhs) const noexcept;
bool operator> (const type_index& rhs) const noexcept;
bool operator>= (const type_index& rhs) const noexcept;
size_t hash_code() const noexcept;
const char* name() const noexcept;
private:
const type_info* target;
// exposition only
// Note that the use of a pointer here, rather than a reference,
// means that the default copy/move constructor and assignment
// operators will be provided and work as expected.
};
}
1
The class type_index provides a simple wrapper for type_info which can be used as an index type in
associative containers (26.4) and in unordered associative containers (26.5).
23.18.3
type_index members
[type.index.members]
type_index(const type_info& rhs) noexcept;
1
Effects: Constructs a type_index object, the equivalent of target
=
&rhs.
bool operator==(const type_index& rhs) const noexcept;
2
Returns: *target == *rhs.target.
bool operator!=(const type_index& rhs) const noexcept;
3
Returns: *target != *rhs.target.
bool operator<(const type_index& rhs) const noexcept;
4
Returns: target->before(*rhs.target).
bool operator<=(const type_index& rhs) const noexcept;
5
Returns: !rhs.target->before(*target).
bool operator>(const type_index& rhs) const noexcept;
6
Returns: rhs.target->before(*target).
bool operator>=(const type_index& rhs) const noexcept;
7
Returns: !target->before(*rhs.target).
size_t hash_code() const noexcept;
8
Returns: target->hash_code().
const char* name() const noexcept;
9
Returns: target->name().
23.18.4
Hash support
[type.index.hash]
template<> struct hash<type_index>;
1
For an object index of type type_index, hash<type_index>()(index) shall evaluate to the same
result as index.hash_code().
23.19
Execution policies
[execpol]
23.19.1
In general
[execpol.general]
1
This subclause describes classes that are execution policy types. An object of an execution policy type
indicates the kinds of parallelism allowed in the execution of an algorithm and expresses the consequent
requirements on the element access functions. [ Example:
using namespace std;
§ 23.19.1
654
vector<int> v = /* ... */;
// standard sequential sort
sort(v.begin(), v.end());
// explicitly sequential sort
sort(execution::seq, v.begin(), v.end());
// permitting parallel execution
sort(execution::par, v.begin(), v.end());
// permitting vectorization as well
sort(execution::par_unseq, v.begin(), v.end());
— end example ] [ Note: Because different parallel architectures may require idiosyncratic parameters for
efficient execution, implementations may provide additional execution policies to those described in this
standard as extensions.
— end note ]
23.19.2
Header <execution> synopsis
[execution.syn]
namespace std {
// 23.19.3, execution policy type trait
template<class T> struct is_execution_policy;
template<class T> inline constexpr bool is_execution_policy_v = is_execution_policy<T>::value;
}
namespace std::execution {
// 23.19.4, sequenced execution policy
class sequenced_policy;
// 23.19.5, parallel execution policy
class parallel_policy;
// 23.19.6, parallel and unsequenced execution policy
class parallel_unsequenced_policy;
// 23.19.7, execution policy objects
inline constexpr sequenced_policy
seq{ unspecified
};
inline constexpr parallel_policy
par{ unspecified
};
inline constexpr parallel_unsequenced_policy par_unseq{ unspecified
};
}
23.19.3
Execution policy type trait
[execpol.type]
template<class T> struct is_execution_policy { see below
};
1
is_execution_policy can be used to detect execution policies for the purpose of excluding function
signatures from otherwise ambiguous overload resolution participation.
2
is_execution_policy<T> shall be a UnaryTypeTrait with a base characteristic of true_type if T is
the type of a standard or implementation-defined execution policy, otherwise false_type.
[Note: This provision reserves the privilege of creating non-standard execution policies to the library
implementation.
— end note ]
3
The behavior of a program that adds specializations for is_execution_policy is undefined.
23.19.4
Sequenced execution policy
[execpol.seq]
class execution::sequenced_policy { unspecified
};
1
The class execution::sequenced_policy is an execution policy type used as a unique type to disam-
biguate parallel algorithm overloading and require that a parallel algorithm’s execution may not be
parallelized.
2
During the execution of a parallel algorithm with the execution::sequenced_policy policy, if the
invocation of an element access function exits via an uncaught exception, terminate() shall be called.
§ 23.19.4
655
23.19.5
Parallel execution policy
[execpol.par]
class execution::parallel_policy { unspecified
};
1
The class execution::parallel_policy is an execution policy type used as a unique type to dis-
ambiguate parallel algorithm overloading and indicate that a parallel algorithm’s execution may be
parallelized.
2
During the execution of a parallel algorithm with the execution::parallel_policy policy, if the
invocation of an element access function exits via an uncaught exception, terminate() shall be called.
23.19.6
Parallel and unsequenced execution policy
[execpol.parunseq]
class execution::parallel_unsequenced_policy { unspecified
};
1
The class execution::parallel_unsequenced_policy is an execution policy type used as a unique
type to disambiguate parallel algorithm overloading and indicate that a parallel algorithm’s execution
may be parallelized and vectorized.
2
During the execution of a parallel algorithm with the execution::parallel_unsequenced_policy
policy, if the invocation of an element access function exits via an uncaught exception, terminate()
shall be called.
23.19.7
Execution policy objects
[execpol.objects]
inline constexpr execution::sequenced_policy
execution::seq{ unspecified
};
inline constexpr execution::parallel_policy
execution::par{ unspecified
};
inline constexpr execution::parallel_unsequenced_policy execution::par_unseq{ unspecified
};
1
The header <execution> declares global objects associated with each type of execution policy.
23.20
Primitive numeric conversions
[charconv]
23.20.1
Header <charconv> synopsis
[charconv.syn]
namespace std {
// floating-point format for primitive numerical conversion
enum class chars_format {
scientific = unspecified ,
fixed = unspecified ,
hex = unspecified ,
general = fixed | scientific
};
// 23.20.2, primitive numerical output conversion
struct to_chars_result {
char* ptr;
errc ec;
};
to_chars_result to_chars(char* first, char* last, see below value, int base = 10);
to_chars_result to_chars(char* first, char* last, float value);
to_chars_result to_chars(char* first, char* last, double value);
to_chars_result to_chars(char* first, char* last, long double value);
to_chars_result to_chars(char* first, char* last, float value, chars_format fmt);
to_chars_result to_chars(char* first, char* last, double value, chars_format fmt);
to_chars_result to_chars(char* first, char* last, long double value, chars_format fmt);
to_chars_result to_chars(char* first, char* last, float value,
chars_format fmt, int precision);
to_chars_result to_chars(char* first, char* last, double value,
chars_format fmt, int precision);
to_chars_result to_chars(char* first, char* last, long double value,
chars_format fmt, int precision);
§ 23.20.1
656
// 23.20.3, primitive numerical input conversion
struct from_chars_result {
const char* ptr;
errc ec;
};
from_chars_result from_chars(const char* first, const char* last,
see below & value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, float& value,
chars_format fmt = chars_format::general);
from_chars_result from_chars(const char* first, const char* last, double& value,
chars_format fmt = chars_format::general);
from_chars_result from_chars(const char* first, const char* last, long double& value,
chars_format fmt = chars_format::general);
}
23.20.2
Primitive numeric output conversion
[charconv.to.chars]
1
All functions named to_chars convert value into a character string by successively filling the range
[first, last), where [first, last) is required to be a valid range. If the member ec of the return
value is such that the value is equal to the value of a value-initialized errc, the conversion was successful
and the member ptr is the one-past-the-end pointer of the characters written. Otherwise, the member ec
has the value errc::value_too_large, the member ptr has the value last, and the contents of the range
[first, last) are unspecified.
2
The functions that take a floating-point value but not a precision parameter ensure that the string
representation consists of the smallest number of characters such that there is at least one digit before the
radix point (if present) and parsing the representation using the corresponding from_chars function recovers
value exactly. [ Note: This guarantee applies only if to_chars and from_chars are executed on the same
implementation.
— end note ] If there are several such representations, the representation with the smallest
difference from the floating-point argument value is chosen, resolving any remaining ties using rounding
according to round_to_nearest (21.3.3.1).
3
The functions taking a chars_format parameter determine the conversion specifier for printf as follows:
The conversion specifier is f if fmt is chars_format::fixed, e if fmt is chars_format::scientific, a
(without leading "0x" in the result) if fmt is chars_format::hex, and g if fmt is chars_format::general.
to_chars_result to_chars(char* first, char* last, see below value, int base = 10);
4
Requires: base has a value between 2 and 36 (inclusive).
5
Effects: The value of value is converted to a string of digits in the given base (with no redundant
leading zeroes). Digits in the range 10..35 (inclusive) are represented as lowercase characters a..z. If
value is less than zero, the representation starts with a minus sign.
6
Throws: Nothing.
7
Remarks: The implementation shall provide overloads for all signed and unsigned integer types and
char as the type of the parameter value.
to_chars_result to_chars(char* first, char* last, float value);
to_chars_result to_chars(char* first, char* last, double value);
to_chars_result to_chars(char* first, char* last, long double value);
8
Effects: value is converted to a string in the style of printf in the "C" locale. The conversion specifier
is f or e, chosen according to the requirement for a shortest representation (see above); a tie is resolved
in favor of f.
9
Throws: Nothing.
to_chars_result to_chars(char* first, char* last, float value, chars_format fmt);
to_chars_result to_chars(char* first, char* last, double value, chars_format fmt);
to_chars_result to_chars(char* first, char* last, long double value, chars_format fmt);
10
Requires: fmt has the value of one of the enumerators of chars_format.
11
Effects: value is converted to a string in the style of printf in the "C" locale.
§ 23.20.2
657
12
Throws: Nothing.
to_chars_result to_chars(char* first, char* last, float value,
chars_format fmt, int precision);
to_chars_result to_chars(char* first, char* last, double value,
chars_format fmt, int precision);
to_chars_result to_chars(char* first, char* last, long double value,
chars_format fmt, int precision);
13
Requires: fmt has the value of one of the enumerators of chars_format.
14
Effects: value is converted to a string in the style of printf in the "C" locale with the given precision.
15
Throws: Nothing.
See also: ISO C 7.21.6.1
23.20.3
Primitive numeric input conversion
[charconv.from.chars]
1
All functions named from_chars analyze the string [first, last) for a pattern, where [first, last) is
required to be a valid range. If no characters match the pattern, value is unmodified, the member ptr of
the return value is first and the member ec is equal to errc::invalid_argument. [Note: If the pattern
allows for an optional sign, but the string has no digit characters following the sign, no characters match the
pattern.
— end note ] Otherwise, the characters matching the pattern are interpreted as a representation
of a value of the type of value. The member ptr of the return value points to the first character not
matching the pattern, or has the value last if all characters match. If the parsed value is not in the range
representable by the type of value, value is unmodified and the member ec of the return value is equal
to errc::result_out_of_range. Otherwise, value is set to the parsed value, after rounding according to
round_to_nearest (21.3.3.1), and the member ec is value-initialized.
from_chars_result from_chars(const char* first, const char* last,
see below & value, int base = 10);
2
Requires: base has a value between 2 and 36 (inclusive).
3
Effects: The pattern is the expected form of the subject sequence in the "C" locale for the given nonzero
base, as described for strtol, except that no "0x" or "0X" prefix shall appear if the value of base is
16, and except that a minus sign is the only sign that may appear, and only if value has a signed type.
4
Throws: Nothing.
5
Remarks: The implementation shall provide overloads for all signed and unsigned integer types and
char as the referenced type of the parameter value.
from_chars_result from_chars(const char* first, const char* last, float& value,
chars_format fmt = chars_format::general);
from_chars_result from_chars(const char* first, const char* last, double& value,
chars_format fmt = chars_format::general);
from_chars_result from_chars(const char* first, const char* last, long double& value,
chars_format fmt = chars_format::general);
6
Requires: fmt has the value of one of the enumerators of chars_format.
7
Effects: The pattern is the expected form of the subject sequence in the "C" locale, as described for
strtod, except that
(7.1)
—
the only sign that may appear is a minus sign;
(7.2)
—
if fmt has chars_format::scientific set but not chars_format::fixed, the otherwise optional
exponent part shall appear;
(7.3)
—
if fmt has chars_format::fixed set but not chars_format::scientific, the optional exponent
part shall not appear; and
(7.4)
—
if fmt is chars_format::hex, the prefix "0x" or "0X" is assumed. [Example: The string 0x123
is parsed to have the value 0 with remaining characters x123.
— end example ]
In any case, the resulting value is one of at most two floating-point values closest to the value of the
string matching the pattern.
8
Throws: Nothing.
§ 23.20.3
658
See also: ISO C 7.22.1.3, 7.22.1.4
§ 23.20.3
659
24
Strings library
[strings]
24.1
General
[strings.general]
1
This Clause describes components for manipulating sequences of any non-array trivial (6.7) type. Such types
are called char-like types, and objects of char-like types are called char-like objects or simply characters.
2
The following subclauses describe a character traits class, string classes, and null-terminated sequence utilities,
as summarized in Table 53.
Table 53 — Strings library summary
Subclause
Header(s)
24.2
Character traits
<string>
24.3
String classes
<string>
24.4
String view classes
<string_view>
<cctype>
<cwctype>
24.5
Null-terminated sequence utilities
<cstring>
<cwchar>
<cstdlib>
<cuchar>
24.2
Character traits
[char.traits]
1
This subclause defines requirements on classes representing character traits, and defines a class template
char_traits<charT>, along with four specializations, char_traits<char>, char_traits<char16_t>,
char_traits<char32_t>, and char_traits<wchar_t>, that satisfy those requirements.
2
Most classes specified in 24.3 and Clause 30 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 typedef-names and functions
in the template parameter traits used by each such template. This subclause defines the semantics of these
members.
3
To specialize those templates to generate a string or iostream class to handle a particular character container
type CharT, that and its related character traits class Traits are passed as a pair of parameters to the string
or iostream template as parameters charT and traits. Traits::char_type shall be the same as CharT.
4
This subclause specifies a class template, char_traits<charT>, and four explicit specializations of it,
char_traits<char>, char_traits<char16_t>, char_traits<char32_t>, and char_traits<wchar_t>, all
of which appear in the header <string> and satisfy the requirements below.
24.2.1
Character traits requirements
[char.traits.require]
1
In Table 54, X denotes a Traits class defining types and functions for the character container type CharT; c
and d denote values of type CharT; p and q denote values of type const CharT*; s denotes a value of type
CharT*; n, i and j denote values of type size_t; e and f denote values of type X::int_type; pos denotes a
value of type X::pos_type; state denotes a value of type X::state_type; and r denotes an lvalue of type
CharT. Operations on Traits shall not throw exceptions.
Table 54 — Character traits requirements
Expression
Return type
Assertion/note
Complexity
pre-/post-condition
X::char_type
charT
(described in 24.2.2)
compile-time
X::int_type
(described in 24.2.2)
compile-time
X::off_type
(described in 24.2.2)
compile-time
X::pos_type
(described in 24.2.2)
compile-time
§ 24.2.1
660
Table 54 — Character traits requirements (continued)
Expression
Return type
Assertion/note
Complexity
pre-/post-condition
X::state_type
(described in 24.2.2)
compile-time
X::eq(c,d)
bool
Returns: whether c is to be
constant
treated as equal to d.
X::lt(c,d)
bool
Returns: whether c is to be
constant
treated as less than d.
X::compare(p,q,n)
int
Returns: 0 if for each i in
linear
[0,n), X::eq(p[i],q[i]) is
true; else, a negative value if,
for some j in [0,n),
X::lt(p[j],q[j]) is true and
for each i in [0,j)
X::eq(p[i],q[i]) is true; else
a positive value.
X::length(p)
size_t
Returns: the smallest i such
linear
that X::eq(p[i],charT()) is
true.
X::find(p,n,c)
const X::char_type*
Returns: the smallest q in
linear
[p,p+n) such that X::eq(*q,c)
is true, zero otherwise.
X::move(s,p,n)
X::char_type*
for each i in [0,n), performs
linear
X::assign(s[i],p[i]). Copies
correctly even where the ranges
[p,p+n) and [s,s+n) overlap.
Returns: s.
X::copy(s,p,n)
X::char_type*
Requires: p not in [s,s+n).
linear
Returns: s.
for each i in [0,n), performs
X::assign(s[i],p[i]).
X::assign(r,d)
(not used)
assigns r=d.
constant
X::assign(s,n,c)
X::char_type*
for each i in [0,n), performs
linear
X::assign(s[i],c).
Returns: s.
X::not_eof(e)
int_type
Returns: e if
constant
X::eq_int_type(e,X::eof())
is false, otherwise a value f
such that
X::eq_int_type(f,X::eof())
is false.
X::to_char_type(e)
X::char_type
Returns: if for some c,
constant
X::eq_int_type(e,X::to_-
int_type(c)) is true, c; else
some unspecified value.
X::to_int_type(c)
X::int_type
Returns: some value e,
constant
constrained by the definitions of
to_char_type and
eq_int_type.
§ 24.2.1
661
Table 54 — Character traits requirements (continued)
Expression
Return type
Assertion/note
Complexity
pre-/post-condition
X::eq_int_type(e,f) bool
Returns: for all c and d,
constant
X::eq(c,d) is equal to X::eq_-
int_type(X::to_int_type(c),
X::to_int_type(d));
otherwise, yields true if e and f
are both copies of X::eof();
otherwise, yields false if one of
e and f is a copy of X::eof()
and the other is not; otherwise
the value is unspecified.
X::eof()
X::int_type
Returns: a value e such that
constant
X::eq_int_type(e,X::to_-
int_type(c)) is false for all
values c.
2
The class template
template<class charT> struct char_traits;
shall be provided in the header <string> as a basis for explicit specializations.
24.2.2
Traits typedefs
[char.traits.typedefs]
using char_type = CHAR_T;
1
The type char_type is used to refer to the character container type in the implementation of the library
classes defined in 24.3 and Clause 30.
using int_type = INT_T;
2
Requires: For a certain character container type char_type, a related container type INT_T shall be a
type or class which can represent all of the valid characters converted from the corresponding char_type
values, as well as an end-of-file value, eof(). The type 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.228
using off_type = implementation-defined ;
using pos_type = implementation-defined ;
3
Requires: Requirements for off_type and pos_type are described in 30.2.2 and 30.3.
using state_type = STATE_T;
4
Requires: state_type shall meet the requirements of CopyAssignable (Table 26), CopyConstructible
(Table 24), and DefaultConstructible (Table 22) types.
24.2.3
char_traits specializations
[char.traits.specializations]
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>;
}
1
The header <string> shall define four specializations of the class template char_traits: char_traits<
char>, char_traits<char16_t>, char_traits<char32_t>, and char_traits<wchar_t>.
2
The requirements for the members of these specializations are given in 24.2.1.
228) If eof() can be held in char_type then some iostreams operations may give surprising results.
§ 24.2.3
662
24.2.3.1
struct char_traits<char>
[char.traits.specializations.char]
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;
};
}
1
The defined types for int_type, pos_type, off_type, and state_type shall be int, streampos, streamoff,
and mbstate_t respectively.
2
The type streampos shall be an implementation-defined type that satisfies the requirements for pos_type
in 30.2.2 and 30.3.
3
The type streamoff shall be an implementation-defined type that satisfies the requirements for off_type
in 30.2.2 and 30.3.
4
The type mbstate_t is defined in <cwchar> and can represent any of the conversion states that can occur in
an implementation-defined set of supported multibyte character encoding rules.
5
The two-argument member assign shall be defined identically to the built-in operator =. The two-argument
members eq and lt shall be defined identically to the built-in operators == and < for type unsigned char.
6
The member eof() shall return EOF.
24.2.3.2
struct char_traits<char16_t>
[char.traits.specializations.char16_t]
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);
§ 24.2.3.2
663
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;
};
}
1
The type u16streampos shall be an implementation-defined type that satisfies the requirements for pos_type
in 30.2.2 and 30.3.
2
The two-argument members assign, eq, and lt shall be defined identically to the built-in operators =, ==,
and < respectively.
3
The member eof() shall return an implementation-defined constant that cannot appear as a valid UTF-16
code unit.
24.2.3.3
struct char_traits<char32_t>
[char.traits.specializations.char32_t]
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;
};
}
1
The type u32streampos shall be an implementation-defined type that satisfies the requirements for pos_type
in 30.2.2 and 30.3.
2
The two-argument members assign, eq, and lt shall be defined identically to the built-in operators =, ==,
and < respectively.
3
The member eof() shall return an implementation-defined constant that cannot appear as a Unicode code
point.
24.2.3.4
struct char_traits<wchar_t>
[char.traits.specializations.wchar.t]
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;
§ 24.2.3.4
664
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;
};
}
1
The defined types for int_type, pos_type, and state_type shall be wint_t, wstreampos, and mbstate_t
respectively.
2
The type wstreampos shall be an implementation-defined type that satisfies the requirements for pos_type
in 30.2.2 and 30.3.
3
The type mbstate_t is defined in <cwchar> and can represent any of the conversion states that can occur in
an implementation-defined set of supported multibyte character encoding rules.
4
The two-argument members assign, eq, and lt shall be defined identically to the built-in operators =, ==,
and < respectively.
5
The member eof() shall return WEOF.
24.3
String classes
[string.classes]
1
The header <string> defines the basic_string class template for manipulating varying-length sequences
of char-like objects and four typedef-names, string, u16string, u32string, and wstring, that name the
specializations basic_string<char>, basic_string<char16_t>, basic_string<char32_t>, and basic_-
string<wchar_t>, respectively.
24.3.1
Header <string> synopsis
[string.syn]
#include <initializer_list>
namespace std {
// 24.2, 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>;
// 24.3.2, 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);
§ 24.3.1
665
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;
§
24.3.1
666
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);
// 24.3.3.8, 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)));
// 24.3.3.9, 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);
§
24.3.1
667
template<class charT, class traits, class Allocator>
basic_istream<charT, traits>&
getline(basic_istream<charT, traits>&& is,
basic_string<charT, traits, Allocator>& str);
// 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>;
// 24.3.4, numeric conversions
int stoi(const string& str, size_t* idx = nullptr, int base = 10);
long stol(const string& str, size_t* idx = nullptr, int base = 10);
unsigned long stoul(const string& str, size_t* idx = nullptr, int base = 10);
long long stoll(const string& str, size_t* idx = nullptr, int base = 10);
unsigned long long stoull(const string& str, size_t* idx = nullptr, int base =
10);
float stof(const string& str, size_t* idx = nullptr);
double stod(const string& str, size_t* idx = nullptr);
long double stold(const string& str, size_t* idx = nullptr);
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 = nullptr, int base = 10);
long stol(const wstring& str, size_t* idx = nullptr, int base = 10);
unsigned long stoul(const wstring& str, size_t* idx = nullptr, int base = 10);
long long stoll(const wstring& str, size_t* idx = nullptr, int base = 10);
unsigned long long stoull(const wstring& str, size_t* idx = nullptr, int base =
10);
float stof(const wstring& str, size_t* idx = nullptr);
double stod(const wstring& str, size_t* idx = nullptr);
long double stold(const wstring& str, size_t* idx = nullptr);
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);
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>;
}
// 24.3.5, hash support
template<class T> struct hash;
template<> struct hash<string>;
template<> struct hash<u16string>;
template<> struct hash<u32string>;
template<> struct hash<wstring>;
§
24.3.1
668
template<> struct hash<pmr::string>;
template<> struct hash<pmr::u16string>;
template<> struct hash<pmr::u32string>;
template<> struct hash<pmr::wstring>;
inline namespace literals {
inline namespace string_literals {
// 24.3.6, 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);
}
}
}
24.3.2
Class template basic_string
[basic.string]
1
The class template 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 basic_string object is designated by charT.
2
The member functions of basic_string use an object of the Allocator class passed as a template parameter
to allocate and free storage for the contained char-like objects.229
3
A basic_string is a contiguous container (26.2.1).
4
In all cases, size() <= capacity().
5
The functions described in this Clause can report two kinds of errors, each associated with an exception type:
(5.1)
—
a length error is associated with exceptions of type length_error (22.2.5);
(5.2)
—
an out-of-range error is associated with exceptions of type out_of_range (22.2.6).
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
= implementation-defined ; // see 26.2
using const_iterator
= implementation-defined ; // see 26.2
using reverse_iterator
= std::reverse_iterator<iterator>;
using const_reverse_iterator = std::reverse_iterator<const_iterator>;
static const size_type npos
= -1;
// 24.3.2.2, 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());
229) Allocator::value_type must name the same type as charT (24.3.2.1).
§ 24.3.2
669
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>);
// 24.3.2.3, 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;
// 24.3.2.4, 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;
[[nodiscard]] bool empty() const noexcept;
// 24.3.2.5, 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();
// 24.3.2.6, modifiers
basic_string& operator+=(const basic_string& str);
basic_string& operator+=(basic_string_view<charT, traits>
sv);
§
24.3.2
670
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);
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 pos, 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, basic_string_view<charT, traits> sv);
template<class T>
basic_string& insert(size_type pos1, const T& t, 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);
void pop_back();
basic_string& replace(size_type pos1, size_type n1, const basic_string& str);
basic_string& replace(size_type pos1, size_type n1, const basic_string& str,
size_type pos2, size_type n2 = npos);
basic_string& replace(size_type pos1, size_type n1, basic_string_view<charT, traits> sv);
template<class T>
basic_string& replace(size_type pos1, size_type n1, const T& t,
size_type pos2, size_type n2 = npos);
basic_string& replace(size_type pos, size_type n1, const charT* s, size_type n2);
basic_string& replace(size_type pos, size_type n1, const charT* s);
basic_string& replace(size_type pos, size_type n1, size_type n2, charT c);
§
24.3.2
671
basic_string& replace(const_iterator i1, const_iterator i2, const basic_string& str);
basic_string& replace(const_iterator i1, const_iterator i2,
basic_string_view<charT, traits> sv);
basic_string& replace(const_iterator i1, const_iterator i2, const charT* s, size_type n);
basic_string& replace(const_iterator i1, const_iterator i2, const charT* s);
basic_string& replace(const_iterator i1, const_iterator i2, size_type n, charT c);
template<class InputIterator>
basic_string& replace(const_iterator i1, const_iterator i2,
InputIterator j1, InputIterator j2);
basic_string& replace(const_iterator, const_iterator, initializer_list<charT>);
size_type copy(charT* s, size_type n, size_type pos = 0) const;
void swap(basic_string& str)
noexcept(allocator_traits<Allocator>::propagate_on_container_swap::value ||
allocator_traits<Allocator>::is_always_equal::value);
// 24.3.2.7, string operations
const charT* c_str() const noexcept;
const charT* data() const noexcept;
charT* data() noexcept;
operator basic_string_view<charT, traits>() const noexcept;
allocator_type get_allocator() const noexcept;
size_type
find (basic_string_view<charT, traits> sv, size_type pos = 0) const noexcept;
size_type
find (const basic_string& str, size_type pos = 0) const noexcept;
size_type
find (const charT* s, size_type pos, size_type n) const;
size_type
find (const charT* s, size_type pos = 0) const;
size_type
find (charT c, size_type pos = 0) const;
size_type
rfind(basic_string_view<charT, traits> sv, size_type pos = npos) const noexcept;
size_type
rfind(const basic_string& str, size_type pos = npos) const noexcept;
size_type
rfind(const charT* s, size_type pos, size_type n) const;
size_type
rfind(const charT* s, size_type pos = npos) const;
size_type
rfind(charT c, size_type pos = npos) const;
size_type
find_first_of(basic_string_view<charT, traits> sv,
size_type pos = 0) const noexcept;
size_type
find_first_of(const basic_string& str, size_type pos = 0) const noexcept;
size_type
find_first_of(const charT* s, size_type pos, size_type n) const;
size_type
find_first_of(const charT* s, size_type pos = 0) const;
size_type
find_first_of(charT c, size_type pos = 0) const;
size_type
find_last_of (basic_string_view<charT, traits> sv,
size_type pos = npos) const noexcept;
size_type
find_last_of (const basic_string& str, size_type pos = npos) const noexcept;
size_type
find_last_of (const charT* s, size_type pos, size_type n) const;
size_type
find_last_of (const charT* s, size_type pos = npos) const;
size_type
find_last_of (charT c, size_type pos = npos) const;
size_type
find_first_not_of(basic_string_view<charT, traits> sv,
size_type pos = 0) const noexcept;
size_type
find_first_not_of(const basic_string& str, size_type pos = 0) const noexcept;
size_type
find_first_not_of(const charT* s, size_type pos, size_type n) const;
size_type
find_first_not_of(const charT* s, size_type pos = 0) const;
size_type
find_first_not_of(charT c, size_type pos = 0) const;
size_type
find_last_not_of (basic_string_view<charT, traits> sv,
size_type pos = npos) const noexcept;
size_type
find_last_not_of (const basic_string& str, size_type pos = npos) const noexcept;
size_type
find_last_not_of (const charT* s, size_type pos, size_type n) const;
size_type
find_last_not_of (const charT* s, size_type pos = npos) const;
size_type
find_last_not_of (charT c, size_type pos = npos) const;
basic_string substr(size_type pos = 0, size_type n = npos) const;
int compare(basic_string_view<charT, traits> sv) const noexcept;
int compare(size_type pos1, size_type n1, basic_string_view<charT, traits> sv) const;
§
24.3.2
672
template<class T>
int compare(size_type pos1, size_type n1, const T& t,
size_type pos2, size_type n2 = npos) const;
int compare(const basic_string& str) const noexcept;
int compare(size_type pos1, size_type n1, const basic_string& str) const;
int compare(size_type pos1, size_type n1, const basic_string& str,
size_type pos2, size_type n2 = npos) const;
int compare(const charT* s) const;
int compare(size_type pos1, size_type n1, const charT* s) const;
int compare(size_type pos1, size_type n1, const charT* s, size_type n2) const;
bool starts_with(basic_string_view<charT, traits> x) const noexcept;
bool starts_with(charT x) const noexcept;
bool starts_with(const charT* x) const;
bool ends_with(basic_string_view<charT, traits> x) const noexcept;
bool ends_with(charT x) const noexcept;
bool ends_with(const charT* x) const;
};
template<class InputIterator,
class Allocator = allocator<typename iterator_traits<InputIterator>::value_type>>
basic_string(InputIterator, InputIterator, Allocator = Allocator())
-> basic_string<typename iterator_traits<InputIterator>::value_type,
char_traits<typename iterator_traits<InputIterator>::value_type>,
Allocator>;
}
24.3.2.1
basic_string general requirements
[string.require]
1
If any operation would cause size() to exceed max_size(), that operation shall throw an exception object
of type length_error.
2
If any member function or operator of basic_string throws an exception, that function or operator shall
have no other effect.
3
In every specialization basic_string<charT, traits, Allocator>, the type allocator_traits<All-
ocator>::value_type shall name the same type as charT. Every object of type basic_string<charT,
traits, Allocator> shall use an object of type Allocator to allocate and free storage for the contained
charT objects as needed. The Allocator object used shall be obtained as described in 26.2.1. In every spe-
cialization basic_string<charT, traits, Allocator>, the type traits shall satisfy the character traits
requirements (24.2), and the type traits::char_type shall name the same type as charT.
4
References, pointers, and iterators referring to the elements of a basic_string sequence may be invalidated
by the following uses of that basic_string object:
(4.1)
—
as an argument to any standard library function taking a reference to non-const basic_string as an
argument.230
(4.2)
—
Calling non-const member functions, except operator[], at, data, front, back, begin, rbegin, end,
and rend.
24.3.2.2
basic_string constructors and assignment operators
[string.cons]
explicit basic_string(const Allocator& a) noexcept;
1
Effects: Constructs an object of class basic_string. The postconditions of this function are indicated
in Table 55.
basic_string(const basic_string& str);
basic_string(basic_string&& str) noexcept;
2
Effects: Constructs an object of class basic_string as indicated in Table 56. In the second form, str
is left in a valid state with an unspecified value.
230) For example, as an argument to non-member functions swap() (24.3.3.8), operator>>() (24.3.3.9), and getline() (24.3.3.9),
or as an argument to basic_string::swap().
§ 24.3.2.2
673
Table 55 — basic_string(const Allocator&) effects
Element
Value
data()
a non-null pointer that is copyable and can have 0
added to it
size()
0
capacity()
an unspecified value
Table 56 — basic_string(const basic_string&) effects
Element
Value
data()
points at the first element of an allocated copy
of the array whose first element is pointed at by
str.data()
size()
str.size()
capacity()
a value at least as large as size()
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());
3
Throws: out_of_range if pos > str.size().
4
Effects: Constructs an object of class basic_string and determines the effective length rlen of the
initial string value as str.size() - pos in the first form and as the smaller of str.size() - pos
and n in the second form, as indicated in Table 57.
Table 57 — basic_string(const basic_string&, size_type, const Allocator&) and
basic_string(const basic_string&, size_type, size_type, const Allocator&) effects
Element
Value
data()
points at the first element of an allocated copy of
rlen consecutive elements of the string controlled
by str beginning at position pos
size()
rlen
capacity()
a value at least as large as size()
template<class T>
basic_string(const T& t, size_type pos, size_type n, const Allocator& a = Allocator());
5
Effects: Creates a variable, sv, as if by basic_string_view<charT, traits> sv = t; and then
behaves the same as:
basic_string(sv.substr(pos, n), a);
6
Remarks: This constructor shall not participate in overload resolution unless is_convertible_v<const
T&, basic_string_view<charT, traits>> is true.
explicit basic_string(basic_string_view<charT, traits> sv, const Allocator& a = Allocator());
7
Effects: Same as basic_string(sv.data(), sv.size(), a).
basic_string(const charT* s, size_type n, const Allocator& a = Allocator());
8
Requires: s points to an array of at least n elements of charT.
9
Effects: Constructs an object of class basic_string and determines its initial string value from the
array of charT of length n whose first element is designated by s, as indicated in Table 58.
basic_string(const charT* s, const Allocator& a = Allocator());
10
Requires: s points to an array of at least traits::length(s) + 1 elements of charT.
§ 24.3.2.2
674
Table 58 — basic_string(const charT*, size_type, const Allocator&) effects
Element
Value
data()
points at the first element of an allocated copy of
the array whose first element is pointed at by s
size()
n
capacity()
a value at least as large as size()
11
Effects: Constructs an object of class basic_string and determines its initial string value from the
array of charT of length traits::length(s) whose first element is designated by s, as indicated in
Table 59.
Table 59 — basic_string(const charT*, const Allocator&) effects
Element
Value
data()
points at the first element of an allocated copy of
the array whose first element is pointed at by s
size()
traits::length(s)
capacity()
a value at least as large as size()
basic_string(size_type n, charT c, const Allocator& a = Allocator());
12
Requires: n < npos.
13
Effects: Constructs an object of class basic_string and determines its initial string value by repeating
the char-like object c for all n elements, as indicated in Table 60.
Table 60 — basic_string(size_t, charT, const Allocator&) effects
Element
Value
data()
points at the first element of an allocated array of
n elements, each storing the initial value c
size()
n
capacity()
a value at least as large as size()
template<class InputIterator>
basic_string(InputIterator begin, InputIterator end, const Allocator& a = Allocator());
14
Effects: If InputIterator is an integral type, equivalent to:
basic_string(static_cast<size_type>(begin), static_cast<value_type>(end), a);
Otherwise constructs a string from the values in the range [begin, end), as indicated in the Sequence
Requirements table (see 26.2.3).
basic_string(initializer_list<charT> il, const Allocator& a = Allocator());
15
Effects: Same as basic_string(il.begin(), il.end(), a).
basic_string(const basic_string& str, const Allocator& alloc);
basic_string(basic_string&& str, const Allocator& alloc);
16
Effects: Constructs an object of class basic_string as indicated in Table 61. The stored allocator is
constructed from alloc. In the second form, str is left in a valid state with an unspecified value.
17
Throws: The second form throws nothing if alloc == str.get_allocator().
template<class InputIterator,
class Allocator = allocator<typename iterator_traits<InputIterator>::value_type>>
basic_string(InputIterator, InputIterator, Allocator = Allocator())
-> basic_string<typename iterator_traits<InputIterator>::value_type,
char_traits<typename iterator_traits<InputIterator>::value_type>,
§ 24.3.2.2
675
Table 61 — basic_string(const basic_string&, const Allocator&)
and basic_string(basic_string&&, const Allocator&) effects
Element
Value
data()
points at the first element of an allocated copy of
the array whose first element is pointed at by the
original value of str.data().
size()
the original value of str.size()
capacity()
a value at least as large as size()
get_allocator()
alloc
Allocator>;
18
Remarks: Shall not participate in overload resolution if InputIterator is a type that does not qualify
as an input iterator, or if Allocator is a type that does not qualify as an allocator (26.2.1).
basic_string& operator=(const basic_string& str);
19
Effects: If *this and str are not the same object, modifies *this as shown in Table 62.
20
If *this and str are the same object, the member has no effect.
21
Returns: *this.
Table 62 — operator=(const basic_string&) effects
Element
Value
data()
points at the first element of an allocated copy
of the array whose first element is pointed at by
str.data()
size()
str.size()
capacity()
a value at least as large as size()
basic_string& operator=(basic_string&& str)
noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
allocator_traits<Allocator>::is_always_equal::value);
22
Effects: Move assigns as a sequence container (26.2), except that iterators, pointers and references may
be invalidated.
23
Returns: *this.
basic_string& operator=(basic_string_view<charT, traits> sv);
24
Effects: Equivalent to: return assign(sv);
basic_string& operator=(const charT* s);
25
Returns: *this = basic_string(s).
26
Remarks: Uses traits::length().
basic_string& operator=(charT c);
27
Returns: *this = basic_string(1, c).
basic_string& operator=(initializer_list<charT> il);
28
Effects: As if by: *this = basic_string(il);
29
Returns: *this.
24.3.2.3
basic_string iterator support
[string.iterators]
iterator
begin() noexcept;
const_iterator begin() const noexcept;
§ 24.3.2.3
676
const_iterator cbegin() const noexcept;
1
Returns: An iterator referring to the first character in the string.
iterator
end() noexcept;
const_iterator end() const noexcept;
const_iterator cend() const noexcept;
2
Returns: An iterator which is the past-the-end value.
reverse_iterator
rbegin() noexcept;
const_reverse_iterator rbegin() const noexcept;
const_reverse_iterator crbegin() const noexcept;
3
Returns: An iterator which is semantically equivalent to reverse_iterator(end()).
reverse_iterator
rend() noexcept;
const_reverse_iterator rend() const noexcept;
const_reverse_iterator crend() const noexcept;
4
Returns: An iterator which is semantically equivalent to reverse_iterator(begin()).
24.3.2.4
basic_string capacity
[string.capacity]
size_type size() const noexcept;
1
Returns: A count of the number of char-like objects currently in the string.
2
Complexity: Constant time.
size_type length() const noexcept;
3
Returns: size().
size_type max_size() const noexcept;
4
Returns: The largest possible number of char-like objects that can be stored in a basic_string.
5
Complexity: Constant time.
void resize(size_type n, charT c);
6
Throws: length_error if n > max_size().
7
Effects: Alters the length of the string designated by *this as follows:
(7.1)
—
If n
<= size(), the function replaces the string designated by *this with a string of length n
whose elements are a copy of the initial elements of the original string designated by *this.
(7.2)
—
If n
> size(), the function replaces the string designated by *this with a string of length n
whose first size() elements are a copy of the original string designated by *this, and whose
remaining elements are all initialized to c.
void resize(size_type n);
8
Effects: As if by resize(n, charT()).
size_type capacity() const noexcept;
9
Returns: The size of the allocated storage in the string.
void reserve(size_type res_arg=0);
10
The member function reserve() is a directive that informs a basic_string object of a planned change
in size, so that it can manage the storage allocation accordingly.
11
Effects: After reserve(), capacity() is greater or equal to the argument of reserve. [ Note: Calling
reserve() with a res_arg argument less than capacity() is in effect a non-binding shrink request.
A call with res_arg <= size() is in effect a non-binding shrink-to-fit request.
— end note ]
12
Throws: length_error if res_arg > max_size().231
231) reserve() uses allocator_traits<Allocator>::allocate() which may throw an appropriate exception.
§ 24.3.2.4
677
void shrink_to_fit();
13
Effects: shrink_to_fit is a non-binding request to reduce capacity() to size(). [ Note: The request
is non-binding to allow latitude for implementation-specific optimizations.
— end note ] It does not
increase capacity(), but may reduce capacity() by causing reallocation.
14
Complexity: Linear in the size of the sequence.
15
Remarks: Reallocation invalidates all the references, pointers, and iterators referring to the elements in
the sequence as well as the past-the-end iterator. If no reallocation happens, they remain valid.
void clear() noexcept;
16
Effects: Behaves as if the function calls:
erase(begin(), end());
[[nodiscard]] bool empty() const noexcept;
17
Returns: size() == 0.
24.3.2.5
basic_string element access
[string.access]
const_reference operator[](size_type pos) const;
reference
operator[](size_type pos);
1
Requires: pos <= size().
2
Returns: *(begin() + pos) if pos < size(). Otherwise, returns a reference to an object of type
charT with value charT(), where modifying the object to any value other than charT() leads to
undefined behavior.
3
Throws: Nothing.
4
Complexity: Constant time.
const_reference at(size_type pos) const;
reference
at(size_type pos);
5
Throws: out_of_range if pos >= size().
6
Returns: operator[](pos).
const charT& front() const;
charT& front();
7
Requires: !empty().
8
Effects: Equivalent to: return operator[](0);
const charT& back() const;
charT& back();
9
Requires: !empty().
10
Effects: Equivalent to: return operator[](size() - 1);
24.3.2.6
basic_string modifiers
[string.modifiers]
24.3.2.6.1
basic_string::operator+=
[string.op+=]
basic_string& operator+=(const basic_string& str);
1
Effects: Calls append(str).
2
Returns: *this.
basic_string& operator+=(basic_string_view<charT, traits> sv);
3
Effects: Calls append(sv).
4
Returns: *this.
basic_string& operator+=(const charT* s);
5
Effects: Calls append(s).
6
Returns: *this.
§ 24.3.2.6.1
678
basic_string& operator+=(charT c);
7
Effects: Calls push_back(c);
8
Returns: *this.
basic_string& operator+=(initializer_list<charT> il);
9
Effects: Calls append(il).
10
Returns: *this.
24.3.2.6.2
basic_string::append
[string.append]
basic_string& append(const basic_string& str);
1
Effects: Calls append(str.data(), str.size()).
2
Returns: *this.
basic_string& append(const basic_string& str, size_type pos, size_type n = npos);
3
Throws: out_of_range if pos > str.size().
4
Effects: Determines the effective length rlen of the string to append as the smaller of n and str.size()
- pos and calls append(str.data() + pos, rlen).
5
Returns: *this.
basic_string& append(basic_string_view<charT, traits> sv);
6
Effects: Equivalent to: return append(sv.data(), sv.size());
template<class T>
basic_string& append(const T& t, size_type pos, size_type n = npos);
7
Throws: out_of_range if pos > sv.size().
8
Effects: Creates a variable, sv, as if by basic_string_view<charT, traits> sv = t. Determines
the effective length rlen of the string to append as the smaller of n and sv.size() - pos and calls
append(sv.data() + pos, rlen).
9
Remarks: This function shall not participate in overload resolution unless is_convertible_v<const T&,
basic_string_view<charT, traits>> is true and is_convertible_v<const T&, const charT*>
is false.
10
Returns: *this.
basic_string& append(const charT* s, size_type n);
11
Requires: s points to an array of at least n elements of charT.
12
Throws: length_error if size() + n > max_size().
13
Effects: The function replaces the string controlled by *this with a string of length size() + n
whose first size() elements are a copy of the original string controlled by *this and whose remaining
elements are a copy of the initial n elements of s.
14
Returns: *this.
basic_string& append(const charT* s);
15
Requires: s points to an array of at least traits::length(s) + 1 elements of charT.
16
Effects: Calls append(s, traits::length(s)).
17
Returns: *this.
basic_string& append(size_type n, charT c);
18
Effects: Equivalent to: return append(basic_string(n, c));
template<class InputIterator>
basic_string& append(InputIterator first, InputIterator last);
19
Requires: [first, last) is a valid range.
20
Effects: Equivalent to: return append(basic_string(first, last, get_allocator()));
§ 24.3.2.6.2
679
basic_string& append(initializer_list<charT> il);
21
Effects: Calls append(il.begin(), il.size()).
22
Returns: *this.
void push_back(charT c);
23
Effects: Equivalent to append(static_cast<size_type>(1), c).
24.3.2.6.3
basic_string::assign
[string.assign]
basic_string& assign(const basic_string& str);
1
Effects: Equivalent to: return *this = str;
basic_string& assign(basic_string&& str)
noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
allocator_traits<Allocator>::is_always_equal::value);
2
Effects: Equivalent to: return *this = std::move(str);
basic_string& assign(const basic_string& str, size_type pos, size_type n = npos);
3
Throws: out_of_range if pos > str.size().
4
Effects: Determines the effective length rlen of the string to assign as the smaller of n and str.size()
- pos and calls assign(str.data() + pos, rlen).
5
Returns: *this.
basic_string& assign(basic_string_view<charT, traits> sv);
6
Effects: Equivalent to: return assign(sv.data(), sv.size());
template<class T>
basic_string& assign(const T& t, size_type pos, size_type n = npos);
7
Throws: out_of_range if pos > sv.size().
8
Effects: Creates a variable, sv, as if by basic_string_view<charT, traits> sv = t. Determines
the effective length rlen of the string to assign as the smaller of n and sv.size() - pos and calls
assign(sv.data() + pos, rlen).
9
Remarks: This function shall not participate in overload resolution unless is_convertible_v<const T&,
basic_string_view<charT, traits>> is true and is_convertible_v<const T&, const charT*>
is false.
10
Returns: *this.
basic_string& assign(const charT* s, size_type n);
11
Requires: s points to an array of at least n elements of charT.
12
Throws: length_error if n > max_size().
13
Effects: Replaces the string controlled by *this with a string of length n whose elements are a copy of
those pointed to by s.
14
Returns: *this.
basic_string& assign(const charT* s);
15
Requires: s points to an array of at least traits::length(s) + 1 elements of charT.
16
Effects: Calls assign(s, traits::length(s)).
17
Returns: *this.
basic_string& assign(initializer_list<charT> il);
18
Effects: Calls assign(il.begin(), il.size()).
19
Returns: *this.
basic_string& assign(size_type n, charT c);
20
Effects: Equivalent to: return assign(basic_string(n, c));
§ 24.3.2.6.3
680
template<class InputIterator>
basic_string& assign(InputIterator first, InputIterator last);
21
Effects: Equivalent to: return assign(basic_string(first, last, get_allocator()));
24.3.2.6.4
basic_string::insert
[string.insert]
basic_string& insert(size_type pos, const basic_string& str);
1
Effects: Equivalent to: return insert(pos, str.data(), str.size());
basic_string& insert(size_type pos1, const basic_string& str, size_type pos2, size_type n = npos);
2
Throws: out_of_range if pos1 > size() or pos2 > str.size().
3
Effects: Determines the effective length rlen of the string to insert as the smaller of n and str.size()
- pos2 and calls insert(pos1, str.data() + pos2, rlen).
4
Returns: *this.
basic_string& insert(size_type pos, basic_string_view<charT, traits> sv);
5
Effects: Equivalent to: return insert(pos, sv.data(), sv.size());
template<class T>
basic_string& insert(size_type pos1, const T& t, size_type pos2, size_type n = npos);
6
Throws: out_of_range if pos1 > size() or pos2 > sv.size().
7
Effects: Creates a variable, sv, as if by basic_string_view<charT, traits> sv = t. Determines
the effective length rlen of the string to assign as the smaller of n and sv.size() - pos2 and calls
insert(pos1, sv.data() + pos2, rlen).
8
Remarks: This function shall not participate in overload resolution unless is_convertible_v<const T&,
basic_string_view<charT, traits>> is true and is_convertible_v<const T&, const charT*>
is false.
9
Returns: *this.
basic_string& insert(size_type pos, const charT* s, size_type n);
10
Requires: s points to an array of at least n elements of charT.
11
Throws: out_of_range if pos > size() or length_error if size() + n > max_size().
12
Effects: Replaces the string controlled by *this with a string of length size() + n whose first pos
elements are a copy of the initial elements of the original string controlled by *this and whose next n
elements are a copy of the elements in s and whose remaining elements are a copy of the remaining
elements of the original string controlled by *this.
13
Returns: *this.
basic_string& insert(size_type pos, const charT* s);
14
Requires: s points to an array of at least traits::length(s) + 1 elements of charT.
15
Effects: Equivalent to: return insert(pos, s, traits::length(s));
basic_string& insert(size_type pos, size_type n, charT c);
16
Effects: Equivalent to: return insert(pos, basic_string(n, c));
iterator insert(const_iterator p, charT c);
17
Requires: p is a valid iterator on *this.
18
Effects: Inserts a copy of c before the character referred to by p.
19
Returns: An iterator which refers to the copy of the inserted character.
iterator insert(const_iterator p, size_type n, charT c);
20
Requires: p is a valid iterator on *this.
21
Effects: Inserts n copies of c before the character referred to by p.
22
Returns: An iterator which refers to the copy of the first inserted character, or p if n == 0.
§ 24.3.2.6.4
681