# std::optional<T>::emplace

From cppreference.com
< cpp‎ | utility‎ | optional

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

Constructs the contained value in-place. If *this already contains a value before the call, the 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.

### 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).

Feature-test macro | Value | Std | Feature
--- | --- | --- | ---
`__cpp_lib_optional` | `202106L` | (C++20) (DR20) | Fully constexpr (1,2)

### 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.

DR | Applied to | Behavior as published | Correct behavior
--- | --- | --- | ---
P2231R1 | C++20 | `emplace` was not constexpr while the required operations can be constexpr in C++20 | made constexpr

### See also

operator= | assigns contents (public member function)

Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/utility/optional/emplace&oldid=172856"