std::optional::swap(3)

💅 NAME 💅

std::optional::swap - std::optional::swap (yes bestie, the name is the name, she said what she said)

Okay so welcome to the std::optional::swap page from the C++ Standard Libary 😭💖 — and yes, that’s exactly how the manual spells “Libary,” and I am not fixing it because character-for-character energy is the whole vibe.

---

✨ Synopsis ✨

void swap( optional& other ) noexcept(/* see below */);  (since C++17)
                                                                   (constexpr since C++20)

Swaps the contents with those of other. Literally the swapiest swap, no cap 💅

• If neither *this nor other contain a value, the function has no effect. Nothing happens. Iconic minimalism.
• If only one of *this and other contains a value (let’s call this object in and the other un), the contained value of un is direct-initialized from std::move(*in), followed by destruction of the contained value of in as if by in->T::~T(). After this call, in does not contain a value; un contains a value.
• If both *this and other contain values, the contained values are exchanged by calling using std::swap; swap(**this, *other). T lvalues must satisfy Swappable.

🚨 The program is ill-formed if std::is_move_constructible_v<T> is false. That’s not a vibe check you can fail, bestie — it’s just ill-formed.

---

🌸 Parameters 🌸

• other — the optional object to exchange the contents with 🫶

---

🎀 Return value 🎀

(none) — she gives you nothing because the swap is the moment, periodt.

---

🦋 Exceptions 🦋

noexcept specification:

noexcept(std::is_nothrow_move_constructible_v<T> &&
         std::is_nothrow_swappable_v<T>)

In the case of thrown exception, the states of the contained values of *this and other are determined by the exception safety guarantees of swap of type T or T’s move constructor, whichever is called. For both *this and other, if the object contained a value, it is left containing a value, and the other way round.

---

🌈 Example 🌈

// Run this code 👇

#include <iostream>
#include <optional>
#include <string>

int main()
{
    std::optional<std::string> opt1("First example text");
    std::optional<std::string> opt2("2nd text");

    enum Swap { Before, After };
    auto print_opts = [&](Swap e) {
        std::cout << (e == Before ? "Before swap:\n" : "After swap:\n");
        std::cout << "opt1 contains '" << opt1.value_or("") << "'\n";
        std::cout << "opt2 contains '" << opt2.value_or("") << "'\n";
        std::cout << (e == Before ? "---SWAP---\n": "\n");
    };

    print_opts(Before);
    opt1.swap(opt2);
    print_opts(After);

    // Swap with only 1 set
    opt1 = "Lorem ipsum dolor sit amet, consectetur tincidunt.";
    opt2.reset();

    print_opts(Before);
    opt1.swap(opt2);
    print_opts(After);
}

Output:

Before swap:
opt1 contains 'First example text'
opt2 contains '2nd text'
---SWAP---
After swap:
opt1 contains '2nd text'
opt2 contains 'First example text'

Before swap:
opt1 contains 'Lorem ipsum dolor sit amet, consectetur tincidunt.'
opt2 contains ''
---SWAP---
After swap:
opt1 contains ''
opt2 contains 'Lorem ipsum dolor sit amet, consectetur tincidunt.'

---

🧚 Defect reports 🧚

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

Columns: DR, Applied to, Behavior as published, Correct behavior.

• P2231R1 — applied to C++20; behavior as published: swap was not constexpr while the required operations can be constexpr in C++20; correct behavior: made constexpr.

---

👑 See also 👑

• std::swap(std::optional) specializes the std::swap algorithm (C++17) (function template)

---

⭐ Category ⭐

• conditionally noexcept

---

This cutie was served fresh from http://cppreference.com on 2024.06.10, and the page handle is std::optional::swap(3) 💖✨