std::variant::variant(3)

💅 std::variant::variant(3) 💅

okay bestie, welcome to the C++ Standard Libary manual page for std::variant::variant. This is the constructor page, and it is lowkey a whole buffet of ways to make a variant. Since C++17, obviously. ✨

---

🌸 NAME 🌸

std::variant::variant - std::variant::variant

yes, that is literally the name twice. it's giving constructor-page energy and we respect it. 💅

---

✨ Synopsis ✨

okay so here's the overload lineup. the (since C++17) notes are part of the page, not me being extra. 🫶

constexpr variant() noexcept(/* see below */);                  (1)
(since C++17)
constexpr variant( const variant& other );                      (2)
(since C++17)
constexpr variant( variant&& other ) noexcept(/* see below */); (3)
(since C++17)
template< class T >                                             (4)
(since C++17)
constexpr variant( T&& t ) noexcept(/* see below */);
template< class T,

          class... Args >                                       (5)
(since C++17)
constexpr explicit variant( std::in_place_type_t<T>,

                            Args&&... args );
template< class T,

          class U,
          class... Args >                                       (6)
(since C++17)
constexpr explicit variant( std::in_place_type_t<T>,
                            std::initializer_list<U> il,

                            Args&&... args );
template< std::size_t I,

          class... Args >                                       (7)
(since C++17)
constexpr explicit variant( std::in_place_index_t<I>,

                            Args&&... args );
template< std::size_t I,

          class U,
          class... Args >                                       (8)
(since C++17)
constexpr explicit variant( std::in_place_index_t<I>,
                            std::initializer_list<U> il,

                            Args&&... args );

okay so the whole mood is: Constructs a new variant object. and here is every single way it does that, no skipping, bestie. 🌈

1. Default constructor. Constructs a variant holding the value-initialized value of the first alternative (index() is zero).
   • This constructor is constexpr if and only if the value initialization of the alternative type T_0 would satisfy the requirements for a constexpr function.
   • This overload participates in overload resolution only if std::is_default_constructible_v<T_0> is true.
2. Copy constructor. If other is not valueless_by_exception, constructs a variant holding the same alternative as other and direct-initializes the contained value with *std::get_if<other.index()>(std::addressof(other)). Otherwise, initializes a valueless_by_exception variant.
   • This constructor is defined as deleted unless std::is_copy_constructible_v<T_i> is true for all T_i in Types....
   • It is trivial if std::is_trivially_copy_constructible_v<T_i> is true for all T_i in Types....
3. Move constructor. If other is not valueless_by_exception, constructs a variant holding the same alternative as other and direct-initializes the contained value with std::move(*std::get_if<other.index()>(std::addressof(other))). Otherwise, initializes a valueless_by_exception variant.
   • This overload participates in overload resolution only if std::is_move_constructible_v<T_i> is true for all T_i in Types....
   • It is trivial if std::is_trivially_move_constructible_v<T_i> is true for all T_i in Types....
4. Converting constructor. Constructs a variant holding the alternative type T_j that would be selected by overload resolution for the expression F(std::forward<T>(t)) if there was an overload of imaginary function F(T_i) for each T_i in Types..., except that narrowing conversions aren't considered.

Formally:

• An overload F(T_i) is only considered if the declaration T_i x[] = { std::forward<T>(t) }; is valid for some invented variable x. Direct-initializes the contained value as if by direct non-list-initialization from std::forward<T>(t).
• This overload participates in overload resolution only if
  • sizeof...(Types) > 0,
  • std::decay_t<T> (until C++20) std::remove_cvref_t<T> (since C++20) is neither the same type as variant, nor a specialization of std::in_place_type_t, nor a specialization of std::in_place_index_t,
  • std::is_constructible_v<T_j, T> is true,
  • and the expression F(std::forward<T>(t)) (with F being the above-mentioned set of imaginary functions) is well formed.
• This constructor is a constexpr constructor if T_j's selected constructor is a constexpr constructor.

std::variant<std::string> v("abc"); // OK
std::variant<std::string, std::string> w("abc"); // ill-formed
std::variant<std::string, const char*> x("abc"); // OK, chooses const char*
std::variant<std::string, bool> y("abc"); // OK, chooses string; bool is not a candidate
std::variant<float, long, double> z = 0; // OK, holds long
                                         // float and double are not candidates

5. Constructs a variant with the specified alternative T and initializes the contained value with the arguments std::forward<Args>(args)....
   • If T's selected constructor is a constexpr constructor, this constructor is also a constexpr constructor.
   • This overload participates in overload resolution only if there is exactly one occurrence of T in Types... and std::is_constructible_v<T, Args...> is true.
6. Constructs a variant with the specified alternative T and initializes the contained value with the arguments il, std::forward<Args>(args)....
   • If T's selected constructor is a constexpr constructor, this constructor is also a constexpr constructor.
   • This overload participates in overload resolution only if there is exactly one occurrence of T in Types... and std::is_constructible_v<T, std::initializer_list<U>&, Args...> is true.
7. Constructs a variant with the alternative T_i specified by the index I and initializes the contained value with the arguments std::forward<Args>(args)....
   • If T_i's selected constructor is a constexpr constructor, this constructor is also a constexpr constructor.
   • This overload participates in overload resolution only if I < sizeof...(Types) and std::is_constructible_v<T_i, Args...> is true.
8. Constructs a variant with the alternative T_i specified by the index I and initializes the contained value with the arguments il, std::forward<Args>(args)....
   • If T_i's selected constructor is a constexpr constructor, this constructor is also a constexpr constructor.
   • This overload participates in overload resolution only if I < sizeof...(Types) and std::is_constructible_v<T_i, std::initializer_list<U>&, Args...> is true.

---

🌸 Parameters 🌸

• other — another variant object whose contained value to copy/move
• t — value to initialize the contained value with
• args... — arguments to initialize the contained value with
• il — initializer list to initialize the contained value with

---

💥 Exceptions 💥

1. May throw any exception thrown by the value initialization of the first alternative.

noexcept specification:

noexcept(std::is_nothrow_default_constructible_v<T_0>)

2. May throw any exception thrown by direct-initializing any T_i in Types....
3. May throw any exception thrown by move-constructing any T_i in Types....

noexcept specification:

noexcept((std::is_nothrow_move_constructible_v<Types> && ...))

4. May throw any exception thrown by the initialization of the selected alternative T_j.

noexcept specification:

noexcept(std::is_nothrow_constructible_v<T_j, T>)

5-8. May throw any exception thrown by calling the selected constructor of the selected alternative.

---

🍓 Example 🍓

// Run this code

#include <cassert>
#include <iostream>
#include <string>
#include <variant>
#include <vector>

using vector_t = std::vector<int>;

auto& operator<<(auto& out, const vector_t& v)
{
    out << "{ ";
    for (int e : v)
        out << e << ' ';
    return out << '}';
}

int main()
{
    // value-initializes first alternative
    std::variant<int, std::string> var0;
    assert(std::holds_alternative<int>(var0) and
           var0.index() == 0 and
           std::get<int>(var0) == 0);

    // initializes first alternative with std::string{"STR"};
    std::variant<std::string, int> var1{"STR"};
    assert(var1.index() == 0);
    std::cout << "1) " << std::get<std::string>(var1) << '\n';

    // initializes second alternative with int == 42;
    std::variant<std::string, int> var2{42};
    assert(std::holds_alternative<int>(var2));
    std::cout << "2) " << std::get<int>(var2) << '\n';

    // initializes first alternative with std::string{4, 'A'};
    std::variant<std::string, vector_t, float> var3
    {
        std::in_place_type<std::string>, 4, 'A'
    };
    assert(var3.index() == 0);
    std::cout << "3) " << std::get<std::string>(var3) << '\n';

    // initializes second alternative with std::vector{1,2,3,4,5};
    std::variant<std::string, vector_t, char> var4
    {
        std::in_place_type<vector_t>, {1, 2, 3, 4, 5}
    };
    assert(var4.index() == 1);
    std::cout << "4) " << std::get<vector_t>(var4) << '\n';

    // initializes first alternative with std::string{"ABCDE", 3};
    std::variant<std::string, vector_t, bool> var5
    {std::in_place_index<0>, "ABCDE", 3};
    assert(var5.index() == 0);
    std::cout << "5) " << std::get<std::string>(var5) << '\n';

    // initializes second alternative with std::vector(4, 42);
    std::variant<std::string, vector_t, char> var6
    {std::in_place_index<1>, 4, 42};
    assert(std::holds_alternative<vector_t>(var6));
    std::cout << "6) " << std::get<vector_t>(var6) << '\n';
}

Output:
        1) STR
        2) 42
        3) AAAA
        4) { 1 2 3 4 5 }
        5) ABC
        6) { 42 42 42 42 }

Bestie, if your terminal prints something that looks exactly like that, you did it right — that's the whole vibe check passed, no notes. 💅

---

💀 Defect reports 💀

Okay so this is the part where the C++ committee admits they fumbled a little and then fixed it retroactively for standards they already published. The following behavior-changing defect reports were applied retroactively to previously published C++ standards. Yes, that means what you think it means — the past got edited. Time travel but make it ISO. 😭

• LWG 2901 — applied to C++17
  • Behavior as published: allocator-aware constructors provided but variant can't properly support allocators
  • Correct behavior: constructors removed
• P0739R0 — applied to C++17
  • Behavior as published: converting constructor template interacts poorly with class template argument deduction
  • Correct behavior: constraint added
• LWG 3024 — applied to C++17
  • Behavior as published: copy constructor doesn't participate in overload resolution if any member type is not copyable
  • Correct behavior: defined as deleted instead
• P0602R4 — applied to C++17
  • Behavior as published: copy/move constructors may not be trivial even if underlying constructors are trivial
  • Correct behavior: required to propagate triviality
• P0608R3 — applied to C++17
  • Behavior as published: converting constructor blindly assembles an overload set, leading to unintended conversions
  • Correct behavior: narrowing and boolean conversions not considered
• P1957R2 — applied to C++17
  • Behavior as published: converting constructor for bool did not allow implicit conversion
  • Correct behavior: Pointer to bool conversion is narrowing and converting constructor has no exception for bool

Ngl, the fact that all six of these say C++17 is sending me. One standard, six glow-ups. She's been through it. 🫶

---

🎀 Category 🎀

• conditionally noexcept ✨

Like, some of the constructors are noexcept and some aren't — it depends on the vibe (and by vibe I mean the underlying types). Conditionally is doing a lot of heavy lifting in that sentence, iykyk. 💜

---

And that's the page, bestie! 🌸 This little masterpiece is straight from http://cppreference.com, dated 2024.06.10, and it's the man page for std::variant::variant(3). Go construct something iconic. Periodt. 👑🦋