std::map::swap(3)

okay bestie, this is std::map::swap(3) from the C++ Standard Libary manual — yes, that spelling is straight from the header, no cap 💀. It's the map-to-map content trade where the containers swap their whole vibe and the individual elements are left completely alone. Iconic.

✨ NAME ✨

std::map::swap - std::map::swap

📜 Synopsis 📜

void swap( map& other );                            (until C++17)
void swap( map& 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. Literally none, bestie 🫶.

All iterators and references remain valid. The end() iterator is invalidated. That part is important, don't forget it 💅.

The Compare objects must be Swappable, and they are exchanged using an unqualified call to non-member swap.

Since C++11: 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. 🫠

🎀 Parameters 🎀

• other — container to exchange the contents with

🫶 Return value 🫶

(none) — literally nothing comes back, it just does the swap.

😭 Exceptions 😭

• Until C++17: any exception thrown by the swap of the Compare objects.

Since C++17, the noexcept specification is:

noexcept(std::allocator_traits<Allocator>::is_always_equal::value
&& std::is_nothrow_swappable<Compare>::value)

⚡ Complexity ⚡

Constant — that's the whole complexity section, bestie ✨.

🌈 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::map<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 }
        m2: { δ:delta ε:epsilon }
        ref: α:alpha
        iter: β:beta
        ──────── after swap ────────
        m1: { δ:delta ε:epsilon }
        m2: { α:alpha β:beta γ:gamma }
        ref: α:alpha
        iter: β:beta

👀 See also 👀

• std::swap(std::map) specializes the std::swap algorithm — (function template)

🏷️ Category 🏷️

• conditionally noexcept

---

<cute>okay bye bestie</cute> 💖 this was std::map::swap(3); source/version/date check: http://cppreference.com, 2024.06.10 🫶✨