std::deque::assign_range(3)

💖 std::deque::assign_range(3) 💖

okay so bestie, welcome to the std::deque::assign_range page from the C++ Standard Library — yes that C++ Standard Library, the one with the manual name std::deque::assign_range(3). grab a lil snack 🍓, we're getting into it.

---

✨ NAME ✨

std::deque::assign_range — literally what it says on the tin: std::deque::assign_range. no cap, that's the whole name section 💅

---

🌸 SYNOPSIS 🌸

template< container-compatible-range<T> R >  (since C++23)
void assign_range( R&& rg );

so what does it do? it replaces elements in the container with a copy of each element in rg. that's the whole main character move 👑

and now the serious part, because this is important — all iterators (including the end() iterator) and all references to the elements are invalidated. 😭 like, all of them. gone. do not hold onto them, bestie, they will betray you.

Each iterator in the range rg is dereferenced exactly once. one and done, no double-dipping 🫶

⚠️ The behavior is undefined if rg overlaps with the container. fr fr, keep them separate, this is not a drill 💀

---

🎀 Parameters 🎀

• rg — an input_range with reference type convertible to the element type of the container

---

🦋 Type requirements 🦋

• std::assignable_from<T&, ranges::range_reference_t<R>> must be modeled. Otherwise, the program is ill-formed. 💀
• T must be EmplaceConstructible into the container from *ranges::begin(rg). Otherwise, the behavior is undefined. 🙈

---

💅 Return value 💅

(none) — nothing, nada, it's giving void. don't @ me ✨

---

🔥 Notes 🔥

okay so there's a feature-test macro you can vibe-check for this one:

• __cpp_lib_containers_ranges — value 202202L, std (C++23), feature Ranges-aware construction and insertion 🌈

---

⭐ Example ⭐

// Run this code

#include <algorithm>
#include <cassert>
#include <deque>
#include <list>

int main()
{
    const auto source = std::list{2, 7, 1};
    auto destination = std::deque{3, 1, 4};
#ifdef __cpp_lib_containers_ranges
    destination.assign_range(source);
#else
    destination.assign(source.cbegin(), source.cend());
#endif
    assert(std::ranges::equal(source, destination));
}

see how it falls back to destination.assign(source.cbegin(), source.cend()); when the macro isn't there? that's the graceful era-appropriate backup, we love a portable icon 💖

---

🧚 See also 🧚

• insert_range — inserts a range of elements (C++23) (public member function)
• prepend_range — adds a range of elements to the beginning (C++23) (public member function)
• append_range — adds a range of elements to the end (C++23) (public member function)
• assign — assigns values to the container (public member function)

---

and that's the page!! 🎀 source is http://cppreference.com, dated 2024.06.10, and this whole little manual page is std::deque::assign_range(3). mwah, go invalidate some iterators responsibly 💜🦋