20 Strings library [strings]

20.3 String classes [string.classes]

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

20.3.1 Header <string> synopsis [string.syn]

#include <initializer_list>

namespace std {
  // [char.traits], character traits
  template<class charT> struct char_traits;
  template<> struct char_traits<char>;
  template<> struct char_traits<char16_t>;
  template<> struct char_traits<char32_t>;
  template<> struct char_traits<wchar_t>;

  // [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>
    basic_string<charT, traits, Allocator>
      operator+(const basic_string<charT, traits, Allocator>& lhs,
                const basic_string<charT, traits, Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    basic_string<charT, traits, Allocator>
      operator+(basic_string<charT, traits, Allocator>&& lhs,
                const basic_string<charT, traits, Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    basic_string<charT, traits, Allocator>
      operator+(const basic_string<charT, traits, Allocator>& lhs,
                basic_string<charT, traits, Allocator>&& rhs);
  template<class charT, class traits, class Allocator>
    basic_string<charT, traits, Allocator>
      operator+(basic_string<charT, traits, Allocator>&& lhs,
                basic_string<charT, traits, Allocator>&& rhs);
  template<class charT, class traits, class Allocator>
    basic_string<charT, traits, Allocator>
      operator+(const charT* lhs,
                const basic_string<charT, traits, Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    basic_string<charT, traits, Allocator>
      operator+(const charT* lhs,
                basic_string<charT, traits, Allocator>&& rhs);
  template<class charT, class traits, class Allocator>
    basic_string<charT, traits, Allocator>
      operator+(charT lhs,
                const basic_string<charT, traits, Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    basic_string<charT, traits, Allocator>
      operator+(charT lhs,
                basic_string<charT, traits, Allocator>&& rhs);
  template<class charT, class traits, class Allocator>
    basic_string<charT, traits, Allocator>
      operator+(const basic_string<charT, traits, Allocator>& lhs,
                const charT* rhs);
  template<class charT, class traits, class Allocator>
    basic_string<charT, traits, Allocator>
      operator+(basic_string<charT, traits, Allocator>&& lhs,
                const charT* rhs);
  template<class charT, class traits, class Allocator>
    basic_string<charT, traits, Allocator>
      operator+(const basic_string<charT, traits, Allocator>& lhs,
                charT rhs);
  template<class charT, class traits, class Allocator>
    basic_string<charT, traits, Allocator>
      operator+(basic_string<charT, traits, Allocator>&& lhs,
                charT rhs);

  template<class charT, class traits, class Allocator>
    bool operator==(const basic_string<charT, traits, Allocator>& lhs,
                    const basic_string<charT, traits, Allocator>& rhs) noexcept;
  template<class charT, class traits, class Allocator>
    bool operator==(const charT* lhs,
                    const basic_string<charT, traits, Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    bool operator==(const basic_string<charT, traits, Allocator>& lhs,
                    const charT* rhs);
  template<class charT, class traits, class Allocator>
    bool operator!=(const basic_string<charT, traits, Allocator>& lhs,
                    const basic_string<charT, traits, Allocator>& rhs) noexcept;
  template<class charT, class traits, class Allocator>
    bool operator!=(const charT* lhs,
                    const basic_string<charT, traits, Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    bool operator!=(const basic_string<charT, traits, Allocator>& lhs,
                    const charT* rhs);

  template<class charT, class traits, class Allocator>
    bool operator< (const basic_string<charT, traits, Allocator>& lhs,
                    const basic_string<charT, traits, Allocator>& rhs) noexcept;
  template<class charT, class traits, class Allocator>
    bool operator< (const basic_string<charT, traits, Allocator>& lhs,
                    const charT* rhs);
  template<class charT, class traits, class Allocator>
    bool operator< (const charT* lhs,
                    const basic_string<charT, traits, Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    bool operator> (const basic_string<charT, traits, Allocator>& lhs,
                    const basic_string<charT, traits, Allocator>& rhs) noexcept;
  template<class charT, class traits, class Allocator>
    bool operator> (const basic_string<charT, traits, Allocator>& lhs,
                    const charT* rhs);
  template<class charT, class traits, class Allocator>
    bool operator> (const charT* lhs,
                    const basic_string<charT, traits, Allocator>& rhs);

  template<class charT, class traits, class Allocator>
    bool operator<=(const basic_string<charT, traits, Allocator>& lhs,
                    const basic_string<charT, traits, Allocator>& rhs) noexcept;
  template<class charT, class traits, class Allocator>
    bool operator<=(const basic_string<charT, traits, Allocator>& lhs,
                    const charT* rhs);
  template<class charT, class traits, class Allocator>
    bool operator<=(const charT* lhs,
                    const basic_string<charT, traits, Allocator>& rhs);
  template<class charT, class traits, class Allocator>
    bool operator>=(const basic_string<charT, traits, Allocator>& lhs,
                    const basic_string<charT, traits, Allocator>& rhs) noexcept;
  template<class charT, class traits, class Allocator>
    bool operator>=(const basic_string<charT, traits, Allocator>& lhs,
                    const charT* rhs);
  template<class charT, class traits, class Allocator>
    bool operator>=(const charT* lhs,
                    const basic_string<charT, traits, Allocator>& rhs);

  // [string.special], swap
  template<class charT, class traits, class Allocator>
    void swap(basic_string<charT, traits, Allocator>& lhs,
              basic_string<charT, traits, Allocator>& rhs)
      noexcept(noexcept(lhs.swap(rhs)));

  // [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);

  // basic_­string typedef names
  using string    = basic_string<char>;
  using u16string = basic_string<char16_t>;
  using u32string = basic_string<char32_t>;
  using wstring   = basic_string<wchar_t>;

  // [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 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<u16string>;
  template<> struct hash<u32string>;
  template<> struct hash<wstring>;
  template<> struct hash<pmr::string>;
  template<> struct hash<pmr::u16string>;
  template<> struct hash<pmr::u32string>;
  template<> struct hash<pmr::wstring>;

  inline namespace literals {
  inline namespace string_literals {
    // [basic.string.literals], suffix for basic_­string literals
    string    operator""s(const char* str, size_t len);
    u16string operator""s(const char16_t* str, size_t len);
    u32string operator""s(const char32_t* str, size_t len);
    wstring   operator""s(const wchar_t* str, size_t len);
  }
  }
}

20.3.2 Class template basic_­string [basic.string]

1
#
The class template basic_­string describes objects that can store a sequence consisting of a varying number of arbitrary char-like objects with the first element of the sequence at position zero.
Such a sequence is also called a “string” if the type of the char-like objects that it holds is clear from context.
In the rest of this Clause, the type of the char-like objects held in a basic_­string object is designated by charT.
2
#
The member functions of basic_­string use an object of the Allocator class passed as a template parameter to allocate and free storage for the contained char-like objects.227
3
#
A basic_­string is a contiguous container.
4
#
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.
5
#
The functions described in this Clause can report two kinds of errors, each associated with an exception type:
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
    basic_string() noexcept(noexcept(Allocator())) : basic_string(Allocator()) { }
    explicit basic_string(const Allocator& a) noexcept;
    basic_string(const basic_string& str);
    basic_string(basic_string&& str) noexcept;
    basic_string(const basic_string& str, size_type pos, const Allocator& a = Allocator());
    basic_string(const basic_string& str, size_type pos, size_type n,
                 const Allocator& a = Allocator());
    template<class T>
      basic_string(const T& t, size_type pos, size_type n, const Allocator& a = Allocator());
    template<class T>
      explicit basic_string(const T& t, const Allocator& a = Allocator());
    basic_string(const charT* s, size_type n, const Allocator& a = Allocator());
    basic_string(const charT* s, const Allocator& a = Allocator());
    basic_string(size_type n, charT c, const Allocator& a = Allocator());
    template<class InputIterator>
      basic_string(InputIterator begin, InputIterator end, const Allocator& a = Allocator());
    basic_string(initializer_list<charT>, const Allocator& = Allocator());
    basic_string(const basic_string&, const Allocator&);
    basic_string(basic_string&&, const Allocator&);

    ~basic_string();
    basic_string& operator=(const basic_string& str);
    basic_string& operator=(basic_string&& str)
      noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
               allocator_traits<Allocator>::is_always_equal::value);
    template<class T>
      basic_string& operator=(const T& t);
    basic_string& operator=(const charT* s);
    basic_string& operator=(charT c);
    basic_string& operator=(initializer_list<charT>);

    // [string.iterators], iterators
    iterator       begin() noexcept;
    const_iterator begin() const noexcept;
    iterator       end() noexcept;
    const_iterator end() const noexcept;

    reverse_iterator       rbegin() noexcept;
    const_reverse_iterator rbegin() const noexcept;
    reverse_iterator       rend() noexcept;
    const_reverse_iterator rend() const noexcept;

    const_iterator         cbegin() const noexcept;
    const_iterator         cend() const noexcept;
    const_reverse_iterator crbegin() const noexcept;
    const_reverse_iterator crend() const noexcept;

    // [string.capacity], capacity
    size_type size() const noexcept;
    size_type length() const noexcept;
    size_type max_size() const noexcept;
    void resize(size_type n, charT c);
    void resize(size_type n);
    size_type capacity() const noexcept;
    void reserve(size_type res_arg);
    void shrink_to_fit();
    void clear() noexcept;
    [[nodiscard]] bool empty() const noexcept;

    // [string.access], element access
    const_reference operator[](size_type pos) const;
    reference       operator[](size_type pos);
    const_reference at(size_type n) const;
    reference       at(size_type n);

    const charT& front() const;
    charT&       front();
    const charT& back() const;
    charT&       back();

    // [string.modifiers], modifiers
    basic_string& operator+=(const basic_string& str);
    template<class T>
      basic_string& operator+=(const T& t);
    basic_string& operator+=(const charT* s);
    basic_string& operator+=(charT c);
    basic_string& operator+=(initializer_list<charT>);
    basic_string& append(const basic_string& str);
    basic_string& append(const basic_string& str, size_type pos, size_type n = npos);
    template<class T>
      basic_string& append(const T& t);
    template<class T>
      basic_string& append(const T& t, size_type pos, size_type n = npos);
    basic_string& append(const charT* s, size_type n);
    basic_string& append(const charT* s);
    basic_string& append(size_type n, charT c);
    template<class InputIterator>
      basic_string& append(InputIterator first, InputIterator last);
    basic_string& append(initializer_list<charT>);

    void push_back(charT c);

    basic_string& assign(const basic_string& str);
    basic_string& assign(basic_string&& str)
      noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
               allocator_traits<Allocator>::is_always_equal::value);
    basic_string& assign(const basic_string& str, size_type pos, size_type n = npos);
    template<class T>
      basic_string& assign(const T& t);
    template<class T>
      basic_string& assign(const T& t, size_type pos, size_type n = npos);
    basic_string& assign(const charT* s, size_type n);
    basic_string& assign(const charT* s);
    basic_string& assign(size_type n, charT c);
    template<class InputIterator>
      basic_string& assign(InputIterator first, InputIterator last);
    basic_string& assign(initializer_list<charT>);

    basic_string& insert(size_type pos, const basic_string& str);
    basic_string& insert(size_type pos1, const basic_string& str,
                         size_type pos2, size_type n = npos);
    template<class T>
      basic_string& insert(size_type pos, const T& t);
    template<class T>
      basic_string& insert(size_type pos1, const T& t, size_type pos2, size_type n = npos);
    basic_string& insert(size_type pos, const charT* s, size_type n);
    basic_string& insert(size_type pos, const charT* s);
    basic_string& insert(size_type pos, size_type n, charT c);
    iterator insert(const_iterator p, charT c);
    iterator insert(const_iterator p, size_type n, charT c);
    template<class InputIterator>
      iterator insert(const_iterator p, InputIterator first, InputIterator last);
    iterator insert(const_iterator p, initializer_list<charT>);

    basic_string& erase(size_type pos = 0, size_type n = npos);
    iterator erase(const_iterator p);
    iterator erase(const_iterator first, const_iterator last);

    void pop_back();

    basic_string& replace(size_type pos1, size_type n1, const basic_string& str);
    basic_string& replace(size_type pos1, size_type n1, const basic_string& str,
                          size_type pos2, size_type n2 = npos);
    template<class T>
      basic_string& replace(size_type pos1, size_type n1, const T& t);
    template<class T>
      basic_string& replace(size_type pos1, size_type n1, const T& t,
                            size_type pos2, size_type n2 = npos);
    basic_string& replace(size_type pos, size_type n1, const charT* s, size_type n2);
    basic_string& replace(size_type pos, size_type n1, const charT* s);
    basic_string& replace(size_type pos, size_type n1, size_type n2, charT c);

    basic_string& replace(const_iterator i1, const_iterator i2, const basic_string& str);
    template<class T>
      basic_string& replace(const_iterator i1, const_iterator i2, const T& t);
    basic_string& replace(const_iterator i1, const_iterator i2, const charT* s, size_type n);
    basic_string& replace(const_iterator i1, const_iterator i2, const charT* s);
    basic_string& replace(const_iterator i1, const_iterator i2, size_type n, charT c);
    template<class InputIterator>
      basic_string& replace(const_iterator i1, const_iterator i2,
                            InputIterator j1, InputIterator j2);
    basic_string& replace(const_iterator, const_iterator, initializer_list<charT>);

    size_type copy(charT* s, size_type n, size_type pos = 0) const;

    void swap(basic_string& str)
      noexcept(allocator_traits<Allocator>::propagate_on_container_swap::value ||
               allocator_traits<Allocator>::is_always_equal::value);

    // [string.ops], string operations
    const charT* c_str() const noexcept;
    const charT* data() const noexcept;
    charT* data() noexcept;
    operator basic_string_view<charT, traits>() const noexcept;
    allocator_type get_allocator() const noexcept;

    template<class T>
      size_type find (const T& t, size_type pos = 0) const;
    size_type find (const basic_string& str, size_type pos = 0) const noexcept;
    size_type find (const charT* s, size_type pos, size_type n) const;
    size_type find (const charT* s, size_type pos = 0) const;
    size_type find (charT c, size_type pos = 0) const;
    template<class T>
      size_type rfind(const T& t, size_type pos = npos) const;
    size_type rfind(const basic_string& str, size_type pos = npos) const noexcept;
    size_type rfind(const charT* s, size_type pos, size_type n) const;
    size_type rfind(const charT* s, size_type pos = npos) const;
    size_type rfind(charT c, size_type pos = npos) const;

    template<class T>
      size_type find_first_of(const T& t, size_type pos = 0) const;
    size_type find_first_of(const basic_string& str, size_type pos = 0) const noexcept;
    size_type find_first_of(const charT* s, size_type pos, size_type n) const;
    size_type find_first_of(const charT* s, size_type pos = 0) const;
    size_type find_first_of(charT c, size_type pos = 0) const;
    template<class T>
      size_type find_last_of (const T& t, size_type pos = npos) const;
    size_type find_last_of (const basic_string& str, size_type pos = npos) const noexcept;
    size_type find_last_of (const charT* s, size_type pos, size_type n) const;
    size_type find_last_of (const charT* s, size_type pos = npos) const;
    size_type find_last_of (charT c, size_type pos = npos) const;

    template<class T>
      size_type find_first_not_of(const T& t, size_type pos = 0) const;
    size_type find_first_not_of(const basic_string& str, size_type pos = 0) const noexcept;
    size_type find_first_not_of(const charT* s, size_type pos, size_type n) const;
    size_type find_first_not_of(const charT* s, size_type pos = 0) const;
    size_type find_first_not_of(charT c, size_type pos = 0) const;
    template<class T>
      size_type find_last_not_of (const T& t, size_type pos = npos) const;
    size_type find_last_not_of (const basic_string& str, size_type pos = npos) const noexcept;
    size_type find_last_not_of (const charT* s, size_type pos, size_type n) const;
    size_type find_last_not_of (const charT* s, size_type pos = npos) const;
    size_type find_last_not_of (charT c, size_type pos = npos) const;

    basic_string substr(size_type pos = 0, size_type n = npos) const;
    template<class T>
      int compare(const T& t) const;
    template<class T>
      int compare(size_type pos1, size_type n1, const T& t) const;
    template<class T>
      int compare(size_type pos1, size_type n1, const T& t,
                  size_type pos2, size_type n2 = npos) const;
    int compare(const basic_string& str) const noexcept;
    int compare(size_type pos1, size_type n1, const basic_string& str) const;
    int compare(size_type pos1, size_type n1, const basic_string& str,
                size_type pos2, size_type n2 = npos) const;
    int compare(const charT* s) const;
    int compare(size_type pos1, size_type n1, const charT* s) const;
    int compare(size_type pos1, size_type n1, const charT* s, size_type n2) const;

    bool starts_with(basic_string_view<charT, traits> x) const noexcept;
    bool starts_with(charT x) const noexcept;
    bool starts_with(const charT* x) const;
    bool ends_with(basic_string_view<charT, traits> x) const noexcept;
    bool ends_with(charT x) const noexcept;
    bool ends_with(const charT* x) const;
  };

  template<class InputIterator,
           class Allocator = allocator<typename iterator_traits<InputIterator>::value_type>>
    basic_string(InputIterator, InputIterator, Allocator = Allocator())
      -> basic_string<typename iterator_traits<InputIterator>::value_type,
                      char_traits<typename iterator_traits<InputIterator>::value_type>,
                      Allocator>;

  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>;
}
6
#
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.
227)
Allocator​::​value_­type must name the same type as charT ([string.require]).

20.3.2.1 General requirements [string.require]

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

20.3.2.2 Constructors and assignment operators [string.cons]

🔗
explicit basic_string(const Allocator& a) noexcept;
1
#
Effects: Constructs an object of class basic_­string.
2
#
Ensures: size() is 0 and capacity() is an unspecified value.
🔗
basic_string(const basic_string& str); basic_string(basic_string&& str) noexcept;
3
#
Effects: Constructs an object of class basic_­string.
4
#
Ensures: data() points at the first element of an allocated copy of the array whose first element is pointed at by the original value str.data(), size() is equal to the original value of str.size(), and capacity() is a value at least as large as size().
In the second form, str is left in a valid state with an unspecified value.
🔗
basic_string(const basic_string& str, size_type pos, const Allocator& a = Allocator()); basic_string(const basic_string& str, size_type pos, size_type n, const Allocator& a = Allocator());
5
#
Throws: out_­of_­range if pos > str.size().
6
#
Effects: Constructs an object of class basic_­string and determines the effective length rlen of the initial string value as str.size() - pos in the first form and as the smaller of str.size() - pos and n in the second form.
7
#
Ensures: data() points at the first element of an allocated copy of rlen consecutive elements of the string controlled by str beginning at position pos, size() is equal to rlen, and capacity() is a value at least as large as size().
🔗
template<class T> basic_string(const T& t, size_type pos, size_type n, const Allocator& a = Allocator());
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.substr(pos, n), a);
9
#
Remarks: This constructor shall not participate in overload resolution unless is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true.
🔗
template<class T> explicit basic_string(const T& t, const Allocator& a = Allocator());
10
#
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).
11
#
Remarks: This constructor shall not participate in overload resolution unless
  • (11.1)
    is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and
  • (11.2)
    is_­convertible_­v<const T&, const charT*> is false.
🔗
basic_string(const charT* s, size_type n, const Allocator& a = Allocator());
12
#
Requires: s points to an array of at least n elements of charT.
13
#
Effects: Constructs an object of class basic_­string and determines its initial string value from the array of charT of length n whose first element is designated by s.
14
#
Ensures: data() points at the first element of an allocated copy of the array whose first element is pointed at by s, size() is equal to n, and capacity() is a value at least as large as size().
🔗
basic_string(const charT* s, const Allocator& a = Allocator());
15
#
Requires: s points to an array of at least traits​::​length(s) + 1 elements of charT.
16
#
Effects: Constructs an object of class basic_­string and determines its initial string value from the array of charT of length traits​::​length(s) whose first element is designated by s.
17
#
Ensures: data() points at the first element of an allocated copy of the array whose first element is pointed at by s, size() is equal to traits​::​length(s), and capacity() is a value at least as large as size().
18
#
Remarks: Shall not participate in overload resolution if Allocator is a type that does not qualify as an allocator ([container.requirements.general]).
[ Note
:
This affects class template argument deduction.
— end note
 ]
🔗
basic_string(size_type n, charT c, const Allocator& a = Allocator());
19
#
Requires: n < npos.
20
#
Effects: Constructs an object of class basic_­string and determines its initial string value by repeating the char-like object c for all n elements.
21
#
Ensures: data() points at the first element of an allocated array of n elements, each storing the initial value c, size() is equal to n, and capacity() is a value at least as large as size().
22
#
Remarks: Shall not participate in overload resolution if Allocator is a type that does not qualify as an allocator ([container.requirements.general]).
[ Note
:
This affects class template argument deduction.
— end note
 ]
🔗
template<class InputIterator> basic_string(InputIterator begin, InputIterator end, const Allocator& a = Allocator());
23
#
Effects: If InputIterator is an integral type, equivalent to: 
basic_string(static_cast<size_type>(begin), static_cast<value_type>(end), a);
Otherwise constructs a string from the values in the range [begin, end), as indicated in the Sequence Requirements table (see [sequence.reqmts]).
🔗
basic_string(initializer_list<charT> il, const Allocator& a = Allocator());
24
#
Effects: Same as basic_­string(il.begin(), il.end(), a).
🔗
basic_string(const basic_string& str, const Allocator& alloc); basic_string(basic_string&& str, const Allocator& alloc);
25
#
Effects: Constructs an object of class basic_­string.
The stored allocator is constructed from alloc.
26
#
Ensures: data() points at the first element of an allocated copy of the array whose first element is pointed at by the original value of str.data(), size() is equal to the original value of str.size(), capacity() is a value at least as large as size(), and get_­allocator() is equal to alloc.
In the second form, str is left in a valid state with an unspecified value.
27
#
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>;
28
#
Remarks: Shall not participate in overload resolution if InputIterator is a type that does not qualify as an input iterator, or if Allocator is a type that does not qualify as an allocator ([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>;
29
#
Remarks: Shall not participate in overload resolution if Allocator is a type that does not qualify as an allocator ([container.requirements.general]).
🔗
basic_string& operator=(const basic_string& str);
30
#
Returns: *this.
31
#
Ensures: If *this and str are the same object, the member has no effect.
Otherwise, data() points at the first element of an allocated copy of the array whose first element is pointed at by str.data(), size() is equal to str.size(), and capacity() is a value at least as large as size().
🔗
basic_string& operator=(basic_string&& str) noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value || allocator_traits<Allocator>::is_always_equal::value);
32
#
Effects: Move assigns as a sequence container, except that iterators, pointers and references may be invalidated.
33
#
Returns: *this.
🔗
template<class T> basic_string& operator=(const T& t);
34
#
Effects: Equivalent to: 
{
  basic_string_view<charT, traits> sv = t;
  return assign(sv);
}
35
#
Remarks: This function shall not participate in overload resolution unless is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and is_­convertible_­v<const T&, const charT*> is false.
🔗
basic_string& operator=(const charT* s);
36
#
Returns: *this = basic_­string(s).
37
#
Remarks: Uses traits​::​length().
🔗
basic_string& operator=(charT c);
38
#
Returns: *this = basic_­string(1, c).
🔗
basic_string& operator=(initializer_list<charT> il);
39
#
Effects: As if by: *this = basic_­string(il);
40
#
Returns: *this.

20.3.2.3 Iterator support [string.iterators]

🔗
iterator begin() noexcept; const_iterator begin() const noexcept; const_iterator cbegin() const noexcept;
1
#
Returns: An iterator referring to the first character in the string.
🔗
iterator end() noexcept; const_iterator end() const noexcept; const_iterator cend() const noexcept;
2
#
Returns: An iterator which is the past-the-end value.
🔗
reverse_iterator rbegin() noexcept; const_reverse_iterator rbegin() const noexcept; const_reverse_iterator crbegin() const noexcept;
3
#
Returns: An iterator which is semantically equivalent to reverse_­iterator(end()).
🔗
reverse_iterator rend() noexcept; const_reverse_iterator rend() const noexcept; const_reverse_iterator crend() const noexcept;
4
#
Returns: An iterator which is semantically equivalent to reverse_­iterator(begin()).

20.3.2.4 Capacity [string.capacity]

🔗
size_type size() const noexcept;
1
#
Returns: A count of the number of char-like objects currently in the string.
2
#
Complexity: Constant time.
🔗
size_type length() const noexcept;
3
#
Returns: size().
🔗
size_type max_size() const noexcept;
4
#
Returns: The largest possible number of char-like objects that can be stored in a basic_­string.
5
#
Complexity: Constant time.
🔗
void resize(size_type n, charT c);
6
#
Throws: length_­error if n > max_­size().
7
#
Effects: Alters the length of the string designated by *this as follows:
  • (7.1)
    If n <= size(), the function replaces the string designated by *this with a string of length n whose elements are a copy of the initial elements of the original string designated by *this.
  • (7.2)
    If n > size(), the function replaces the string designated by *this with a string of length n whose first size() elements are a copy of the original string designated by *this, and whose remaining elements are all initialized to c.
🔗
void resize(size_type n);
8
#
Effects: As if by resize(n, charT()).
🔗
size_type capacity() const noexcept;
9
#
Returns: The size of the allocated storage in the string.
10
#
Complexity: Constant time.
🔗
void reserve(size_type res_arg);
11
#
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().
12
#
Throws: length_­error if res_­arg > max_­size().229
🔗
void shrink_to_fit();
13
#
Effects: shrink_­to_­fit is a non-binding request to reduce capacity() to size().
[ Note
:
The request is non-binding to allow latitude for implementation-specific optimizations.
— end note
 ]
It does not increase capacity(), but may reduce capacity() by causing reallocation.
14
#
Complexity: Linear in the size of the sequence.
15
#
Remarks: Reallocation invalidates all the references, pointers, and iterators referring to the elements in the sequence as well as the past-the-end iterator.
If no reallocation happens, they remain valid.
🔗
void clear() noexcept;
16
#
Effects: Behaves as if the function calls:
erase(begin(), end());
🔗
[[nodiscard]] bool empty() const noexcept;
17
#
Returns: size() == 0.
229)
reserve() uses allocator_­traits<Allocator>​::​allocate() which may throw an appropriate exception.

20.3.2.5 Element access [string.access]

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

20.3.2.6 Modifiers [string.modifiers]

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

🔗
basic_string& operator+=(const basic_string& str);
1
#
Effects: Calls append(str).
2
#
Returns: *this.
🔗
template<class T> basic_string& operator+=(const T& t);
3
#
Effects: Creates a variable, sv, as if by basic_­string_­view<charT, traits> sv = t; and then calls append(sv).
4
#
Returns: *this.
5
#
Remarks: This function shall not participate in overload resolution unless is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and is_­convertible_­v<const T&, const charT*> is false.
🔗
basic_string& operator+=(const charT* s);
6
#
Effects: Calls append(s).
7
#
Returns: *this.
🔗
basic_string& operator+=(charT c);
8
#
Effects: Calls push_­back(c);
9
#
Returns: *this.
🔗
basic_string& operator+=(initializer_list<charT> il);
10
#
Effects: Calls append(il).
11
#
Returns: *this.

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

🔗
basic_string& append(const basic_string& str);
1
#
Effects: Calls append(str.data(), str.size()).
2
#
Returns: *this.
🔗
basic_string& append(const basic_string& str, size_type pos, size_type n = npos);
3
#
Throws: out_­of_­range if pos > str.size().
4
#
Effects: Determines the effective length rlen of the string to append as the smaller of n and str.size() - pos and calls append(str.data() + pos, rlen).
5
#
Returns: *this.
🔗
template<class T> basic_string& append(const T& t);
6
#
Effects: Equivalent to: 
{
  basic_string_view<charT, traits> sv = t;
  return append(sv.data(), sv.size());
}
7
#
Remarks: This function shall not participate in overload resolution unless is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and is_­convertible_­v<const T&, const charT*> is false.
🔗
template<class T> basic_string& append(const T& t, size_type pos, size_type n = npos);
8
#
Throws: out_­of_­range if pos > sv.size().
9
#
Effects: Creates a variable, sv, as if by basic_­string_­view<charT, traits> sv = t.
Determines the effective length rlen of the string to append as the smaller of n and sv.size() - pos and calls append(sv.data() + pos, rlen).
10
#
Remarks: This function shall not participate in overload resolution unless is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and is_­convertible_­v<const T&, const charT*> is false.
11
#
Returns: *this.
🔗
basic_string& append(const charT* s, size_type n);
12
#
Requires: s points to an array of at least n elements of charT.
13
#
Throws: length_­error if size() + n > max_­size().
14
#
Effects: The function replaces the string controlled by *this with a string of length size() + n whose first size() elements are a copy of the original string controlled by *this and whose remaining elements are a copy of the initial n elements of s.
15
#
Returns: *this.
🔗
basic_string& append(const charT* s);
16
#
Requires: s points to an array of at least traits​::​length(s) + 1 elements of charT.
17
#
Effects: Calls append(s, traits​::​length(s)).
18
#
Returns: *this.
🔗
basic_string& append(size_type n, charT c);
19
#
Effects: Equivalent to: return append(basic_­string(n, c));
🔗
template<class InputIterator> basic_string& append(InputIterator first, InputIterator last);
20
#
Requires: [first, last) is a valid range.
21
#
Effects: Equivalent to: return append(basic_­string(first, last, get_­allocator()));
🔗
basic_string& append(initializer_list<charT> il);
22
#
Effects: Calls append(il.begin(), il.size()).
23
#
Returns: *this.
🔗
void push_back(charT c);
24
#
Effects: Equivalent to append(static_­cast<size_­type>(1), c).

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

🔗
basic_string& assign(const basic_string& str);
1
#
Effects: Equivalent to: return *this = str;
🔗
basic_string& assign(basic_string&& str) noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value || allocator_traits<Allocator>::is_always_equal::value);
2
#
Effects: Equivalent to: return *this = std​::​move(str);
🔗
basic_string& assign(const basic_string& str, size_type pos, size_type n = npos);
3
#
Throws: out_­of_­range if pos > str.size().
4
#
Effects: Determines the effective length rlen of the string to assign as the smaller of n and str.size() - pos and calls assign(str.data() + pos, rlen).
5
#
Returns: *this.
🔗
template<class T> basic_string& assign(const T& t);
6
#
Effects: Equivalent to: 
{
  basic_string_view<charT, traits> sv = t;
  return assign(sv.data(), sv.size());
}
7
#
Remarks: This function shall not participate in overload resolution unless is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and is_­convertible_­v<const T&, const charT*> is false.
🔗
template<class T> basic_string& assign(const T& t, size_type pos, size_type n = npos);
8
#
Throws: out_­of_­range if pos > sv.size().
9
#
Effects: Creates a variable, sv, as if by basic_­string_­view<charT, traits> sv = t.
Determines the effective length rlen of the string to assign as the smaller of n and sv.size() - pos and calls assign(sv.data() + pos, rlen).
10
#
Remarks: This function shall not participate in overload resolution unless is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and is_­convertible_­v<const T&, const charT*> is false.
11
#
Returns: *this.
🔗
basic_string& assign(const charT* s, size_type n);
12
#
Requires: s points to an array of at least n elements of charT.
13
#
Throws: length_­error if n > max_­size().
14
#
Effects: Replaces the string controlled by *this with a string of length n whose elements are a copy of those pointed to by s.
15
#
Returns: *this.
🔗
basic_string& assign(const charT* s);
16
#
Requires: s points to an array of at least traits​::​length(s) + 1 elements of charT.
17
#
Effects: Calls assign(s, traits​::​length(s)).
18
#
Returns: *this.
🔗
basic_string& assign(initializer_list<charT> il);
19
#
Effects: Calls assign(il.begin(), il.size()).
20
#
Returns: *this.
🔗
basic_string& assign(size_type n, charT c);
21
#
Effects: Equivalent to: return assign(basic_­string(n, c));
🔗
template<class InputIterator> basic_string& assign(InputIterator first, InputIterator last);
22
#
Effects: Equivalent to: return assign(basic_­string(first, last, get_­allocator()));

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

🔗
basic_string& insert(size_type pos, const basic_string& str);
1
#
Effects: Equivalent to: return insert(pos, str.data(), str.size());
🔗
basic_string& insert(size_type pos1, const basic_string& str, size_type pos2, size_type n = npos);
2
#
Throws: out_­of_­range if pos1 > size() or pos2 > str.size().
3
#
Effects: Determines the effective length rlen of the string to insert as the smaller of n and str.size() - pos2 and calls insert(pos1, str.data() + pos2, rlen).
4
#
Returns: *this.
🔗
template<class T> basic_string& insert(size_type pos, const T& t);
5
#
Effects: Equivalent to: 
{
  basic_string_view<charT, traits> sv = t;
  return insert(pos, sv.data(), sv.size());
}
6
#
Remarks: This function shall not participate in overload resolution unless is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and is_­convertible_­v<const T&, const charT*> is false.
🔗
template<class T> basic_string& insert(size_type pos1, const T& t, size_type pos2, size_type n = npos);
7
#
Throws: out_­of_­range if pos1 > size() or pos2 > sv.size().
8
#
Effects: Creates a variable, sv, as if by basic_­string_­view<charT, traits> sv = t.
Determines the effective length rlen of the string to assign as the smaller of n and sv.size() - pos2 and calls insert(pos1, sv.data() + pos2, rlen).
9
#
Remarks: This function shall not participate in overload resolution unless is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and is_­convertible_­v<const T&, const charT*> is false.
10
#
Returns: *this.
🔗
basic_string& insert(size_type pos, const charT* s, size_type n);
11
#
Requires: s points to an array of at least n elements of charT.
12
#
Throws: out_­of_­range if pos > size() or length_­error if size() + n > max_­size().
13
#
Effects: Replaces the string controlled by *this with a string of length size() + n whose first pos elements are a copy of the initial elements of the original string controlled by *this and whose next n elements are a copy of the elements in s and whose remaining elements are a copy of the remaining elements of the original string controlled by *this.
14
#
Returns: *this.
🔗
basic_string& insert(size_type pos, const charT* s);
15
#
Requires: s points to an array of at least traits​::​length(s) + 1 elements of charT.
16
#
Effects: Equivalent to: return insert(pos, s, traits​::​length(s));
🔗
basic_string& insert(size_type pos, size_type n, charT c);
17
#
Effects: Equivalent to: return insert(pos, basic_­string(n, c));
🔗
iterator insert(const_iterator p, charT c);
18
#
Requires: p is a valid iterator on *this.
19
#
Effects: Inserts a copy of c before the character referred to by p.
20
#
Returns: An iterator which refers to the copy of the inserted character.
🔗
iterator insert(const_iterator p, size_type n, charT c);
21
#
Requires: p is a valid iterator on *this.
22
#
Effects: Inserts n copies of c before the character referred to by p.
23
#
Returns: An iterator which refers to the copy of the first inserted character, or p if n == 0.
🔗
template<class InputIterator> iterator insert(const_iterator p, InputIterator first, InputIterator last);
24
#
Requires: p is a valid iterator on *this.
[first, last) is a valid range.
25
#
Effects: Equivalent to insert(p - begin(), basic_­string(first, last, get_­allocator())).
26
#
Returns: An iterator which refers to the copy of the first inserted character, or p if first == last.
🔗
iterator insert(const_iterator p, initializer_list<charT> il);
27
#
Effects: As if by insert(p, il.begin(), il.end()).
28
#
Returns: An iterator which refers to the copy of the first inserted character, or p if i1 is empty.

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

🔗
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.
3
#
The function then replaces the string controlled by *this with a string of length size() - xlen whose first pos elements are a copy of the initial elements of the original string controlled by *this, and whose remaining elements are a copy of the elements of the original string controlled by *this beginning at position pos + xlen.
4
#
Returns: *this.
🔗
iterator erase(const_iterator p);
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.
🔗
iterator erase(const_iterator first, const_iterator last);
8
#
Requires: first and last are valid iterators on *this, defining a range [first, last).
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.
🔗
void pop_back();
12
#
Requires: !empty().
13
#
Throws: Nothing.
14
#
Effects: Equivalent to erase(size() - 1, 1).

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

🔗
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());
🔗
basic_string& replace(size_type pos1, size_type n1, const basic_string& str, size_type pos2, size_type n2 = npos);
2
#
Throws: out_­of_­range if pos1 > size() or pos2 > str.size().
3
#
Effects: Determines the effective length rlen of the string to be inserted as the smaller of n2 and str.size() - pos2 and calls replace(pos1, n1, str.data() + pos2, rlen).
4
#
Returns: *this.
🔗
template<class T> basic_string& replace(size_type pos1, size_type n1, const T& t);
5
#
Effects: Equivalent to: 
{
  basic_string_view<charT, traits> sv = t;
  return replace(pos1, n1, sv.data(), sv.size());
}
6
#
Remarks: This function shall not participate in overload resolution unless is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and is_­convertible_­v<const T&, const charT*> is false.
🔗
template<class T> basic_string& replace(size_type pos1, size_type n1, const T& t, size_type pos2, size_type n2 = npos);
7
#
Throws: out_­of_­range if pos1 > size() or pos2 > sv.size().
8
#
Effects: Creates a variable, sv, as if by basic_­string_­view<charT, traits> sv = t.
Determines the effective length rlen of the string to be inserted as the smaller of n2 and sv.size() - pos2 and calls replace(pos1, n1, sv.data() + pos2, rlen).
9
#
Remarks: This function shall not participate in overload resolution unless is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and is_­convertible_­v<const T&, const charT*> is false.
10
#
Returns: *this.
🔗
basic_string& replace(size_type pos1, size_type n1, const charT* s, size_type n2);
11
#
Requires: s points to an array of at least n2 elements of charT.
12
#
Throws: out_­of_­range if pos1 > size() or length_­error if the length of the resulting string would exceed max_­size() (see below).
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 string controlled by *this with a string of length size() - xlen + n2 whose first pos1 elements are a copy of the initial elements of the original string controlled by *this, whose next n2 elements are a copy of the initial n2 elements of s, and whose remaining elements are a copy of the elements of the original string controlled by *this beginning at position pos + xlen.
14
#
Returns: *this.
🔗
basic_string& replace(size_type pos, size_type n, const charT* s);
15
#
Requires: s points to an array of at least traits​::​length(s) + 1 elements of charT.
16
#
Effects: Equivalent to: return replace(pos, n, s, traits​::​length(s));
🔗
basic_string& replace(size_type pos1, size_type n1, size_type n2, charT c);
17
#
Effects: Equivalent to: return replace(pos1, n1, basic_­string(n2, c));
🔗
basic_string& replace(const_iterator i1, const_iterator i2, const basic_string& str);
18
#
Requires: [begin(), i1) and [i1, i2) are valid ranges.
19
#
Effects: Calls replace(i1 - begin(), i2 - i1, str).
20
#
Returns: *this.
🔗
template<class T> basic_string& replace(const_iterator i1, const_iterator i2, const T& t);
21
#
Requires: [begin(), i1) and [i1, i2) are valid ranges.
22
#
Effects: Creates a variable, sv, as if by basic_­string_­view<charT, traits> sv = t; and then calls replace(i1 - begin(), i2 - i1, sv).
23
#
Returns: *this.
24
#
Remarks: This function shall not participate in overload resolution unless is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and is_­convertible_­v<const T&, const charT*> is false.
🔗
basic_string& replace(const_iterator i1, const_iterator i2, const charT* s, size_type n);
25
#
Requires: [begin(), i1) and [i1, i2) are valid ranges and s points to an array of at least n elements of charT.
26
#
Effects: Calls replace(i1 - begin(), i2 - i1, s, n).
27
#
Returns: *this.
🔗
basic_string& replace(const_iterator i1, const_iterator i2, const charT* s);
28
#
Requires: [begin(), i1) and [i1, i2) are valid ranges and s points to an array of at least traits​::​​length(s) + 1 elements of charT.
29
#
Effects: Calls replace(i1 - begin(), i2 - i1, s, traits​::​length(s)).
30
#
Returns: *this.
🔗
basic_string& replace(const_iterator i1, const_iterator i2, size_type n, charT c);
31
#
Requires: [begin(), i1) and [i1, i2) are valid ranges.
32
#
Effects: Calls replace(i1 - begin(), i2 - i1, basic_­string(n, c)).
33
#
Returns: *this.
🔗
template<class InputIterator> basic_string& replace(const_iterator i1, const_iterator i2, InputIterator j1, InputIterator j2);
34
#
Requires: [begin(), i1), [i1, i2) and [j1, j2) are valid ranges.
35
#
Effects: Calls replace(i1 - begin(), i2 - i1, basic_­string(j1, j2, get_­allocator())).
36
#
Returns: *this.
🔗
basic_string& replace(const_iterator i1, const_iterator i2, initializer_list<charT> il);
37
#
Requires: [begin(), i1) and [i1, i2) are valid ranges.
38
#
Effects: Calls replace(i1 - begin(), i2 - i1, il.begin(), il.size()).
39
#
Returns: *this.

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

🔗
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
#
Requires: [s, s + rlen) is a valid range.
4
#
Effects: Equivalent to traits​::​copy(s, data() + pos, rlen).
[ Note
:
This does not terminate s with a null object.
— end note
 ]
5
#
Returns: rlen.

20.3.2.6.8 basic_­string​::​swap [string.swap]

🔗
void swap(basic_string& s) noexcept(allocator_traits<Allocator>::propagate_on_container_swap::value || allocator_traits<Allocator>::is_always_equal::value);
1
#
Ensures: *this contains the same sequence of characters that was in s, s contains the same sequence of characters that was in *this.
2
#
Throws: Nothing.
3
#
Complexity: Constant time.

20.3.2.7 String operations [string.ops]

20.3.2.7.1 Accessors [string.accessors]

🔗
const charT* c_str() const noexcept; const charT* data() const noexcept;
1
#
Returns: A pointer p such that p + i == &operator[](i) for each i in [0, size()].
2
#
Complexity: Constant time.
3
#
Requires: The program shall not alter any of the values stored in the character array.
🔗
charT* data() noexcept;
4
#
Returns: A pointer p such that p + i == &operator[](i) for each i in [0, size()].
5
#
Complexity: Constant time.
6
#
Requires: The program shall not alter the value stored at p + size().
🔗
operator basic_string_view<charT, traits>() const noexcept;
7
#
Effects: Equivalent to: return basic_­string_­view<charT, traits>(data(), size());
🔗
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.

20.3.2.7.2 basic_­string​::​find [string.find]

🔗
template<class T> size_type find(const T& t, size_type pos = 0) const;
1
#
Effects: Creates a variable, sv, as if by basic_­string_­view<charT, traits> sv = t; and then determines the lowest position xpos, if possible, such that both of the following conditions hold:
  • (1.1)
    pos <= xpos and xpos + sv.size() <= size();
  • (1.2)
    traits​::​eq(at(xpos + I), sv.at(I)) for all elements I of the data referenced by sv.
2
#
Returns: xpos if the function can determine such a value for xpos.
Otherwise, returns npos.
3
#
Remarks: This function shall not participate in overload resolution unless is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and is_­convertible_­v<const T&, const charT*> is false.
4
#
Throws: Nothing unless the initialization of sv throws an exception.
🔗
size_type find(const basic_string& str, size_type pos = 0) const noexcept;
5
#
Effects: Equivalent to: return find(basic_­string_­view<charT, traits>(str), pos);
🔗
size_type find(const charT* s, size_type pos, size_type n) const;
6
#
Returns: find(basic_­string_­view<charT, traits>(s, n), pos).
🔗
size_type find(const charT* s, size_type pos = 0) const;
7
#
Requires: s points to an array of at least traits​::​length(s) + 1 elements of charT.
8
#
Returns: find(basic_­string_­view<charT, traits>(s), pos).
🔗
size_type find(charT c, size_type pos = 0) const;
9
#
Returns: find(basic_­string(1, c), pos).

20.3.2.7.3 basic_­string​::​rfind [string.rfind]

🔗
template<class T> size_type rfind(const T& t, size_type pos = npos) const;
1
#
Effects: Creates a variable, sv, as if by basic_­string_­view<charT, traits> sv = t; and then determines the highest position xpos, if possible, such that both of the following conditions hold:
  • (1.1)
    xpos <= pos and xpos + sv.size() <= size();
  • (1.2)
    traits​::​eq(at(xpos + I), sv.at(I)) for all elements I of the data referenced by sv.
2
#
Returns: xpos if the function can determine such a value for xpos.
Otherwise, returns npos.
3
#
Remarks: This function shall not participate in overload resolution unless is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and is_­convertible_­v<const T&, const charT*> is false.
4
#
Throws: Nothing unless the initialization of sv throws an exception.
🔗
size_type rfind(const basic_string& str, size_type pos = npos) const noexcept;
5
#
Effects: Equivalent to: return rfind(basic_­string_­view<charT, traits>(str), pos);
🔗
size_type rfind(const charT* s, size_type pos, size_type n) const;
6
#
Returns: rfind(basic_­string_­view<charT, traits>(s, n), pos).
🔗
size_type rfind(const charT* s, size_type pos = npos) const;
7
#
Requires: s points to an array of at least traits​::​length(s) + 1 elements of charT.
8
#
Returns: rfind(basic_­string_­view<charT, traits>(s), pos).
🔗
size_type rfind(charT c, size_type pos = npos) const;
9
#
Returns: rfind(basic_­string(1, c), pos).

20.3.2.7.4 basic_­string​::​find_­first_­of [string.find.first.of]

🔗
template<class T> size_type find_first_of(const T& t, size_type pos = 0) const;
1
#
Effects: Creates a variable, sv, as if by basic_­string_­view<charT, traits> sv = t; and then determines the lowest position xpos, if possible, such that both of the following conditions hold:
  • (1.1)
    pos <= xpos and xpos < size();
  • (1.2)
    traits​::​eq(at(xpos), sv.at(I)) for some element I of the data referenced by sv.
2
#
Returns: xpos if the function can determine such a value for xpos.
Otherwise, returns npos.
3
#
Remarks: This function shall not participate in overload resolution unless is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and is_­convertible_­v<const T&, const charT*> is false.
4
#
Throws: Nothing unless the initialization of sv throws an exception.
🔗
size_type find_first_of(const basic_string& str, size_type pos = 0) const noexcept;
5
#
Effects: Equivalent to: return find_­first_­of(basic_­string_­view<charT, traits>(str), pos);
🔗
size_type find_first_of(const charT* s, size_type pos, size_type n) const;
6
#
Returns: find_­first_­of(basic_­string_­view<charT, traits>(s, n), pos).
🔗
size_type find_first_of(const charT* s, size_type pos = 0) const;
7
#
Requires: s points to an array of at least traits​::​length(s) + 1 elements of charT.
8
#
Returns: find_­first_­of(basic_­string_­view<charT, traits>(s), pos).
🔗
size_type find_first_of(charT c, size_type pos = 0) const;
9
#
Returns: find_­first_­of(basic_­string(1, c), pos).

20.3.2.7.5 basic_­string​::​find_­last_­of [string.find.last.of]

🔗
template<class T> size_type find_last_of(const T& t, size_type pos = npos) const;
1
#
Effects: Creates a variable, sv, as if by basic_­string_­view<charT, traits> sv = t; and then determines the highest position xpos, if possible, such that both of the following conditions hold:
  • (1.1)
    xpos <= pos and xpos < size();
  • (1.2)
    traits​::​eq(at(xpos), sv.at(I)) for some element I of the data referenced by sv.
2
#
Remarks: This function shall not participate in overload resolution unless is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and is_­convertible_­v<const T&, const charT*> is false.
3
#
Throws: Nothing unless the initialization of sv throws an exception.
4
#
Returns: xpos if the function can determine such a value for xpos.
Otherwise, returns npos.
🔗
size_type find_last_of(const basic_string& str, size_type pos = npos) const noexcept;
5
#
Effects: Equivalent to: return find_­last_­of(basic_­string_­view<charT, traits>(str), pos);
🔗
size_type find_last_of(const charT* s, size_type pos, size_type n) const;
6
#
Returns: find_­last_­of(basic_­string_­view<charT, traits>(s, n), pos).
🔗
size_type find_last_of(const charT* s, size_type pos = npos) const;
7
#
Requires: s points to an array of at least traits​::​length(s) + 1 elements of charT.
8
#
Returns: find_­last_­of(basic_­string_­view<charT, traits>(s), pos).
🔗
size_type find_last_of(charT c, size_type pos = npos) const;
9
#
Returns: find_­last_­of(basic_­string(1, c), pos).

20.3.2.7.6 basic_­string​::​find_­first_­not_­of [string.find.first.not.of]

🔗
template<class T> size_type find_first_not_of(const T& t, size_type pos = 0) const;
1
#
Effects: Creates a variable, sv, as if by basic_­string_­view<charT, traits> sv = t; and then determines the lowest position xpos, if possible, such that both of the following conditions hold:
  • (1.1)
    pos <= xpos and xpos < size();
  • (1.2)
    traits​::​eq(at(xpos), sv.at(I)) for no element I of the data referenced by sv.
2
#
Remarks: This function shall not participate in overload resolution unless is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and is_­convertible_­v<const T&, const charT*> is false.
3
#
Throws: Nothing unless the initialization of sv throws an exception.
4
#
Returns: xpos if the function can determine such a value for xpos.
Otherwise, returns npos.
🔗
size_type find_first_not_of(const basic_string& str, size_type pos = 0) const noexcept;
5
#
Effects: Equivalent to: 
return find_first_not_of(basic_string_view<charT, traits>(str), pos);
🔗
size_type find_first_not_of(const charT* s, size_type pos, size_type n) const;
6
#
Returns: find_­first_­not_­of(basic_­string_­view<charT, traits>(s, n), pos).
🔗
size_type find_first_not_of(const charT* s, size_type pos = 0) const;
7
#
Requires: s points to an array of at least traits​::​length(s) + 1 elements of charT.
8
#
Returns: find_­first_­not_­of(basic_­string_­view<charT, traits>(s), pos).
🔗
size_type find_first_not_of(charT c, size_type pos = 0) const;
9
#
Returns: find_­first_­not_­of(basic_­string(1, c), pos).

20.3.2.7.7 basic_­string​::​find_­last_­not_­of [string.find.last.not.of]

🔗
template<class T> size_type find_last_not_of(const T& t, size_type pos = npos) const;
1
#
Effects: Creates a variable, sv, as if by basic_­string_­view<charT, traits> sv = t; and then determines the highest position xpos, if possible, such that both of the following conditions hold:
  • (1.1)
    xpos <= pos and xpos < size();
  • (1.2)
    traits​::​eq(at(xpos), sv.at(I)) for no element I of the data referenced by sv.
2
#
Remarks: This function shall not participate in overload resolution unless is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and is_­convertible_­v<const T&, const charT*> is false.
3
#
Throws: Nothing unless the initialization of sv throws an exception.
4
#
Returns: xpos if the function can determine such a value for xpos.
Otherwise, returns npos.
🔗
size_type find_last_not_of(const basic_string& str, size_type pos = npos) const noexcept;
5
#
Effects: Equivalent to: 
return find_last_not_of(basic_string_view<charT, traits>(str), pos);
🔗
size_type find_last_not_of(const charT* s, size_type pos, size_type n) const;
6
#
Returns: find_­last_­not_­of(basic_­string_­view<charT, traits>(s, n), pos).
🔗
size_type find_last_not_of(const charT* s, size_type pos = npos) const;
7
#
Requires: s points to an array of at least traits​::​length(s) + 1 elements of charT.
8
#
Returns: find_­last_­not_­of(basic_­string_­view<charT, traits>(s), pos).
🔗
size_type find_last_not_of(charT c, size_type pos = npos) const;
9
#
Returns: find_­last_­not_­of(basic_­string(1, c), pos).

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

🔗
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).

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

🔗
template<class T> int compare(const T& t) const;
1
#
Effects: Creates a variable, sv, as if by basic_­string_­view<charT, traits> sv = t; and then determines the effective length rlen of the strings to compare as the smaller of size() and sv.size().
The function then compares the two strings by calling traits​::​compare(data(), sv.data(), rlen).
2
#
Returns: The nonzero result if the result of the comparison is nonzero.
Otherwise, returns a value as indicated in Table 58.
Table 58 — compare() results
Condition
Return Value
size() <  sv.size()
< 0
size() == sv.size()
 0
size() >  sv.size()
> 0
3
#
Remarks: This function shall not participate in overload resolution unless is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and is_­convertible_­v<const T&, const charT*> is false.
4
#
Throws: Nothing unless the initialization of sv throws an exception.
🔗
template<class T> int compare(size_type pos1, size_type n1, const T& t) const;
5
#
Effects: Equivalent to: 
{
  basic_string_view<charT, traits> sv = t;
  return basic_string_view<charT, traits>(data(), size()).substr(pos1, n1).compare(sv);
}
6
#
Remarks: This function shall not participate in overload resolution unless is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and is_­convertible_­v<const T&, const charT*> is false.
🔗
template<class T> int compare(size_type pos1, size_type n1, const T& t, size_type pos2, size_type n2 = npos) const;
7
#
Effects: Equivalent to: 
basic_string_view<charT, traits> sv = t;
return basic_string_view<charT, traits>(
    data(), size()).substr(pos1, n1).compare(sv.substr(pos2, n2));
8
#
Remarks: This function shall not participate in overload resolution unless is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and is_­convertible_­v<const T&, const charT*> is false.
🔗
int compare(const basic_string& str) const noexcept;
9
#
Effects: Equivalent to: return compare(basic_­string_­view<charT, traits>(str));
🔗
int compare(size_type pos1, size_type n1, const basic_string& str) const;
10
#
Effects: Equivalent to: return compare(pos1, n1, basic_­string_­view<charT, traits>(str));
🔗
int compare(size_type pos1, size_type n1, const basic_string& str, size_type pos2, size_type n2 = npos) const;
11
#
Effects: Equivalent to: 
return compare(pos1, n1, basic_string_view<charT, traits>(str), pos2, n2);
🔗
int compare(const charT* s) const;
12
#
Returns: compare(basic_­string(s)).
🔗
int compare(size_type pos, size_type n1, const charT* s) const;
13
#
Returns: basic_­string(*this, pos, n1).compare(basic_­string(s)).
🔗
int compare(size_type pos, size_type n1, const charT* s, size_type n2) const;
14
#
Returns: basic_­string(*this, pos, n1).compare(basic_­string(s, n2)).

20.3.2.7.10 basic_­string​::​starts_­with [string.starts.with]

🔗
bool starts_with(basic_string_view<charT, traits> x) const noexcept; bool starts_with(charT x) const noexcept; bool starts_with(const charT* x) const;
1
#
Effects: Equivalent to: 
return basic_string_view<charT, traits>(data(), size()).starts_with(x);

20.3.2.7.11 basic_­string​::​ends_­with [string.ends.with]

🔗
bool ends_with(basic_string_view<charT, traits> x) const noexcept; bool ends_with(charT x) const noexcept; bool ends_with(const charT* x) const;
1
#
Effects: Equivalent to: 
return basic_string_view<charT, traits>(data(), size()).ends_with(x);

20.3.3 Non-member functions [string.nonmembers]

20.3.3.1 operator+ [string.op+]

🔗
template<class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator+(const basic_string<charT, traits, Allocator>& lhs, const basic_string<charT, traits, Allocator>& rhs);
1
#
Returns: basic_­string<charT, traits, Allocator>(lhs).append(rhs).
🔗
template<class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator+(basic_string<charT, traits, Allocator>&& lhs, const basic_string<charT, traits, Allocator>& rhs);
2
#
Returns: std​::​move(lhs.append(rhs)).
🔗
template<class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator+(const basic_string<charT, traits, Allocator>& lhs, basic_string<charT, traits, Allocator>&& rhs);
3
#
Returns: std​::​move(rhs.insert(0, lhs)).
🔗
template<class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator+(basic_string<charT, traits, Allocator>&& lhs, basic_string<charT, traits, Allocator>&& rhs);
4
#
Returns: std​::​move(lhs.append(rhs)).
[ Note
:
Or equivalently, std​::​move(rhs.insert(0, lhs)).
— end note
 ]
🔗
template<class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator+(const charT* lhs, const basic_string<charT, traits, Allocator>& rhs);
5
#
Returns: basic_­string<charT, traits, Allocator>(lhs) + rhs.
6
#
Remarks: Uses traits​::​length().
🔗
template<class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator+(const charT* lhs, basic_string<charT, traits, Allocator>&& rhs);
7
#
Returns: std​::​move(rhs.insert(0, lhs)).
8
#
Remarks: Uses traits​::​length().
🔗
template<class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator+(charT lhs, const basic_string<charT, traits, Allocator>& rhs);
9
#
Returns: basic_­string<charT, traits, Allocator>(1, lhs) + rhs.
🔗
template<class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator+(charT lhs, basic_string<charT, traits, Allocator>&& rhs);
10
#
Returns: std​::​move(rhs.insert(0, 1, lhs)).
🔗
template<class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator+(const basic_string<charT, traits, Allocator>& lhs, const charT* rhs);
11
#
Returns: lhs + basic_­string<charT, traits, Allocator>(rhs).
12
#
Remarks: Uses traits​::​length().
🔗
template<class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator+(basic_string<charT, traits, Allocator>&& lhs, const charT* rhs);
13
#
Returns: std​::​move(lhs.append(rhs)).
14
#
Remarks: Uses traits​::​length().
🔗
template<class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator+(const basic_string<charT, traits, Allocator>& lhs, charT rhs);
15
#
Returns: lhs + basic_­string<charT, traits, Allocator>(1, rhs).
🔗
template<class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator+(basic_string<charT, traits, Allocator>&& lhs, charT rhs);
16
#
Returns: std​::​move(lhs.append(1, rhs)).

20.3.3.2 operator== [string.operator==]

🔗
template<class charT, class traits, class Allocator> bool operator==(const basic_string<charT, traits, Allocator>& lhs, const basic_string<charT, traits, Allocator>& rhs) noexcept;
1
#
Returns: lhs.compare(rhs) == 0.
🔗
template<class charT, class traits, class Allocator> bool operator==(const charT* lhs, const basic_string<charT, traits, Allocator>& rhs);
2
#
Returns: rhs == lhs.
🔗
template<class charT, class traits, class Allocator> bool operator==(const basic_string<charT, traits, Allocator>& lhs, const charT* rhs);
3
#
Requires: rhs points to an array of at least traits​::​length(rhs) + 1 elements of charT.
4
#
Returns: lhs.compare(rhs) == 0.

20.3.3.3 operator!= [string.op!=]

🔗
template<class charT, class traits, class Allocator> bool operator!=(const basic_string<charT, traits, Allocator>& lhs, const basic_string<charT, traits, Allocator>& rhs) noexcept;
1
#
Returns: !(lhs == rhs).
🔗
template<class charT, class traits, class Allocator> bool operator!=(const charT* lhs, const basic_string<charT, traits, Allocator>& rhs);
2
#
Returns: rhs != lhs.
🔗
template<class charT, class traits, class Allocator> bool operator!=(const basic_string<charT, traits, Allocator>& lhs, const charT* rhs);
3
#
Requires: rhs points to an array of at least traits​::​length(rhs) + 1 elements of charT.
4
#
Returns: lhs.compare(rhs) != 0.

20.3.3.4 operator< [string.op<]

🔗
template<class charT, class traits, class Allocator> bool operator<(const basic_string<charT, traits, Allocator>& lhs, const basic_string<charT, traits, Allocator>& rhs) noexcept;
1
#
Returns: lhs.compare(rhs) < 0.
🔗
template<class charT, class traits, class Allocator> bool operator<(const charT* lhs, const basic_string<charT, traits, Allocator>& rhs);
2
#
Returns: rhs.compare(lhs) > 0.
🔗
template<class charT, class traits, class Allocator> bool operator<(const basic_string<charT, traits, Allocator>& lhs, const charT* rhs);
3
#
Returns: lhs.compare(rhs) < 0.

20.3.3.5 operator> [string.op>]

🔗
template<class charT, class traits, class Allocator> bool operator>(const basic_string<charT, traits, Allocator>& lhs, const basic_string<charT, traits, Allocator>& rhs) noexcept;
1
#
Returns: lhs.compare(rhs) > 0.
🔗
template<class charT, class traits, class Allocator> bool operator>(const charT* lhs, const basic_string<charT, traits, Allocator>& rhs);
2
#
Returns: rhs.compare(lhs) < 0.
🔗
template<class charT, class traits, class Allocator> bool operator>(const basic_string<charT, traits, Allocator>& lhs, const charT* rhs);
3
#
Returns: lhs.compare(rhs) > 0.

20.3.3.6 operator<= [string.op<=]

🔗
template<class charT, class traits, class Allocator> bool operator<=(const basic_string<charT, traits, Allocator>& lhs, const basic_string<charT, traits, Allocator>& rhs) noexcept;
1
#
Returns: lhs.compare(rhs) <= 0.
🔗
template<class charT, class traits, class Allocator> bool operator<=(const charT* lhs, const basic_string<charT, traits, Allocator>& rhs);
2
#
Returns: rhs.compare(lhs) >= 0.
🔗
template<class charT, class traits, class Allocator> bool operator<=(const basic_string<charT, traits, Allocator>& lhs, const charT* rhs);
3
#
Returns: lhs.compare(rhs) <= 0.

20.3.3.7 operator>= [string.op>=]

🔗
template<class charT, class traits, class Allocator> bool operator>=(const basic_string<charT, traits, Allocator>& lhs, const basic_string<charT, traits, Allocator>& rhs) noexcept;
1
#
Returns: lhs.compare(rhs) >= 0.
🔗
template<class charT, class traits, class Allocator> bool operator>=(const charT* lhs, const basic_string<charT, traits, Allocator>& rhs);
2
#
Returns: rhs.compare(lhs) <= 0.
🔗
template<class charT, class traits, class Allocator> bool operator>=(const basic_string<charT, traits, Allocator>& lhs, const charT* rhs);
3
#
Returns: lhs.compare(rhs) >= 0.

20.3.3.8 swap [string.special]

🔗
template<class charT, class traits, class Allocator> void swap(basic_string<charT, traits, Allocator>& lhs, basic_string<charT, traits, Allocator>& rhs) noexcept(noexcept(lhs.swap(rhs)));
1
#
Effects: Equivalent to lhs.swap(rhs).

20.3.3.9 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​::​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')).

20.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 != 0, 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 != 0, 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 != 0, 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 != 0, 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.

20.3.5 Hash support [basic.string.hash]

🔗
template<> struct hash<string>; template<> struct hash<u16string>; template<> struct hash<u32string>; template<> struct hash<wstring>; template<> struct hash<pmr::string>; 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)).

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

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