Scroll to navigation

std::optional::emplace(3) C++ Standard Libary std::optional::emplace(3)


std::optional::emplace - std::optional::emplace


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

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.


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.


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


// Run this code

#include <optional>
#include <iostream>

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";


+ constructed #0
+ move constructed #1
~ destructed #0
~ 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 made constexpr
operations can be constexpr in C++20

See also

operator= assigns contents
(public member function)