# std::variant<Types...>::emplace

> C++ Atlas: `cppatlas.com/w/cpp/utility/variant/emplace` | Source: https://en.cppreference.com/w/cpp/utility/variant/emplace | Domain: Utility | Standards: C++17, C++20

Creates a new value in-place, in an existing variant object

## Official Specification Summary (cppreference)

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

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

template< std::size_t I, class... Args >
std::variant_alternative_t<I, variant>& emplace( Args&&... args ); // (3) (since C++17) (constexpr since C++20)

template< std::size_t I, class U, class... Args >
std::variant_alternative_t<I, variant>&
    emplace( std::initializer_list<U> il, Args&&... args ); // (4) (since C++17) (constexpr since C++20)
```

Creates a new value in-place, in an existing `variant` object

1) Equivalent to `emplace<I>(std::forward<Args>(args)...)`, where `I` is the zero-based index of `T` in `Types...`.

   - This overload participates in overload resolution only if `std::is_constructible_v<T, Args...>` is `true`, and `T` occurs exactly once in `Types...`.

2) Equivalent to `emplace<I>(il, std::forward<Args>(args)...)`, where `I` is the zero-based index of `T` in `Types...`.

   - This overload participates in overload resolution only if `std::is_constructible_v<T, std::initializer_list<U>&, Args...>` is `true`, and `T` occurs exactly once in `Types...`.

3) First, destroys the currently contained value (if any). Then direct-initializes the contained value as if constructing a value of type `T_I` with the arguments `std::forward<Args>(args)...`. If an exception is thrown, `*this` may become `valueless_by_exception`.

   - This overload participates in overload resolution only if `std::is_constructible_v<T_I, Args...>` is `true`.
   - It is a compile-time error if `I` is not less than `sizeof...(Types)`.

4) First, destroys the currently contained value (if any). Then direct-initializes the contained value as if constructing a value of type `T_I` with the arguments `il, std::forward<Args>(args)...`. If an exception is thrown, `*this` may become `valueless_by_exception`.

   - This overload participates in overload resolution only if `std::is_constructible_v<T_I, std::initializer_list<U>&, Args...>` is `true`.
   - It is a compile-time error if `I` is not less than `sizeof...(Types)`.

### Parameters

- `args` - constructor arguments to use when constructing the new value
- `il` - initializer_list argument to use when constructing the new value

### Return value

A reference to the new contained value.

### Exceptions

1-4) Any exception thrown during the initialization of the contained value.

### Notes

| Feature-test macro | Value | Std | Feature |
| --- | --- | --- | --- |
| `__cpp_lib_variant` | `202106L` | (C++20) (DR) | Fully `constexpr` `std::variant` (1-4) |

### Example

```cpp
#include <iostream>
#include <string>
#include <variant>

int main()
{
    std::variant<std::string> v1;
    v1.emplace<0>("abc"); // OK
    std::cout << std::get<0>(v1) << '\n';
    v1.emplace<std::string>("def"); // OK
    std::cout << std::get<0>(v1) << '\n';

    std::variant<std::string, std::string> v2;
    v2.emplace<1>("ghi"); // OK
    std::cout << std::get<1>(v2) << '\n';
    // v2.emplace<std::string>("abc"); -> Error
}
```

Output:

```text
abc
def
ghi
```

### 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=`](https://en.cppreference.com/w/cpp/utility/variant/operator=): assigns a `variant` (public member function)

---
Attribution: content from https://en.cppreference.com/w/cpp/utility/variant/emplace (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.