[variant.variant]

Any instance of variant at any given time either holds a value of one of its alternative types or holds no value.

When an instance of variant holds a value of alternative type T, it means that a value of type T, referred to as the variant object's contained value, is nested within ([intro.object]) the variant object.

All types in Types shall meet the Cpp17Destructible requirements (Table 35).

A program that instantiates the definition of variant with no template arguments is ill-formed.

If a program declares an explicit or partial specialization of variant, the program is ill-formed, no diagnostic required.

22.6.3.2 Constructors [variant.ctor]

In the descriptions that follow, let i be in the range [0, sizeof.(Types)), and

T {i be the {i th type in Types .}^{th type in Types .}}_{i be the {i th type in Types .}^{th type in Types .}}

🔗

constexpr variant() noexcept(see below);

Throws: Any exception thrown by the value-initialization of

T {0 .}_{0 .}

Remarks: This function is constexpr if and only if the value-initialization of the alternative type

T {0 would be constexpr-suitable ([dcl. constexpr]) .}_{0 would be constexpr-suitable ([dcl. constexpr]) .}

The exception specification is equivalent to is_nothrow_default_constructible_v<

T {0 > .}_{0 >}

[Note 1:

See also class monostate.

— end note]

🔗

constexpr variant(const variant& w) noexcept(see below);

Effects: If w holds a value, initializes the variant to hold the same alternative as w and direct-initializes the contained value with GET<j>(w), where j is w.index().

Otherwise, initializes the variant to not hold a value.

Remarks: This constructor is defined as deleted unless is_copy_constructible_v<

T {i > is true for all i .}_{i >}

If is_trivially_copy_constructible_v<

T {i > is true for all i, this constructor is trivial .}_{i >}

The exception specification is equivalent to the logical and of is_nothrow_copy_constructible_v<

T {i > for all i .}_{i >}

🔗

constexpr variant(variant&& w) noexcept(see below);

Effects: If w holds a value, initializes the variant to hold the same alternative as w and direct-initializes the contained value with GET<j>(std::move(w)), where j is w.index().

Otherwise, initializes the variant to not hold a value.

Remarks: The exception specification is equivalent to the logical and of is_nothrow_move_constructible_v<

T {i > for all i .}_{i >}

If is_trivially_move_constructible_v<

T {i > is true for all i, this constructor is trivial .}_{i >}

🔗

template<class T> constexpr variant(T&& t) noexcept(see below);

Let

T {j be a type that is determined as follows: build an imaginary function FUN (T {i) for each alternative type T {i for which T {i x [] = {std ​::​ forward < T > (t)}; is well-formed for some invented variable x .}_{i x [] =}}_{i for which T {i x [] = {std ​::​ forward < T > (t)}; is well-formed for some invented variable x .}_{i x [] =}}}_{i)}}_{j be a type that is determined as follows: build an imaginary function FUN (T {i) for each alternative type T {i for which T {i x [] = {std ​::​ forward < T > (t)}; is well-formed for some invented variable x .}_{i x [] =}}_{i for which T {i x [] = {std ​::​ forward < T > (t)}; is well-formed for some invented variable x .}_{i x [] =}}}_{i)}}

The overload FUN(

T {j) selected by overload resolution for the expression FUN (std ​::​ forward < T > (​t)) defines the alternative T {j which is the type of the contained value after construction .}_{j which is the type of the contained value after construction .}}_{j)}

Constraints:

(15.1)
sizeof.(Types) is nonzero,
(15.2)
is_same_v<remove_cvref_t<T>, variant> is false,
(15.3)
remove_cvref_t<T> is neither a specialization of in_place_type_t nor a specialization of in_place_index_t,
(15.4)
is_constructible_v< $T {j, T > is true, and}_{j, T >}$
(15.5)
the expression FUN(std::forward<T>(t)) (with FUN being the above-mentioned set of imaginary functions) is well-formed.
[Note 2:
variant<string, string> v("abc"); is ill-formed, as both alternative types have an equally viable constructor for the argument.
— end note]

Effects: Initializes *this to hold the alternative type

T {j and direct-non-list-initializes the contained value with std ​::​ forward < T > (t) .}_{j and direct-non-list-initializes the contained value with std ​::​ forward < T > (t) .}

Remarks: The exception specification is equivalent to is_nothrow_constructible_v<

T {j, T > .}_{j, T >}

T {j's selected constructor is a constexpr constructor, this constructor is a constexpr constructor .}_{j's selected constructor is a constexpr constructor, this constructor is a constexpr constructor .}

🔗

template<class T, class. Args> constexpr explicit variant(in_place_type_t<T>, Args&&. args);

Effects: Direct-non-list-initializes the contained value of type T with std::forward<Args>(args)..

Remarks: If T's selected constructor is a constexpr constructor, this constructor is a constexpr constructor.

🔗

template<class T, class U, class. Args>
  constexpr explicit variant(in_place_type_t<T>, initializer_list<U> il, Args&&. args);

Effects: Direct-non-list-initializes the contained value of type T with il, std::forward<Args>(args)..

Remarks: If T's selected constructor is a constexpr constructor, this constructor is a constexpr constructor.

🔗

template<size_t I, class. Args> constexpr explicit variant(in_place_index_t<I>, Args&&. args);

Effects: Direct-non-list-initializes the contained value of type

T {I with std ​::​ forward < Args > (args) . .}_{I with std ​::​ forward < Args > (args) . .}

Remarks: If

T {I's selected constructor is a constexpr constructor, this constructor is a constexpr constructor .}_{I's selected constructor is a constexpr constructor, this constructor is a constexpr constructor .}

🔗

template<size_t I, class U, class. Args>
  constexpr explicit variant(in_place_index_t<I>, initializer_list<U> il, Args&&. args);

Effects: Direct-non-list-initializes the contained value of type

T {I with il, std ​::​ forward < Args > (​args) . .}_{I with il, std ​::​ forward < Args > (​args) . .}

Remarks: If

T {I's selected constructor is a constexpr constructor, this constructor is a constexpr constructor .}_{I's selected constructor is a constexpr constructor, this constructor is a constexpr constructor .}

22.6.3.3 Destructor [variant.dtor]

🔗

constexpr ~variant();

Effects: If valueless_by_exception() is false, destroys the currently contained value.

Remarks: If is_trivially_destructible_v<

T {i > is true for all T {i, then this destructor is trivial .}_{i, then this destructor is trivial .}}_{i >}

22.6.3.4 Assignment [variant.assign]

🔗

constexpr variant& operator=(const variant& rhs);

Effects:

(2.1)
If neither *this nor rhs holds a value, there is no effect.
(2.2)
Otherwise, if *this holds a value but rhs does not, destroys the value contained in *this and sets *this to not hold a value.
(2.3)
Otherwise, if index() == j, assigns the value contained in rhs to the value contained in *this.
(2.4)
Otherwise, if either is_nothrow_copy_constructible_v< $T {j > is true or is_nothrow_move_constructible_v < T {j > is false, equivalent to emplace < j > (GET < j > (rhs)) .}_{j >}}_{j >}$
(2.5)
Otherwise, equivalent to operator=(variant(rhs)).

Remarks: This operator is defined as deleted unless is_copy_constructible_v<

T {i > & & is_copy_assignable_v < T {i > is true for all i .}_{i >}}_{i > & &}

If is_trivially_copy_constructible_v<

T {i > & & is_trivially_copy_assignable_v < T {i > & & is_trivially_destructible_v < T {i > is true for all i, this assignment operator is trivial .}_{i >}}_{i > & &}}_{i > & &}

🔗

constexpr variant& operator=(variant&& rhs) noexcept(see below);

Constraints: is_move_constructible_v<

T {i > & & is_move_assignable_v < T {i > is true for all i .}_{i >}}_{i > & &}

Effects:

(8.1)
If neither *this nor rhs holds a value, there is no effect.
(8.2)
Otherwise, if *this holds a value but rhs does not, destroys the value contained in *this and sets *this to not hold a value.
(8.3)
Otherwise, if index() == j, assigns GET<j>(std::move(rhs)) to the value contained in *this.
(8.4)
Otherwise, equivalent to emplace<j>(GET<j>(std::move(rhs)).

Remarks: If is_trivially_move_constructible_v<

T {i > & & is_trivially_move_assignable_v < T {i > & & is_trivially_destructible_v < T {i > is true for all i, this assignment operator is trivial .}_{i >}}_{i > & &}}_{i > & &}

The exception specification is equivalent to is_nothrow_move_constructible_v<

T {i > & & is_nothrow_move_assignable_v < T {i > for all i .}_{i >}}_{i > & & is_nothrow_move_assignable_v < T {i > for all i .}_{i >}}

(10.1)
If an exception is thrown during the call to $T {j's move construction (with j being rhs . index ()), the variant will hold no value .}_{j's move construction (with j being rhs . index ()), the variant will hold no value .}$
(10.2)
If an exception is thrown during the call to $T {j's move assignment, the state of the contained value is as defined by the exception safety guarantee of T {j's move assignment; index () will be j .}_{j's move assignment; index () will be j .}}_{j's move assignment, the state of the contained value is as defined by the exception safety guarantee of T {j's move assignment; index () will be j .}_{j's move assignment; index () will be j .}}$

🔗

template<class T> constexpr variant& operator=(T&& t) noexcept(see below);

Let

T {j be a type that is determined as follows: build an imaginary function FUN (T {i) for each alternative type T {i for which T {i x [] = {std ​::​ forward < T > (t)}; is well-formed for some invented variable x .}_{i x [] =}}_{i for which T {i x [] = {std ​::​ forward < T > (t)}; is well-formed for some invented variable x .}_{i x [] =}}}_{i)}}_{j be a type that is determined as follows: build an imaginary function FUN (T {i) for each alternative type T {i for which T {i x [] = {std ​::​ forward < T > (t)}; is well-formed for some invented variable x .}_{i x [] =}}_{i for which T {i x [] = {std ​::​ forward < T > (t)}; is well-formed for some invented variable x .}_{i x [] =}}}_{i)}}

The overload FUN(

T {j) selected by overload resolution for the expression FUN (std ​::​ forward < T > (​t)) defines the alternative T {j which is the type of the contained value after assignment .}_{j which is the type of the contained value after assignment .}}_{j)}

Constraints:

(12.1)
is_same_v<remove_cvref_t<T>, variant> is false,
(12.2)
is_assignable_v< $T {j &, T > & & is_constructible_v < T {j, T > is true, and}_{j, T >}}_{j &, T > & & is_constructible_v < T {j, T > is true, and}_{j, T >}}$
(12.3)
the expression FUN(std::forward<T>(t)) (with FUN being the above-mentioned set of imaginary functions) is well-formed.
[Note 1:
variant<string, string> v; v = "abc"; is ill-formed, as both alternative types have an equally viable constructor for the argument.
— end note]

Effects:

(13.1)
If *this holds a $T {j, assigns std :: forward < T > (t) to the value contained in * this .}_{j, assigns std :: forward < T > (t) to the value contained in * this .}$
(13.2)
Otherwise, if is_nothrow_constructible_v< $T {j, T > | |! is_nothrow_move_constructible_v < T {j > is true, equivalent to emplace < j > (std :: forward < T > (t)) .}_{j >}}_{j, T > | |}$
(13.3)
Otherwise, equivalent to emplace<j>( $T {j (std :: forward < T > (t)) .}_{j (std :: forward < T > (t))}$

Postconditions: holds_alternative<

T {j > (* this) is true, with T {j selected by the imaginary function overload resolution described above .}_{j selected by the imaginary function overload resolution described above .}}_{j > (* this)}

Remarks: The exception specification is equivalent to: is_nothrow_assignable_v<T

{j &, T > & & is_nothrow_constructible_v < T {j, T > (16.1) If an exception is thrown during the assignment of std ​::​ forward < T > (t) to the value contained in * this, the state of the contained value and t are as defined by the exception safety guarantee of the assignment expression; valueless_by_exception () will be false . (16.2) If an exception is thrown during the initialization of the contained value, the variant object is permitted to not hold a value .}_{j, T >}}_{j &, T > & & is_nothrow_constructible_v < T {j, T > (16.1) If an exception is thrown during the assignment of std ​::​ forward < T > (t) to the value contained in * this, the state of the contained value and t are as defined by the exception safety guarantee of the assignment expression; valueless_by_exception () will be false . (16.2) If an exception is thrown during the initialization of the contained value, the variant object is permitted to not hold a value .}_{j, T >}}

22.6.3.5 Modifiers [variant.mod]

🔗

template<class T, class. Args> constexpr T& emplace(Args&&. args);

Constraints: is_constructible_v<T, Args..> is true, and T occurs exactly once in Types.

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

🔗

template<class T, class U, class. Args>
  constexpr T& emplace(initializer_list<U> il, Args&&. args);

Constraints: is_constructible_v<T, initializer_list&, Args..> is true, and T occurs exactly once in Types.

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

🔗

template<size_t I, class. Args>
  constexpr variant_alternative_t<I, variant<Types..>& emplace(Args&&. args);

Effects: Destroys the currently contained value if valueless_by_exception() is false.

Then direct-non-list-initializes the contained value of type

T {I with the arguments std ​::​ forward < Args > (args) . .}_{I with the arguments std ​::​ forward < Args > (args) . .}

Remarks: If an exception is thrown during the initialization of the contained value, the variant is permitted to not hold a value.

🔗

template<size_t I, class U, class. Args>
  constexpr variant_alternative_t<I, variant<Types..>&
    emplace(initializer_list<U> il, Args&&. args);

Effects: Destroys the currently contained value if valueless_by_exception() is false.

Then direct-non-list-initializes the contained value of type

T {I with il, std ​::​ forward < Args > (args) . .}_{I with il, std ​::​ forward < Args > (args) . .}

Remarks: If an exception is thrown during the initialization of the contained value, the variant is permitted to not hold a value.

22.6.3.6 Value status [variant.status]

🔗

constexpr bool valueless_by_exception() const noexcept;

[Note 1:

It is possible for a variant to hold no value if an exception is thrown during a type-changing assignment or emplacement.

The latter means that even a variant<float, int> can become valueless_by_exception(), for instance by struct S { operator int() { throw 42; }}; variant<float, int> v{12.f}; v.emplace<1>(S();

— end note]

🔗

constexpr size_t index() const noexcept;

Effects: If valueless_by_exception() is true, returns variant_npos.

Otherwise, returns the zero-based index of the alternative of the contained value.

22.6.3.7 Swap [variant.swap]

🔗

constexpr void swap(variant& rhs) noexcept(see below);

Throws: If index() == rhs.index(), any exception thrown by swap(GET(*this), GET(rhs)) with i being index().

Otherwise, any exception thrown by the move constructor of

T {i or T {j with i being index () and j being rhs . index () .}_{j with i being index () and j being rhs . index () .}}_{i or T {j with i being index () and j being rhs . index () .}_{j with i being index () and j being rhs . index () .}}

Remarks: If an exception is thrown during the call to function swap(GET(*this), GET(rhs)), the states of the contained values of *this and of rhs are determined by the exception safety guarantee of swap for lvalues of

T {i with i being index () .}_{i with i being index () .}

If an exception is thrown during the exchange of the values of *this and rhs, the states of the values of *this and of rhs are determined by the exception safety guarantee of variant's move constructor.

The exception specification is equivalent to the logical and of is_nothrow_move_constructible_v<

T {i > & & is_nothrow_swappable_v < T {i > for all i .}_{i >}}_{i > & & is_nothrow_swappable_v < T {i > for all i .}_{i >}}

22 General utilities library [utilities]

22.6 Variants [variant]

22.6.3 Class template variant [variant.variant]

22.6.3.1 General [variant.variant.general]

22.6.3.2 Constructors [variant.ctor]

22.6.3.3 Destructor [variant.dtor]

22.6.3.4 Assignment [variant.assign]

22.6.3.5 Modifiers [variant.mod]

22.6.3.6 Value status [variant.status]

22.6.3.7 Swap [variant.swap]

22.6.3.1 General [variant.variant.general]

22.6.3.2 Constructors [variant.ctor]

22.6.3.3 Destructor [variant.dtor]

22.6.3.4 Assignment [variant.assign]

22.6.3.5 Modifiers [variant.mod]

22.6.3.6 Value status [variant.status]

22.6.3.7 Swap [variant.swap]