std::optional::emplace(3)

🦋 std::optional::emplace(3) 🦋

okay bestie, welcome to the C++ Standard Libary manual page for std::optional::emplace — yes, “Libary” is literally how it’s spelled up top and we’re keeping that energy. 💅

---

🌸 NAME 🌸

• std::optional::emplace — std::optional::emplace, bestie. That’s the name. No cap.

---

✨ Synopsis ✨

Two overloads, both with that since C++17 energy and constexpr since C++20 glow-up:

template< class... Args >                                (1) (since C++17)
T& emplace( Args&&... args );
(constexpr since C++20)

template< class U, class... Args >                           (since C++17)
T& emplace( std::initializer_list<U> ilist, Args&&...    (2)
args );
(constexpr since C++20)

So what’s the vibe? It constructs the contained value in-place. If *this already contains a value before the call, that contained value is destroyed by calling its destructor. 💀

1. Initializes the contained value by direct-initializing (but not direct-list-initializing) with std::forward<Args>(args)... as parameters.
2. Initializes the contained value by calling its constructor with ilist, std::forward<Args>(args)... as parameters. This overload participates in overload resolution only if std::is_constructible<T, std::initializer_list<U>&, Args&&...>::value is true.

---

🛠️ Parameters 🛠️

• args... — the arguments to pass to the constructor.
• ilist — the initializer list to pass to the constructor.

---

🧐 Type requirements 🧐

• T must be constructible from Args... for overload (1).
• T must be constructible from std::initializer_list and Args... for overload (2).

---

🎁 Return value 🎁

A reference to the new contained value. Slay.

---

😭 Exceptions 😭

Any exception thrown by the selected constructor of T. If an exception is thrown, *this does not contain a value after this call (the previously contained value, if any, had been destroyed). So yeah, bestie — if it throws, the old value is gone and there’s no value in there afterward. 🫠

---

🧪 Example 🧪

// Run this code

#include <iostream>
#include <optional>

struct A
{
    std::string s;

    A(std::string str) : s(std::move(str)), id{n++} { note("+ constructed"); }
    ~A() { note("~ destructed"); }
    A(const A& o) : s(o.s), id{n++} { note("+ copy constructed"); }
    A(A&& o) : s(std::move(o.s)), id{n++} { note("+ move constructed"); }

    A& operator=(const A& other)
    {
        s = other.s;
        note("= copy assigned");
        return *this;
    }

    A& operator=(A&& other)
    {
        s = std::move(other.s);
        note("= move assigned");
        return *this;
    }

    inline static int n{};
    int id{};
    void note(auto s) { std::cout << "  " << s << " #" << id << '\n'; }
};

int main()
{
    std::optional<A> opt;

    std::cout << "Assign:\n";
    opt = A("Lorem ipsum dolor sit amet, consectetur adipiscing elit nec.");

    std::cout << "Emplace:\n";
    // As opt contains a value it will also destroy that value
    opt.emplace("Lorem ipsum dolor sit amet, consectetur efficitur.");

    std::cout << "End example\n";
}

📤 Output

Assign:
  + constructed #0
  + move constructed #1
  ~ destructed #0
Emplace:
  ~ destructed #1
  + constructed #2
End example
  ~ destructed #2

---

🩹 Defect reports 🩹

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

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

---

👀 See also 👀

• operator= — assigns contents (public member function).

---

okay bye bestie 💖 — source: http://cppreference.com; version/date: 2024.06.10; page: std::optional::emplace(3). mwah 💋✨