21 Strings library [strings]

21.1 General [strings.general]

1
#
This Clause describes components for manipulating sequences of any non-array trivial standard-layout ([basic.types]) type.
Such types are called char-like types, and objects of char-like types are called char-like objects or simply characters.
2
#
The following subclauses describe a character traits class, string classes, and null-terminated sequence utilities, as summarized in Table 68.
Table 68: Strings library summary   [tab:strings.summary]
Subclause
Header
Character traits
<string>
String classes
String view classes
<string_­view>
Null-terminated sequence utilities
<cctype>, <cstdlib>, <cstring>, <cuchar>, <cwchar>, <cwctype>

21.2 Character traits [char.traits]

1
#
This subclause defines requirements on classes representing character traits, and defines a class template char_­traits<charT>, along with five specializations, char_­traits<char>, char_­traits<char8_­t>, char_­traits<char16_­t>, char_­traits<char32_­t>, and char_­traits<wchar_­t>, that meet those requirements.
2
#
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.
This subclause defines the semantics of these members.
3
#
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 class X are passed as a pair of parameters to the string, string view, or iostream template as parameters charT and traits.
If X​::​char_­type is not the same type as C, the program is ill-formed.

21.2.1 Character traits requirements [char.traits.require]

1
#
In Table 69, X denotes a traits class defining types and functions for the character container type C; c and d denote values of type C; p and q denote values of type const C*; s denotes a value of type C*; n, i and j denote values of type size_­t; e and f denote values of type X​::​int_­type; pos denotes a value of type X​::​pos_­type; and r denotes an lvalue of type C.
Operations on X shall not throw exceptions.
Table 69: Character traits requirements   [tab:char.traits.req]
Expression
Return type
Assertion/note
Complexity
pre-/post-condition
X​::​char_­type
C
compile-time
X​::​int_­type
(described in [char.traits.typedefs])
compile-time
X​::​off_­type
compile-time
X​::​pos_­type
compile-time
X​::​state_­type
(described in [char.traits.typedefs])
compile-time
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 that X​::​eq(*q,c) is true, zero 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: p not in [s, s+n).

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), performs X​::​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 that X​::​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 of to_­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 to X​::​eq_­int_­type(X​::​to_­int_­type(c), X​::​to_­int_­type(d)); otherwise, yields true if e and f are both copies of X​::​eof(); otherwise, yields false if one of e and f is a copy of X​::​eof() and the other is not; otherwise the value is unspecified.
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
2
#
The class template 
template<class charT> struct char_traits;
is provided in the header <string> as a basis for explicit specializations.

21.2.2 Traits typedefs [char.traits.typedefs]

🔗
using int_type = see below;
1
#
Preconditions: int_­type shall be able to represent all of the valid characters converted from the corresponding char_­type values, as well as an end-of-file value, eof().221
🔗
using state_type = see below;
2
#
Preconditions: state_­type meets the Cpp17Destructible (Table 32), Cpp17CopyAssignable (Table 31), Cpp17CopyConstructible (Table 29), and Cpp17DefaultConstructible (Table 27) requirements.
221)
If eof() can be held in char_­type then some iostreams operations can give surprising results.
⮥

21.2.3 char_­traits specializations [char.traits.specializations]

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>;
}
1
#
The header <string> defines five specializations of the class template char_­traits: char_­traits<​char>, char_­traits<char8_­t>, char_­traits<char16_­t>, char_­traits<char32_­t>, and char_­traits<wchar_­t>.

21.2.3.1 struct char_­traits<char> [char.traits.specializations.char]

namespace std {
  template<> struct char_traits<char> {
    using char_type  = char;
    using int_type   = int;
    using off_type   = streamoff;
    using pos_type   = streampos;
    using state_type = mbstate_t;
    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;
  };
}
1
#
The type mbstate_­t is defined in <cwchar> and can represent any of the conversion states that can occur in an implementation-defined set of supported multibyte character encoding rules.
2
#
The two-argument member assign is defined identically to the built-in operator =.
The two-argument members eq and lt are defined identically to the built-in operators == and < for type unsigned char.
3
#
The member eof() returns EOF.

21.2.3.2 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;
  };
}
1
#
The two-argument members assign, eq, and lt are defined identically to the built-in operators =, ==, and < respectively.
2
#
The member eof() returns an implementation-defined constant that cannot appear as a valid UTF-8 code unit.

21.2.3.3 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;
  };
}
1
#
The two-argument members assign, eq, and lt are defined identically to the built-in operators =, ==, and <, respectively.
2
#
The member eof() returns an implementation-defined constant that cannot appear as a valid UTF-16 code unit.

21.2.3.4 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;
  };
}
1
#
The two-argument members assign, eq, and lt are defined identically to the built-in operators =, ==, and <, respectively.
2
#
The member eof() returns an implementation-defined constant that cannot appear as a Unicode code point.

21.2.3.5 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;
  };
}
1
#
The two-argument members assign, eq, and lt are defined identically to the built-in operators =, ==, and <, respectively.
2
#
The member eof() returns WEOF.

21.3 String classes [string.classes]

1
#
The header <string> defines the basic_­string class template for manipulating varying-length sequences of char-like objects and five typedef-names, string, u8string, u16string, u32string, and wstring, that name the specializations basic_­string<char>, basic_­string<char8_­t>, basic_­string<char16_­t>, basic_­string<char32_­t>, and basic_­string<​wchar_­t>, respectively.

21.3.1 Header <string> synopsis [string.syn]

#include <compare>              // see [compare.syn]
#include <initializer_list>     // see [initializer.list.syn]

namespace std {
  // [char.traits], character traits
  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>;

  // [basic.string], basic_­string
  template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
    class basic_string;

  template<class charT, class traits, class Allocator>
    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 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);

  // [string.special], swap
  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)));

  // [string.io], inserters and extractors
  template<class charT, class traits, class Allocator>
    basic_istream<charT, traits>&
      operator>>(basic_istream<charT, traits>& is,
                 basic_string<charT, traits, Allocator>& str);
  template<class charT, class traits, class Allocator>
    basic_ostream<charT, traits>&
      operator<<(basic_ostream<charT, traits>& os,
                 const basic_string<charT, traits, Allocator>& str);
  template<class charT, class traits, class Allocator>
    basic_istream<charT, traits>&
      getline(basic_istream<charT, traits>& is,
              basic_string<charT, traits, Allocator>& str,
              charT delim);
  template<class charT, class traits, class Allocator>
    basic_istream<charT, traits>&
      getline(basic_istream<charT, traits>&& is,
              basic_string<charT, traits, Allocator>& str,
              charT delim);
  template<class charT, class traits, class Allocator>
    basic_istream<charT, traits>&
      getline(basic_istream<charT, traits>& is,
              basic_string<charT, traits, Allocator>& str);
  template<class charT, class traits, class Allocator>
    basic_istream<charT, traits>&
      getline(basic_istream<charT, traits>&& is,
              basic_string<charT, traits, Allocator>& str);

  // [string.erasure], erasure
  template<class charT, class traits, class Allocator, class U>
    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);

  // basic_­string typedef names
  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>;

  // [string.conversions], numeric conversions
  int stoi(const string& str, size_t* idx = nullptr, int base = 10);
  long stol(const string& str, size_t* idx = nullptr, int base = 10);
  unsigned long stoul(const string& str, size_t* idx = nullptr, int base = 10);
  long long stoll(const string& str, size_t* idx = nullptr, int base = 10);
  unsigned long long stoull(const string& str, size_t* idx = nullptr, int base = 10);
  float stof(const string& str, size_t* idx = nullptr);
  double stod(const string& str, size_t* idx = nullptr);
  long double stold(const string& str, size_t* idx = nullptr);
  string to_string(int val);
  string to_string(unsigned val);
  string to_string(long val);
  string to_string(unsigned long val);
  string to_string(long long val);
  string to_string(unsigned long long val);
  string to_string(float val);
  string to_string(double val);
  string to_string(long double val);

  int stoi(const wstring& str, size_t* idx = nullptr, int base = 10);
  long stol(const wstring& str, size_t* idx = nullptr, int base = 10);
  unsigned long stoul(const wstring& str, size_t* idx = nullptr, int base = 10);
  long long stoll(const wstring& str, size_t* idx = nullptr, int base = 10);
  unsigned long long stoull(const wstring& str, size_t* idx = nullptr, int base = 10);
  float stof(const wstring& str, size_t* idx = nullptr);
  double stod(const wstring& str, size_t* idx = nullptr);
  long double stold(const wstring& str, size_t* idx = nullptr);
  wstring to_wstring(int val);
  wstring to_wstring(unsigned val);
  wstring to_wstring(long val);
  wstring to_wstring(unsigned long val);
  wstring to_wstring(long long val);
  wstring to_wstring(unsigned long long val);
  wstring to_wstring(float val);
  wstring to_wstring(double val);
  wstring to_wstring(long double val);

  namespace pmr {
    template<class charT, class traits = char_traits<charT>>
      using basic_string = std::basic_string<charT, traits, polymorphic_allocator<charT>>;

    using string    = basic_string<char>;
    using u8string  = basic_string<char8_t>;
    using u16string = basic_string<char16_t>;
    using u32string = basic_string<char32_t>;
    using wstring   = basic_string<wchar_t>;
  }

  // [basic.string.hash], hash support
  template<class T> struct hash;
  template<> struct hash<string>;
  template<> struct hash<u8string>;
  template<> struct hash<u16string>;
  template<> struct hash<u32string>;
  template<> struct hash<wstring>;
  template<> struct hash<pmr::string>;
  template<> struct hash<pmr::u8string>;
  template<> struct hash<pmr::u16string>;
  template<> struct hash<pmr::u32string>;
  template<> struct hash<pmr::wstring>;

  inline namespace literals {
  inline namespace string_literals {
    // [basic.string.literals], suffix for basic_­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);
  }
  }
}

21.3.2 Class template basic_­string [basic.string]

1
#
The class template basic_­string describes objects that can store a sequence consisting of a varying number of arbitrary char-like objects with the first element of the sequence at position zero.
Such a sequence is also called a “string” if the type of the char-like objects that it holds is clear from context.
In the rest of this Clause, the type of the char-like objects held in a basic_­string object is designated by charT.
2
#
A specialization of basic_­string is a contiguous container ([container.requirements.general]).
3
#
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:
    // types
    using traits_type            = traits;
    using value_type             = charT;
    using allocator_type         = Allocator;
    using size_type              = typename allocator_traits<Allocator>::size_type;
    using difference_type        = typename allocator_traits<Allocator>::difference_type;
    using pointer                = typename allocator_traits<Allocator>::pointer;
    using const_pointer          = typename allocator_traits<Allocator>::const_pointer;
    using reference              = value_type&;
    using const_reference        = const value_type&;

    using iterator               = implementation-defined; // see [container.requirements]
    using const_iterator         = implementation-defined; // see [container.requirements]
    using reverse_iterator       = std::reverse_iterator<iterator>;
    using const_reverse_iterator = std::reverse_iterator<const_iterator>;
    static const size_type npos  = -1;

    // [string.cons], construct/copy/destroy
    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());
    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());
    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());
    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);
    constexpr basic_string& operator=(charT c);
    constexpr basic_string& operator=(initializer_list<charT>);

    // [string.iterators], iterators
    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;

    // [string.capacity], capacity
    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);
    constexpr size_type capacity() const noexcept;
    constexpr void reserve(size_type res_arg);
    constexpr void shrink_to_fit();
    constexpr void clear() noexcept;
    [[nodiscard]] constexpr bool empty() const noexcept;

    // [string.access], element access
    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();

    // [string.modifiers], modifiers
    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);
    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);
    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);
    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);
    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);

    // [string.ops], string operations
    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;

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

  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<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>;
}
4
#
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.

21.3.2.1 General requirements [string.require]

1
#
If any operation would cause size() to exceed max_­size(), that operation throws an exception object of type length_­error.
2
#
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.
3
#
In every specialization basic_­string<charT, traits, Allocator>, the type allocator_­traits<Allocator>​::​value_­type shall name the same type as charT.
Every object of type basic_­string<charT, traits, Allocator> uses an object of type Allocator to allocate and free storage for the contained charT objects as needed.
The Allocator object used is obtained as described in [container.requirements.general].
In every specialization basic_­string<charT, traits, Allocator>, the type traits shall meet the character traits requirements ([char.traits]).
[Note
:
The program is ill-formed if traits​::​char_­type is not the same type as charT.
— end note
]
4
#
References, pointers, and iterators referring to the elements of a basic_­string sequence may be invalidated by the following uses of that basic_­string object:
  • (4.1)
    Passing as an argument to any standard library function taking a reference to non-const basic_­string as an argument.222
  • (4.2)
    Calling non-const member functions, except operator[], at, data, front, back, begin, rbegin, end, and rend.
222)
For example, as an argument to non-member functions swap(), operator>>(), and getline(), or as an argument to basic_­string​::​swap().
⮥

21.3.2.2 Constructors and assignment operators [string.cons]

🔗
constexpr explicit basic_string(const Allocator& a) noexcept;
1
#
Postconditions: size() is equal to 0.
🔗
constexpr basic_string(const basic_string& str); constexpr basic_string(basic_string&& str) noexcept;
2
#
Effects: Constructs an object whose value is that of str prior to this call.
3
#
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());
4
#
Effects: Let n be npos for the first overload.
Equivalent to: 
basic_string(basic_string_view<charT, traits>(str).substr(pos, n), a)
🔗
template<class T> constexpr basic_string(const T& t, size_type pos, size_type n, const Allocator& a = Allocator());
5
#
Constraints: is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true.
6
#
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());
7
#
Constraints:
  • (7.1)
    is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and
  • (7.2)
    is_­convertible_­v<const T&, const charT*> is false.
8
#
Effects: Creates a variable, sv, as if by basic_­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());
9
#
Preconditions: [s, s + n) is a valid range.
10
#
Effects: Constructs an object whose initial value is the range [s, s + n).
11
#
Postconditions: size() is equal to n, and traits​::​compare(data(), s, n) is equal to 0.
🔗
constexpr basic_string(const charT* s, const Allocator& a = Allocator());
12
#
Constraints: Allocator is a type that qualifies as an allocator ([container.requirements.general]).
[Note
:
This affects class template argument deduction.
— end note
]
13
#
Effects: Equivalent to: basic_­string(s, traits​::​length(s), a).
🔗
constexpr basic_string(size_type n, charT c, const Allocator& a = Allocator());
14
#
Constraints: Allocator is a type that qualifies as an allocator ([container.requirements.general]).
[Note
:
This affects class template argument deduction.
— end note
]
15
#
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());
16
#
Constraints: InputIterator is a type that qualifies as an input iterator ([container.requirements.general]).
17
#
Effects: Constructs a string from the values in the range [begin, end), as indicated in Table 77.
🔗
constexpr basic_string(initializer_list<charT> il, const Allocator& a = Allocator());
18
#
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);
19
#
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.
20
#
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>;
21
#
Constraints: InputIterator is a type that qualifies as an input iterator, and Allocator is a type that qualifies as an allocator ([container.requirements.general]).
🔗
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>;
22
#
Constraints: Allocator is a type that qualifies as an allocator ([container.requirements.general]).
🔗
constexpr basic_string& operator=(const basic_string& str);
23
#
Effects: If *this and str are the same object, has no effect.
Otherwise, replaces the value of *this with a copy of str.
24
#
Returns: *this.
🔗
constexpr basic_string& operator=(basic_string&& str) noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value || allocator_traits<Allocator>::is_always_equal::value);
25
#
Effects: Move assigns as a sequence container, except that iterators, pointers and references may be invalidated.
26
#
Returns: *this.
🔗
template<class T> constexpr basic_string& operator=(const T& t);
27
#
Constraints:
  • (27.1)
    is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and
  • (27.2)
    is_­convertible_­v<const T&, const charT*> is false.
28
#
Effects: Equivalent to: 
basic_string_view<charT, traits> sv = t;
return assign(sv);
🔗
constexpr basic_string& operator=(const charT* s);
29
#
Effects: Equivalent to: return *this = basic_­string_­view<charT, traits>(s);
🔗
constexpr basic_string& operator=(charT c);
30
#
Effects: Equivalent to: 
return *this = basic_string_view<charT, traits>(addressof(c), 1);
🔗
constexpr basic_string& operator=(initializer_list<charT> il);
31
#
Effects: Equivalent to: 
return *this = basic_string_view<charT, traits>(il.begin(), il.size());

21.3.2.3 Iterator support [string.iterators]

🔗
constexpr iterator begin() noexcept; constexpr const_iterator begin() const noexcept; constexpr const_iterator cbegin() const noexcept;
1
#
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;
2
#
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;
3
#
Returns: An iterator which is semantically equivalent to reverse_­iterator(end()).
🔗
constexpr reverse_iterator rend() noexcept; constexpr const_reverse_iterator rend() const noexcept; constexpr const_reverse_iterator crend() const noexcept;
4
#
Returns: An iterator which is semantically equivalent to reverse_­iterator(begin()).

21.3.2.4 Capacity [string.capacity]

🔗
constexpr size_type size() const noexcept; constexpr size_type length() const noexcept;
1
#
Returns: A count of the number of char-like objects currently in the string.
2
#
Complexity: Constant time.
🔗
constexpr size_type max_size() const noexcept;
3
#
Returns: The largest possible number of char-like objects that can be stored in a basic_­string.
4
#
Complexity: Constant time.
🔗
constexpr void resize(size_type n, charT c);
5
#
Effects: Alters the value of *this as follows:
  • (5.1)
    If n <= size(), erases the last size() - n elements.
  • (5.2)
    If n > size(), appends n - size() copies of c.
🔗
constexpr void resize(size_type n);
6
#
Effects: Equivalent to resize(n, charT()).
🔗
constexpr size_type capacity() const noexcept;
7
#
Returns: The size of the allocated storage in the string.
8
#
Complexity: Constant time.
🔗
constexpr void reserve(size_type res_arg);
9
#
Effects: A directive that informs a basic_­string of a planned change in size, so that the storage allocation can be managed accordingly.
After reserve(), capacity() is greater or equal to the argument of reserve if reallocation happens; and equal to the previous value of capacity() otherwise.
Reallocation happens at this point if and only if the current capacity is less than the argument of reserve().
10
#
Throws: length_­error if res_­arg > max_­size() or any exceptions thrown by allocator_­traits <Allocator>​::​allocate.
🔗
constexpr void shrink_to_fit();
11
#
Effects: shrink_­to_­fit is a non-binding request to reduce capacity() to size().
[Note
:
The request is non-binding to allow latitude for implementation-specific optimizations.
— end note
]
It does not increase capacity(), but may reduce capacity() by causing reallocation.
12
#
Complexity: If the size is not equal to the old capacity, linear in the size of the sequence; otherwise constant.
13
#
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
:
If no reallocation happens, they remain valid.
— end note
]
🔗
constexpr void clear() noexcept;
14
#
Effects: Equivalent to: erase(begin(), end());
🔗
[[nodiscard]] constexpr bool empty() const noexcept;
15
#
Effects: Equivalent to: return size() == 0;

21.3.2.5 Element access [string.access]

🔗
constexpr const_reference operator[](size_type pos) const; constexpr reference operator[](size_type pos);
1
#
Preconditions: pos <= size().
2
#
Returns: *(begin() + pos) if pos < size().
Otherwise, returns a reference to an object of type charT with value charT(), where modifying the object to any value other than charT() leads to undefined behavior.
3
#
Throws: Nothing.
4
#
Complexity: Constant time.
🔗
constexpr const_reference at(size_type pos) const; constexpr reference at(size_type pos);
5
#
Throws: out_­of_­range if pos >= size().
6
#
Returns: operator[](pos).
🔗
constexpr const charT& front() const; constexpr charT& front();
7
#
Preconditions: !empty().
8
#
Effects: Equivalent to: return operator[](0);
🔗
constexpr const charT& back() const; constexpr charT& back();
9
#
Preconditions: !empty().
10
#
Effects: Equivalent to: return operator[](size() - 1);

21.3.2.6 Modifiers [string.modifiers]

21.3.2.6.1 basic_­string​::​operator+= [string.op.append]

🔗
constexpr basic_string& operator+=(const basic_string& str);
1
#
Effects: Equivalent to: return append(str);
🔗
template<class T> constexpr basic_string& operator+=(const T& t);
2
#
Constraints:
  • (2.1)
    is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and
  • (2.2)
    is_­convertible_­v<const T&, const charT*> is false.
3
#
Effects: Equivalent to: 
basic_string_view<charT, traits> sv = t;
return append(sv);
🔗
constexpr basic_string& operator+=(const charT* s);
4
#
Effects: Equivalent to: return append(s);
🔗
constexpr basic_string& operator+=(charT c);
5
#
Effects: Equivalent to: return append(size_­type{1}, c);
🔗
constexpr basic_string& operator+=(initializer_list<charT> il);
6
#
Effects: Equivalent to: return append(il);

21.3.2.6.2 basic_­string​::​append [string.append]

🔗
constexpr basic_string& append(const basic_string& str);
1
#
Effects: Equivalent to: return append(str.data(), str.size());
🔗
constexpr basic_string& append(const basic_string& str, size_type pos, size_type n = npos);
2
#
Effects: Equivalent to: 
return append(basic_string_view<charT, traits>(str).substr(pos, n));
🔗
template<class T> constexpr basic_string& append(const T& t);
3
#
Constraints:
  • (3.1)
    is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and
  • (3.2)
    is_­convertible_­v<const T&, const charT*> is false.
4
#
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);
5
#
Constraints:
  • (5.1)
    is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and
  • (5.2)
    is_­convertible_­v<const T&, const charT*> is false.
6
#
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);
7
#
Preconditions: [s, s + n) is a valid range.
8
#
Effects: Appends a copy of the range [s, s + n) to the string.
9
#
Returns: *this.
🔗
constexpr basic_string& append(const charT* s);
10
#
Effects: Equivalent to: return append(s, traits​::​length(s));
🔗
constexpr basic_string& append(size_type n, charT c);
11
#
Effects: Appends n copies of c to the string.
12
#
Returns: *this.
🔗
template<class InputIterator> constexpr basic_string& append(InputIterator first, InputIterator last);
13
#
Constraints: InputIterator is a type that qualifies as an input iterator ([container.requirements.general]).
14
#
Effects: Equivalent to: return append(basic_­string(first, last, get_­allocator()));
🔗
constexpr basic_string& append(initializer_list<charT> il);
15
#
Effects: Equivalent to: return append(il.begin(), il.size());
🔗
constexpr void push_back(charT c);
16
#
Effects: Equivalent to append(size_­type{1}, c).

21.3.2.6.3 basic_­string​::​assign [string.assign]

🔗
constexpr basic_string& assign(const basic_string& str);
1
#
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);
2
#
Effects: Equivalent to: return *this = std​::​move(str);
🔗
constexpr basic_string& assign(const basic_string& str, size_type pos, size_type n = npos);
3
#
Effects: Equivalent to: 
return assign(basic_string_view<charT, traits>(str).substr(pos, n));
🔗
template<class T> constexpr basic_string& assign(const T& t);
4
#
Constraints:
  • (4.1)
    is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and
  • (4.2)
    is_­convertible_­v<const T&, const charT*> is false.
5
#
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);
6
#
Constraints:
  • (6.1)
    is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and
  • (6.2)
    is_­convertible_­v<const T&, const charT*> is false.
7
#
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);
8
#
Preconditions: [s, s + n) is a valid range.
9
#
Effects: Replaces the string controlled by *this with a copy of the range [s, s + n).
10
#
Returns: *this.
🔗
constexpr basic_string& assign(const charT* s);
11
#
Effects: Equivalent to: return assign(s, traits​::​length(s));
🔗
constexpr basic_string& assign(initializer_list<charT> il);
12
#
Effects: Equivalent to: return assign(il.begin(), il.size());
🔗
constexpr basic_string& assign(size_type n, charT c);
13
#
Effects: Equivalent to: 
clear();
resize(n, c);
return *this;
🔗
template<class InputIterator> constexpr basic_string& assign(InputIterator first, InputIterator last);
14
#
Constraints: InputIterator is a type that qualifies as an input iterator ([container.requirements.general]).
15
#
Effects: Equivalent to: return assign(basic_­string(first, last, get_­allocator()));

21.3.2.6.4 basic_­string​::​insert [string.insert]

🔗
constexpr basic_string& insert(size_type pos, const basic_string& str);
1
#
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);
2
#
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);
3
#
Constraints:
  • (3.1)
    is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and
  • (3.2)
    is_­convertible_­v<const T&, const charT*> is false.
4
#
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);
5
#
Constraints:
  • (5.1)
    is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and
  • (5.2)
    is_­convertible_­v<const T&, const charT*> is false.
6
#
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);
7
#
Preconditions: [s, s + n) is a valid range.
8
#
Throws:
  • (8.1)
    out_­of_­range if pos > size(),
  • (8.2)
    length_­error if n > max_­size() - size(), or
  • (8.3)
    any exceptions thrown by allocator_­traits<Allocator>​::​allocate.
9
#
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.
10
#
Returns: *this.
🔗
constexpr basic_string& insert(size_type pos, const charT* s);
11
#
Effects: Equivalent to: return insert(pos, s, traits​::​length(s));
🔗
constexpr basic_string& insert(size_type pos, size_type n, charT c);
12
#
Effects: Inserts n copies of c before the character at position pos if pos < size(), or otherwise at the end of the string.
13
#
Returns: *this
14
#
Throws:
  • (14.1)
    out_­of_­range if pos > size(),
  • (14.2)
    length_­error if n > max_­size() - size(), or
  • (14.3)
    any exceptions thrown by allocator_­traits<Allocator>​::​allocate.
🔗
constexpr iterator insert(const_iterator p, charT c);
15
#
Preconditions: p is a valid iterator on *this.
16
#
Effects: Inserts a copy of c at the position p.
17
#
Returns: An iterator which refers to the inserted character.
🔗
constexpr iterator insert(const_iterator p, size_type n, charT c);
18
#
Preconditions: p is a valid iterator on *this.
19
#
Effects: Inserts n copies of c at the position p.
20
#
Returns: An iterator which refers to the first inserted character, or p if n == 0.
🔗
template<class InputIterator> constexpr iterator insert(const_iterator p, InputIterator first, InputIterator last);
21
#
Constraints: InputIterator is a type that qualifies as an input iterator ([container.requirements.general]).
22
#
Preconditions: p is a valid iterator on *this.
23
#
Effects: Equivalent to insert(p - begin(), basic_­string(first, last, get_­allocator())).
24
#
Returns: An iterator which refers to the first inserted character, or p if first == last.
🔗
constexpr iterator insert(const_iterator p, initializer_list<charT> il);
25
#
Effects: Equivalent to: return insert(p, il.begin(), il.end());

21.3.2.6.5 basic_­string​::​erase [string.erase]

🔗
constexpr basic_string& erase(size_type pos = 0, size_type n = npos);
1
#
Throws: out_­of_­range if pos > size().
2
#
Effects: Determines the effective length xlen of the string to be removed as the smaller of n and size() - pos.
Removes the characters in the range [begin() + pos, begin() + pos + xlen).
3
#
Returns: *this.
🔗
constexpr iterator erase(const_iterator p);
4
#
Preconditions: p is a valid dereferenceable iterator on *this.
5
#
Throws: Nothing.
6
#
Effects: Removes the character referred to by p.
7
#
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);
8
#
Preconditions: first and last are valid iterators on *this.
[first, last) is a valid range.
9
#
Throws: Nothing.
10
#
Effects: Removes the characters in the range [first, last).
11
#
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();
12
#
Preconditions: !empty().
13
#
Throws: Nothing.
14
#
Effects: Equivalent to erase(end() - 1).

21.3.2.6.6 basic_­string​::​replace [string.replace]

🔗
constexpr basic_string& replace(size_type pos1, size_type n1, const basic_string& str);
1
#
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);
2
#
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);
3
#
Constraints:
  • (3.1)
    is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and
  • (3.2)
    is_­convertible_­v<const T&, const charT*> is false.
4
#
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);
5
#
Constraints:
  • (5.1)
    is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and
  • (5.2)
    is_­convertible_­v<const T&, const charT*> is false.
6
#
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);
7
#
Preconditions: [s, s + n2) is a valid range.
8
#
Throws:
  • (8.1)
    out_­of_­range if pos1 > size(),
  • (8.2)
    length_­error if the length of the resulting string would exceed max_­size() (see below), or
  • (8.3)
    any exceptions thrown by allocator_­traits<Allocator>​::​allocate.
9
#
Effects: Determines the effective length xlen of the string to be removed as the smaller of n1 and size() - pos1.
If size() - 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).
10
#
Returns: *this.
🔗
constexpr basic_string& replace(size_type pos, size_type n, const charT* s);
11
#
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);
12
#
Throws:
  • (12.1)
    out_­of_­range if pos1 > size(),
  • (12.2)
    length_­error if the length of the resulting string would exceed max_­size() (see below), or
  • (12.3)
    any exceptions thrown by allocator_­traits<Allocator>​::​allocate.
13
#
Effects: Determines the effective length xlen of the string to be removed as the smaller of n1 and size() - pos1.
If size() - 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.
14
#
Returns: *this.
🔗
constexpr basic_string& replace(const_iterator i1, const_iterator i2, const basic_string& str);
15
#
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);
16
#
Constraints:
  • (16.1)
    is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and
  • (16.2)
    is_­convertible_­v<const T&, const charT*> is false.
17
#
Preconditions: [begin(), i1) and [i1, i2) are valid ranges.
18
#
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);
19
#
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);
20
#
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);
21
#
Preconditions: [begin(), i1) and [i1, i2) are valid ranges.
22
#
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);
23
#
Constraints: InputIterator is a type that qualifies as an input iterator ([container.requirements.general]).
24
#
Effects: Equivalent to: return replace(i1, i2, basic_­string(j1, j2, get_­allocator()));
🔗
constexpr basic_string& replace(const_iterator i1, const_iterator i2, initializer_list<charT> il);
25
#
Effects: Equivalent to: return replace(i1, i2, il.begin(), il.size());

21.3.2.6.7 basic_­string​::​copy [string.copy]

🔗
constexpr size_type copy(charT* s, size_type n, size_type pos = 0) const;
1
#
Effects: Equivalent to: return basic_­string_­view<charT, traits>(*this).copy(s, n, pos);
[Note
: This does not terminate s with a null object. — end note
]

21.3.2.6.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);
1
#
Preconditions: allocator_­traits<Allocator>​::​propagate_­on_­container_­swap​::​value is true or get_­allocator() == s.get_­allocator().
2
#
Postconditions: *this contains the same sequence of characters that was in s, s contains the same sequence of characters that was in *this.
3
#
Throws: Nothing.
4
#
Complexity: Constant time.

21.3.2.7 String operations [string.ops]

21.3.2.7.1 Accessors [string.accessors]

🔗
constexpr const charT* c_str() const noexcept; constexpr const charT* data() const noexcept;
1
#
Returns: A pointer p such that p + i == addressof(operator[](i)) for each i in [0, size()].
2
#
Complexity: Constant time.
3
#
Remarks: The program shall not modify any of the values stored in the character array; otherwise, the behavior is undefined.
🔗
constexpr charT* data() noexcept;
4
#
Returns: A pointer p such that p + i == addressof(operator[](i)) for each i in [0, size()].
5
#
Complexity: Constant time.
6
#
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;
7
#
Effects: Equivalent to: return basic_­string_­view<charT, traits>(data(), size());
🔗
constexpr allocator_type get_allocator() const noexcept;
8
#
Returns: A copy of the Allocator object used to construct the string or, if that allocator has been replaced, a copy of the most recent replacement.

21.3.2.7.2 Searching [string.find]

1
#
Let F be one of find, rfind, find_­first_­of, find_­last_­of, find_­first_­not_­of, and find_­last_­not_­of.
  • (1.1)
    Each member function of the form 
    constexpr 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);
  • (1.2)
    Each member function of the form 
    constexpr size_type F(const charT* s, size_type pos) const;
    has effects equivalent to: return F(basic_­string_­view<charT, traits>(s), pos);
  • (1.3)
    Each member function of the form 
    constexpr 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);
  • (1.4)
    Each member function of the form 
    constexpr 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);
2
#
Constraints:
  • (2.1)
    is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and
  • (2.2)
    is_­convertible_­v<const T&, const charT*> is false.
3
#
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);
4
#
Remarks: The expression inside noexcept is equivalent to is_­nothrow_­convertible_­v<const T&, basic_­string_­view<charT, traits>>.

21.3.2.7.3 basic_­string​::​substr [string.substr]

🔗
constexpr basic_string substr(size_type pos = 0, size_type n = npos) const;
1
#
Throws: out_­of_­range if pos > size().
2
#
Effects: Determines the effective length rlen of the string to copy as the smaller of n and size() - pos.
3
#
Returns: basic_­string(data()+pos, rlen).

21.3.2.7.4 basic_­string​::​compare [string.compare]

🔗
template<class T> constexpr int compare(const T& t) const noexcept(see below);
1
#
Constraints:
  • (1.1)
    is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and
  • (1.2)
    is_­convertible_­v<const T&, const charT*> is false.
2
#
Effects: Equivalent to: return basic_­string_­view<charT, traits>(*this).compare(t);
3
#
Remarks: The expression inside noexcept is equivalent to is_­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;
4
#
Constraints:
  • (4.1)
    is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and
  • (4.2)
    is_­convertible_­v<const T&, const charT*> is false.
5
#
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;
6
#
Constraints:
  • (6.1)
    is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and
  • (6.2)
    is_­convertible_­v<const T&, const charT*> is false.
7
#
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;
8
#
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;
9
#
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;
10
#
Effects: Equivalent to: 
return compare(pos1, n1, basic_string_view<charT, traits>(str), pos2, n2);
🔗
constexpr int compare(const charT* s) const;
11
#
Effects: Equivalent to: return compare(basic_­string_­view<charT, traits>(s));
🔗
constexpr int compare(size_type pos, size_type n1, const charT* s) const;
12
#
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;
13
#
Effects: Equivalent to: return compare(pos, n1, basic_­string_­view<charT, traits>(s, n2));

21.3.2.7.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;
1
#
Effects: Equivalent to: 
return basic_string_view<charT, traits>(data(), size()).starts_with(x);

21.3.2.7.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;
1
#
Effects: Equivalent to: 
return basic_string_view<charT, traits>(data(), size()).ends_with(x);

21.3.3 Non-member functions [string.nonmembers]

21.3.3.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);
1
#
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);
2
#
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);
3
#
Effects: Equivalent to: 
lhs.append(rhs);
return std::move(lhs);
except that both lhs and rhs are left in valid but unspecified states.
[Note
:
If lhs and rhs have equal allocators, the implementation may 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);
4
#
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);
5
#
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);
6
#
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);
7
#
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);
8
#
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);
9
#
Effects: Equivalent to: 
lhs.push_back(rhs);
return std::move(lhs);

21.3.3.2 Non-member comparison 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);
1
#
Effects: Let op be the operator.
Equivalent to: 
return basic_string_view<charT, traits>(lhs) op basic_string_view<charT, traits>(rhs);

21.3.3.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)));
1
#
Effects: Equivalent to lhs.swap(rhs).

21.3.3.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);
1
#
Effects: Behaves as a formatted input function.
After constructing a sentry object, if the sentry converts to true, calls str.erase() and then extracts characters from is and appends them to str as if by calling str.append(1, c).
If is.width() is greater than zero, the maximum number n of characters appended is is.width(); otherwise n is str.max_­size().
Characters are extracted and appended until any of the following occurs:
  • (1.1)
    n characters are stored;
  • (1.2)
    end-of-file occurs on the input sequence;
  • (1.3)
    isspace(c, is.getloc()) is true for the next available input character c.
2
#
After the last character (if any) is extracted, is.width(0) is called and the sentry object is destroyed.
3
#
If the function extracts no characters, it calls is.setstate(ios_­base​::​failbit), which may throw ios_­base​::​failure ([iostate.flags]).
4
#
Returns: is.
🔗
template<class charT, class traits, class Allocator> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const basic_string<charT, traits, Allocator>& str);
5
#
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);
6
#
Effects: Behaves as an unformatted input function, except that it does not affect the value returned by subsequent calls to basic_­istream<>​::​gcount().
After constructing a sentry object, if the sentry converts to true, calls str.erase() and then extracts characters from is and appends them to str as if by calling str.append(1, c) until any of the following occurs:
  • (6.1)
    end-of-file occurs on the input sequence (in which case, the getline function calls is.setstate(​ios_­base​::​eofbit)).
  • (6.2)
    traits​::​eq(c, delim) for the next available input character c (in which case, c is extracted but not appended) ([iostate.flags])
  • (6.3)
    str.max_­size() characters are stored (in which case, the function calls is.setstate(ios_­base​::​failbit)) ([iostate.flags])
7
#
The conditions are tested in the order shown.
In any case, after the last character is extracted, the sentry object is destroyed.
8
#
If the function extracts no characters, it calls is.setstate(ios_­base​::​failbit) which may throw ios_­base​::​failure ([iostate.flags]).
9
#
Returns: is.
🔗
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);
10
#
Returns: getline(is, str, is.widen('\n')).

21.3.3.5 Erasure [string.erasure]

🔗
template<class charT, class traits, class Allocator, class U> constexpr typename basic_string<charT, traits, Allocator>::size_type erase(basic_string<charT, traits, Allocator>& c, const U& value);
1
#
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);
2
#
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;

21.3.4 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);
1
#
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 *idx the index of the first unconverted element of str.
2
#
Returns: The converted result.
3
#
Throws: invalid_­argument if strtol, strtoul, strtoll, or strtoull reports that no conversion could 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);
4
#
Effects: These functions call strtof(str.c_­str(), ptr), strtod(str.c_­str(), ptr), and strtold(​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.
5
#
Returns: The converted result.
6
#
Throws: invalid_­argument if strtof, strtod, or strtold reports that no conversion could be performed.
Throws out_­of_­range if strtof, strtod, or strtold sets errno to ERANGE or 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);
7
#
Returns: Each function returns a string object holding the character representation of the value of its argument that would be generated by calling sprintf(buf, fmt, val) with a format specifier of "%d", "%u", "%ld", "%lu", "%lld", "%llu", "%f", "%f", or "%Lf", respectively, where buf designates an internal character buffer of sufficient size.
🔗
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);
8
#
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 *idx the index of the first unconverted element of str.
9
#
Returns: The converted result.
10
#
Throws: invalid_­argument if wcstol, wcstoul, wcstoll, or wcstoull reports that no conversion could be performed.
Throws out_­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);
11
#
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 *idx the index of the first unconverted element of str.
12
#
Returns: The converted result.
13
#
Throws: invalid_­argument if wcstof, wcstod, or wcstold reports that no conversion could be performed.
Throws out_­of_­range if wcstof, wcstod, or wcstold 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);
14
#
Returns: Each function returns a wstring object holding the character representation of the value of its argument that would be generated by calling swprintf(buf, buffsz, fmt, val) with a format specifier of L"%d", L"%u", L"%ld", L"%lu", L"%lld", L"%llu", L"%f", L"%f", or L"%Lf", respectively, where buf designates an internal character buffer of sufficient size buffsz.

21.3.5 Hash support [basic.string.hash]

🔗
template<> struct hash<string>; template<> struct hash<u8string>; template<> struct hash<u16string>; template<> struct hash<u32string>; template<> struct hash<wstring>; template<> struct hash<pmr::string>; template<> struct hash<pmr::u8string>; template<> struct hash<pmr::u16string>; template<> struct hash<pmr::u32string>; template<> struct hash<pmr::wstring>;
1
#
If S is one of these string types, SV is the corresponding string view type, and s is an object of type S, then hash<S>()(s) == hash<SV>()(SV(s)).

21.3.6 Suffix for basic_­string literals [basic.string.literals]

🔗
constexpr string operator""s(const char* str, size_t len);
1
#
Returns: string{str, len}.
🔗
constexpr u8string operator""s(const char8_t* str, size_t len);
2
#
Returns: u8string{str, len}.
🔗
constexpr u16string operator""s(const char16_t* str, size_t len);
3
#
Returns: u16string{str, len}.
🔗
constexpr u32string operator""s(const char32_t* str, size_t len);
4
#
Returns: u32string{str, len}.
🔗
constexpr wstring operator""s(const wchar_t* str, size_t len);
5
#
Returns: wstring{str, len}.
6
#
[Note
:
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
]

21.4 String view classes [string.view]

1
#
The class template basic_­string_­view describes an object that can refer to a constant contiguous sequence of char-like objects with the first element of the sequence at position zero.
In the rest of this subclause, the type of the char-like objects held in a basic_­string_­view object is designated by charT.
2
#
[Note
:
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 should define their own implicit conversions to std​::​basic_­string_­view in order to interoperate with these functions.
— end note
]

21.4.1 Header <string_­view> synopsis [string.view.synop]

#include <compare>              // see [compare.syn]

namespace std {
  // [string.view.template], class template basic_­string_­view
  template<class charT, class traits = char_traits<charT>>
  class basic_string_view;

  template<class charT, class traits>
    inline constexpr bool ranges::enable_view<basic_string_view<charT, traits>> = true;
  template<class charT, class traits>
    inline constexpr bool ranges::enable_borrowed_range<basic_string_view<charT, traits>> = true;

  // [string.view.comparison], non-member comparison functions
  template<class charT, class traits>
    constexpr bool operator==(basic_string_view<charT, traits> x,
                              basic_string_view<charT, traits> y) noexcept;
  template<class charT, class traits>
    constexpr see below operator<=>(basic_string_view<charT, traits> x,
                                    basic_string_view<charT, traits> y) noexcept;

  // see [string.view.comparison], sufficient additional overloads of comparison functions

  // [string.view.io], inserters and extractors
  template<class charT, class traits>
    basic_ostream<charT, traits>&
      operator<<(basic_ostream<charT, traits>& os,
                 basic_string_view<charT, traits> str);

  // basic_­string_­view typedef names
  using string_view    = basic_string_view<char>;
  using u8string_view  = basic_string_view<char8_t>;
  using u16string_view = basic_string_view<char16_t>;
  using u32string_view = basic_string_view<char32_t>;
  using wstring_view   = basic_string_view<wchar_t>;

  // [string.view.hash], hash support
  template<class T> struct hash;
  template<> struct hash<string_view>;
  template<> struct hash<u8string_view>;
  template<> struct hash<u16string_view>;
  template<> struct hash<u32string_view>;
  template<> struct hash<wstring_view>;

  inline namespace literals {
  inline namespace string_view_literals {
    // [string.view.literals], suffix for basic_­string_­view literals
    constexpr string_view    operator""sv(const char* str, size_t len) noexcept;
    constexpr u8string_view  operator""sv(const char8_t* str, size_t len) noexcept;
    constexpr u16string_view operator""sv(const char16_t* str, size_t len) noexcept;
    constexpr u32string_view operator""sv(const char32_t* str, size_t len) noexcept;
    constexpr wstring_view   operator""sv(const wchar_t* str, size_t len) noexcept;
  }
  }
}
1
#
The function templates defined in [utility.swap] and [iterator.range] are available when <string_­view> is included.

21.4.2 Class template basic_­string_­view [string.view.template]

namespace std {
  template<class charT, class traits = char_traits<charT>>
  class basic_string_view {
  public:
    // types
    using traits_type            = traits;
    using value_type             = charT;
    using pointer                = value_type*;
    using const_pointer          = const value_type*;
    using reference              = value_type&;
    using const_reference        = const value_type&;
    using const_iterator         = implementation-defined; // see [string.view.iterators]
    using iterator               = const_iterator;223
    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);

    // [string.view.cons], construction and assignment
    constexpr basic_string_view() noexcept;
    constexpr basic_string_view(const basic_string_view&) noexcept = default;
    constexpr basic_string_view& operator=(const basic_string_view&) noexcept = default;
    constexpr basic_string_view(const charT* str);
    constexpr basic_string_view(const charT* str, size_type len);
    template<class It, class End>
      constexpr basic_string_view(It begin, End end);

    // [string.view.iterators], iterator support
    constexpr const_iterator begin() const noexcept;
    constexpr const_iterator end() const noexcept;
    constexpr const_iterator cbegin() const noexcept;
    constexpr const_iterator cend() const noexcept;
    constexpr const_reverse_iterator rbegin() const noexcept;
    constexpr const_reverse_iterator rend() const noexcept;
    constexpr const_reverse_iterator crbegin() const noexcept;
    constexpr const_reverse_iterator crend() const noexcept;

    // [string.view.capacity], capacity
    constexpr size_type size() const noexcept;
    constexpr size_type length() const noexcept;
    constexpr size_type max_size() const noexcept;
    [[nodiscard]] constexpr bool empty() const noexcept;

    // [string.view.access], element access
    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;

    // [string.view.modifiers], modifiers
    constexpr void remove_prefix(size_type n);
    constexpr void remove_suffix(size_type n);
    constexpr void swap(basic_string_view& s) noexcept;

    // [string.view.ops], string operations
    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 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;

    // [string.view.find], searching
    constexpr size_type find(basic_string_view s, size_type pos = 0) const noexcept;
    constexpr size_type find(charT c, size_type pos = 0) const noexcept;
    constexpr size_type find(const charT* s, size_type pos, size_type n) const;
    constexpr size_type find(const charT* s, size_type pos = 0) const;
    constexpr size_type rfind(basic_string_view s, size_type pos = npos) const noexcept;
    constexpr size_type rfind(charT c, size_type pos = npos) const noexcept;
    constexpr size_type rfind(const charT* s, size_type pos, size_type n) const;
    constexpr size_type rfind(const charT* s, size_type pos = npos) const;

    constexpr size_type find_first_of(basic_string_view s, size_type pos = 0) const noexcept;
    constexpr size_type find_first_of(charT c, size_type pos = 0) const noexcept;
    constexpr size_type find_first_of(const charT* s, size_type pos, size_type n) const;
    constexpr size_type find_first_of(const charT* s, size_type pos = 0) const;
    constexpr size_type find_last_of(basic_string_view s, size_type pos = npos) const noexcept;
    constexpr size_type find_last_of(charT c, size_type pos = npos) const noexcept;
    constexpr size_type find_last_of(const charT* s, size_type pos, size_type n) const;
    constexpr size_type find_last_of(const charT* s, size_type pos = npos) const;
    constexpr size_type find_first_not_of(basic_string_view s, size_type pos = 0) const noexcept;
    constexpr size_type find_first_not_of(charT c, size_type pos = 0) const noexcept;
    constexpr size_type find_first_not_of(const charT* s, size_type pos,
                                          size_type n) const;
    constexpr size_type find_first_not_of(const charT* s, size_type pos = 0) const;
    constexpr size_type find_last_not_of(basic_string_view s,
                                         size_type pos = npos) const noexcept;
    constexpr size_type find_last_not_of(charT c, size_type pos = npos) const noexcept;
    constexpr size_type find_last_not_of(const charT* s, size_type pos,
                                         size_type n) const;
    constexpr size_type find_last_not_of(const charT* s, size_type pos = npos) const;

  private:
    const_pointer data_;        // exposition only
    size_type size_;            // exposition only
  };

  // [string.view.deduct], deduction guide
  template<class It, class End>
    basic_string_view(It, End) -> basic_string_view<iter_value_t<It>>;
}
1
#
In every specialization basic_­string_­view<charT, traits>, the type traits shall meet the character traits requirements ([char.traits]).
[Note
:
The program is ill-formed if traits​::​char_­type is not the same type as charT.
— end note
]
2
#
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 returned from str's member functions.
3
#
The complexity of basic_­string_­view member functions is unless otherwise specified.
223)
Because basic_­string_­view refers to a constant sequence, iterator and const_­iterator are the same type.
⮥

21.4.2.1 Construction and assignment [string.view.cons]

🔗
constexpr basic_string_view() noexcept;
1
#
Postconditions: size_­ == 0 and data_­ == nullptr.
🔗
constexpr basic_string_view(const charT* str);
2
#
Preconditions: [str, str + traits​::​length(str)) is a valid range.
3
#
Effects: Constructs a basic_­string_­view, initializing data_­ with str and initializing size_­ with traits​::​length(str).
4
#
Complexity: .
🔗
constexpr basic_string_view(const charT* str, size_type len);
5
#
Preconditions: [str, str + len) is a valid range.
6
#
Effects: Constructs a basic_­string_­view, initializing data_­ with str and initializing size_­ with len.
🔗
template<class It, class End> constexpr basic_string_view(It begin, End end);
7
#
Constraints:
  • (7.1)
    It satisfies contiguous_­iterator.
  • (7.2)
    End satisfies sized_­sentinel_­for<It>.
  • (7.3)
    is_­same_­v<iter_­value_­t<It>, charT> is true.
  • (7.4)
    is_­convertible_­v<End, size_­type> is false.
8
#
Preconditions:
  • (8.1)
    [begin, end) is a valid range.
  • (8.2)
    It models contiguous_­iterator.
  • (8.3)
    End models sized_­sentinel_­for<It>.
9
#
Effects: Initializes data_­ with to_­address(begin) and initializes size_­ with end - begin.

21.4.2.2 Iterator support [string.view.iterators]

🔗
using const_iterator = implementation-defined;
1
#
A type that meets the requirements of a constant Cpp17RandomAccessIterator ([random.access.iterators]), models contiguous_­iterator ([iterator.concept.contiguous]), and meets the constexpr iterator requirements ([iterator.requirements.general]), whose value_­type is the template parameter charT.
2
#
All requirements on container iterators ([container.requirements]) apply to basic_­string_­view​::​const_­iterator as well.
🔗
constexpr const_iterator begin() const noexcept; constexpr const_iterator cbegin() const noexcept;
3
#
Returns: An iterator such that
  • (3.1)
    if !empty(), addressof(*begin()) == data_­,
  • (3.2)
    otherwise, an unspecified value such that [begin(), end()) is a valid range.
🔗
constexpr const_iterator end() const noexcept; constexpr const_iterator cend() const noexcept;
4
#
Returns: begin() + size().
🔗
constexpr const_reverse_iterator rbegin() const noexcept; constexpr const_reverse_iterator crbegin() const noexcept;
5
#
Returns: const_­reverse_­iterator(end()).
🔗
constexpr const_reverse_iterator rend() const noexcept; constexpr const_reverse_iterator crend() const noexcept;
6
#
Returns: const_­reverse_­iterator(begin()).

21.4.2.3 Capacity [string.view.capacity]

🔗
constexpr size_type size() const noexcept; constexpr size_type length() const noexcept;
1
#
Returns: size_­.
🔗
constexpr size_type max_size() const noexcept;
2
#
Returns: The largest possible number of char-like objects that can be referred to by a basic_­string_­view.
🔗
[[nodiscard]] constexpr bool empty() const noexcept;
3
#
Returns: size_­ == 0.

21.4.2.4 Element access [string.view.access]

🔗
constexpr const_reference operator[](size_type pos) const;
1
#
Preconditions: pos < size().
2
#
Returns: data_­[pos].
3
#
Throws: Nothing.
4
#
[Note
:
Unlike basic_­string​::​operator[], basic_­string_­view​::​operator[](size()) has undefined behavior instead of returning charT().
— end note
]
🔗
constexpr const_reference at(size_type pos) const;
5
#
Throws: out_­of_­range if pos >= size().
6
#
Returns: data_­[pos].
🔗
constexpr const_reference front() const;
7
#
Preconditions: !empty().
8
#
Returns: data_­[0].
9
#
Throws: Nothing.
🔗
constexpr const_reference back() const;
10
#
Preconditions: !empty().
11
#
Returns: data_­[size() - 1].
12
#
Throws: Nothing.
🔗
constexpr const_pointer data() const noexcept;
13
#
Returns: data_­.
14
#
[Note
:
Unlike basic_­string​::​data() and string-literals, data() may 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
]

21.4.2.5 Modifiers [string.view.modifiers]

🔗
constexpr void remove_prefix(size_type n);
1
#
Preconditions: n <= size().
2
#
Effects: Equivalent to: data_­ += n; size_­ -= n;
🔗
constexpr void remove_suffix(size_type n);
3
#
Preconditions: n <= size().
4
#
Effects: Equivalent to: size_­ -= n;
🔗
constexpr void swap(basic_string_view& s) noexcept;
5
#
Effects: Exchanges the values of *this and s.

21.4.2.6 String operations [string.view.ops]

🔗
constexpr size_type copy(charT* s, size_type n, size_type pos = 0) const;
1
#
Let rlen be the smaller of n and size() - pos.
2
#
Throws: out_­of_­range if pos > size().
3
#
Preconditions: [s, s + rlen) is a valid range.
4
#
Effects: Equivalent to traits​::​copy(s, data() + pos, rlen).
5
#
Returns: rlen.
6
#
Complexity: .
🔗
constexpr basic_string_view substr(size_type pos = 0, size_type n = npos) const;
7
#
Let rlen be the smaller of n and size() - pos.
8
#
Throws: out_­of_­range if pos > size().
9
#
Effects: Determines rlen, the effective length of the string to reference.
10
#
Returns: basic_­string_­view(data() + pos, rlen).
🔗
constexpr int compare(basic_string_view str) const noexcept;
11
#
Let rlen be the smaller of size() and str.size().
12
#
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).
13
#
Complexity: .
14
#
Returns: The nonzero result if the result of the comparison is nonzero.
Otherwise, returns a value as indicated in Table 70.
Table 70: compare() results   [tab:string.view.compare]
Condition
Return Value
size() < str.size()
< 0
size() == str.size()
 0
size() > str.size()
> 0
🔗
constexpr int compare(size_type pos1, size_type n1, basic_string_view str) const;
15
#
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;
16
#
Effects: Equivalent to: return substr(pos1, n1).compare(str.substr(pos2, n2));
🔗
constexpr int compare(const charT* s) const;
17
#
Effects: Equivalent to: return compare(basic_­string_­view(s));
🔗
constexpr int compare(size_type pos1, size_type n1, const charT* s) const;
18
#
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;
19
#
Effects: Equivalent to: return substr(pos1, n1).compare(basic_­string_­view(s, n2));
🔗
constexpr bool starts_with(basic_string_view x) const noexcept;
20
#
Effects: Equivalent to: return substr(0, x.size()) == x;
🔗
constexpr bool starts_with(charT x) const noexcept;
21
#
Effects: Equivalent to: return !empty() && traits​::​eq(front(), x);
🔗
constexpr bool starts_with(const charT* x) const;
22
#
Effects: Equivalent to: return starts_­with(basic_­string_­view(x));
🔗
constexpr bool ends_with(basic_string_view x) const noexcept;
23
#
Effects: Equivalent to: 
return size() >= x.size() && compare(size() - x.size(), npos, x) == 0;
🔗
constexpr bool ends_with(charT x) const noexcept;
24
#
Effects: Equivalent to: return !empty() && traits​::​eq(back(), x);
🔗
constexpr bool ends_with(const charT* x) const;
25
#
Effects: Equivalent to: return ends_­with(basic_­string_­view(x));

21.4.2.7 Searching [string.view.find]

1
#
Member functions in this subclause have complexity at worst, although implementations should do better.
2
#
Let F be one of find, rfind, find_­first_­of, find_­last_­of, find_­first_­not_­of, and find_­last_­not_­of.
  • (2.1)
    Each member function of the form 
    constexpr return-type F(const charT* s, size_type pos) const;
    has effects equivalent to: return F(basic_­string_­view(s), pos);
  • (2.2)
    Each member function of the form 
    constexpr 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);
  • (2.3)
    Each member function of the form 
    constexpr 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;
3
#
Let xpos be the lowest position, if possible, such that the following conditions hold:
  • (3.1)
    pos <= xpos
  • (3.2)
    xpos + str.size() <= size()
  • (3.3)
    traits​::​eq(at(xpos + I), str.at(I)) for all elements I of the string referenced by str.
4
#
Effects: Determines xpos.
5
#
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;
6
#
Let xpos be the highest position, if possible, such that the following conditions hold:
  • (6.1)
    xpos <= pos
  • (6.2)
    xpos + str.size() <= size()
  • (6.3)
    traits​::​eq(at(xpos + I), str.at(I)) for all elements I of the string referenced by str.
7
#
Effects: Determines xpos.
8
#
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;
9
#
Let xpos be the lowest position, if possible, such that the following conditions hold:
  • (9.1)
    pos <= xpos
  • (9.2)
    xpos < size()
  • (9.3)
    traits​::​eq(at(xpos), str.at(I)) for some element I of the string referenced by str.
10
#
Effects: Determines xpos.
11
#
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;
12
#
Let xpos be the highest position, if possible, such that the following conditions hold:
  • (12.1)
    xpos <= pos
  • (12.2)
    xpos < size()
  • (12.3)
    traits​::​eq(at(xpos), str.at(I)) for some element I of the string referenced by str.
13
#
Effects: Determines xpos.
14
#
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;
15
#
Let xpos be the lowest position, if possible, such that the following conditions hold:
  • (15.1)
    pos <= xpos
  • (15.2)
    xpos < size()
  • (15.3)
    traits​::​eq(at(xpos), str.at(I)) for no element I of the string referenced by str.
16
#
Effects: Determines xpos.
17
#
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;
18
#
Let xpos be the highest position, if possible, such that the following conditions hold:
  • (18.1)
    xpos <= pos
  • (18.2)
    xpos < size()
  • (18.3)
    traits​::​eq(at(xpos), str.at(I)) for no element I of the string referenced by str.
19
#
Effects: Determines xpos.
20
#
Returns: xpos if the function can determine such a value for xpos.
Otherwise, returns npos.

21.4.3 Deduction guide [string.view.deduct]

🔗
template<class It, class End> basic_string_view(It, End) -> basic_string_view<iter_value_t<It>>;
1
#
Constraints:
  • (1.1)
    It satisfies contiguous_­iterator.
  • (1.2)
    End satisfies sized_­sentinel_­for<It>.

21.4.4 Non-member comparison functions [string.view.comparison]

1
#
Let S be basic_­string_­view<charT, traits>, and sv be an instance of S.
Implementations shall provide sufficient additional overloads marked constexpr and noexcept so that an object t with an implicit conversion to S can be compared according to Table 71.
Table 71: Additional basic_­string_­view comparison overloads   [tab:string.view.comparison.overloads]
Expression
Equivalent to
t == sv
S(t) == sv
sv == t
sv == S(t)
t != sv
S(t) != sv
sv != t
sv != S(t)
t < sv
S(t) < sv
sv < t
sv < S(t)
t > sv
S(t) > sv
sv > t
sv > S(t)
t <= sv
S(t) <= sv
sv <= t
sv <= S(t)
t >= sv
S(t) >= sv
sv >= t
sv >= S(t)
t <=> sv
S(t) <=> sv
sv <=> t
sv <=> S(t)
[Example
:
A sample conforming implementation for operator== would be: 
template<class charT, class traits>
  constexpr bool operator==(basic_string_view<charT, traits> lhs,
                            basic_string_view<charT, traits> rhs) noexcept {
    return lhs.compare(rhs) == 0;
  }
template<class charT, class traits>
  constexpr bool operator==(basic_string_view<charT, traits> lhs,
                            type_identity_t<basic_string_view<charT, traits>> rhs) noexcept {
    return lhs.compare(rhs) == 0;
  }
— end example
]
🔗
template<class charT, class traits> constexpr bool operator==(basic_string_view<charT, traits> lhs, basic_string_view<charT, traits> rhs) noexcept;
2
#
Returns: lhs.compare(rhs) == 0.
🔗
template<class charT, class traits> constexpr see below operator<=>(basic_string_view<charT, traits> lhs, basic_string_view<charT, traits> rhs) noexcept;
3
#
Let R denote the type traits​::​comparison_­category if it exists, otherwise R is weak_­ordering.
4
#
Returns: static_­cast<R>(lhs.compare(rhs) <=> 0).

21.4.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);
1
#
Effects: Behaves as a formatted output function of os.
Forms a character sequence seq, initially consisting of the elements defined by the range [str.begin(), str.end()).
Determines padding for seq as described in [ostream.formatted.reqmts].
Then inserts seq as if by calling os.rdbuf()->sputn(​seq, n), where n is the larger of os.width() and str.size(); then calls os.​width(0).
2
#
Returns: os

21.4.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>;
1
#
The specialization is enabled ([unord.hash]).
[Note
:
The hash value of a string view object is equal to the hash value of the corresponding string object ([basic.string.hash]).
— end note
]

21.4.7 Suffix for basic_­string_­view literals [string.view.literals]

🔗
constexpr string_view operator""sv(const char* str, size_t len) noexcept;
1
#
Returns: string_­view{str, len}.
🔗
constexpr u8string_view operator""sv(const char8_t* str, size_t len) noexcept;
2
#
Returns: u8string_­view{str, len}.
🔗
constexpr u16string_view operator""sv(const char16_t* str, size_t len) noexcept;
3
#
Returns: u16string_­view{str, len}.
🔗
constexpr u32string_view operator""sv(const char32_t* str, size_t len) noexcept;
4
#
Returns: u32string_­view{str, len}.
🔗
constexpr wstring_view operator""sv(const wchar_t* str, size_t len) noexcept;
5
#
Returns: wstring_­view{str, len}.

21.5 Null-terminated sequence utilities [c.strings]

21.5.1 Header <cctype> synopsis [cctype.syn]

namespace std {
  int isalnum(int c);
  int isalpha(int c);
  int isblank(int c);
  int iscntrl(int c);
  int isdigit(int c);
  int isgraph(int c);
  int islower(int c);
  int isprint(int c);
  int ispunct(int c);
  int isspace(int c);
  int isupper(int c);
  int isxdigit(int c);
  int tolower(int c);
  int toupper(int c);
}
1
#
The contents and meaning of the header <cctype> are the same as the C standard library header <ctype.h>.
See also: ISO C 7.4

21.5.2 Header <cwctype> synopsis [cwctype.syn]

namespace std {
  using wint_t = see below;
  using wctrans_t = see below;
  using wctype_t = see below;

  int iswalnum(wint_t wc);
  int iswalpha(wint_t wc);
  int iswblank(wint_t wc);
  int iswcntrl(wint_t wc);
  int iswdigit(wint_t wc);
  int iswgraph(wint_t wc);
  int iswlower(wint_t wc);
  int iswprint(wint_t wc);
  int iswpunct(wint_t wc);
  int iswspace(wint_t wc);
  int iswupper(wint_t wc);
  int iswxdigit(wint_t wc);
  int iswctype(wint_t wc, wctype_t desc);
  wctype_t wctype(const char* property);
  wint_t towlower(wint_t wc);
  wint_t towupper(wint_t wc);
  wint_t towctrans(wint_t wc, wctrans_t desc);
  wctrans_t wctrans(const char* property);
}

#define WEOF see below
1
#
The contents and meaning of the header <cwctype> are the same as the C standard library header <wctype.h>.
See also: ISO C 7.30

21.5.3 Header <cstring> synopsis [cstring.syn]

namespace std {
  using size_t = see [support.types.layout];

  void* memcpy(void* s1, const void* s2, 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* 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);           // see [library.c]
  void* memchr(void* s, int c, size_t n);                       // see [library.c]
  const char* strchr(const char* s, int c);                     // see [library.c]
  char* strchr(char* s, int c);                                 // see [library.c]
  size_t strcspn(const char* s1, const char* s2);
  const char* strpbrk(const char* s1, const char* s2);          // see [library.c]
  char* strpbrk(char* s1, const char* s2);                      // see [library.c]
  const char* strrchr(const char* s, int c);                    // see [library.c]
  char* strrchr(char* s, int c);                                // see [library.c]
  size_t strspn(const char* s1, const char* s2);
  const char* strstr(const char* s1, const char* s2);           // see [library.c]
  char* strstr(char* s1, const char* s2);                       // see [library.c]
  char* strtok(char* s1, const char* s2);
  void* memset(void* s, int c, size_t n);
  char* strerror(int errnum);
  size_t strlen(const char* s);
}

#define NULL see [support.types.nullptr]
1
#
The contents and meaning of the header <cstring> are the same as the C standard library header <string.h>.
2
#
The functions strerror and strtok are not required to avoid data races.
3
#
The functions memcpy and memmove are signal-safe.
Both functions implicitly create objects ([intro.object]) in the destination region of storage immediately prior to copying the sequence of characters to the destination.
4
#
[Note
:
The functions strchr, 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 C 7.24

21.5.4 Header <cwchar> synopsis [cwchar.syn]

namespace std {
  using size_t = see [support.types.layout];
  using mbstate_t = see below;
  using wint_t = see below;

  struct tm;

  int fwprintf(FILE* stream, const wchar_t* format, ...);
  int fwscanf(FILE* stream, const wchar_t* format, ...);
  int swprintf(wchar_t* s, size_t n, const wchar_t* format, ...);
  int swscanf(const wchar_t* s, const wchar_t* format, ...);
  int vfwprintf(FILE* stream, const wchar_t* format, va_list arg);
  int vfwscanf(FILE* stream, const wchar_t* format, va_list arg);
  int vswprintf(wchar_t* s, size_t n, const wchar_t* format, va_list arg);
  int vswscanf(const wchar_t* s, const wchar_t* format, va_list arg);
  int vwprintf(const wchar_t* format, va_list arg);
  int vwscanf(const wchar_t* format, va_list arg);
  int wprintf(const wchar_t* format, ...);
  int wscanf(const wchar_t* format, ...);
  wint_t fgetwc(FILE* stream);
  wchar_t* fgetws(wchar_t* s, int n, FILE* stream);
  wint_t fputwc(wchar_t c, FILE* stream);
  int fputws(const wchar_t* s, FILE* stream);
  int fwide(FILE* stream, int mode);
  wint_t getwc(FILE* stream);
  wint_t getwchar();
  wint_t putwc(wchar_t c, FILE* stream);
  wint_t putwchar(wchar_t c);
  wint_t ungetwc(wint_t c, FILE* stream);
  double wcstod(const wchar_t* nptr, wchar_t** endptr);
  float wcstof(const wchar_t* nptr, wchar_t** endptr);
  long double wcstold(const wchar_t* nptr, wchar_t** endptr);
  long int wcstol(const wchar_t* nptr, wchar_t** endptr, int base);
  long long int wcstoll(const wchar_t* nptr, wchar_t** endptr, int base);
  unsigned long int wcstoul(const wchar_t* nptr, wchar_t** endptr, int base);
  unsigned long long int wcstoull(const wchar_t* nptr, wchar_t** endptr, int base);
  wchar_t* wcscpy(wchar_t* s1, const wchar_t* s2);
  wchar_t* wcsncpy(wchar_t* s1, const wchar_t* s2, size_t n);
  wchar_t* wmemcpy(wchar_t* s1, const wchar_t* s2, size_t n);
  wchar_t* wmemmove(wchar_t* s1, const wchar_t* s2, size_t n);
  wchar_t* wcscat(wchar_t* s1, const wchar_t* s2);
  wchar_t* wcsncat(wchar_t* s1, const wchar_t* s2, size_t n);
  int wcscmp(const wchar_t* s1, const wchar_t* s2);
  int wcscoll(const wchar_t* s1, const wchar_t* s2);
  int wcsncmp(const wchar_t* s1, const wchar_t* s2, size_t n);
  size_t wcsxfrm(wchar_t* s1, const wchar_t* s2, size_t n);
  int wmemcmp(const wchar_t* s1, const wchar_t* s2, size_t n);
  const wchar_t* wcschr(const wchar_t* s, wchar_t c);           // see [library.c]
  wchar_t* wcschr(wchar_t* s, wchar_t c);                       // see [library.c]
  size_t wcscspn(const wchar_t* s1, const wchar_t* s2);
  const wchar_t* wcspbrk(const wchar_t* s1, const wchar_t* s2); // see [library.c]
  wchar_t* wcspbrk(wchar_t* s1, const wchar_t* s2);             // see [library.c]
  const wchar_t* wcsrchr(const wchar_t* s, wchar_t c);          // see [library.c]
  wchar_t* wcsrchr(wchar_t* s, wchar_t c);                      // see [library.c]
  size_t wcsspn(const wchar_t* s1, const wchar_t* s2);
  const wchar_t* wcsstr(const wchar_t* s1, const wchar_t* s2);  // see [library.c]
  wchar_t* wcsstr(wchar_t* s1, const wchar_t* s2);              // see [library.c]
  wchar_t* wcstok(wchar_t* s1, const wchar_t* s2, wchar_t** ptr);
  const wchar_t* wmemchr(const wchar_t* s, wchar_t c, size_t n);    // see [library.c]
  wchar_t* wmemchr(wchar_t* s, wchar_t c, size_t n);            // see [library.c]
  size_t wcslen(const wchar_t* s);
  wchar_t* wmemset(wchar_t* s, wchar_t c, size_t n);
  size_t wcsftime(wchar_t* s, size_t maxsize, const wchar_t* format, const struct tm* timeptr);
  wint_t btowc(int c);
  int wctob(wint_t c);

  // [c.mb.wcs], multibyte / wide string and character conversion functions
  int mbsinit(const mbstate_t* ps);
  size_t mbrlen(const char* s, size_t n, mbstate_t* ps);
  size_t mbrtowc(wchar_t* pwc, const char* s, size_t n, mbstate_t* ps);
  size_t wcrtomb(char* s, wchar_t wc, mbstate_t* ps);
  size_t mbsrtowcs(wchar_t* dst, const char** src, size_t len, mbstate_t* ps);
  size_t wcsrtombs(char* dst, const wchar_t** src, size_t len, mbstate_t* ps);
}

#define NULL see [support.types.nullptr]
#define WCHAR_MAX see below
#define WCHAR_MIN see below
#define WEOF see below
1
#
The contents and meaning of the header <cwchar> are the same as the C standard library header <wchar.h>, except that it does not declare a type wchar_­t.
2
#
[Note
:
The functions wcschr, wcspbrk, wcsrchr, wcsstr, and wmemchr have different signatures in this document, but they have the same behavior as in the C standard library.
— end note
]
See also: ISO C 7.29

21.5.5 Header <cuchar> synopsis [cuchar.syn]

namespace std {
  using mbstate_t = see below;
  using size_t = see [support.types.layout];

  size_t mbrtoc8(char8_t* pc8, const char* s, size_t n, mbstate_t* ps);
  size_t c8rtomb(char* s, char8_t c8, mbstate_t* ps);
  size_t mbrtoc16(char16_t* pc16, const char* s, size_t n, mbstate_t* ps);
  size_t c16rtomb(char* s, char16_t c16, mbstate_t* ps);
  size_t mbrtoc32(char32_t* pc32, const char* s, size_t n, mbstate_t* ps);
  size_t c32rtomb(char* s, char32_t c32, mbstate_t* ps);
}
1
#
The contents and meaning of the header <cuchar> are the same as the C standard library header <uchar.h>, except that it declares the additional mbrtoc8 and c8rtomb functions and does not declare types char16_­t nor char32_­t.
See also: ISO C 7.28

21.5.6 Multibyte / wide string and character conversion functions [c.mb.wcs]

1
#
[Note
:
The headers <cstdlib> ([cstdlib.syn]), <cuchar> ([cuchar.syn]), and <cwchar> ([cwchar.syn]) declare the functions described in this subclause.
— end note
]
🔗
int mbsinit(const mbstate_t* ps); int mblen(const char* s, size_t n); size_t mbstowcs(wchar_t* pwcs, const char* s, size_t n); size_t wcstombs(char* s, const wchar_t* pwcs, size_t n);
2
#
Effects: These functions have the semantics specified in the C standard library.
See also: ISO C 7.22.7.1, 7.22.8, 7.29.6.2.1
🔗
int mbtowc(wchar_t* pwc, const char* s, size_t n); int wctomb(char* s, wchar_t wchar);
3
#
Effects: These functions have the semantics specified in the C standard library.
4
#
Remarks: Calls to these functions may introduce a data race ([res.on.data.races]) with other calls to the same function.
See also: ISO C 7.22.7
🔗
size_t mbrlen(const char* s, size_t n, mbstate_t* ps); size_t mbrtowc(wchar_t* pwc, const char* s, size_t n, mbstate_t* ps); size_t wcrtomb(char* s, wchar_t wc, mbstate_t* ps); size_t mbsrtowcs(wchar_t* dst, const char** src, size_t len, mbstate_t* ps); size_t wcsrtombs(char* dst, const wchar_t** src, size_t len, mbstate_t* ps);
5
#
Effects: These functions have the semantics specified in the C standard library.
6
#
Remarks: Calling these functions with an mbstate_­t* argument that is a null pointer value may introduce a data race ([res.on.data.races]) with other calls to the same function with an mbstate_­t* argument that is a null pointer value.
See also: ISO C 7.29.6.3
🔗
size_t mbrtoc8(char8_t* pc8, const char* s, size_t n, mbstate_t* ps);
7
#
Effects: If s is a null pointer, equivalent to mbrtoc8(nullptr, "", 1, ps).
Otherwise, the function inspects at most n bytes beginning with the byte pointed to by s to determine the number of bytes needed to complete the next multibyte character (including any shift sequences).
If the function determines that the next multibyte character is complete and valid, it determines the values of the corresponding UTF-8 code units and then, if pc8 is not a null pointer, stores the value of the first (or only) such code unit in the object pointed to by pc8.
Subsequent calls will store successive UTF-8 code units without consuming any additional input until all the code units have been stored.
If the corresponding Unicode character is U+0000, the resulting state described is the initial conversion state.
8
#
Returns: The first of the following that applies (given the current conversion state):
  • (8.1)
    0, if the next n or fewer bytes complete the multibyte character that corresponds to the U+0000 Unicode character (which is the value stored).
  • (8.2)
    between 1 and n (inclusive), if the next n or fewer bytes complete a valid multibyte character (which is the value stored); the value returned is the number of bytes that complete the multibyte character.
  • (8.3)
    (size_­t)(-3), if the next character resulting from a previous call has been stored (no bytes from the input have been consumed by this call).
  • (8.4)
    (size_­t)(-2), if the next n bytes contribute to an incomplete (but potentially valid) multibyte character, and all n bytes have been processed (no value is stored).
  • (8.5)
    (size_­t)(-1), if an encoding error occurs, in which case the next n or fewer bytes do not contribute to a complete and valid multibyte character (no value is stored); the value of the macro EILSEQ is stored in errno, and the conversion state is unspecified.
🔗
size_t c8rtomb(char* s, char8_t c8, mbstate_t* ps);
9
#
Effects: If s is a null pointer, equivalent to c8rtomb(buf, u8'\0', ps) where buf is an internal buffer.
Otherwise, if c8 completes a sequence of valid UTF-8 code units, determines the number of bytes needed to represent the multibyte character (including any shift sequences), and stores the multibyte character representation in the array whose first element is pointed to by s.
At most MB_­CUR_­MAX bytes are stored.
If the multibyte character is a null character, a null byte is stored, preceded by any shift sequence needed to restore the initial shift state; the resulting state described is the initial conversion state.
10
#
Returns: The number of bytes stored in the array object (including any shift sequences).
If c8 does not contribute to a sequence of char8_­t corresponding to a valid multibyte character, the value of the macro EILSEQ is stored in errno, (size_­t) (-1) is returned, and the conversion state is unspecified.
11
#
Remarks: Calls to c8rtomb with a null pointer argument for s may introduce a data race ([res.on.data.races]) with other calls to c8rtomb with a null pointer argument for s.