std::list::swap(3)

okay bestie, welcome to std::list::swap(3) from the C++ Standard Libary — yes, we're doing linked-list container swap discourse, and it's lowkey iconic. 🦋

💖 NAME 💖

std::list::swap — std::list::swap. That's the name, no notes, no extra lore. ✨

✨ Synopsis ✨

here's the signature tea, exactly as written:

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

so what does it do? It exchanges the contents of the container with those of other. It does not invoke any move, copy, or swap operations on individual elements. Not even one. The elements themselves are just chillin'. 💅

All iterators and references remain valid. But heads up: it is unspecified whether an iterator holding the end() value in this container will refer to this or the other container after the operation. The end() iterator is being mysterious, iykyk. 🙈

allocator tea (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. That undefined behavior part is your red flag. 🚩

🫶 Parameters 🫶

• other — container to exchange the contents with.

💌 Return value 💌

(none) — literally no return value. The function is just out here doing the swap and leaving. 🫶

😭 Exceptions 😭

• until C++17: (none) — no exceptions, she's unbothered. 😌
• since C++17: noexcept specification: noexcept(std::allocator_traits<Allocator>::is_always_equal::value) — so the noexcept-ness is conditional, periodt. 🔥

🧚 Complexity 🧚

Constant. — that's the whole complexity. no scaling drama. ✨

🌈 Example 🌈

// Run this code — okay, demo time. This is the exact code from the page:

        #include <iostream>
        #include <list>

        template<class Os, class Co>
        Os& operator<<(Os& os, const Co& co)
        {
            os << '{';
            for (auto const& i : co)
                os << ' ' << i;
            return os << " } ";
        }

        int main()
        {
            std::list<int> a1{1, 2, 3}, a2{4, 5};

            auto it1 = std::next(a1.begin());
            auto it2 = std::next(a2.begin());

            int& ref1 = a1.front();
            int& ref2 = a2.front();

            std::cout << a1 << a2 << *it1 << ' ' << *it2 << ' ' << ref1 << ' '
       << ref2 << '\n';
            a1.swap(a2);
            std::cout << a1 << a2 << *it1 << ' ' << *it2 << ' ' << ref1 << ' '
       << ref2 << '\n';

            // Note that after swap the iterators and references stay
       associated with their
            // original elements, e.g. it1 that pointed to an element in 'a1'
       with value 2
            // still points to the same element, though this element was moved
       into 'a2'.
        }

🍓 Output 🍓

and the output is giving:

{ 1 2 3 } { 4 5 } 2 5 1 4
{ 4 5 } { 1 2 3 } 2 5 1 4

👑 See also 👑

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

💅 Category 💅

• * conditionally noexcept — yes, that's the category, and it's giving conditional noexcept realness. 💅

---

that's the page, bestie 💖 — source/version is http://cppreference.com, dated 2024.06.10, and the page is std::list::swap(3). now go swap those lists and stay hydrated. 🫶