21 Strings library [strings]

21.3 String classes [string.classes]

21.3.2 Class template basic_­string [basic.string]

21.3.2.6 Modifiers [string.modifiers]

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

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

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

basic_string& append(const basic_string& str);
Effects: Equivalent to: return append(str.data(), str.size());
basic_string& append(const basic_string& str, size_type pos, size_type n = npos);
Effects: Equivalent to:
return append(basic_string_view<charT, traits>(str).substr(pos, n));
template<class T> basic_string& append(const T& t);
Constraints:
  • is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and
  • is_­convertible_­v<const T&, const charT*> is false.
Effects: Equivalent to:
basic_string_view<charT, traits> sv = t;
return append(sv.data(), sv.size());
template<class T> basic_string& append(const T& t, size_type pos, size_type n = npos);
Constraints:
  • is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and
  • is_­convertible_­v<const T&, const charT*> is false.
Effects: Equivalent to:
basic_string_view<charT, traits> sv = t;
return append(sv.substr(pos, n));
basic_string& append(const charT* s, size_type n);
Expects: [s, s + n) is a valid range.
Effects: Appends a copy of the range [s, s + n) to the string.
Returns: *this.
basic_string& append(const charT* s);
Effects: Equivalent to: return append(s, traits::length(s));
basic_string& append(size_type n, charT c);
Effects: Appends n copies of c to the string.
Returns: *this.
template<class InputIterator> basic_string& append(InputIterator first, InputIterator last);
Constraints: InputIterator is a type that qualifies as an input iterator ([container.requirements.general]).
Effects: Equivalent to: return append(basic_­string(first, last, get_­allocator()));
basic_string& append(initializer_list<charT> il);
Effects: Equivalent to: return append(il.begin(), il.size());
void push_back(charT c);
Effects: Equivalent to append(size_­type{1}, c).

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

basic_string& assign(const basic_string& str);
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);
Effects: Equivalent to: return *this = std::move(str);
basic_string& assign(const basic_string& str, size_type pos, size_type n = npos);
Effects: Equivalent to:
return assign(basic_string_view<charT, traits>(str).substr(pos, n));
template<class T> basic_string& assign(const T& t);
Constraints:
  • is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and
  • is_­convertible_­v<const T&, const charT*> is false.
Effects: Equivalent to:
basic_string_view<charT, traits> sv = t;
return assign(sv.data(), sv.size());
template<class T> basic_string& assign(const T& t, size_type pos, size_type n = npos);
Constraints:
  • is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and
  • is_­convertible_­v<const T&, const charT*> is false.
Effects: Equivalent to:
basic_string_view<charT, traits> sv = t;
return assign(sv.substr(pos, n));
basic_string& assign(const charT* s, size_type n);
Expects: [s, s + n) is a valid range.
Effects: Replaces the string controlled by *this with a copy of the range [s, s + n).
Returns: *this.
basic_string& assign(const charT* s);
Effects: Equivalent to: return assign(s, traits::length(s));
basic_string& assign(initializer_list<charT> il);
Effects: Equivalent to: return assign(il.begin(), il.size());
basic_string& assign(size_type n, charT c);
Effects: Equivalent to:
clear();
resize(n, c);
return *this;
template<class InputIterator> basic_string& assign(InputIterator first, InputIterator last);
Constraints: InputIterator is a type that qualifies as an input iterator ([container.requirements.general]).
Effects: Equivalent to: return assign(basic_­string(first, last, get_­allocator()));

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

basic_string& insert(size_type pos, const basic_string& str);
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);
Effects: Equivalent to:
return insert(pos1, basic_string_view<charT, traits>(str), pos2, n);
template<class T> basic_string& insert(size_type pos, const T& t);
Constraints:
  • is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and
  • is_­convertible_­v<const T&, const charT*> is false.
Effects: Equivalent to:
basic_string_view<charT, traits> sv = t;
return insert(pos, sv.data(), sv.size());
template<class T> basic_string& insert(size_type pos1, const T& t, size_type pos2, size_type n = npos);
Constraints:
  • is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and
  • is_­convertible_­v<const T&, const charT*> is false.
Effects: Equivalent to:
basic_string_view<charT, traits> sv = t;
return insert(pos1, sv.substr(pos2, n));
basic_string& insert(size_type pos, const charT* s, size_type n);
Expects: [s, s + n) is a valid range.
Throws:
  • out_­of_­range if pos > size(),
  • length_­error if n > max_­size() - size(), or
  • any exceptions thrown by allocator_­traits<Allocator>::allocate.
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.
Returns: *this.
basic_string& insert(size_type pos, const charT* s);
Effects: Equivalent to: return insert(pos, s, traits::length(s));
basic_string& insert(size_type pos, size_type n, charT c);
Effects: Inserts n copies of c before the character at position pos if pos < size(), or otherwise at the end of the string.
Returns: *this
Throws:
  • out_­of_­range if pos > size(),
  • length_­error if n > max_­size() - size(), or
  • any exceptions thrown by allocator_­traits<Allocator>::allocate.
iterator insert(const_iterator p, charT c);
Expects: p is a valid iterator on *this.
Effects: Inserts a copy of c at the position p.
Returns: An iterator which refers to the inserted character.
iterator insert(const_iterator p, size_type n, charT c);
Expects: p is a valid iterator on *this.
Effects: Inserts n copies of c at the position p.
Returns: An iterator which refers to the first inserted character, or p if n == 0.
template<class InputIterator> iterator insert(const_iterator p, InputIterator first, InputIterator last);
Constraints: InputIterator is a type that qualifies as an input iterator ([container.requirements.general]).
Expects: p is a valid iterator on *this.
Effects: Equivalent to insert(p - begin(), basic_­string(first, last, get_­allocator())).
Returns: An iterator which refers to the first inserted character, or p if first == last.
iterator insert(const_iterator p, initializer_list<charT> il);
Effects: Equivalent to: return insert(p, il.begin(), il.end());

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

basic_string& erase(size_type pos = 0, size_type n = npos);
Throws: out_­of_­range if pos > size().
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).
Returns: *this.
iterator erase(const_iterator p);
Expects: p is a valid dereferenceable iterator on *this.
Throws: Nothing.
Effects: Removes the character referred to by p.
Returns: An iterator which points to the element immediately following p prior to the element being erased.
If no such element exists, end() is returned.
iterator erase(const_iterator first, const_iterator last);
Expects: first and last are valid iterators on *this.
[first, last) is a valid range.
Throws: Nothing.
Effects: Removes the characters in the range [first, last).
Returns: An iterator which points to the element pointed to by last prior to the other elements being erased.
If no such element exists, end() is returned.
void pop_back();
Expects: !empty().
Throws: Nothing.
Effects: Equivalent to erase(end() - 1).

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

basic_string& replace(size_type pos1, size_type n1, const basic_string& str);
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);
Effects: Equivalent to:
return replace(pos1, n1, basic_string_view<charT, traits>(str).substr(pos2, n2));
template<class T> basic_string& replace(size_type pos1, size_type n1, const T& t);
Constraints:
  • is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and
  • is_­convertible_­v<const T&, const charT*> is false.
Effects: Equivalent to:
basic_string_view<charT, traits> sv = t;
return replace(pos1, n1, sv.data(), sv.size());
template<class T> basic_string& replace(size_type pos1, size_type n1, const T& t, size_type pos2, size_type n2 = npos);
Constraints:
  • is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and
  • is_­convertible_­v<const T&, const charT*> is false.
Effects: Equivalent to:
basic_string_view<charT, traits> sv = t;
return replace(pos1, n1, sv.substr(pos2, n2));
basic_string& replace(size_type pos1, size_type n1, const charT* s, size_type n2);
Expects: [s, s + n2) is a valid range.
Throws:
  • out_­of_­range if pos1 > size(),
  • length_­error if the length of the resulting string would exceed max_­size() (see below), or
  • any exceptions thrown by allocator_­traits<Allocator>::allocate.
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).
Returns: *this.
basic_string& replace(size_type pos, size_type n, const charT* s);
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);
Throws:
  • out_­of_­range if pos1 > size(),
  • length_­error if the length of the resulting string would exceed max_­size() (see below), or
  • any exceptions thrown by allocator_­traits<Allocator>::allocate.
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.
Returns: *this.
basic_string& replace(const_iterator i1, const_iterator i2, const basic_string& str);
Effects: Equivalent to: return replace(i1, i2, basic_­string_­view<charT, traits>(str));
template<class T> basic_string& replace(const_iterator i1, const_iterator i2, const T& t);
Constraints:
  • is_­convertible_­v<const T&, basic_­string_­view<charT, traits>> is true and
  • is_­convertible_­v<const T&, const charT*> is false.
Expects: [begin(), i1) and [i1, i2) are valid ranges.
Effects: Equivalent to:
basic_string_view<charT, traits> sv = t;
return replace(i1 - begin(), i2 - i1, sv.data(), sv.size());
basic_string& replace(const_iterator i1, const_iterator i2, const charT* s, size_type n);
Effects: Equivalent to: return replace(i1, i2, basic_­string_­view<charT, traits>(s, n));
basic_string& replace(const_iterator i1, const_iterator i2, const charT* s);
Effects: Equivalent to: return replace(i1, i2, basic_­string_­view<charT, traits>(s));
basic_string& replace(const_iterator i1, const_iterator i2, size_type n, charT c);
Expects: [begin(), i1) and [i1, i2) are valid ranges.
Effects: Equivalent to: return replace(i1 - begin(), i2 - i1, n, c);
template<class InputIterator> basic_string& replace(const_iterator i1, const_iterator i2, InputIterator j1, InputIterator j2);
Constraints: InputIterator is a type that qualifies as an input iterator ([container.requirements.general]).
Effects: Equivalent to: return replace(i1, i2, basic_­string(j1, j2, get_­allocator()));
basic_string& replace(const_iterator i1, const_iterator i2, initializer_list<charT> il);
Effects: Equivalent to: return replace(i1, i2, il.begin(), il.size());

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

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

21.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);
Expects: allocator_­traits<Allocator>::propagate_­on_­container_­swap::value is true or get_­allocator() == s.get_­allocator().
Ensures: *this contains the same sequence of characters that was in s, s contains the same sequence of characters that was in *this.
Throws: Nothing.
Complexity: Constant time.