NAME¶

std::basic_string::replace - std::basic_string::replace

Synopsis¶

basic_string& replace( size_type pos,
size_type count, (1) (constexpr since
const basic_string& str C++20)
);
basic_string& replace( const_iterator first,
const_iterator last, (2) (constexpr since
const basic_string& str C++20)
);
basic_string& replace( size_type pos,
size_type count,

const basic_string& (until C++14)
str,

size_type pos2,
size_type count2 );
basic_string& replace( size_type pos,
size_type count,
(since C++14)
const basic_string& (constexpr since
str, C++20)

size_type pos2,
size_type count2 = npos );
basic_string& replace( size_type pos,
size_type count, (4) (constexpr since
const CharT* cstr, C++20)
size_type count2 );
basic_string& replace( const_iterator first,
const_iterator last, (5) (constexpr since
const CharT* cstr, C++20)
size_type count2 );
basic_string& replace( size_type pos, (constexpr since
size_type count, (6) C++20)
const CharT* cstr );
basic_string& replace( const_iterator first, (constexpr since
const_iterator last, (7) C++20)
const CharT* cstr );
basic_string& replace( size_type pos,
size_type count, (8) (constexpr since
size_type count2, CharT C++20)
ch );
basic_string& replace( const_iterator first,
const_iterator last, (3) (9) (constexpr since
size_type count2, CharT C++20)
ch );
template< class InputIt >

basic_string& replace( const_iterator first, (constexpr since
const_iterator last, (10) C++20)

InputIt first2, InputIt
last2 );
basic_string& replace( const_iterator first, (since C++11)
const_iterator last, (11) (constexpr since
C++20)
std::initializer_list<CharT> ilist );
template< class StringViewLike >

basic_string& replace( size_type pos, (since C++17)
size_type count, (12) (constexpr since
C++20)
const StringViewLike& t
);
template< class StringViewLike >

basic_string& replace( const_iterator first, (since C++17)
const_iterator last, (13) (constexpr since
C++20)
const StringViewLike& t
);
template< class StringViewLike >

basic_string& replace( size_type pos,
size_type count, (since C++17)
const StringViewLike& (14) (constexpr since
t, C++20)

size_type pos2,
size_type count2 = npos );

Replaces the characters in the range [begin() + pos, begin() + std::min(pos + count,
size())) or [first, last) with given characters.

1,2) Those characters are replaced with str.
3) Those characters are replaced with a substring [pos2, std::min(pos2 + count2,
str.size())) of str.
4,5) Those characters are replaced with the characters in the range [cstr, cstr +
count2).
If [cstr, cstr + count2) is not a valid range, the behavior is undefined.
6,7) Those characters are replaced with the characters in the range [cstr, cstr +
Traits::length(cstr)).
8,9) Those characters are replaced with count2 copies of ch.
10) Those characters are replaced with the characters in the range [first2, last2)
as if by replace(first, last, basic_string(first2, last2, get_allocator())).
11) Those characters are replaced with the characters in ilist.
12,13) Implicitly converts t to a string view sv as if by
std::basic_string_view<CharT, Traits> sv = t;, then those characters are replaced
with the characters from sv.
These overloads participate in overload resolution only if
std::is_convertible_v<const StringViewLike&,
std::basic_string_view<CharT, Traits>> is true and
std::is_convertible_v<const StringViewLike&, const CharT*> is false.
14) Implicitly converts t to a string view sv as if by std::basic_string_view<CharT,
Traits> sv = t;, then those characters are replaced with the characters from the
subview sv.substr(pos2, count2).
This overload participates in overload resolution only if
std::is_convertible_v<const StringViewLike&,
std::basic_string_view<CharT, Traits>> is true and
std::is_convertible_v<const StringViewLike&, const CharT*> is false.

If [begin(), first) or [first, last) is not a valid range, the behavior is
undefined.

Parameters¶

pos - start of the substring that is going to be replaced
count - length of the substring that is going to be replaced
first, last - range of characters that is going to be replaced
str - string to use for replacement
pos2 - start of the substring to replace with
count2 - number of characters to replace with
cstr - pointer to the character string to use for replacement
ch - character value to use for replacement
first2, last2 - range of characters to use for replacement
ilist - initializer list with the characters to use for replacement
t - object (convertible to std::basic_string_view) with the characters
to use for replacement

Type requirements¶

-
InputIt must meet the requirements of LegacyInputIterator.

Return value¶

*this.

Exceptions¶

1) Throws std::out_of_range if pos > size().
3) Throws std::out_of_range if pos > size() or pos2 > str.size().
4,6,8) Throws std::out_of_range if pos > size().
12,14) Throws std::out_of_range if pos > size().

If the operation would result in size() > max_size(), throws std::length_error.

If an exception is thrown for any reason, these functions have no effect (strong
exception safety guarantee).

Example¶

This section is incomplete
Reason: no example

Defect reports

The following behavior-changing defect reports were applied retroactively to
previously published C++ standards.

DR Applied to Behavior as published Correct behavior
LWG 847 C++98 there was no exception safety added strong exception safety
guarantee guarantee
LWG 1323 C++98 the types of first and last changed to const_iterator
were iterator
LWG 2946 C++17 overloads (12,13) caused avoided by making them templates
ambiguity in some cases

See also¶

replace_with_range replaces specified portion of a string with a range of characters
(C++23) (public member function)
regex_replace replaces occurrences of a regular expression with formatted
(C++11) replacement text
(function template)
replace replaces all values satisfying specific criteria with another
replace_if value
(function template)

Category:¶

* Todo no example