[strings] (original) (raw)
27 Strings library [strings]
27.1 General [strings.general]
27.2 Character traits [char.traits]
27.2.1 General [char.traits.general]
27.2.2 Character traits requirements [char.traits.require]
27.2.3 Traits typedefs [char.traits.typedefs]
27.2.4 char_traits specializations [char.traits.specializations]
27.2.4.1 General [char.traits.specializations.general]
27.2.4.2 struct char_traits [char.traits.specializations.char]
27.2.4.3 struct char_traits<char8_t> [char.traits.specializations.char8.t]
27.2.4.4 struct char_traits<char16_t> [char.traits.specializations.char16.t]
27.2.4.5 struct char_traits<char32_t> [char.traits.specializations.char32.t]
27.2.4.6 struct char_traits<wchar_t> [char.traits.specializations.wchar.t]
27.3 String view classes [string.view]
27.3.1 General [string.view.general]
27.3.2 Header <string_view> synopsis [string.view.synop]
27.3.3 Class template basic_string_view [string.view.template]
27.3.3.1 General [string.view.template.general]
27.3.3.2 Construction and assignment [string.view.cons]
27.3.3.3 Deduction guides [string.view.deduct]
27.3.3.4 Iterator support [string.view.iterators]
27.3.3.5 Capacity [string.view.capacity]
27.3.3.6 Element access [string.view.access]
27.3.3.7 Modifiers [string.view.modifiers]
27.3.3.8 String operations [string.view.ops]
27.3.3.9 Searching [string.view.find]
27.3.4 Non-member comparison functions [string.view.comparison]
27.3.5 Inserters and extractors [string.view.io]
27.3.6 Hash support [string.view.hash]
27.3.7 Suffix for basic_string_view literals [string.view.literals]
27.4 String classes [string.classes]
27.4.1 General [string.classes.general]
27.4.2 Header synopsis [string.syn]
27.4.3 Class template basic_string [basic.string]
27.4.3.1 General [basic.string.general]
27.4.3.2 General requirements [string.require]
27.4.3.3 Constructors and assignment operators [string.cons]
27.4.3.4 Iterator support [string.iterators]
27.4.3.5 Capacity [string.capacity]
27.4.3.6 Element access [string.access]
27.4.3.7 Modifiers [string.modifiers]
27.4.3.7.1 basic_string::operator+= [string.op.append]
27.4.3.7.2 basic_string::append [string.append]
27.4.3.7.3 basic_string::assign [string.assign]
27.4.3.7.4 basic_string::insert [string.insert]
27.4.3.7.5 basic_string::erase [string.erase]
27.4.3.7.6 basic_string::replace [string.replace]
27.4.3.7.7 basic_string::copy [string.copy]
27.4.3.7.8 basic_string::swap [string.swap]
27.4.3.8 String operations [string.ops]
27.4.3.8.1 Accessors [string.accessors]
27.4.3.8.2 Searching [string.find]
27.4.3.8.3 basic_string::substr [string.substr]
27.4.3.8.4 basic_string::compare [string.compare]
27.4.3.8.5 basic_string::starts_with [string.starts.with]
27.4.3.8.6 basic_string::ends_with [string.ends.with]
27.4.3.8.7 basic_string::contains [string.contains]
27.4.4 Non-member functions [string.nonmembers]
27.4.4.1 operator+ [string.op.plus]
27.4.4.2 Non-member comparison operator functions [string.cmp]
27.4.4.3 swap [string.special]
27.4.4.4 Inserters and extractors [string.io]
27.4.4.5 Erasure [string.erasure]
27.4.5 Numeric conversions [string.conversions]
27.4.6 Hash support [basic.string.hash]
27.4.7 Suffix for basic_string literals [basic.string.literals]
27.5 Null-terminated sequence utilities [c.strings]
27.5.1 Header synopsis [cstring.syn]
27.1 General [strings.general]
This Clause describes components for manipulating sequences of any non-array trivially copyable standard-layout ([basic.types.general]) type Twhere is_trivially_default_constructible_v<T> is true.
Such types are called char-like types, and objects of char-like types are called char-like objects or simply characters.
The following subclauses describe a character traits class, string classes, and null-terminated sequence utilities, as summarized in Table 86.
Table 86 — Strings library summary [tab:strings.summary]
| 🔗 | Subclause | Header |
|---|---|---|
| 🔗[char.traits] | Character traits | <string> |
| 🔗[string.view] | String view classes | <string_view> |
| 🔗[string.classes] | String classes | <string> |
| 🔗[c.strings] | Null-terminated sequence utilities | <cstring> |
27.2 Character traits [char.traits]
27.2.1 General [char.traits.general]
Subclause [char.traits] defines requirements on classes representingcharacter traits, and defines a class templatechar_traits<charT>, along with five specializations,char_traits<char>,char_traits<char8_t>,char_traits<char16_t>,char_traits<char32_t>, andchar_traits<wchar_t>, that meet those requirements.
Most classes specified in [string.classes], [string.view], and [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 typedef-names and functions in the template parameter traits used by each such template.
Subclause [char.traits] defines the semantics of these members.
To specialize those templates to generate a string, string view, or iostream class to handle a particular character container type ([defns.character.container])C, that and its related character traits classXare passed as a pair of parameters to the string, string view, or iostream template as parameterscharTandtraits.
IfX::char_typeis not the same type asC, the program is ill-formed.
27.2.2 Character traits requirements [char.traits.require]
In Table 87,Xdenotes a traits class defining types and functions for the character container typeC;candddenote values of typeC;pandqdenote values of typeconst C*;sdenotes a value of typeC*;n,iandjdenote values of typesize_t;eandfdenote values of typeX::int_type;posdenotes a value of typeX::pos_type; andrdenotes an lvalue of typeC.
No expression which is part of the character traits requirements specified in [char.traits.require]shall exit via an exception.
Table 87 — Character traits requirements [tab:char.traits.req]
| 🔗Expression | Return type | Assertion/note | Complexity |
|---|---|---|---|
| 🔗 | pre-/post-condition | ||
| 🔗X::char_type | C | ||
| 🔗X::int_type | (described in [char.traits.typedefs]) | ||
| 🔗X::off_type | (described in [iostreams.limits.pos] and [iostream.forward]) | ||
| 🔗X::pos_type | (described in [iostreams.limits.pos] and [iostream.forward]) | ||
| 🔗X::state_type | (described in [char.traits.typedefs]) | ||
| 🔗X::eq(c,d) | bool | Returns: whether c is to be treated as equal to d. | constant |
| 🔗X::lt(c,d) | bool | Returns: whether c is to be treated as less than d. | constant |
| 🔗X::compare(p,q,n) | int | Returns: 0 if for each i in [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. | linear |
| 🔗X::length(p) | size_t | Returns: the smallest i such that X::eq(p[i],charT()) is true. | linear |
| 🔗X::find(p,n,c) | const X::char_type* | Returns: the smallest q in [p, p+n) such thatX::eq(*q,c) is true, nullptr otherwise. | linear |
| 🔗X::move(s,p,n) | X::char_type* | for each i in [0, n), performs X::assign(s[i],p[i]). Copies correctly even where the ranges [p, p+n) and [s, s+n) overlap. Returns: s. | linear |
| 🔗X::copy(s,p,n) | X::char_type* | Preconditions: The ranges [p, p+n) and [s, s+n) do not overlap. Returns: s. for each i in [0, n), performs X::assign(s[i],p[i]). | linear |
| 🔗X::assign(r,d) | (not used) | assigns r=d. | constant |
| 🔗X::assign(s,n,c) | X::char_type* | for each i in [0, n), performsX::assign(s[i],c). Returns: s. | linear |
| 🔗X::not_eof(e) | int_type | Returns: e if X::eq_int_type(e,X::eof()) is false, otherwise a value f such thatX::eq_int_type(f,X::eof()) is false. | constant |
| 🔗X::to_char_type(e) | X::char_type | Returns: if for some c, X::eq_int_type(e,X::to_int_type(c))is true, c; else some unspecified value. | constant |
| 🔗X::to_int_type(c) | X::int_type | Returns: some value e, constrained by the definitions ofto_char_type and eq_int_type. | constant |
| 🔗X::eq_int_type(e,f) | bool | Returns: for all c and d, X::eq(c,d) is equal toX::eq_int_type(X::to_int_type(c), X::to_int_type(d)); otherwise, yields trueif 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. | constant |
| 🔗X::eof() | X::int_type | Returns: a value e such that X::eq_int_type(e,X::to_int_type(c))is false for all values c. | constant |
The class templatetemplate<class charT> struct char_traits;is provided in the header as a basis for explicit specializations.
27.2.3 Traits typedefs [char.traits.typedefs]
using int_type = _see below_;
Preconditions: int_typeshall be able to represent all of the valid characters converted from the correspondingchar_typevalues, as well as an end-of-file value,eof().210
using state_type = _see below_;
27.2.4 char_traits specializations [char.traits.specializations]
27.2.4.1 General [char.traits.specializations.general]
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>;}
The header defines five specializations of the class templatechar_traits:char_traits<char>,char_traits<char8_t>,char_traits<char16_t>,char_traits<char32_t>, andchar_traits<wchar_t>.
27.2.4.2 struct char_traits [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;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;};}
The type mbstate_t is defined in and can represent any of the conversion states that can occur in animplementation-defined set of supported multibyte character encoding rules.
The two-argument member assign is defined identically to the built-in operator =.
The two-argument members eqand lt are defined identically to the built-in operators== and < for type unsigned char.
The membereof()returnsEOF.
27.2.4.3 struct char_traits<char8_t> [char.traits.specializations.char8.t]
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;};}
The two-argument members assign, eq, and ltare defined identically to the built-in operators =, ==, and < respectively.
The member eof() returns animplementation-defined constant that cannot appear as a valid UTF-8 code unit.
27.2.4.4 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;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;};}
The two-argument members assign,eq, and lt are defined identically to the built-in operators =, ==, and<, respectively.
The member eof() returns animplementation-defined constant that cannot appear as a valid UTF-16 code unit.
27.2.4.5 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;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;};}
The two-argument members assign,eq, and lt are defined identically to the built-in operators =, ==, and<, respectively.
The member eof() returns animplementation-defined constant that cannot appear as a Unicode code point.
27.2.4.6 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;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;};}
The two-argument membersassign,eq, andltare defined identically to the built-in operators=,==, and<, respectively.
The membereof()returnsWEOF.
27.3 String view classes [string.view]
27.3.1 General [string.view.general]
The class template basic_string_view describes an object that can refer to a constant contiguous sequence of char-like ([strings.general]) objects with the first element of the sequence at position zero.
In the rest of [string.view], the type of the char-like objects held in a basic_string_view object is designated by charT.
[Note 1:
The library provides implicit conversions from const charT* and std::basic_string<charT, ...> to std::basic_string_view<charT, ...> so that user code can accept just 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 std::basic_string_view<charT> in order to interoperate with these functions.
— _end note_]
27.3.2 Header <string_view> synopsis [string.view.synop]
27.3.3 Class template basic_string_view [string.view.template]
27.3.3.1 General [string.view.template.general]
namespace std { template<class charT, class traits = char_traits<charT>> class basic_string_view { public: 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 = implementation-defined; using iterator = const_iterator;211 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);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);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;constexpr size_type size() const noexcept;constexpr size_type length() const noexcept;constexpr size_type max_size() const noexcept;constexpr bool empty() const noexcept;constexpr const_reference operator[](size_type pos) const;constexpr const_reference at(size_type pos) const; constexpr const_reference front() const;constexpr const_reference back() const;constexpr const_pointer data() const noexcept;constexpr void remove_prefix(size_type n);constexpr void remove_suffix(size_type n);constexpr void swap(basic_string_view& s) noexcept;constexpr size_type copy(charT* s, size_type n, size_type pos = 0) const; constexpr basic_string_view substr(size_type pos = 0, size_type n = npos) const; constexpr basic_string_view subview(size_type pos = 0, size_type n = npos) const; constexpr int compare(basic_string_view s) const noexcept;constexpr int compare(size_type pos1, size_type n1, basic_string_view s) const; constexpr int compare(size_type pos1, size_type n1, basic_string_view s, size_type pos2, size_type n2) const; constexpr int compare(const charT* s) const;constexpr int compare(size_type pos1, size_type n1,const charT* s) const; constexpr int compare(size_type pos1, size_type n1, const charT* s, size_type n2) const; 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;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_pointer data_; size_type size_; };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>>;}
In every specialization basic_string_view<charT, traits>, the type traits shall meet the character traits requirements ([char.traits]).
[Note 1:
The program is ill-formed if traits::char_type is not the same type as charT.
— _end note_]
For a basic_string_view str, any operation that invalidates a pointer in the range[str.data(), str.data() + str.size()) invalidates pointers, iterators, and references to elements of str.
The complexity of basic_string_view member functions is unless otherwise specified.
27.3.3.2 Construction and assignment [string.view.cons]
constexpr basic_string_view() noexcept;
Postconditions: size_ == 0 and data_ == nullptr.
constexpr basic_string_view(const charT* str);
Preconditions: [str, str + traits::length(str)) is a valid range.
Effects: Constructs a basic_string_view, initializing data_ with strand initializing size_ with traits::length(str).
constexpr basic_string_view(const charT* str, size_type len);
Preconditions: [str, str + len) is a valid range.
Effects: Constructs a basic_string_view, initializing data_ with strand initializing size_ with len.
template<class It, class End> constexpr basic_string_view(It begin, End end);
Constraints:
Preconditions:
- [begin, end) is a valid range.
Effects: Initializes data_ with to_address(begin) and initializes size_ with end - begin.
Throws: When and what end - begin throws.
template<class R> constexpr explicit basic_string_view(R&& r);
Let d be an lvalue of type remove_cvref_t<R>.
Constraints:
- remove_cvref_t<R> is not the same type as basic_string_view,
- R modelsranges::contiguous_range and ranges::sized_range,
- is_same_v<ranges::range_value_t<R>, charT> is true,
- is_convertible_v<R, const charT*> is false, and
- d.operator ::std::basic_string_view<charT, traits>()is not a valid expression.
Effects: Initializes data_ with ranges::data(r) and_size__ with ranges::size(r).
Throws: Any exception thrown by ranges::data(r) and ranges::size(r).
27.3.3.3 Deduction guides [string.view.deduct]
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>>;
27.3.3.4 Iterator support [string.view.iterators]
using const_iterator = _implementation-defined_;
constexpr const_iterator begin() const noexcept;constexpr const_iterator cbegin() const noexcept;
Returns: An iterator such that
- if !empty(), addressof(*begin()) == data_,
- otherwise, an unspecified value such that [begin(), end()) is a valid range.
constexpr const_iterator end() const noexcept;constexpr const_iterator cend() const noexcept;
Returns: begin() + size().
constexpr const_reverse_iterator rbegin() const noexcept;constexpr const_reverse_iterator crbegin() const noexcept;
Returns: const_reverse_iterator(end()).
constexpr const_reverse_iterator rend() const noexcept;constexpr const_reverse_iterator crend() const noexcept;
Returns: const_reverse_iterator(begin()).
27.3.3.5 Capacity [string.view.capacity]
constexpr size_type size() const noexcept;constexpr size_type length() const noexcept;
constexpr size_type max_size() const noexcept;
Returns: The largest possible number of char-like objects that can be referred to by a basic_string_view.
constexpr bool empty() const noexcept;
27.3.3.6 Element access [string.view.access]
constexpr const_reference operator[](size_type pos) const;
Hardened preconditions: pos < size() is true.
[Note 1:
This precondition is stronger than the one on basic_string::operator[].
— _end note_]
constexpr const_reference at(size_type pos) const;
Throws: out_of_range if pos >= size().
constexpr const_reference front() const;
Hardened preconditions: empty() is false.
constexpr const_reference back() const;
Hardened preconditions: empty() is false.
Returns: _data__[size() - 1].
constexpr const_pointer data() const noexcept;
[Note 2:
Unlike basic_string::data() and string-literals,data() can return a pointer to a buffer that is not null-terminated.
Therefore it is typically a mistake to pass data() to a function that takes just a const charT* and expects a null-terminated string.
— _end note_]
27.3.3.7 Modifiers [string.view.modifiers]
constexpr void remove_prefix(size_type n);
Hardened preconditions: n <= size() is true.
Effects: Equivalent to: data_ += n; size_ -= n;
constexpr void remove_suffix(size_type n);
Hardened preconditions: n <= size() is true.
Effects: Equivalent to: size_ -= n;
constexpr void swap(basic_string_view& s) noexcept;
Effects: Exchanges the values of *this and s.
27.3.3.8 String operations [string.view.ops]
constexpr size_type copy(charT* s, size_type n, size_type pos = 0) const;
Let rlen be the smaller of n and size() - pos.
Preconditions: [s, s + rlen) is a valid range.
Effects: Equivalent to traits::copy(s, data() + pos, rlen).
Throws: out_of_range if pos > size().
constexpr basic_string_view substr(size_type pos = 0, size_type n = npos) const;constexpr basic_string_view subview(size_type pos = 0, size_type n = npos) const;
Let rlen be the smaller of n and size() - pos.
Effects: Determines rlen, the effective length of the string to reference.
Returns: basic_string_view(data() + pos, rlen).
Throws: out_of_range if pos > size().
constexpr int compare(basic_string_view str) const noexcept;
Let rlen be the smaller of size() and str.size().
Effects: Determines rlen, the effective length of the strings to compare.
The function then compares the two strings by calling traits::compare(data(), str.data(), rlen).
Returns: The nonzero result if the result of the comparison is nonzero.
Otherwise, returns a value as indicated in Table 88.
constexpr int compare(size_type pos1, size_type n1, basic_string_view str) const;
Effects: Equivalent to: return substr(pos1, n1).compare(str);
constexpr int compare(size_type pos1, size_type n1, basic_string_view str, size_type pos2, size_type n2) const;
Effects: Equivalent to: return substr(pos1, n1).compare(str.substr(pos2, n2));
constexpr int compare(const charT* s) const;
Effects: Equivalent to: return compare(basic_string_view(s));
constexpr int compare(size_type pos1, size_type n1, const charT* s) const;
Effects: Equivalent to: return substr(pos1, n1).compare(basic_string_view(s));
constexpr int compare(size_type pos1, size_type n1, const charT* s, size_type n2) const;
Effects: Equivalent to: return substr(pos1, n1).compare(basic_string_view(s, n2));
constexpr bool starts_with(basic_string_view x) const noexcept;
Let rlen be the smaller of size() and x.size().
Effects: Equivalent to: return basic_string_view(data(), rlen) == x;
constexpr bool starts_with(charT x) const noexcept;
Effects: Equivalent to: return !empty() && traits::eq(front(), x);
constexpr bool starts_with(const charT* x) const;
Effects: Equivalent to: return starts_with(basic_string_view(x));
constexpr bool ends_with(basic_string_view x) const noexcept;
Let rlen be the smaller of size() and x.size().
Effects: Equivalent to:return basic_string_view(data() + (size() - rlen), rlen) == x;
constexpr bool ends_with(charT x) const noexcept;
Effects: Equivalent to: return !empty() && traits::eq(back(), x);
constexpr bool ends_with(const charT* x) const;
Effects: Equivalent to: return ends_with(basic_string_view(x));
constexpr bool contains(basic_string_view x) const noexcept;constexpr bool contains(charT x) const noexcept;constexpr bool contains(const charT* x) const;
Effects: Equivalent to: return find(x) != npos;
27.3.3.9 Searching [string.view.find]
Member functions in this subclause have complexity at worst, although implementations should do better.
Let F be one offind,rfind,find_first_of,find_last_of,find_first_not_of, andfind_last_not_of.
- Each member function of the formconstexpr return-type F(const charT* s, size_type pos) const;has effects equivalent to: return F(basic_string_view(s), pos);
- Each member function of the formconstexpr return-type F(const charT* s, size_type pos, size_type n) const;has effects equivalent to: return F(basic_string_view(s, n), pos);
- Each member function of the formconstexpr return-type F(charT c, size_type pos) const noexcept;has effects equivalent to: return F(basic_string_view(addressof(c), 1), pos);
constexpr size_type find(basic_string_view str, size_type pos = 0) const noexcept;
Let xpos be the lowest position, if possible, such that the following conditions hold:
- pos <= xpos
- xpos + str.size() <= size()
- traits::eq(_data__[xpos + I], str[I]) for all elements I of the string referenced by str.
Effects: Determines xpos.
Returns: xpos if the function can determine such a value for xpos.
Otherwise, returns npos.
constexpr size_type rfind(basic_string_view str, size_type pos = npos) const noexcept;
Let xpos be the highest position, if possible, such that the following conditions hold:
- xpos <= pos
- xpos + str.size() <= size()
- traits::eq(_data__[xpos + I], str[I]) for all elements I of the string referenced by str.
Effects: Determines xpos.
Returns: xpos if the function can determine such a value for xpos.
Otherwise, returns npos.
constexpr size_type find_first_of(basic_string_view str, size_type pos = 0) const noexcept;
Let xpos be the lowest position, if possible, such that the following conditions hold:
- pos <= xpos
- xpos < size()
- traits::eq(_data__[xpos], str[I]) for some element I of the string referenced by str.
Effects: Determines xpos.
Returns: xpos if the function can determine such a value for xpos.
Otherwise, returns npos.
constexpr size_type find_last_of(basic_string_view str, size_type pos = npos) const noexcept;
Let xpos be the highest position, if possible, such that the following conditions hold:
- xpos <= pos
- xpos < size()
- traits::eq(_data__[xpos], str[I]) for some element I of the string referenced by str.
Effects: Determines xpos.
Returns: xpos if the function can determine such a value for xpos.
Otherwise, returns npos.
constexpr size_type find_first_not_of(basic_string_view str, size_type pos = 0) const noexcept;
Let xpos be the lowest position, if possible, such that the following conditions hold:
- pos <= xpos
- xpos < size()
- traits::eq(_data__[xpos], str[I]) for no element I of the string referenced by str.
Effects: Determines xpos.
Returns: xpos if the function can determine such a value for xpos.
Otherwise, returns npos.
constexpr size_type find_last_not_of(basic_string_view str, size_type pos = npos) const noexcept;
Let xpos be the highest position, if possible, such that the following conditions hold:
- xpos <= pos
- xpos < size()
- traits::eq(_data__[xpos], str[I]) for no element I of the string referenced by str.
Effects: Determines xpos.
Returns: xpos if the function can determine such a value for xpos.
Otherwise, returns npos.
27.3.4 Non-member comparison functions [string.view.comparison]
template<class charT, class traits> constexpr bool operator==(basic_string_view<charT, traits> lhs, type_identity_t<basic_string_view<charT, traits>> rhs) noexcept;
Returns: lhs.compare(rhs) == 0.
template<class charT, class traits> constexpr _see below_ operator<=>(basic_string_view<charT, traits> lhs, type_identity_t<basic_string_view<charT, traits>> rhs) noexcept;
Let R denote the type traits::comparison_category if that qualified-id is valid and denotes a type ([temp.deduct]), otherwise R is weak_ordering.
Returns: static_cast<R>(lhs.compare(rhs) <=> 0).
[Note 1:
The usage of type_identity_t as parameter ensures that an object of type basic_string_view<charT, traits>can always be compared with an object of a type T with an implicit conversion to basic_string_view<charT, traits>, and vice versa, as per [over.match.oper].
— _end note_]
27.3.5 Inserters and extractors [string.view.io]
template<class charT, class traits> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, basic_string_view<charT, traits> str);
Forms a character sequenceseq, initially consisting of the elements defined by the range [str.begin(), str.end()).
Then inserts seq as if by callingos.rdbuf()->sputn(seq, n), where n is the larger of os.width() and str.size(); then calls os.width(0).
27.3.6 Hash support [string.view.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>;
[Note 1:
The hash value of a string view object is equal to the hash value of the corresponding string object ([basic.string.hash]).
— _end note_]
27.3.7 Suffix for basic_string_view literals [string.view.literals]
constexpr string_view operator""sv(const char* str, size_t len) noexcept;
Returns: string_view{str, len}.
constexpr u8string_view operator""sv(const char8_t* str, size_t len) noexcept;
Returns: u8string_view{str, len}.
constexpr u16string_view operator""sv(const char16_t* str, size_t len) noexcept;
Returns: u16string_view{str, len}.
constexpr u32string_view operator""sv(const char32_t* str, size_t len) noexcept;
Returns: u32string_view{str, len}.
constexpr wstring_view operator""sv(const wchar_t* str, size_t len) noexcept;
Returns: wstring_view{str, len}.
27.4 String classes [string.classes]
27.4.1 General [string.classes.general]
The header <string> defines thebasic_string class template for manipulating varying-length sequences of char-like objects and fivetypedef-names, string,u8string,u16string,u32string, and wstring, that name the specializationsbasic_string<char>,basic_string<char8_t>,basic_string<char16_t>,basic_string<char32_t>, andbasic_string<wchar_t>, respectively.
27.4.2 Header synopsis [string.syn]
#include <compare> #include <initializer_list> namespace std { template<class charT> struct char_traits; 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>; template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>> class basic_string;template<class charT, class traits, class Allocator> constexpr 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> constexpr basic_string<charT, traits, Allocator> operator+(basic_string<charT, traits, Allocator>&& lhs,const basic_string<charT, traits, Allocator>& rhs);template<class charT, class traits, class Allocator> constexpr 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> constexpr 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> constexpr basic_string<charT, traits, Allocator> operator+(const charT* lhs,const basic_string<charT, traits, Allocator>& rhs);template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(const charT* lhs, basic_string<charT, traits, Allocator>&& rhs);template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(charT lhs,const basic_string<charT, traits, Allocator>& rhs);template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(charT lhs, basic_string<charT, traits, Allocator>&& rhs);template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(const basic_string<charT, traits, Allocator>& lhs,const charT* rhs);template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(basic_string<charT, traits, Allocator>&& lhs,const charT* rhs);template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(const basic_string<charT, traits, Allocator>& lhs, charT rhs);template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(basic_string<charT, traits, Allocator>&& lhs, charT rhs);template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(const basic_string<charT, traits, Allocator>& lhs, type_identity_t<basic_string_view<charT, traits>> rhs);template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(basic_string<charT, traits, Allocator>&& lhs, type_identity_t<basic_string_view<charT, traits>> rhs);template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(type_identity_t<basic_string_view<charT, traits>> lhs,const basic_string<charT, traits, Allocator>& rhs);template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(type_identity_t<basic_string_view<charT, traits>> lhs, basic_string<charT, traits, Allocator>&& rhs);template<class charT, class traits, class Allocator> constexpr bool operator==(const basic_string<charT, traits, Allocator>& lhs,const basic_string<charT, traits, Allocator>& rhs) noexcept;template<class charT, class traits, class Allocator> constexpr bool operator==(const basic_string<charT, traits, Allocator>& lhs,const charT* rhs);template<class charT, class traits, class Allocator> constexpr see below operator<=>(const basic_string<charT, traits, Allocator>& lhs,const basic_string<charT, traits, Allocator>& rhs) noexcept;template<class charT, class traits, class Allocator> constexpr see below operator<=>(const basic_string<charT, traits, Allocator>& lhs,const charT* rhs);template<class charT, class traits, class Allocator> constexpr void swap(basic_string<charT, traits, Allocator>& lhs, basic_string<charT, traits, Allocator>& rhs) noexcept(noexcept(lhs.swap(rhs)));template<class charT, class traits, class Allocator> basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, basic_string<charT, traits, Allocator>& str);template<class charT, class traits, class Allocator> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os,const basic_string<charT, traits, Allocator>& str);template<class charT, class traits, class Allocator> basic_istream<charT, traits>& getline(basic_istream<charT, traits>& is, basic_string<charT, traits, Allocator>& str, charT delim);template<class charT, class traits, class Allocator> basic_istream<charT, traits>& getline(basic_istream<charT, traits>&& is, basic_string<charT, traits, Allocator>& str, charT delim);template<class charT, class traits, class Allocator> basic_istream<charT, traits>& getline(basic_istream<charT, traits>& is, basic_string<charT, traits, Allocator>& str);template<class charT, class traits, class Allocator> basic_istream<charT, traits>& getline(basic_istream<charT, traits>&& is, basic_string<charT, traits, Allocator>& str);template<class charT, class traits, class Allocator, class U = charT> constexpr typename basic_string<charT, traits, Allocator>::size_type erase(basic_string<charT, traits, Allocator>& c, const U& value);template<class charT, class traits, class Allocator, class Predicate> constexpr typename basic_string<charT, traits, Allocator>::size_type erase_if(basic_string<charT, traits, Allocator>& c, Predicate pred);using string = basic_string<char>;using u8string = basic_string<char8_t>;using u16string = basic_string<char16_t>;using u32string = basic_string<char32_t>;using wstring = basic_string<wchar_t>;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 u8string = basic_string<char8_t>;using u16string = basic_string<char16_t>;using u32string = basic_string<char32_t>;using wstring = basic_string<wchar_t>;} template<class T> struct hash;template<class A> struct hash<basic_string<char, char_traits<char>, A>>;template<class A> struct hash<basic_string<char8_t, char_traits<char8_t>, A>>;template<class A> struct hash<basic_string<char16_t, char_traits<char16_t>, A>>;template<class A> struct hash<basic_string<char32_t, char_traits<char32_t>, A>>;template<class A> struct hash<basic_string<wchar_t, char_traits<wchar_t>, A>>;inline namespace literals { inline namespace string_literals { constexpr string operator""s(const char* str, size_t len);constexpr u8string operator""s(const char8_t* str, size_t len);constexpr u16string operator""s(const char16_t* str, size_t len);constexpr u32string operator""s(const char32_t* str, size_t len);constexpr wstring operator""s(const wchar_t* str, size_t len);} } }
27.4.3 Class template basic_string [basic.string]
27.4.3.1 General [basic.string.general]
The class templatebasic_stringdescribes 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 [basic.string], the type of the char-like objects held in a basic_string object is designated by charT.
In all cases, [data(), data() + size()] is a valid range,data() + size() points at an object with value charT()(a “null terminator”), and size() <= capacity() is true.
namespace std { template<class charT, class traits = char_traits<charT>,class Allocator = allocator<charT>> class basic_string { public: using traits_type = traits;using value_type = charT;using allocator_type = Allocator;using size_type = allocator_traits<Allocator>::size_type;using difference_type = allocator_traits<Allocator>::difference_type;using pointer = allocator_traits<Allocator>::pointer;using const_pointer = allocator_traits<Allocator>::const_pointer;using reference = value_type&;using const_reference = const value_type&;using iterator = implementation-defined; using const_iterator = implementation-defined; using reverse_iterator = std::reverse_iterator<iterator>;using const_reverse_iterator = std::reverse_iterator<const_iterator>;static constexpr size_type npos = size_type(-1);constexpr basic_string() noexcept(noexcept(Allocator())) : basic_string(Allocator()) { } constexpr explicit basic_string(const Allocator& a) noexcept;constexpr basic_string(const basic_string& str);constexpr basic_string(basic_string&& str) noexcept;constexpr basic_string(const basic_string& str, size_type pos,const Allocator& a = Allocator());constexpr basic_string(const basic_string& str, size_type pos, size_type n,const Allocator& a = Allocator());constexpr basic_string(basic_string&& str, size_type pos,const Allocator& a = Allocator());constexpr basic_string(basic_string&& str, size_type pos, size_type n,const Allocator& a = Allocator());template<class T> constexpr basic_string(const T& t, size_type pos, size_type n,const Allocator& a = Allocator());template<class T> constexpr explicit basic_string(const T& t, const Allocator& a = Allocator());constexpr basic_string(const charT* s, size_type n, const Allocator& a = Allocator());constexpr basic_string(const charT* s, const Allocator& a = Allocator()); basic_string(nullptr_t) = delete;constexpr basic_string(size_type n, charT c, const Allocator& a = Allocator());template<class InputIterator> constexpr basic_string(InputIterator begin, InputIterator end,const Allocator& a = Allocator());template<container-compatible-range<charT> R> constexpr basic_string(from_range_t, R&& rg, const Allocator& a = Allocator());constexpr basic_string(initializer_list<charT>, const Allocator& = Allocator());constexpr basic_string(const basic_string&, const Allocator&);constexpr basic_string(basic_string&&, const Allocator&);constexpr ~basic_string();constexpr basic_string& operator=(const basic_string& str);constexpr basic_string& operator=(basic_string&& str) noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value || allocator_traits<Allocator>::is_always_equal::value);template<class T> constexpr basic_string& operator=(const T& t);constexpr basic_string& operator=(const charT* s); basic_string& operator=(nullptr_t) = delete;constexpr basic_string& operator=(charT c);constexpr basic_string& operator=(initializer_list<charT>);constexpr iterator begin() noexcept;constexpr const_iterator begin() const noexcept;constexpr iterator end() noexcept;constexpr const_iterator end() const noexcept;constexpr reverse_iterator rbegin() noexcept;constexpr const_reverse_iterator rbegin() const noexcept;constexpr reverse_iterator rend() noexcept;constexpr const_reverse_iterator rend() const noexcept;constexpr const_iterator cbegin() const noexcept;constexpr const_iterator cend() const noexcept;constexpr const_reverse_iterator crbegin() const noexcept;constexpr const_reverse_iterator crend() const noexcept;constexpr size_type size() const noexcept;constexpr size_type length() const noexcept;constexpr size_type max_size() const noexcept;constexpr void resize(size_type n, charT c);constexpr void resize(size_type n);template<class Operation> constexpr void resize_and_overwrite(size_type n, Operation op);constexpr size_type capacity() const noexcept;constexpr void reserve(size_type res_arg);constexpr void shrink_to_fit();constexpr void clear() noexcept;constexpr bool empty() const noexcept;constexpr const_reference operator[](size_type pos) const;constexpr reference operator[](size_type pos);constexpr const_reference at(size_type n) const;constexpr reference at(size_type n);constexpr const charT& front() const;constexpr charT& front();constexpr const charT& back() const;constexpr charT& back();constexpr basic_string& operator+=(const basic_string& str);template<class T> constexpr basic_string& operator+=(const T& t);constexpr basic_string& operator+=(const charT* s);constexpr basic_string& operator+=(charT c);constexpr basic_string& operator+=(initializer_list<charT>);constexpr basic_string& append(const basic_string& str);constexpr basic_string& append(const basic_string& str, size_type pos, size_type n = npos);template<class T> constexpr basic_string& append(const T& t);template<class T> constexpr basic_string& append(const T& t, size_type pos, size_type n = npos);constexpr basic_string& append(const charT* s, size_type n);constexpr basic_string& append(const charT* s);constexpr basic_string& append(size_type n, charT c);template<class InputIterator> constexpr basic_string& append(InputIterator first, InputIterator last);template<container-compatible-range<charT> R> constexpr basic_string& append_range(R&& rg);constexpr basic_string& append(initializer_list<charT>);constexpr void push_back(charT c);constexpr basic_string& assign(const basic_string& str);constexpr basic_string& assign(basic_string&& str) noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value || allocator_traits<Allocator>::is_always_equal::value);constexpr basic_string& assign(const basic_string& str, size_type pos, size_type n = npos);template<class T> constexpr basic_string& assign(const T& t);template<class T> constexpr basic_string& assign(const T& t, size_type pos, size_type n = npos);constexpr basic_string& assign(const charT* s, size_type n);constexpr basic_string& assign(const charT* s);constexpr basic_string& assign(size_type n, charT c);template<class InputIterator> constexpr basic_string& assign(InputIterator first, InputIterator last);template<container-compatible-range<charT> R> constexpr basic_string& assign_range(R&& rg);constexpr basic_string& assign(initializer_list<charT>);constexpr basic_string& insert(size_type pos, const basic_string& str);constexpr basic_string& insert(size_type pos1, const basic_string& str, size_type pos2, size_type n = npos);template<class T> constexpr basic_string& insert(size_type pos, const T& t);template<class T> constexpr basic_string& insert(size_type pos1, const T& t, size_type pos2, size_type n = npos);constexpr basic_string& insert(size_type pos, const charT* s, size_type n);constexpr basic_string& insert(size_type pos, const charT* s);constexpr basic_string& insert(size_type pos, size_type n, charT c);constexpr iterator insert(const_iterator p, charT c);constexpr iterator insert(const_iterator p, size_type n, charT c);template<class InputIterator> constexpr iterator insert(const_iterator p, InputIterator first, InputIterator last);template<container-compatible-range<charT> R> constexpr iterator insert_range(const_iterator p, R&& rg);constexpr iterator insert(const_iterator p, initializer_list<charT>);constexpr basic_string& erase(size_type pos = 0, size_type n = npos);constexpr iterator erase(const_iterator p);constexpr iterator erase(const_iterator first, const_iterator last);constexpr void pop_back();constexpr basic_string& replace(size_type pos1, size_type n1, const basic_string& str);constexpr basic_string& replace(size_type pos1, size_type n1, const basic_string& str, size_type pos2, size_type n2 = npos);template<class T> constexpr basic_string& replace(size_type pos1, size_type n1, const T& t);template<class T> constexpr basic_string& replace(size_type pos1, size_type n1, const T& t, size_type pos2, size_type n2 = npos);constexpr basic_string& replace(size_type pos, size_type n1, const charT* s, size_type n2);constexpr basic_string& replace(size_type pos, size_type n1, const charT* s);constexpr basic_string& replace(size_type pos, size_type n1, size_type n2, charT c);constexpr basic_string& replace(const_iterator i1, const_iterator i2,const basic_string& str);template<class T> constexpr basic_string& replace(const_iterator i1, const_iterator i2, const T& t);constexpr basic_string& replace(const_iterator i1, const_iterator i2, const charT* s, size_type n);constexpr basic_string& replace(const_iterator i1, const_iterator i2, const charT* s);constexpr basic_string& replace(const_iterator i1, const_iterator i2, size_type n, charT c);template<class InputIterator> constexpr basic_string& replace(const_iterator i1, const_iterator i2, InputIterator j1, InputIterator j2);template<container-compatible-range<charT> R> constexpr basic_string& replace_with_range(const_iterator i1, const_iterator i2, R&& rg);constexpr basic_string& replace(const_iterator, const_iterator, initializer_list<charT>);constexpr size_type copy(charT* s, size_type n, size_type pos = 0) const;constexpr void swap(basic_string& str) noexcept(allocator_traits<Allocator>::propagate_on_container_swap::value || allocator_traits<Allocator>::is_always_equal::value);constexpr const charT* c_str() const noexcept;constexpr const charT* data() const noexcept;constexpr charT* data() noexcept;constexpr operator basic_string_view<charT, traits>() const noexcept;constexpr allocator_type get_allocator() const noexcept;template<class T> constexpr size_type find(const T& t, size_type pos = 0) const noexcept(see below);constexpr size_type find(const basic_string& str, 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 find(charT c, size_type pos = 0) const noexcept;template<class T> constexpr size_type rfind(const T& t, size_type pos = npos) const noexcept(see below);constexpr size_type rfind(const basic_string& str, 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 rfind(charT c, size_type pos = npos) const noexcept;template<class T> constexpr size_type find_first_of(const T& t, size_type pos = 0) const noexcept(see below);constexpr size_type find_first_of(const basic_string& str, 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_first_of(charT c, size_type pos = 0) const noexcept;template<class T> constexpr size_type find_last_of(const T& t, size_type pos = npos) const noexcept(see below);constexpr size_type find_last_of(const basic_string& str, 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_last_of(charT c, size_type pos = npos) const noexcept;template<class T> constexpr size_type find_first_not_of(const T& t, size_type pos = 0) const noexcept(see below);constexpr size_type find_first_not_of(const basic_string& str, 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_first_not_of(charT c, size_type pos = 0) const noexcept;template<class T> constexpr size_type find_last_not_of(const T& t, size_type pos = npos) const noexcept(see below);constexpr size_type find_last_not_of(const basic_string& str, 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;constexpr size_type find_last_not_of(charT c, size_type pos = npos) const noexcept;constexpr basic_string substr(size_type pos = 0, size_type n = npos) const &;constexpr basic_string substr(size_type pos = 0, size_type n = npos) &&;constexpr basic_string_view<charT, traits> subview(size_type pos = 0, size_type n = npos) const;template<class T> constexpr int compare(const T& t) const noexcept(see below);template<class T> constexpr int compare(size_type pos1, size_type n1, const T& t) const;template<class T> constexpr int compare(size_type pos1, size_type n1, const T& t, size_type pos2, size_type n2 = npos) const;constexpr int compare(const basic_string& str) const noexcept;constexpr int compare(size_type pos1, size_type n1, const basic_string& str) const;constexpr int compare(size_type pos1, size_type n1, const basic_string& str, size_type pos2, size_type n2 = npos) const;constexpr int compare(const charT* s) const;constexpr int compare(size_type pos1, size_type n1, const charT* s) const;constexpr int compare(size_type pos1, size_type n1, const charT* s, size_type n2) const;constexpr bool starts_with(basic_string_view<charT, traits> 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<charT, traits> 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<charT, traits> x) const noexcept;constexpr bool contains(charT x) const noexcept;constexpr bool contains(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>;template<ranges::input_range R,class Allocator = allocator<ranges::range_value_t<R>>> basic_string(from_range_t, R&&, Allocator = Allocator()) -> basic_string<ranges::range_value_t<R>, char_traits<ranges::range_value_t<R>>, Allocator>;template<class charT,class traits,class Allocator = allocator<charT>> explicit basic_string(basic_string_view<charT, traits>, const Allocator& = Allocator()) -> basic_string<charT, traits, Allocator>;template<class charT,class traits,class Allocator = allocator<charT>> basic_string(basic_string_view<charT, traits>,typename see below::size_type, typename see below::size_type,const Allocator& = Allocator()) -> basic_string<charT, traits, Allocator>;}
A size_type parameter type in a basic_string deduction guide refers to the size_type member type of the type deduced by the deduction guide.
27.4.3.2 General requirements [string.require]
If any operation would cause size() to exceed max_size(), that operation throws an exception object of type length_error.
If any member function or operator of basic_string throws an exception, that function or operator has no other effect on the basic_string object.
Every object of typebasic_string<charT, traits, Allocator> uses an object of typeAllocator to allocate and free storage for the contained charTobjects as needed.
In every specialization basic_string<charT, traits, Allocator>, the type traits shall meet the character traits requirements ([char.traits]).
[Note 1:
Every specialization basic_string<charT, traits, Allocator> is an allocator-aware container ([container.alloc.reqmts]), but does not use the allocator's construct and destroymember functions ([container.requirements.pre]).
The program is ill-formed ifAllocator::value_type is not the same type as charT.
— _end note_]
[Note 2:
The program is ill-formed if traits::char_typeis not the same type as charT.
— _end note_]
References, pointers, and iterators referring to the elements of abasic_string sequence may be invalidated by the following uses of that basic_string object:
- Passing as an argument to any standard library function taking a reference to non-constbasic_string as an argument.212
- Calling non-const member functions, exceptoperator[],at,data,front,back,begin,rbegin,end, andrend.
27.4.3.3 Constructors and assignment operators [string.cons]
constexpr explicit basic_string(const Allocator& a) noexcept;
Postconditions: size() is equal to 0.
constexpr basic_string(const basic_string& str);constexpr basic_string(basic_string&& str) noexcept;
Effects: Constructs an object whose value is that of str prior to this call.
Remarks: In the second form, str is left in a valid but unspecified state.
constexpr basic_string(const basic_string& str, size_type pos,const Allocator& a = Allocator());constexpr basic_string(const basic_string& str, size_type pos, size_type n,const Allocator& a = Allocator());constexpr basic_string(basic_string&& str, size_type pos,const Allocator& a = Allocator());constexpr basic_string(basic_string&& str, size_type pos, size_type n,const Allocator& a = Allocator());
Let
- s be the value of str prior to this call and
- rlen be pos + min(n, s.size() - pos)for the overloads with parameter n, ands.size() otherwise.
Effects: Constructs an object whose initial value is the range [s.data() + pos, s.data() + rlen).
Throws: out_of_range if pos > s.size().
Remarks: For the overloads with a basic_string&& parameter,str is left in a valid but unspecified state.
Recommended practice: For the overloads with a basic_string&& parameter, implementations should avoid allocation if s.get_allocator() == a is true.
template<class T> constexpr basic_string(const T& t, size_type pos, size_type n, const Allocator& a = Allocator());
Constraints: is_convertible_v<const T&, basic_string_view<charT, traits>>is true.
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);
template<class T> constexpr explicit basic_string(const T& t, const Allocator& a = Allocator());
Constraints:
- is_convertible_v<const T&, basic_string_view<charT, traits>> istrue and
- is_convertible_v<const T&, const charT*> isfalse.
Effects: Creates a variable, sv, as if bybasic_string_view<charT, traits> sv = t; and then behaves the same as basic_string(sv.data(), sv.size(), a).
constexpr basic_string(const charT* s, size_type n, const Allocator& a = Allocator());
Preconditions: [s, s + n) is a valid range.
Effects: Constructs an object whose initial value is the range [s, s + n).
Postconditions: size() is equal to n, andtraits::compare(data(), s, n) is equal to 0.
constexpr basic_string(const charT* s, const Allocator& a = Allocator());
Constraints: Allocator is a type that qualifies as an allocator ([container.reqmts]).
[Note 1:
This affects class template argument deduction.
— _end note_]
Effects: Equivalent to: basic_string(s, traits::length(s), a).
constexpr basic_string(size_type n, charT c, const Allocator& a = Allocator());
Constraints: Allocator is a type that qualifies as an allocator ([container.reqmts]).
[Note 2:
This affects class template argument deduction.
— _end note_]
Effects: Constructs an object whose value consists of n copies of c.
template<class InputIterator> constexpr basic_string(InputIterator begin, InputIterator end, const Allocator& a = Allocator());
Constraints: InputIterator is a type that qualifies as an input iterator ([container.reqmts]).
Effects: Constructs a string from the values in the range [begin, end), as specified in [sequence.reqmts].
Effects: Constructs a string from the values in the range rg, as specified in [sequence.reqmts].
constexpr basic_string(initializer_list<charT> il, const Allocator& a = Allocator());
Effects: Equivalent to basic_string(il.begin(), il.end(), a).
constexpr basic_string(const basic_string& str, const Allocator& alloc);constexpr basic_string(basic_string&& str, const Allocator& alloc);
Effects: Constructs an object whose value is that of str prior to this call.
The stored allocator is constructed from alloc.
In the second form, str is left in a valid but unspecified state.
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>, Allocator>;
Constraints: InputIterator is a type that qualifies as an input iterator, and Allocator is a type that qualifies as an allocator ([container.reqmts]).
template<class charT,class traits,class Allocator = allocator<charT>> explicit basic_string(basic_string_view<charT, traits>, const Allocator& = Allocator()) -> basic_string<charT, traits, Allocator>;template<class charT,class traits,class Allocator = allocator<charT>> basic_string(basic_string_view<charT, traits>,typename _see below_::size_type, typename _see below_::size_type,const Allocator& = Allocator()) -> basic_string<charT, traits, Allocator>;
constexpr basic_string& operator=(const basic_string& str);
Effects: If *this and str are the same object, has no effect.
Otherwise, replaces the value of *this with a copy of str.
constexpr basic_string& operator=(basic_string&& str) noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value || allocator_traits<Allocator>::is_always_equal::value);
Effects: Move assigns as a sequence container ([sequence.reqmts]), except that iterators, pointers and references may be invalidated.
template<class T> constexpr basic_string& operator=(const T& t);
Constraints:
- is_convertible_v<const T&, basic_string_view<charT, traits>>is true and
- is_convertible_v<const T&, const charT*>is false.
Effects: Equivalent to:basic_string_view<charT, traits> sv = t;return assign(sv);
constexpr basic_string& operator=(const charT* s);
Effects: Equivalent to:return *this = basic_string_view<charT, traits>(s);
constexpr basic_string& operator=(charT c);
Effects: Equivalent to:return *this = basic_string_view<charT, traits>(addressof(c), 1);
constexpr basic_string& operator=(initializer_list<charT> il);
Effects: Equivalent to:return *this = basic_string_view<charT, traits>(il.begin(), il.size());
27.4.3.4 Iterator support [string.iterators]
constexpr iterator begin() noexcept;constexpr const_iterator begin() const noexcept;constexpr const_iterator cbegin() const noexcept;
Returns: An iterator referring to the first character in the string.
constexpr iterator end() noexcept;constexpr const_iterator end() const noexcept;constexpr const_iterator cend() const noexcept;
Returns: An iterator which is the past-the-end value.
constexpr reverse_iterator rbegin() noexcept;constexpr const_reverse_iterator rbegin() const noexcept;constexpr const_reverse_iterator crbegin() const noexcept;
Returns: An iterator which is semantically equivalent toreverse_iterator(end()).
constexpr reverse_iterator rend() noexcept;constexpr const_reverse_iterator rend() const noexcept;constexpr const_reverse_iterator crend() const noexcept;
Returns: An iterator which is semantically equivalent toreverse_iterator(begin()).
27.4.3.5 Capacity [string.capacity]
constexpr size_type size() const noexcept;constexpr size_type length() const noexcept;
Returns: A count of the number of char-like objects currently in the string.
Complexity: Constant time.
constexpr size_type max_size() const noexcept;
Returns: The largest possible number of char-like objects that can be stored in abasic_string.
Complexity: Constant time.
constexpr void resize(size_type n, charT c);
Effects: Alters the value of*thisas follows:
constexpr void resize(size_type n);
Effects: Equivalent to resize(n, charT()).
template<class Operation> constexpr void resize_and_overwrite(size_type n, Operation op);
Let
- o = size() before the call to resize_and_overwrite.
- p be a value of type charT* or charT* const, such that the range [p, p + n] is valid andthis->compare(0, k, p, k) == 0 is true before the call.
The values in the range [p + k, p + n] may be indeterminate ([basic.indet]). - m be a value of type size_type or const size_typeequal to n.
- OP be the expression std::move(op)(p, m).
Preconditions:
- OP does not throw an exception or modify p or m.
- After evaluating _OP_there are no indeterminate values in the range [p, p + r).
Effects: Evaluates OP, replaces the contents of *this with [p, p + r), and invalidates all pointers and references to the range [p, p + n].
Recommended practice: Implementations should avoid unnecessary copies and allocations by, for example, making p a pointer into internal storage and by restoring *(p + r) to charT() after evaluating OP.
constexpr size_type capacity() const noexcept;
Returns: The size of the allocated storage in the string.
Complexity: Constant time.
constexpr void reserve(size_type res_arg);
Effects: A directive that informs a basic_string of a planned change in size, so that the storage allocation can be managed accordingly.
Following a call toreserve,capacity()is greater or equal to the argument ofreserveif reallocation happens; and equal to the previous value ofcapacity()otherwise.
Reallocation happens at this point if and only if the current capacity is less than the argument of reserve.
Throws: length_errorifres_arg > max_size() or any exceptions thrown byallocator_traits <Allocator>::allocate.
constexpr void shrink_to_fit();
Effects: shrink_to_fit is a non-binding request to reducecapacity() to size().
[Note 1:
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.
Complexity: If the size is not equal to the old capacity, linear in the size of the sequence; otherwise constant.
Remarks: Reallocation invalidates all the references, pointers, and iterators referring to the elements in the sequence, as well as the past-the-end iterator.
[Note 2:
If no reallocation happens, they remain valid.
— _end note_]
constexpr void clear() noexcept;
Effects: Equivalent to: erase(begin(), end());
constexpr bool empty() const noexcept;
Effects: Equivalent to:return size() == 0;
27.4.3.6 Element access [string.access]
constexpr const_reference operator[](size_type pos) const;constexpr reference operator[](size_type pos);
Hardened preconditions: pos <= size() is true.
Returns: *(begin() + pos) if pos < size().
Otherwise, returns a reference to an object of type charT with valuecharT(), where modifying the object to any value other thancharT() leads to undefined behavior.
Complexity: Constant time.
constexpr const_reference at(size_type pos) const;constexpr reference at(size_type pos);
Returns: operator[](pos).
Throws: out_of_rangeifpos >= size().
constexpr const charT& front() const;constexpr charT& front();
Hardened preconditions: empty() is false.
Effects: Equivalent to: return operator[](0);
constexpr const charT& back() const;constexpr charT& back();
Hardened preconditions: empty() is false.
Effects: Equivalent to: return operator[](size() - 1);
27.4.3.7 Modifiers [string.modifiers]
27.4.3.7.1 basic_string::operator+= [string.op.append]
constexpr basic_string& operator+=(const basic_string& str);
Effects: Equivalent to: return append(str);
template<class T> constexpr basic_string& operator+=(const T& t);
Constraints:
- is_convertible_v<const T&, basic_string_view<charT, traits>> istrue and
- is_convertible_v<const T&, const charT*> isfalse.
Effects: Equivalent to:basic_string_view<charT, traits> sv = t;return append(sv);
constexpr basic_string& operator+=(const charT* s);
Effects: Equivalent to: return append(s);
constexpr basic_string& operator+=(charT c);
Effects: Equivalent to: return append(size_type{1}, c);
constexpr basic_string& operator+=(initializer_list<charT> il);
Effects: Equivalent to: return append(il);
27.4.3.7.2 basic_string::append [string.append]
constexpr basic_string& append(const basic_string& str);
Effects: Equivalent to: return append(str.data(), str.size());
constexpr basic_string& append(const basic_string& str, size_type pos, size_type n = npos);
Effects: Equivalent to:return append(basic_string_view<charT, traits>(str).substr(pos, n));
template<class T> constexpr basic_string& append(const T& t);
Constraints:
- is_convertible_v<const T&, basic_string_view<charT, traits>> istrue and
- is_convertible_v<const T&, const charT*> isfalse.
Effects: Equivalent to:basic_string_view<charT, traits> sv = t;return append(sv.data(), sv.size());
template<class T> constexpr basic_string& append(const T& t, size_type pos, size_type n = npos);
Constraints:
- is_convertible_v<const T&, basic_string_view<charT, traits>> istrue and
- is_convertible_v<const T&, const charT*> isfalse.
Effects: Equivalent to:basic_string_view<charT, traits> sv = t;return append(sv.substr(pos, n));
constexpr basic_string& append(const charT* s, size_type n);
Preconditions: [s, s + n) is a valid range.
Effects: Appends a copy of the range [s, s + n) to the string.
constexpr basic_string& append(const charT* s);
Effects: Equivalent to: return append(s, traits::length(s));
constexpr basic_string& append(size_type n, charT c);
Effects: Appends n copies of c to the string.
template<class InputIterator> constexpr basic_string& append(InputIterator first, InputIterator last);
Constraints: InputIterator is a type that qualifies as an input iterator ([container.reqmts]).
Effects: Equivalent to: return append(basic_string(first, last, get_allocator()));
Effects: Equivalent to: return append(basic_string(from_range, std::forward<R>(rg), get_allocator()));
constexpr basic_string& append(initializer_list<charT> il);
Effects: Equivalent to: return append(il.begin(), il.size());
constexpr void push_back(charT c);
Effects: Equivalent toappend(size_type{1}, c).
27.4.3.7.3 basic_string::assign [string.assign]
constexpr basic_string& assign(const basic_string& str);
Effects: Equivalent to: return *this = str;
constexpr basic_string& assign(basic_string&& str) noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value || allocator_traits<Allocator>::is_always_equal::value);
Effects: Equivalent to: return *this = std::move(str);
constexpr basic_string& assign(const basic_string& str, size_type pos, size_type n = npos);
Effects: Equivalent to:return assign(basic_string_view<charT, traits>(str).substr(pos, n));
template<class T> constexpr basic_string& assign(const T& t);
Constraints:
- is_convertible_v<const T&, basic_string_view<charT, traits>> istrue and
- is_convertible_v<const T&, const charT*> isfalse.
Effects: Equivalent to:basic_string_view<charT, traits> sv = t;return assign(sv.data(), sv.size());
template<class T> constexpr basic_string& assign(const T& t, size_type pos, size_type n = npos);
Constraints:
- is_convertible_v<const T&, basic_string_view<charT, traits>> istrue and
- is_convertible_v<const T&, const charT*> isfalse.
Effects: Equivalent to:basic_string_view<charT, traits> sv = t;return assign(sv.substr(pos, n));
constexpr basic_string& assign(const charT* s, size_type n);
Preconditions: [s, s + n) is a valid range.
Effects: Replaces the string controlled by *this with a copy of the range [s, s + n).
constexpr basic_string& assign(const charT* s);
Effects: Equivalent to: return assign(s, traits::length(s));
constexpr basic_string& assign(initializer_list<charT> il);
Effects: Equivalent to: return assign(il.begin(), il.size());
constexpr basic_string& assign(size_type n, charT c);
Effects: Equivalent to:clear(); resize(n, c);return *this;
template<class InputIterator> constexpr basic_string& assign(InputIterator first, InputIterator last);
Constraints: InputIterator is a type that qualifies as an input iterator ([container.reqmts]).
Effects: Equivalent to: return assign(basic_string(first, last, get_allocator()));
Effects: Equivalent to: return assign(basic_string(from_range, std::forward<R>(rg), get_allocator()));
27.4.3.7.4 basic_string::insert [string.insert]
constexpr basic_string& insert(size_type pos, const basic_string& str);
Effects: Equivalent to: return insert(pos, str.data(), str.size());
constexpr basic_string& insert(size_type pos1, const basic_string& str, size_type pos2, size_type n = npos);
Effects: Equivalent to:return insert(pos1, basic_string_view<charT, traits>(str), pos2, n);
template<class T> constexpr basic_string& insert(size_type pos, const T& t);
Constraints:
- is_convertible_v<const T&, basic_string_view<charT, traits>> istrue and
- is_convertible_v<const T&, const charT*> isfalse.
Effects: Equivalent to:basic_string_view<charT, traits> sv = t;return insert(pos, sv.data(), sv.size());
template<class T> constexpr basic_string& insert(size_type pos1, const T& t, size_type pos2, size_type n = npos);
Constraints:
- is_convertible_v<const T&, basic_string_view<charT, traits>> istrue and
- is_convertible_v<const T&, const charT*> isfalse.
Effects: Equivalent to:basic_string_view<charT, traits> sv = t;return insert(pos1, sv.substr(pos2, n));
constexpr basic_string& insert(size_type pos, const charT* s, size_type n);
Preconditions: [s, s + n) is a valid range.
Effects: Inserts a copy of the range [s, s + n) immediately before the character at position pos if pos < size(), or otherwise at the end of the string.
Throws:
- out_of_range if pos > size(),
- length_error if n > max_size() - size(), or
- any exceptions thrown by allocator_traits<Allocator>::allocate.
constexpr basic_string& insert(size_type pos, const charT* s);
Effects: Equivalent to: return insert(pos, s, traits::length(s));
constexpr basic_string& insert(size_type pos, size_type n, charT c);
Effects: Inserts n copies of c before the character at position posif pos < size(), or otherwise at the end of the string.
Throws:
- out_of_range if pos > size(),
- length_error if n > max_size() - size(), or
- any exceptions thrown by allocator_traits<Allocator>::allocate.
constexpr iterator insert(const_iterator p, charT c);
Preconditions: p is a valid iterator on*this.
Effects: Inserts a copy of c at the position p.
Returns: An iterator which refers to the inserted character.
constexpr iterator insert(const_iterator p, size_type n, charT c);
Preconditions: p is a valid iterator on*this.
Effects: Inserts n copies of c at the position p.
Returns: An iterator which refers to the first inserted character, orp if n == 0.
template<class InputIterator> constexpr iterator insert(const_iterator p, InputIterator first, InputIterator last);
Constraints: InputIterator is a type that qualifies as an input iterator ([container.reqmts]).
Preconditions: p is a valid iterator on*this.
Effects: Equivalent toinsert(p - begin(), basic_string(first, last, get_allocator())).
Returns: An iterator which refers to the first inserted character, orp if first == last.
Preconditions: p is a valid iterator on *this.
Effects: Equivalent toinsert(p - begin(), basic_string(from_range, std::forward<R>(rg), get_allocator())).
Returns: An iterator which refers to the first inserted character, orp if rg is empty.
constexpr iterator insert(const_iterator p, initializer_list<charT> il);
Effects: Equivalent to: return insert(p, il.begin(), il.end());
27.4.3.7.5 basic_string::erase [string.erase]
constexpr basic_string& erase(size_type pos = 0, size_type n = npos);
Effects: Determines the effective length xlenof the string to be removed as the smaller of n andsize() - pos.
Removes the characters in the range [begin() + pos, begin() + pos + xlen).
Throws: out_of_rangeif pos > size().
constexpr iterator erase(const_iterator p);
Preconditions: p is a valid dereferenceable iterator on *this.
Effects: Removes the character referred to by p.
Returns: An iterator which points to the element immediately following p prior to the element being erased.
If no such element exists,end()is returned.
constexpr iterator erase(const_iterator first, const_iterator last);
Preconditions: first and last are valid iterators on*this.
[first, last) is a valid range.
Effects: Removes the characters in the range [first, last).
Returns: An iterator which points to the element pointed to by last prior to the other elements being erased.
If no such element exists,end()is returned.
constexpr void pop_back();
Hardened preconditions: empty() is false.
Effects: Equivalent to erase(end() - 1).
27.4.3.7.6 basic_string::replace [string.replace]
constexpr basic_string& replace(size_type pos1, size_type n1, const basic_string& str);
Effects: Equivalent to: return replace(pos1, n1, str.data(), str.size());
constexpr basic_string& replace(size_type pos1, size_type n1, const basic_string& str, size_type pos2, size_type n2 = npos);
Effects: Equivalent to:return replace(pos1, n1, basic_string_view<charT, traits>(str).substr(pos2, n2));
template<class T> constexpr basic_string& replace(size_type pos1, size_type n1, const T& t);
Constraints:
- is_convertible_v<const T&, basic_string_view<charT, traits>> istrue and
- is_convertible_v<const T&, const charT*> isfalse.
Effects: Equivalent to:basic_string_view<charT, traits> sv = t;return replace(pos1, n1, sv.data(), sv.size());
template<class T> constexpr basic_string& replace(size_type pos1, size_type n1, const T& t, size_type pos2, size_type n2 = npos);
Constraints:
- is_convertible_v<const T&, basic_string_view<charT, traits>> istrue and
- is_convertible_v<const T&, const charT*> isfalse.
Effects: Equivalent to:basic_string_view<charT, traits> sv = t;return replace(pos1, n1, sv.substr(pos2, n2));
constexpr basic_string& replace(size_type pos1, size_type n1, const charT* s, size_type n2);
Preconditions: [s, s + n2) is a valid range.
Effects: Determines the effective length xlen of the string to be removed as the smaller of n1 and size() - pos1.
Ifsize() - xlen >= max_size() - n2 throws length_error.
Otherwise, the function replaces the characters in the range [begin() + pos1, begin() + pos1 + xlen) with a copy of the range [s, s + n2).
Throws:
- out_of_range if pos1 > size(),
- length_error if the length of the resulting string would exceed max_size(), or
- any exceptions thrown by allocator_traits<Allocator>::allocate.
constexpr basic_string& replace(size_type pos, size_type n, const charT* s);
Effects: Equivalent to: return replace(pos, n, s, traits::length(s));
constexpr basic_string& replace(size_type pos1, size_type n1, size_type n2, charT c);
Effects: Determines the effective length xlen of the string to be removed as the smaller of n1 and size() - pos1.
Ifsize() - xlen >= max_size() - n2 throws length_error.
Otherwise, the function replaces the characters in the range [begin() + pos1, begin() + pos1 + xlen) with n2 copies of c.
Throws:
- out_of_range if pos1 > size(),
- length_error if the length of the resulting string would exceed max_size(), or
- any exceptions thrown by allocator_traits<Allocator>::allocate.
constexpr basic_string& replace(const_iterator i1, const_iterator i2, const basic_string& str);
Effects: Equivalent to: return replace(i1, i2, basic_string_view<charT, traits>(str));
template<class T> constexpr basic_string& replace(const_iterator i1, const_iterator i2, const T& t);
Constraints:
- is_convertible_v<const T&, basic_string_view<charT, traits>> istrue and
- is_convertible_v<const T&, const charT*> isfalse.
Preconditions: [begin(), i1) and [i1, i2) are valid ranges.
Effects: Equivalent to:basic_string_view<charT, traits> sv = t;return replace(i1 - begin(), i2 - i1, sv.data(), sv.size());
constexpr basic_string& replace(const_iterator i1, const_iterator i2, const charT* s, size_type n);
Effects: Equivalent to: return replace(i1, i2, basic_string_view<charT, traits>(s, n));
constexpr basic_string& replace(const_iterator i1, const_iterator i2, const charT* s);
Effects: Equivalent to: return replace(i1, i2, basic_string_view<charT, traits>(s));
constexpr basic_string& replace(const_iterator i1, const_iterator i2, size_type n, charT c);
Preconditions: [begin(), i1) and [i1, i2) are valid ranges.
Effects: Equivalent to: return replace(i1 - begin(), i2 - i1, n, c);
template<class InputIterator> constexpr basic_string& replace(const_iterator i1, const_iterator i2, InputIterator j1, InputIterator j2);
Constraints: InputIterator is a type that qualifies as an input iterator ([container.reqmts]).
Effects: Equivalent to: return replace(i1, i2, basic_string(j1, j2, get_allocator()));
template<[_container-compatible-range_](container.intro.reqmts#concept:container-compatible-range "23.2.2.1 Introduction [container.intro.reqmts]")<charT> R> constexpr basic_string& replace_with_range(const_iterator i1, const_iterator i2, R&& rg);
Effects: Equivalent to:return replace(i1, i2, basic_string(from_range, std::forward<R>(rg), get_allocator()));
constexpr basic_string& replace(const_iterator i1, const_iterator i2, initializer_list<charT> il);
Effects: Equivalent to: return replace(i1, i2, il.begin(), il.size());
27.4.3.7.7 basic_string::copy [string.copy]
constexpr size_type copy(charT* s, size_type n, size_type pos = 0) const;
Effects: Equivalent to:return basic_string_view<charT, traits>(*this).copy(s, n, pos);
[Note 1:
This does not terminate s with a null object.
— _end note_]
27.4.3.7.8 basic_string::swap [string.swap]
constexpr void swap(basic_string& s) noexcept(allocator_traits<Allocator>::propagate_on_container_swap::value || allocator_traits<Allocator>::is_always_equal::value);
Preconditions: allocator_traits<Allocator>::propagate_on_container_swap::value is trueorget_allocator() == s.get_allocator().
Postconditions: *thiscontains the same sequence of characters that was in s,s contains the same sequence of characters that was in*this.
Complexity: Constant time.
27.4.3.8 String operations [string.ops]
27.4.3.8.1 Accessors [string.accessors]
constexpr const charT* c_str() const noexcept;constexpr const charT* data() const noexcept;
Returns: A pointer p such that p + i == addressof(operator[](i)) for eachi in [0, size()].
Complexity: Constant time.
Remarks: The program shall not modify any of the values stored in the character array; otherwise, the behavior is undefined.
constexpr charT* data() noexcept;
Returns: A pointer p such that p + i == addressof(operator[](i)) for eachi in [0, size()].
Complexity: Constant time.
Remarks: The program shall not modify the value stored at p + size()to any value other than charT(); otherwise, the behavior is undefined.
constexpr operator basic_string_view<charT, traits>() const noexcept;
Effects: Equivalent to:return basic_string_view<charT, traits>(data(), size());
constexpr allocator_type get_allocator() const noexcept;
Returns: A copy of theAllocatorobject used to construct the string or, if that allocator has been replaced, a copy of the most recent replacement.
27.4.3.8.2 Searching [string.find]
Let F be one offind, rfind, find_first_of, find_last_of,find_first_not_of, and find_last_not_of.
- Each member function of the formconstexpr size_type F(const basic_string& str, size_type pos) const noexcept;has effects equivalent to:return F(basic_string_view<charT, traits>(str), pos);
- Each member function of the formconstexpr size_type F(const charT* s, size_type pos) const;has effects equivalent to:return F(basic_string_view<charT, traits>(s), pos);
- Each member function of the formconstexpr size_type F(const charT* s, size_type pos, size_type n) const;has effects equivalent to:return F(basic_string_view<charT, traits>(s, n), pos);
- Each member function of the formconstexpr size_type F(charT c, size_type pos) const noexcept;has effects equivalent to:return F(basic_string_view<charT, traits>(addressof(c), 1), pos);
template<class T> constexpr size_type find(const T& t, size_type pos = 0) const noexcept(_see below_);template<class T> constexpr size_type rfind(const T& t, size_type pos = npos) const noexcept(_see below_);template<class T> constexpr size_type find_first_of(const T& t, size_type pos = 0) const noexcept(_see below_);template<class T> constexpr size_type find_last_of(const T& t, size_type pos = npos) const noexcept(_see below_);template<class T> constexpr size_type find_first_not_of(const T& t, size_type pos = 0) const noexcept(_see below_);template<class T> constexpr size_type find_last_not_of(const T& t, size_type pos = npos) const noexcept(_see below_);
Constraints:
- is_convertible_v<const T&, basic_string_view<charT, traits>> istrue and
- is_convertible_v<const T&, const charT*> isfalse.
Effects: Let G be the name of the function.
Equivalent to:basic_string_view<charT, traits> s = *this, sv = t;return s.G(sv, pos);
Remarks: The exception specification is equivalent tois_nothrow_convertible_v<const T&, basic_string_view<charT, traits>>.
27.4.3.8.3 basic_string::substr [string.substr]
constexpr basic_string substr(size_type pos = 0, size_type n = npos) const &;
Effects: Equivalent to: return basic_string(*this, pos, n);
constexpr basic_string substr(size_type pos = 0, size_type n = npos) &&;
Effects: Equivalent to: return basic_string(std::move(*this), pos, n);
constexpr basic_string_view<charT, traits> subview(size_type pos = 0, size_type n = npos) const;
Effects: Equivalent to: return basic_string_view<charT, traits>(*this).subview(pos, n);
27.4.3.8.4 basic_string::compare [string.compare]
template<class T> constexpr int compare(const T& t) const noexcept(_see below_);
Constraints:
- is_convertible_v<const T&, basic_string_view<charT, traits>> istrue and
- is_convertible_v<const T&, const charT*> isfalse.
Effects: Equivalent to: return basic_string_view<charT, traits>(*this).compare(t);
Remarks: The exception specification is equivalent tois_nothrow_convertible_v<const T&, basic_string_view<charT, traits>>.
template<class T> constexpr int compare(size_type pos1, size_type n1, const T& t) const;
Constraints:
- is_convertible_v<const T&, basic_string_view<charT, traits>> istrue and
- is_convertible_v<const T&, const charT*> isfalse.
Effects: Equivalent to:return basic_string_view<charT, traits>(*this).substr(pos1, n1).compare(t);
template<class T> constexpr int compare(size_type pos1, size_type n1, const T& t, size_type pos2, size_type n2 = npos) const;
Constraints:
- is_convertible_v<const T&, basic_string_view<charT, traits>> istrue and
- is_convertible_v<const T&, const charT*> isfalse.
Effects: Equivalent to:basic_string_view<charT, traits> s = *this, sv = t;return s.substr(pos1, n1).compare(sv.substr(pos2, n2));
constexpr int compare(const basic_string& str) const noexcept;
Effects: Equivalent to:return compare(basic_string_view<charT, traits>(str));
constexpr int compare(size_type pos1, size_type n1, const basic_string& str) const;
Effects: Equivalent to:return compare(pos1, n1, basic_string_view<charT, traits>(str));
constexpr int compare(size_type pos1, size_type n1, const basic_string& str, size_type pos2, size_type n2 = npos) const;
Effects: Equivalent to:return compare(pos1, n1, basic_string_view<charT, traits>(str), pos2, n2);
constexpr int compare(const charT* s) const;
Effects: Equivalent to:return compare(basic_string_view<charT, traits>(s));
constexpr int compare(size_type pos, size_type n1, const charT* s) const;
Effects: Equivalent to: return compare(pos, n1, basic_string_view<charT, traits>(s));
constexpr int compare(size_type pos, size_type n1, const charT* s, size_type n2) const;
Effects: Equivalent to: return compare(pos, n1, basic_string_view<charT, traits>(s, n2));
27.4.3.8.5 basic_string::starts_with [string.starts.with]
constexpr bool starts_with(basic_string_view<charT, traits> x) const noexcept;constexpr bool starts_with(charT x) const noexcept;constexpr bool starts_with(const charT* x) const;
Effects: Equivalent to:return basic_string_view<charT, traits>(data(), size()).starts_with(x);
27.4.3.8.6 basic_string::ends_with [string.ends.with]
constexpr bool ends_with(basic_string_view<charT, traits> x) const noexcept;constexpr bool ends_with(charT x) const noexcept;constexpr bool ends_with(const charT* x) const;
Effects: Equivalent to:return basic_string_view<charT, traits>(data(), size()).ends_with(x);
27.4.3.8.7 basic_string::contains [string.contains]
constexpr bool contains(basic_string_view<charT, traits> x) const noexcept;constexpr bool contains(charT x) const noexcept;constexpr bool contains(const charT* x) const;
Effects: Equivalent to:return basic_string_view<charT, traits>(data(), size()).contains(x);
27.4.4 Non-member functions [string.nonmembers]
27.4.4.1 operator+ [string.op.plus]
template<class charT, class traits, class Allocator> constexpr 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> constexpr basic_string<charT, traits, Allocator> operator+(const basic_string<charT, traits, Allocator>& lhs, const charT* rhs);
Effects: Equivalent to:basic_string<charT, traits, Allocator> r = lhs; r.append(rhs);return r;
template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(basic_string<charT, traits, Allocator>&& lhs,const basic_string<charT, traits, Allocator>& rhs);template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(basic_string<charT, traits, Allocator>&& lhs, const charT* rhs);
Effects: Equivalent to:lhs.append(rhs);return std::move(lhs);
template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(basic_string<charT, traits, Allocator>&& lhs, basic_string<charT, traits, Allocator>&& rhs);
Effects: Equivalent to:lhs.append(rhs);return std::move(lhs);except that both lhs and rhsare left in valid but unspecified states.
[Note 1:
If lhs and rhs have equal allocators, the implementation can move from either.
— _end note_]
template<class charT, class traits, class Allocator> constexpr 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> constexpr basic_string<charT, traits, Allocator> operator+(const charT* lhs, basic_string<charT, traits, Allocator>&& rhs);
Effects: Equivalent to:rhs.insert(0, lhs);return std::move(rhs);
template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(const charT* lhs, const basic_string<charT, traits, Allocator>& rhs);
Effects: Equivalent to:basic_string<charT, traits, Allocator> r = rhs; r.insert(0, lhs);return r;
template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(charT lhs, const basic_string<charT, traits, Allocator>& rhs);
Effects: Equivalent to:basic_string<charT, traits, Allocator> r = rhs; r.insert(r.begin(), lhs);return r;
template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(charT lhs, basic_string<charT, traits, Allocator>&& rhs);
Effects: Equivalent to:rhs.insert(rhs.begin(), lhs);return std::move(rhs);
template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(const basic_string<charT, traits, Allocator>& lhs, charT rhs);
Effects: Equivalent to:basic_string<charT, traits, Allocator> r = lhs; r.push_back(rhs);return r;
template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(basic_string<charT, traits, Allocator>&& lhs, charT rhs);
Effects: Equivalent to:lhs.push_back(rhs);return std::move(lhs);
template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(const basic_string<charT, traits, Allocator>& lhs, type_identity_t<basic_string_view<charT, traits>> rhs);
Equivalent to:basic_string<charT, traits, Allocator> r = lhs; r.append(rhs);return r;
template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(basic_string<charT, traits, Allocator>&& lhs, type_identity_t<basic_string_view<charT, traits>> rhs);
Equivalent to:lhs.append(rhs);return std::move(lhs);
template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(type_identity_t<basic_string_view<charT, traits>> lhs,const basic_string<charT, traits, Allocator>& rhs);
Equivalent to:basic_string<charT, traits, Allocator> r = rhs; r.insert(0, lhs);return r;
template<class charT, class traits, class Allocator> constexpr basic_string<charT, traits, Allocator> operator+(type_identity_t<basic_string_view<charT, traits>> lhs, basic_string<charT, traits, Allocator>&& rhs);
Equivalent to:rhs.insert(0, lhs);return std::move(rhs);
[Note 2:
Using a specialization of type_identity_t as a parameter type ensures that an object of type basic_string<charT, traits, Allocator>can be concatenated with an object of a type Thaving an implicit conversion tobasic_string_view<charT, traits> ([over.match.oper]).
— _end note_]
27.4.4.2 Non-member comparison operator functions [string.cmp]
template<class charT, class traits, class Allocator> constexpr bool operator==(const basic_string<charT, traits, Allocator>& lhs,const basic_string<charT, traits, Allocator>& rhs) noexcept;template<class charT, class traits, class Allocator> constexpr bool operator==(const basic_string<charT, traits, Allocator>& lhs,const charT* rhs);template<class charT, class traits, class Allocator> constexpr _see below_ operator<=>(const basic_string<charT, traits, Allocator>& lhs,const basic_string<charT, traits, Allocator>& rhs) noexcept;template<class charT, class traits, class Allocator> constexpr _see below_ operator<=>(const basic_string<charT, traits, Allocator>& lhs,const charT* rhs);
Effects: Let op be the operator.
Equivalent to:return basic_string_view<charT, traits>(lhs) op basic_string_view<charT, traits>(rhs);
27.4.4.3 swap [string.special]
template<class charT, class traits, class Allocator> constexpr void swap(basic_string<charT, traits, Allocator>& lhs, basic_string<charT, traits, Allocator>& rhs) noexcept(noexcept(lhs.swap(rhs)));
Effects: Equivalent to lhs.swap(rhs).
27.4.4.4 Inserters and extractors [string.io]
template<class charT, class traits, class Allocator> basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, basic_string<charT, traits, Allocator>& str);
After constructing a sentry object, if the sentry object returns truewhen converted to a value of type bool, calls str.erase()and then extracts characters from is and appends them to str as if by callingstr.append(1, c).
Ifis.width()is greater than zero, the maximum number n of characters appended isis.width(); otherwise n isstr.max_size().
Characters are extracted and appended until any of the following occurs:
- _n_characters are stored;
- end-of-file occurs on the input sequence;
- isspace(c, is.getloc())is true for the next available input character_c_.
After the last character (if any) is extracted,is.width(0)is called and thesentryobject is destroyed.
If the function extracts no characters,ios_base::failbit is set in the input function's local error state before setstate is called.
template<class charT, class traits, class Allocator> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os,const basic_string<charT, traits, Allocator>& str);
Effects: Equivalent to: return os << basic_string_view<charT, traits>(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);
Effects: Behaves as an unformatted input function ([istream.unformatted]), except that it does not affect the value returned by subsequent calls tobasic_istream<>::gcount().
After constructing a sentry object, if the sentry object returns truewhen converted to a value of type bool, calls str.erase()and then extracts characters from is and appends them to str as if by callingstr.append(1, c)until any of the following occurs:
- end-of-file occurs on the input sequence;
- traits::eq(c, delim)for the next available input character_c_(in which case,_c_is extracted but not appended);
- str.max_size()characters are stored (in which case,ios_base::failbit is set in the input function's local error state).
The conditions are tested in the order shown.
In any case, after the last character is extracted, thesentryobject is destroyed.
If the function extracts no characters,ios_base::failbit is set in the input function's local error state before setstate is called.
template<class charT, class traits, class Allocator> basic_istream<charT, traits>& getline(basic_istream<charT, traits>& is, basic_string<charT, traits, Allocator>& str);template<class charT, class traits, class Allocator> basic_istream<charT, traits>& getline(basic_istream<charT, traits>&& is, basic_string<charT, traits, Allocator>& str);
Returns: getline(is, str, is.widen('\n')).
27.4.4.5 Erasure [string.erasure]
template<class charT, class traits, class Allocator, class U = charT> constexpr typename basic_string<charT, traits, Allocator>::size_type erase(basic_string<charT, traits, Allocator>& c, const U& value);
Effects: Equivalent to:auto it = remove(c.begin(), c.end(), value);auto r = distance(it, c.end()); c.erase(it, c.end());return r;
template<class charT, class traits, class Allocator, class Predicate> constexpr typename basic_string<charT, traits, Allocator>::size_type erase_if(basic_string<charT, traits, Allocator>& c, Predicate pred);
Effects: Equivalent to:auto it = remove_if(c.begin(), c.end(), pred);auto r = distance(it, c.end()); c.erase(it, c.end());return r;
27.4.5 Numeric conversions [string.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);
Effects: The first two functions call strtol(str.c_str(), ptr, base), and the last three functions call strtoul(str.c_str(), ptr, base),strtoll(str.c_str(), ptr, base), and strtoull(str.c_str(), ptr, base), respectively.
Each function returns the converted result, if any.
The argument ptr designates a pointer to an object internal to the function that is used to determine what to store at *idx.
If the function does not throw an exception and idx != nullptr, the function stores in *idxthe index of the first unconverted element of str.
Returns: The converted result.
Throws: invalid_argument if strtol, strtoul,strtoll, or strtoull reports that no conversion can be performed.
Throws out_of_range if strtol, strtoul,strtoll or strtoull sets errno to ERANGE, or if the converted value is outside the range of representable values for the return type.
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);
Effects: These functions callstrtof(str.c_str(), ptr), strtod(str.c_str(), ptr), andstrtold(str.c_str(), ptr), respectively.
Each function returns the converted result, if any.
The argument ptr designates a pointer to an object internal to the function that is used to determine what to store at*idx.
If the function does not throw an exception and idx != nullptr, the function stores in *idx the index of the first unconverted element of str.
Returns: The converted result.
Throws: invalid_argument if strtof, strtod, orstrtold reports that no conversion can be performed.
Throwsout_of_range if strtof, strtod, orstrtold sets errno to ERANGEor if the converted value is outside the range of representable values for the return type.
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);
Returns: format("{}", 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);
Effects: The first two functions call wcstol(str.c_str(), ptr, base), and the last three functions call wcstoul(str.c_str(), ptr, base),wcstoll(str.c_str(), ptr, base), and wcstoull(str.c_str(), ptr, base), respectively.
Each function returns the converted result, if any.
The argument ptr designates a pointer to an object internal to the function that is used to determine what to store at *idx.
If the function does not throw an exception and idx != nullptr, the function stores in *idxthe index of the first unconverted element of str.
Returns: The converted result.
Throws: invalid_argument if wcstol, wcstoul, wcstoll, orwcstoull reports that no conversion can be performed.
Throwsout_of_range if the converted value is outside the range of representable values for the return type.
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);
Effects: These functions call wcstof(str.c_str(), ptr),wcstod(str.c_str(), ptr), and wcstold(str.c_str(), ptr), respectively.
Each function returns the converted result, if any.
The argument ptr designates a pointer to an object internal to the function that is used to determine what to store at *idx.
If the function does not throw an exception and idx != nullptr, the function stores in *idxthe index of the first unconverted element of str.
Returns: The converted result.
Throws: invalid_argument if wcstof, wcstod, or wcstold reports that no conversion can be performed.
Throws out_of_range if wcstof, wcstod, orwcstold sets errno to ERANGE.
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);
Returns: format(L"{}", val).
27.4.6 Hash support [basic.string.hash]
template<class A> struct hash<basic_string<char, char_traits<char>, A>>;template<class A> struct hash<basic_string<char8_t, char_traits<char8_t>, A>>;template<class A> struct hash<basic_string<char16_t, char_traits<char16_t>, A>>;template<class A> struct hash<basic_string<char32_t, char_traits<char32_t>, A>>;template<class A> struct hash<basic_string<wchar_t, char_traits<wchar_t>, A>>;
If S is one of these string types,SV is the corresponding string view type, ands is an object of type S, then hash<S>()(s) == hash<SV>()(SV(s)).
27.4.7 Suffix for basic_string literals [basic.string.literals]
constexpr string operator""s(const char* str, size_t len);
Returns: string{str, len}.
constexpr u8string operator""s(const char8_t* str, size_t len);
Returns: u8string{str, len}.
constexpr u16string operator""s(const char16_t* str, size_t len);
Returns: u16string{str, len}.
constexpr u32string operator""s(const char32_t* str, size_t len);
Returns: u32string{str, len}.
constexpr wstring operator""s(const wchar_t* str, size_t len);
Returns: wstring{str, len}.
[Note 1:
The same suffix s is used for chrono::duration literals denoting seconds but there is no conflict, since duration suffixes apply to numbers and string literal suffixes apply to character array literals.
— _end note_]
27.5 Null-terminated sequence utilities [c.strings]
27.5.1 Header synopsis [cstring.syn]
#define __STDC_VERSION_STRING_H__ 202311L namespace std { using size_t = see [support.types.layout]; void* memcpy(void* s1, const void* s2, size_t n); void* memccpy(void* s1, const void* s2, int c, size_t n); void* memmove(void* s1, const void* s2, size_t n); char* strcpy(char* s1, const char* s2); char* strncpy(char* s1, const char* s2, size_t n); char* strdup(const char* s);char* strndup(const char* s, size_t size);char* strcat(char* s1, const char* s2); char* strncat(char* s1, const char* s2, size_t n); int memcmp(const void* s1, const void* s2, size_t n); int strcmp(const char* s1, const char* s2); int strcoll(const char* s1, const char* s2);int strncmp(const char* s1, const char* s2, size_t n); size_t strxfrm(char* s1, const char* s2, size_t n);const void* memchr(const void* s, int c, size_t n); void* memchr(void* s, int c, size_t n); const char* strchr(const char* s, int c); char* strchr(char* s, int c); size_t strcspn(const char* s1, const char* s2); const char* strpbrk(const char* s1, const char* s2); char* strpbrk(char* s1, const char* s2); const char* strrchr(const char* s, int c); char* strrchr(char* s, int c); size_t strspn(const char* s1, const char* s2); const char* strstr(const char* s1, const char* s2); char* strstr(char* s1, const char* s2); char* strtok(char* s1, const char* s2);void* memset(void* s, int c, size_t n); void* memset_explicit(void* s, int c, size_t n); char* strerror(int errnum); size_t strlen(const char* s); } #define NULL see [support.types.nullptr]
The contents and meaning of the header are the same as the C standard library header .
The functions memcpy and memmove are signal-safe.
Each of these functions implicitly creates objects ([intro.object]) in the destination region of storage immediately prior to copying the sequence of characters to the destination.
Each of these functions returns a pointer to a suitable created object, if any, otherwise the value of the first parameter.
[Note 1:
The functionsstrchr, strpbrk, strrchr, strstr, and memchr, have different signatures in this document, but they have the same behavior as in the C standard library.
— _end note_]
See also: ISO/IEC 9899:2024, 7.26