std::basic_string::replace(3)

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