std::basic_string::replace(3)

hiii bestie 💖 welcome to the std::basic_string::replace(3) page — that’s the manual name, and we’re in the C++ Standard Libary (their spelling, not mine 💀). This is the member function that swaps out a chunk of characters in a basic_string for new ones, and yes, it has a whole overload cinematic universe. We’re keeping every flag, range, exception, and constexpr since C++20 receipt. Periodt. ✨

✨ NAME ✨

std::basic_string::replace — std::basic_string::replace. The name and the description are literally the same, minimal queen behavior. 👑

🌸 Synopsis 🌸

basic_string& replace( size_type pos,
                       size_type count,
                       const basic_string& str );                      // (1) (constexpr since C++20)
basic_string& replace( const_iterator first,
                       const_iterator last,
                       const basic_string& str );                      // (2) (constexpr since C++20)
basic_string& replace( size_type pos,
                       size_type count,
                       const basic_string& str,
                       size_type pos2,
                       size_type count2 );                             // (until C++14)
basic_string& replace( size_type pos,
                       size_type count,
                       const basic_string& str,
                       size_type pos2,
                       size_type count2 = npos );                      // (since C++14) (constexpr since C++20)
basic_string& replace( size_type pos,
                       size_type count,
                       const CharT* cstr,
                       size_type count2 );                             // (4) (constexpr since C++20)
basic_string& replace( const_iterator first,
                       const_iterator last,
                       const CharT* cstr,
                       size_type count2 );                             // (5) (constexpr since C++20)
basic_string& replace( size_type pos,
                       size_type count,
                       const CharT* cstr );                            // (6) (constexpr since C++20)
basic_string& replace( const_iterator first,
                       const_iterator last,
                       const CharT* cstr );                            // (7) (constexpr since C++20)
basic_string& replace( size_type pos,
                       size_type count,
                       size_type count2,
                       CharT ch );                                     // (8) (constexpr since C++20)
basic_string& replace( const_iterator first,
                       const_iterator last,
                       size_type count2,
                       CharT ch );                                     // (3) (9) (constexpr since C++20)
template< class InputIt >
basic_string& replace( const_iterator first,
                       const_iterator last,
                       InputIt first2,
                       InputIt last2 );                                // (10) (constexpr since C++20)
basic_string& replace( const_iterator first,
                       const_iterator last,
                       std::initializer_list<CharT> ilist );           // (11) (since C++11) (constexpr since C++20)
template< class StringViewLike >
basic_string& replace( size_type pos,
                       size_type count,
                       const StringViewLike& t );                      // (12) (since C++17) (constexpr since C++20)
template< class StringViewLike >
basic_string& replace( const_iterator first,
                       const_iterator last,
                       const StringViewLike& t );                      // (13) (since C++17) (constexpr since C++20)
template< class StringViewLike >
basic_string& replace( size_type pos,
                       size_type count,
                       const StringViewLike& t,
                       size_type pos2,
                       size_type count2 = npos );                      // (14) (since C++17) (constexpr since C++20)

💖 Description 💖

okay so here’s the vibe: these functions replace the characters in the range [begin() + pos, begin() + std::min(pos + count, size())) or [first, last) with the characters you give them. The exact replacement depends on which overload you pick:

1. Overloads (1), (2): those characters are replaced with str. 💅
2. Overload (3): those characters are replaced with a substring [pos2, std::min(pos2 + count2, str.size())) of str.
3. Overloads (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 — not cute, do not do this. 🚨
4. Overloads (6), (7): those characters are replaced with the characters in the range [cstr, cstr + Traits::length(cstr)).
5. Overloads (8), (9): those characters are replaced with count2 copies of ch.
6. Overload (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())).
7. Overload (11): those characters are replaced with the characters in ilist.
8. Overloads (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. 🫶
9. Overload (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. the same string object, now with new characters. thank u, next. 💁‍♀️

💀 Exceptions 💀

• Overload (1): throws std::out_of_range if pos > size().
• Overload (3): throws std::out_of_range if pos > size() or pos2 > str.size().
• Overloads (4), (6), (8): throw std::out_of_range if pos > size().
• Overloads (12), (14): throw std::out_of_range if pos > size().

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

If an exception is thrown for any reason, these functions have no effect (strong exception safety guarantee). so your string stays unbothered, fr fr. 🛡️

🍓 Example 🍓

This section is incomplete. Reason: no example.

bestie, the example literally didn’t show up 😭 no code demo here. not me being the messenger. 🙈

🔥 Defect reports 🔥

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

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

🌈 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 replacement text (C++11) (function template)
• replace, replace_if — replaces all values satisfying specific criteria with another value (function template)

💜 Category 💜

Category: * Todo no example — yeah, it’s a todo. The example section is still waiting for its main character moment. 💀

---

catch u later, bestie 🫶 this page came from http://cppreference.com, version/date 2024.06.10, and the manual page is std::basic_string::replace(3). mwah 💋