std::flat_m...nsert_range(3)

💅 std::flat_multimap::insert_range

ok so bestie, we're in the C++ Standard Libary manual — yes that's how it's spelled on the tin, we don't ask questions — and today's main character is std::flat_multimap::insert_range. this page is dated 2024.06.10 and it lives at http://cppreference.com, and honestly? it ate. let's get into it 🫶

---

✨ NAME ✨

std::flat_multimap::insert_range — literally just std::flat_multimap::insert_range, no notes, the name is the name 💅

---

🌸 Synopsis 🌸

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

So what's the vibe? It inserts a copy of each element in the range rg into underlying containers c — and it does it as if by this whole situation right here:

for (const auto& e : rg)
{
    c.keys.insert(c.keys.end(), e.first);
    c.values.insert(c.values.end(), e.second);
}

Then — and this is the part where it gets iconic — it sorts the range of newly inserted elements with respect to value_comp(), and then merges the resulting sorted range and the sorted range of pre-existing elements into a single sorted range. like, it's giving organized. it's giving tidy. 🌈

Two things you NEED to know, no cap:

• Each iterator in the range rg is dereferenced exactly once ⭐
• The behavior is undefined if rg overlaps with the container 😭 so like. don't do that. fr.

Information on iterator invalidation is copied from here.

(that's a direct quote, we're just relaying the message 🧚)

---

🎀 Parameters 🎀

• rg — a container compatible range, that is, an input_range whose elements are convertible to T. that's it, that's the whole parameter, she's low maintenance 💖

---

💜 Return value 💜

(none) — nada, nothing, zero, the void. she does the work and leaves without a word 👑

---

🔥 Complexity 🔥

N + M·log(M), where N is size() before the operation and M is ranges::distance(rg). math girlies rise 😤

---

🦋 Notes 🦋

Since insert_range performs an in-place merge operation, that may allocate memory. heads up, bestie — it's not free, keep an eye on your allocator 🙈

---

🌟 Example 🌟

// Run this code — as the manpage says, go run it ✨

#include <iostream>
#include <flat_map>
#include <utility>

void println(auto, auto const& container)
{
    for (const auto& [key, value] : container)
        std::cout << '{' << key << ',' << value << '}' << ' ';
    std::cout << '\n';
}

int main()
{
    auto container = std::flat_multimap{std::pair{1, 11}, {3, 33}, {2, 22}, {4, 44}};
    const auto rg = {std::pair{-1, -11}, {3, -33}, {-2, -22}};
#ifdef __cpp_lib_containers_ranges
    container.insert_range(rg);
#else
    container.insert(rg.begin(), rg.end());
#endif
    println("{}", container);
}

💀 Output 💀

{-2,-22} {-1,-11} {1,11} {2,22} {3,33} {3,-33} {4,44}

look at that sorted little family. the {3,33} and {3,-33} sitting next to each other? that's the multimap of it all, periodt 🎀

---

👑 See also 👑

• insert — inserts elements (public member function) 💅

---

ok bye bestie, go sort something beautiful 💖

— that's the whole page, sourced from http://cppreference.com, dated 2024.06.10, in the C++ Standard Libary manual, std::flat_m...nsert_range(3). mwah 🫶🌸