std::unorde...iset::merge(3)

🎀 std::unordered_multiset::merge — bestie edition 🎀

okay so this is the std::unorde...iset::merge(3) page from the C++ Standard Libary manual — yes, that's how “Libary” is spelled up top, and no, we're not fixing it, it's iconic. 💅

---

💖 NAME 💖

std::unordered_multiset::merge — literally std::unordered_multiset::merge. that's the whole name, bestie. ✨

---

✨ Synopsis ✨

bestie, there are four overloads and they're all since C++17. here they are, exactly:

(1) (since C++17)
template< class H2, class P2 >
void merge( std::unordered_set<Key, H2, P2, Allocator>& source );

(2) (since C++17)
template< class H2, class P2 >
void merge( std::unordered_set<Key, H2, P2, Allocator>&& source );

(3) (since C++17)
template< class H2, class P2 >
void merge( std::unordered_multiset<Key, H2, P2, Allocator>& source );

(4) (since C++17)
template< class H2, class P2 >
void merge( std::unordered_multiset<Key, H2, P2, Allocator>&& source );

so what does it do? it attempts to extract ("splice") each element in source and insert it into *this using the hash function and key equality predicate of *this. 🫶

and here's the cute part: no elements are copied or moved — only the internal pointers of the container nodes are repointed. so all pointers and references to the transferred elements remain valid, but now refer into *this, not into source. 💫

but bestie, listen: iterators referring to the transferred elements and all iterators referring to *this are invalidated. 😭

⚠️ DANGER, bestie: the behavior is undefined if get_allocator() != source.get_allocator(). like, undefined behavior is not the vibe. do not do that. 💀

---

🫶 Parameters 🫶

• source — compatible container to transfer the nodes from. that's it, that's the parameter. 🎀

---

💫 Return value 💫

• (none) — nothing comes back. it does the thing and dips. 🦋

---

🔥 Complexity 🔥

average case O(N), worst case O(N * size() + N), where N is source.size(). slay. ✨

---

🌈 Example 🌈

the page says // Run this code, so run it, bestie:

#include <iostream>
#include <unordered_set>

// print out a container
template<class Os, class K>
Os& operator<<(Os& os, const std::unordered_multiset<K>& v)
{
    os << '[' << v.size() << "] {";
    bool o{};
    for (const auto& e : v)
        os << (o ? ", " : (o = 1, " ")) << e;
    return os << " }\n";
}

int main()
{
    std::unordered_multiset<char>
        p{'C', 'B', 'B', 'A'},
        q{'E', 'D', 'E', 'C'};

    std::cout << "p: " << p << "q: " << q;

    p.merge(q);

    std::cout << "p.merge(q);\n" << "p: " << p << "q: " << q;
}

💀 Possible output 💀

p: [4] { A, B, B, C }
q: [4] { C, D, E, E }
p.merge(q);
p: [8] { E, E, D, A, B, B, C, C }
q: [0] { }

look at q after the merge: [0] { }. empty. gone. she transferred everything and said periodt. 💅

---

👑 See also 👑

• extract — extracts nodes from the container. (C++17) (public member function) 🌸
• insert — inserts elements or nodes. (since C++17) (public member function) ⭐

---

🫶 that's the whole page, bestie. footer vibe check: source http://cppreference.com, version/date 2024.06.10, page std::unorde...iset::merge(3). no cap, that's the sign-off. 💜