std::multimap::swap(3)

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

okay bestie, this is std::multimap::swap(3) from the C++ Standard Libary — yes, the header spells it like that, and we respect the typo 💀. it's the member swap for std::multimap, and it's about to trade whole container contents. let's go. ✨

💖 NAME 💖

std::multimap::swap — std::multimap::swap (the name section is literally the name twice, and honestly? iconic. 💅)

✨ Synopsis ✨

void swap( multimap& other );                            (until C++17)
void swap( multimap& other ) noexcept(/* see below */);  (since C++17)

Exchanges the contents of the container with those of other. Does not invoke any move, copy, or swap operations on individual elements. no cap, it just trades the whole vibe. 🔥

All iterators and references remain valid. The end() iterator is invalidated.

end() said “not today” and dipped. 🙈

The Compare objects must be Swappable, and they are exchanged using unqualified call to non-member swap. (yes, “unqualified call to non-member swap” is the exact phrase — write it down, bestie. 🎀)

If std::allocator_traits<allocator_type>::propagate_on_container_swap::value is true, then the allocators are exchanged using an unqualified call to non-member swap. Otherwise, they are not swapped (and if get_allocator() != other.get_allocator(), the behavior is undefined). (since C++11)

undefined behavior alert: if those allocators don’t match and the propagate value isn’t true, it’s giving “we don’t know her” and you should not go there. 💀

🫶 Parameters 🫶

• other — container to exchange the contents with

🌸 Return value 🌸

(none) — literally no return value, bestie. 💅

🔥 Exceptions 🔥

• Any exception thrown by the swap of the Compare objects. (until C++17)
• noexcept specification: noexcept(std::allocator_traits<Allocator>::is_always_equal::value && std::is_nothrow_swappable<Compare>::value) (since C++17)

⭐ Complexity ⭐

Constant. that’s the whole complexity. 😌

🧚 Example 🧚

        // Run this code

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

        // print out a std::pair
        template<class Os, class U, class V>
        Os& operator<<(Os& os, const std::pair<U, V>& p)
        {
            return os << p.first << ':' << p.second;
        }

        // print out a container
        template<class Os, class Co>
        Os& operator<<(Os& os, const Co& co)
        {
            os << '{';
            for (auto const& i : co)
                os << ' ' << i;
            return os << " }\n";
        }

        int main()
        {
            std::multimap<std::string, std::string>
                m1{{"γ", "gamma"}, {"β", "beta"}, {"α", "alpha"}, {"γ",
       "gamma"}},
                m2{{"ε", "epsilon"}, {"δ", "delta"}, {"ε", "epsilon"}};

            const auto& ref = *(m1.begin());
            const auto iter = std::next(m1.cbegin());

            std::cout << "──────── before swap ────────\n"
                      << "m1: " << m1 << "m2: " << m2 << "ref: " << ref
                      << "\niter: " << *iter << '\n';

            m1.swap(m2);

            std::cout << "──────── after swap ────────\n"
                      << "m1: " << m1 << "m2: " << m2 << "ref: " << ref
                      << "\niter: " << *iter << '\n';

            // Note that every iterator referring to an element in one
       container before
            // the swap refers to the same element in the other container after
       the swap.
            // Same is true for references.
        }

🌈 Output 🌈

        ──────── before swap ────────
        m1: { α:alpha β:beta γ:gamma γ:gamma }
        m2: { δ:delta ε:epsilon ε:epsilon }
        ref: α:alpha
        iter: β:beta
        ──────── after swap ────────
        m1: { δ:delta ε:epsilon ε:epsilon }
        m2: { α:alpha β:beta γ:gamma γ:gamma }
        ref: α:alpha
        iter: β:beta

👑 See also 👑

• std::swap(std::multimap) specializes the std::swap algorithm (function template)

🏷️ Category 🏷️

• * conditionally noexcept — yes, that’s the category line, star and all. 💅

---

big mwah from http://cppreference.com, version/date 2024.06.10, on the std::multimap::swap(3) page — bye bestie! 💖