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]

namespace std { template<class... Types> class variant { public: // [variant.ctor], constructors constexpr variant() noexcept(see below); constexpr variant(const variant&); constexpr variant(variant&&) noexcept(see below); template<class T> constexpr variant(T&&) noexcept(see below); template<class T, class... Args> constexpr explicit variant(in_place_type_t<T>, Args&&...); template<class T, class U, class... Args> constexpr explicit variant(in_place_type_t<T>, initializer_list, Args&&...); template<size_t I, class... Args> constexpr explicit variant(in_place_index_t, Args&&...); template<size_t I, class U, class... Args> constexpr explicit variant(in_place_index_t, initializer_list, Args&&...); // [variant.dtor], destructor constexpr ~variant(); // [variant.assign], assignment constexpr variant& operator=(const variant&); constexpr variant& operator=(variant&&) noexcept(see below); template<class T> constexpr variant& operator=(T&&) noexcept(see below); // [variant.mod], modifiers template<class T, class... Args> constexpr T& emplace(Args&&...); template<class T, class U, class... Args> constexpr T& emplace(initializer_list, Args&&...); template<size_t I, class... Args> constexpr variant_alternative_t<I, variant<Types...>>& emplace(Args&&...); template<size_t I, class U, class... Args> constexpr variant_alternative_t<I, variant<Types...>>& emplace(initializer_list, Args&&...); // [variant.status], value status constexpr bool valueless_by_exception() const noexcept; constexpr size_t index() const noexcept; // [variant.swap], swap constexpr void swap(variant&) noexcept(see below); }; }

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 allocated within the storage of the variant object.

Implementations are not permitted to use additional storage, such as dynamic memory, to allocate the contained value.

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.

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.

🔗

constexpr variant() noexcept(see below);

Constraints: is_default_constructible_v<

T_{0}

> is true.

Effects: Constructs a variant holding a value-initialized value of type

T_{0}

Postconditions: valueless_by_exception() is false and index() is 0.

Throws: Any exception thrown by the value-initialization of

T_{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]).

The exception specification is equivalent to is_nothrow_default_constructible_v<

T_{0}

[Note 1:

See also class monostate.

— end note]

🔗

constexpr variant(const variant& w);

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.

Throws: Any exception thrown by direct-initializing any

T_{i}

for all i.

Remarks: This constructor is defined as deleted unless is_copy_constructible_v<

T_{i}

> is true for all i.

If is_trivially_copy_constructible_v<

T_{i}

> is true for all i, this constructor is trivial.

🔗

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

Constraints: is_move_constructible_v<

T_{i}

> is true for all i.

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.

Throws: Any exception thrown by move-constructing any

T_{i}

for all i.

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

T_{i}

> for all i.

If is_trivially_move_constructible_v<

T_{i}

> is true for all i, this constructor is trivial.

🔗

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.

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.

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

Postconditions: holds_alternative<

T_{j}

>(*this) is true.

Throws: Any exception thrown by the initialization of the selected alternative

T_{j}

Remarks: The exception specification is equivalent to is_nothrow_constructible_v<

T_{j}

, T>.

T_{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);

Constraints:

(20.1)
There is exactly one occurrence of T in Types... and
(20.2)
is_constructible_v<T, Args...> is true.

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

Postconditions: holds_alternative<T>(*this) is true.

Throws: Any exception thrown by calling the selected constructor of T.

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

Constraints:

(25.1)
There is exactly one occurrence of T in Types... and
(25.2)
is_constructible_v<T, initializer_list&, Args...> is true.

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

Postconditions: holds_alternative<T>(*this) is true.

Throws: Any exception thrown by calling the selected constructor of T.

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

Constraints:

(30.1)
I is less than sizeof...(Types) and
(30.2)
is_constructible_v< $T_{I}$ , Args...> is true.

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

T_{I}

with std::forward<Args>(args)....

Postconditions: index() is I.

Throws: Any exception thrown by calling the selected constructor of

T_{I}

Remarks: If

T_{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);

Constraints:

(35.1)
I is less than sizeof...(Types) and
(35.2)
is_constructible_v< $T_{I}$ , initializer_list&, Args...> is true.

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

T_{I}

with il, std::forward<Args>(args)....

Postconditions: index() is I.

Remarks: If

T_{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.

22.6.3.4 Assignment [variant.assign]

🔗

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

Let j be rhs.index().

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)).
(2.5)
Otherwise, equivalent to operator=(variant(rhs)).

Postconditions: index() == rhs.index().

Returns: *this.

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.

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.

🔗

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

Let j be rhs.index().

Constraints: is_move_constructible_v<

T_{i}

> && is_move_assignable_v<

T_{i}

> is true for all 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))).

Returns: *this.

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.

The exception specification is equivalent to is_nothrow_move_constructible_v<

T_{i}

> && is_nothrow_move_assignable_v<

T_{i}

> for all 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.
(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.

🔗

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.

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.

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
(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.
(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)).
(13.3)
Otherwise, equivalent to emplace<j>( $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.

Returns: *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.

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

Mandates: I < sizeof...(Types).

Constraints: is_constructible_v<

T_{I}

, Args...> is true.

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

Postconditions: index() is I.

Returns: A reference to the new contained value.

Throws: Any exception thrown during the initialization of the contained value.

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

Mandates: I < sizeof...(Types).

Constraints: is_constructible_v<

T_{I}

, initializer_list&, Args...> is true.

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

Postconditions: index() is I.

Returns: A reference to the new contained value.

Throws: Any exception thrown during the initialization of the contained value.

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;

Effects: Returns false if and only if the variant holds a value.

[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);

Mandates: is_move_constructible_v<

T_{i}

> is true for all i.

Preconditions: Each

T_{i}

meets the Cpp17Swappable requirements ([swappable.requirements]).

Effects:

(3.1)
If valueless_by_exception() && rhs.valueless_by_exception() no effect.
(3.2)
Otherwise, if index() == rhs.index(), calls swap(get(*this), get(rhs)) where i is index().
(3.3)
Otherwise, exchanges values of rhs and *this.

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}

T_{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().

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.