std::basic_...e_with_range(3)

💖 std::basic_string::replace_with_range 💖

okay bestie, this one comes straight from the C++ Standard Libary manual — and yes, that's how it's spelled in the header, I'm not fixing it, I'm just delivering the facts with glitter. ✨ The header title is out here looking like std::basic_...e_with_range(3), so consider this your very cute near-the-top manual-name moment. 🫶

---

🌸 NAME 🌸

std::basic_string::replace_with_range — and the NAME section literally says it twice: std::basic_string::replace_with_range. We love a name so nice they had to say it twice. 💅

---

✨ Synopsis ✨

          template< container-compatible-range<CharT> R >

          constexpr std::basic_string& replace_with_range( const_iterator
          first,
       (since C++23)
                                                           const_iterator last,

                                                           R&& rg );

So this one replaces the characters in the range [first, last) with the characters from the range rg. It is equivalent to this exact code right here:

return replace(first,
               last,
               std::basic_string(
                   std::from_range,
                   std::forward<R>(rg),
                   get_allocator())
);

---

🎀 Parameters 🎀

• first, last — range of characters that is going to be replaced.
• rg — a container compatible range.

---

🦋 Return value 🦋

*this

---

🌸 Complexity 🌸

Linear in size of rg.

---

💀 Exceptions 💀

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

If an exception is thrown for any reason, this function has no effect — that's the strong exception safety guarantee, bestie. No messy half-done vibes. 🫶

---

👑 Notes 👑

• Feature-test macro: __cpp_lib_containers_ranges — value 202202L, std (C++23), feature: member functions that accept container compatible range.

---

🌈 Example 🌈

// Run this code

#include <algorithm>
#include <cassert>
#include <forward_list>
#include <iterator>
#include <string>

int main()
{
    using namespace std::literals;

    auto s{"Today is today!"s};
    constexpr auto today{"today"sv};
    constexpr auto tomorrow{"tomorrow's yesterday"sv};
    std::forward_list<char> rg;
    std::ranges::reverse_copy(tomorrow, std::front_inserter(rg));

    const auto pos{s.rfind(today)};
    assert(pos != s.npos);
    const auto first{std::next(s.begin(), pos)};
    const auto last{std::next(first, today.length())};

#ifdef __cpp_lib_containers_ranges
    s.replace_range(first, last, rg);
#else
    s.replace(first, last, rg.cbegin(), rg.cend());
#endif

    assert("Today is tomorrow's yesterday!" == s);
}

The code block above is exactly as the page gives it — including the s.replace_range(first, last, rg); line. I am not fixing a single character, bestie. 💅

---

⭐ See also ⭐

• replace — replaces specified portion of a string (public member function).

---

okay that's the whole page 💖 — source/version is http://cppreference.com and the date on it is 2024.06.10, for the std::basic_...e_with_range(3) page. periodt. 🫶✨