std::multimap::merge(3)

🦋 std::multimap::merge(3) — C++ Standard Libary manual 🦋

okay bestie, welcome to the std::multimap::merge(3) page from the C++ Standard Libary manual — yes, “Libary,” we keep the typo, it’s part of the lore 💅✨

🌸 NAME 🌸

std::multimap::merge — std::multimap::merge (that’s the name, no cap, it’s giving self-titled era 🎀)

✨ Synopsis ✨

template< class C2 >                                         (1)
(since C++17)
void merge( std::map<Key, T, C2, Allocator>& source );
template< class C2 >                                         (2)
(since C++17)
void merge( std::map<Key, T, C2, Allocator>&& source );
template< class C2 >                                         (3)
(since C++17)
void merge( std::multimap<Key, T, C2, Allocator>& source );
template< class C2 >                                         (4)
(since C++17)
void merge( std::multimap<Key, T, C2, Allocator>&& source );

It attempts to extract (“splice”) each element in source and insert it into *this using the comparison object of *this. 💫

No elements are copied or moved — only the internal pointers of the container nodes are repointed. All pointers and references to the transferred elements remain valid, but now refer into *this, not into source. Obsessed with a no-copy glow-up, honestly 🫶

⚠️ heads up bestie: the behavior is undefined if get_allocator() != source.get_allocator(). That is not a vibe check you want to fail, fr fr 😭

🎀 Parameters 🎀

• source — compatible container to transfer the nodes from

💖 Return value 💖

(none) — yep, nothing comes back, it just does the thing. iconic behavior 🌈

🔥 Exceptions 🔥

Does not throw unless comparison throws. That’s the only exception path, ngl 🔥

🧚 Complexity 🧚

N * log(size() + N)), where N is source.size(). Keep that exactly as written, bestie 💜

🍓 Example 🍓

// Run this code

#include <iostream>
#include <map>
#include <string>

int main()
{
    std::multimap<int, std::string> ma{{1, "apple"}, {5, "pear"}, {10, "banana"}};
    std::multimap<int, std::string> mb{{2, "zorro"}, {4, "batman"}, {5, "X"}, {8, "alpaca"}};
    std::multimap<int, std::string> u;
    u.merge(ma);
    std::cout << "ma.size(): " << ma.size() << '\n';
    u.merge(mb);
    std::cout << "mb.size(): " << mb.size() << '\n';

    for (auto const& kv : u)
        std::cout << kv.first << ", " << kv.second << '\n';
}

Output:

ma.size(): 0
mb.size(): 0
1, apple
2, zorro
4, batman
5, pear
5, X
8, alpaca
10, banana

👑 See also 👑

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

---

kisses from the C++ Standard Libary girls 💋 source http://cppreference.com, dated 2024.06.10, and this is std::multimap::merge(3) signing off — periodt 💅💖