std::swap(std::stack)(3)

💅 std::swap(std::stack) — the glow-up your stack deserves ✨

Okay so bestie, welcome to the std::swap(std::stack)(3) page from the C++ Standard Libary manual — yes, that's the whole vibe, let's get into it 🫶

---

🌸 NAME 🌸

std::swap(std::stack) — literally std::swap(std::stack), no notes, she's self-titled 👑

---

✨ Synopsis ✨

She lives in the header <stack>, periodt.

<tulip>Version one, the classic:</tulip>

template< class T, class Container >              (since C++11)
void swap( std::stack<T, Container>& lhs,         (until C++17)
           std::stack<T, Container>& rhs );

<tulip>Version two, the glow-up with noexcept:</tulip>

template< class T, class Container >
void swap( std::stack<T, Container>& lhs,         (since C++17)
           std::stack<T, Container>& rhs )
    noexcept(/* see below */);

So what does she actually do? She specializes the std::swap algorithm for std::stack 💖 She swaps the contents of lhs and rhs, and underneath it all she just calls lhs.swap(rhs). Iconic delegation, no cap.

Version-check moment 🕰️ (since C++17): this overload only participates in overload resolution if std::is_swappable_v<Container> is true. So if your Container isn't swappable, she simply does not show up to the party 🙈

---

🎀 Parameters 🎀

• lhs, rhs — the containers whose contents you wanna swap, bestie 🦋

---

💜 Return value 💜

(none) — she gives you nothing back and honestly? She doesn't have to 💅

---

🌈 Complexity 🌈

Same as swapping the underlying container. That's the whole sentence, girlboss said what she said ✨

---

🔥 Exceptions 🔥

The noexcept specification, (since C++17):

noexcept(noexcept(lhs.swap(rhs)))

That's it, that's the whole clause 🧚

---

🦋 Notes 🦋

Real talk — even though the std::swap overloads for container adaptors were only introduced in C++11, container adaptors could already be swapped by std::swap back in C++98 😭 So this isn't brand new behavior, it's a paperwork glow-up.

Those old C++98 calls to std::swap usually have linear time complexity, but better complexity may be provided. So like… don't assume, okay? ⭐

---

🍓 Example 🍓

Run this code, she's cute, she's demo-ready 🎀

// Run this code

#include <algorithm>
#include <iostream>
#include <stack>

int main()
{
    std::stack<int> alice;
    std::stack<int> bob;

    auto print = [](const auto& title, const auto& cont)
    {
        std::cout << title << " size=" << cont.size();
        std::cout << " top=" << cont.top() << '\n';
    };

    for (int i = 1; i < 4; ++i)
        alice.push(i);
    for (int i = 7; i < 11; ++i)
        bob.push(i);

    // Print state before swap
    print("Alice:", alice);
    print("Bob  :", bob);

    std::cout << "-- SWAP\n";
    std::swap(alice, bob);

    // Print state after swap
    print("Alice:", alice);
    print("Bob  :", bob);
}

<tulip>Output:</tulip>

Alice: size=3 top=3
Bob  : size=4 top=10
-- SWAP
Alice: size=4 top=10
Bob  : size=3 top=3

Look at Alice and Bob trading entire stack personalities 😭💀 Truly the swap of all time.

---

👑 See also 👑

• swap — swaps the contents. (C++11) (public member function) 🌸

---

💫 Category 💫

• * conditionally noexcept — yes that bullet point really starts with an asterisk in the original, we keep the lore 🙈

---

Kisses and closures, bestie 🫶 This whole page came straight from http://cppreference.com, dated 2024.06.10, and it's the std::swap(std::stack)(3) page — screenshot it, cite it, live by it 💖✨🎀