Variant: a type-safe union for C++17 (v8).

Variant is the very spice of life,
That gives it all its flavor.
- William Cowper's "The Task", or actually a variant thereof

Introduction

C++17 needs a type-safe union:

Lets not make the same mistake we made with std::optional by putting this library into a TS. We waited three years where no substantial feedback or discussion occurred, and then moved it into the IS virtually unchanged. Meanwhile, the C++ community suffered, and we continue to suffer from lack of this essential vocabulary type in interfaces.

The implications of the consensus variant design are well understood and have been explored over several LEWG discussions, over a thousand emails, a joint LEWG/EWG session, and not to mention 12 years of experience with Boost and other libraries. The last major change made to the proposal was non-breaking and added exception throws where previously there was undefined behavior. Since then, all suggested modifications have been cosmetic, rehashes of older discussions, or would be handled just as well by defect resolutions.

The C++ community should not wait three years for a widely useful library that is already done, fits its purpose, and has had such extensive review. There is a low chance that we will regret including variant in C++17, but a high chance that we will regret omitting it.

This proposal attempts to apply the lessons learned from optional (1). It behaves as below:


variant<int, float> v, w;
v = 12;
int i = get<int>(v);
w = get<int>(v);
w = get<0>(v); // same effect as the previous line
w = v; // same effect as the previous line

get<double>(v); // ill formed
get<3>(v); // ill formed

try {
  get<float>(w); // will throw.
}
catch (bad_variant_access&) {}

Results of the LEWG review in Urbana

The LEWG review in Urbana resulted in the following straw polls that motivated changes in this revision of the paper:

Should we use a tuple-like interface instead of the collection of variant-specific functions, is_alternative etc.? SF=8 WF=5 N=2 WA=1 SA=0
Consent: variant should be as constexpr as std::optional
Consent: The paper should discuss the never-empty guarantee
Consent: Expand on variant<int, int> and variant<int, const int>.
Visitors are needed for the initial variant in the TS? SF=4 WF=3 N=5 WA=4 SA=0
Recursive variants are needed? SF=0 WF=0 N=8 WA=4 SA=2

Results of the LEWG review in Lenexa

In Lenexa, LEWG decided that variant should model a discriminated union.

Approval votes on emptiness:
empty, queryable state: 12
invalid, assignable, UB on read: 13
invalid, throws on read: 6
double buffer: 5
require all members nothrow-move-constructible: 1
require either move-noexcept or one-default-construct-noexcept: 0
Want to query whether in empty state: SF=4 WF=4 N=4 WA=1 SA=1
Should the default constructor lead to the empty state? SF=3 WF=1 N=3 WA=1 SA=5; later SF=2 WF=0 N=2 WA=1 SA=6
Should the default constructor try to construct the first element? SF=5 WF=3 N=1 WA=2 SA=2, later SF=6 WF=3 N=0 WA=1 SA=1
Should the default constructor search for a default-constructible type and take the first possible one? (no earlier poll), later SF=0 WF=1 N=2 WA=5 SA=3
Remove heterogeneous assignment? SF=9 WF=5 N=3 WA=0 SA=1
Remove conversions, e.g. variant<int, string> x = "abc";? SF=5 WF=4 N=1 WA=1 SA=0
Allow variant<string> == const char * and variant<const char *, string> == const char *? SF=0 WF=2 N=5 WA=3 SA=3
Allow variant<string> == variant<const char *>, and variant<A, B, C> == variant<X, Y, Z>? SF=0 WF=1 N=0 WA=4 SA=8
Allow variant<int, const int>, qualified types in general? SF=9 WF=4 N=1 WA=1 SA=1
Allow types to be reference types? SF=6 WF=4 N=6 WA=1 SA=0
Allow void? SF=6 WF=9 N=2 WA=0 SA=0
Provide multi-visitation visit(VISITOR, var1, var2, var3, ...)? SF=0 WF=7 N=7 WA=1 SA=0
Provide binary visitation visit(VISITOR, v1, v2)? SF=0 WF=1 N=10 WA=1 SA=3
Approval vote of visitor return types:
common_type: 12
require same return type: 13
return type of op()(), rest must convert to that: 1
variant<return types>: 2
variant<return types> if they're different, otherwise single return type: 0
no void * data()
yes T* get<T>(variant<A, B, C> *) (a la any_cast)
Should index() return -1 on empty? (The alternative is to make non-emptiness a precondition.) SF=4 WF=1 N=3 WA=1 SA=2
Should variant::{visit,get} have preconditions that the variant not be empty? SF=4 WF=8 N=2 WA=0 SA=0

Results of the second LEWG review in Lenexa

Name of empty state:
empty: 0
error: 6
invalid: 14
bad: 5
fail: 0
partially formed: 4
Name of query function:
- query function: valid 13
- is_valid 2
- invalid 1
- is_invalid 2
- explicit operator bool 7
- index() == tuple_not_found 10
Upon invalid, should index return a magic value? SF=5, F=3, N=1, A=2, SA=2
index() has a precondition of being valid() (otherwise UB) SF=5 F=2 N=0 A=3 SA=3
What do we want to call the "empty_t" stand-in type?
- empty_t 4
- empty 4
- one_t 1
- blank 6
- blank_t 7
- monostate 7
Runoff:
- blank* 3
- monostate 8
Add assignment from an exact type if the type is unique? Unanimous consent.
Add an example of multi-visitation; change visit() to a variadic signature.
Keep names in_place_type and in_place_index to be consistent with optional? General consent.

Results of Evening Session review in Kona

Do we want P0088R0 + exceptions on invalid (so no undefined behavior)? SF=13, F=15, N=2, A=3, SA=0

Results of LEWG Session in Kona

This addressed items raised by LWG.

LEWG accepted (and embraced!) LWG's proposal for the overload resolution mechanism for template <class T> variant operator=(T&&), using a hypothetical function taking the alternative types.
Allow conversion in both construction and assignment. The detailed polls were:
- keep assignment and construction asymmetrical: SF=0, F=0, N=1, A=7, SA=6
- restrict assign and construction to alternative types only: SF=2, F=5, N=4, A=3, SA=4
- allow conversion for construction and assignment: SF=4, F=4, N=3, A=4, SA=0
Allow visitation without passing a variant, i.e. visit(Visitor).
Strong consensus to rename valid() to !corrupted_by_exception() (14 votes, runner-up: 7 votes) that was later on changed to !valueless_by_exception() after a discussion and based on a poll on the LWG and LEWG email lists, with 32 responses.

Revision history

Differences to revision 1 (N4218)

As requested by the LEWG review in Urbana, this revision

considerably expands the discussion of why this proposal allows the variant to be empty;
explains how duplicate (possibly cv-qualified) types and void as alternatives behave;
reuses (and extends, for consistency) the facilities provided by tuple for parameter pack operations; is_alternative does not yet exist as part of tuple and is thus kept;
employs the "perfect initialization" approach to for explicit conversions (2);
changes index() to return -1 (now also known is tuple_not_found) if !valid();
adds a visitation interface.

Beyond these requests, this revision

discusses the options for relational operators, construction and assignments, with / from a same-type variant, an alternative, and a different variant type;
hopefully makes the variant a regular type.

Differences to revision 2 (N4450)

Everything requested by LEWG, most notably, variant now models a discriminated union.
hash<variant<int>> can now return different values than hash<int> (and it should - presumably it should take the index() into account).
Describe template <size_t,...> get<I,...>(variant).
Remove is_alternative that is not strictly needed to make variant usable (LEWG feedback).
Remove std::swap() specialization; the default is just fine.
Add obligatory introductory quote.
Expanded on disadvantages of double buffering.

Differences to revision 3 (N4516)

Added discussion of (semi-) destructive move.
Assignment from an alternative types are back.
Multi-visitation example added.
visit() is now variadic.
Implemented several suggestions by Peter Dimov: removed type_list; reduced probability of !valid() for copy assignment / construction.
Renamed to monostate, get_if().

Differences to revision 4 (N4542)

Make valid() a visible state for value extraction functions (get(), visit()).
Move general design discussion into P0086.
Remove valid() precondition for copy / move construction from a variant.

Differences to revision 5 (P0088R0)

The Kona compromise: f !v.valid(), make get<...>(v) and visit(v) throw.
Change the overload resolution mechanism for template <class T> variant::variant(T&&) and template <class T> variant::operator=(T&&), using a hypothetical function taking the alternative types.
Allow conversion in both construction and assignment.
Allow visitation without passing a variant, i.e. visit(Visitor).
Rename valid() to !valueless_by_exception(), following the strong recommendation from a L(E)WG poll.
Remove tuple_find: it was not relevant for using variant as that already provides index- and type-based accesses; it was a considerable fraction of the proposed wording; it warrants a dedicated design paper, should someone wish to have it.
Provide real wording. Fixes:
- emplaced_... becomes in_place_...
- provide intended basic constexpr support: construction, accessors, destruction,
- implement all requests from the LWG review at Kona.

Differences to revision 6 (P0088R1)

Bring back tuple_not_found that got removed by mistake. Call it variant_npos.
Implement wording comments from Jacksonville LWG.
Rename tuple_size to variant_size, tuple_element to variant_alternative to clarify that this is not tuple-like. This avoids a clash with structured binding. The committee seems to have changed its common mind regarding these templates, reverting LEWG's decision from the first revision.
Do not implicitly force the variant valueless_by_exception if an exception is thrown during emplace / construction; merely state that it might become valueless_by_exception.
Reflect LEWG's updated recommended shipping vehicle (was TS, now C++17).

Differences to revision 7 (P0088R2)

Resolve noexcept(see below) for swap.
Added a missing std::move().
Replace uses of "must".
Some minor wording tweaks: strike "regular" in "regular overload resolution", stray experimental:: removed, is_constructible_v<T_j, T&&> is now spelled is_constructible_v<T_j, T>; some postconditions that are already specified in the equivalent Effects elements have been removed. These tweaks have not been highlighted in blue.

Discussion

Additional empty state

LEWG opted against introducing an explicit additional variant state, representing its invalid (and possibly empty, default constructed) state. This is meant to simplify the variant use: as getting a variant into the invalid state is sufficiently difficult, it was felt that there is no need to regularly check for a variant becoming invalid. This prevents all get<int>(v) calls from being protected by if (v.valid()).

Visibility of the Invalid State

Accessing an invalid variant's value is undefined behavior, whatever alternative is accessed.

The variant's invalid state needs to be visible: accessing its contents or visiting it will violate preconditions; users must be able to verify that a variant is not in this state.

When in the invalid state, index() returns variant_npos; variant provides valid() as a usability feature.

This usually does not need to be checked given how rare the invalid case is. It (generally) keeps a variant with N alternatives as an N-state type.

Empty state and default construction

Default construction of a variant should be allowed, to increase usability for instance in containers. LEWG opted against a variant default-initialized into its invalid state, to make invalid variants really rare.

Instead, the variant can be initialized with the first alternative (similar to the behavior of initialization of a union) only if that is default constructible. For cases where this behavior should be explicit, and for cases where no such default constructible alternative exists, there is a separate type monostate that can be used as first alternative, to explicitly enable default construction.

Feature Test

No header called variant exists; testing for this header's existence is thus sufficient.

Proposed wording

The insertions and deletions in this section describe the changes to the C++ Working Paper. Grayish background indicates proposed wording.

Variant Objects

Insert a new element in Table 14, C++ library headers of [general.namespaces], named <variant>.

Insert a new section:

? Variants [variant]

?.1 In general [variant.general]

A variant object holds and manages the lifetime of a value. If the variant holds a value, that value's type has to be one of the template argument types given to variant. These template arguments are called alternatives.

?.2 Header <variant> synopsis [variant.synopsis]
namespace std {
 // ?.3, variant of value types
 template <class... Types> class variant;

 // ?.4, variant helper classes
 template <class T> struct variant_size; // undefined
 template <class T> struct variant_size<const T>;
 template <class T> struct variant_size<volatile T>;
 template <class T> struct variant_size<const volatile T>;
 template <class T> constexpr size_t variant_size_v
 = variant_size<T>::value;

 template <class... Types>
 struct variant_size<variant<Types...>>;

 template <size_t I, class T> struct variant_alternative; // undefined
 template <size_t I, class T> struct variant_alternative<I, const T>;
 template <size_t I, class T> struct variant_alternative<I, volatile T>;
 template <size_t I, class T> struct variant_alternative<I, const volatile T>;
 template <size_t I, class T>
 using variant_alternative_t = typename variant_alternative<I, T>::type;

 template <size_t I, class... Types>
 struct variant_alternative<I, variant<Types...>>;

 constexpr size_t variant_npos = -1;


 // ?.5, In-place construction
 template <class T> struct in_place_type_t{ explicit in_place_type_t() = default; };
 template <class T> constexpr in_place_type_t<T> in_place_type{};

 template <size_t I> struct in_place_index_t{ explicit in_place_index_t() = default; };
 template <size_t I> constexpr in_place_index_t in_place_index{};

 // ?.6, Value access
 template <class T, class... Types>
 constexpr bool holds_alternative(const variant<Types...>&) noexcept;

 template <size_t I, class... Types>
 constexpr variant_alternative_t<I, variant<Types...>>&
 get(variant<Types...>&);
 template <size_t I, class... Types>
 constexpr variant_alternative_t<I, variant<Types...>>&&
 get(variant<Types...>&&);
 template <size_t I, class... Types>
 constexpr variant_alternative_t<I, variant<Types...>> const&
 get(const variant<Types...>&);
 template <size_t I, class... Types>
 constexpr variant_alternative_t<I, variant<Types...>> const&&
 get(const variant<Types...>&&);

 template <class T, class... Types>
 constexpr T& get(variant<Types...>&);
 template <class T, class... Types>
 constexpr T&& get(variant<Types...>&&);
 template <class T, class... Types>
 constexpr const T& get(const variant<Types...>&);
 template <class T, class... Types>
 constexpr const T&& get(const variant<Types...>&&);

 template <size_t I, class... Types>
 constexpr add_pointer_t<variant_alternative_t<I, variant<Types...>>>
 get_if(variant<Types...>*) noexcept;
 template <size_t I, class... Types>
 constexpr add_pointer_t<const variant_alternative_t<I, variant<Types...>>>
 get_if(const variant<Types...>*) noexcept;

 template <class T, class... Types>
 constexpr add_pointer_t<T> get_if(variant<Types...>*) noexcept;
 template <class T, class... Types>
 constexpr add_pointer_t<const T> get_if(const variant<Types...>*) noexcept;

 // ?.7, Relational operators
 template <class... Types>
 constexpr bool operator==(const variant<Types...>&,
 const variant<Types...>&);
 template <class... Types>
 constexpr bool operator!=(const variant<Types...>&,
 const variant<Types...>&);
 template <class... Types>
 constexpr bool operator<(const variant<Types...>&,
 const variant<Types...>&);
 template <class... Types>
 constexpr bool operator>(const variant<Types...>&,
 const variant<Types...>&);
 template <class... Types>
 constexpr bool operator<=(const variant<Types...>&,
 const variant<Types...>&);
 template <class... Types>
 constexpr bool operator>=(const variant<Types...>&,
 const variant<Types...>&);

 // ?.8, Visitation
 template <class Visitor, class... Variants>
 constexpr see below visit(Visitor&&, Variants&&...);

 // ?.9, Class monostate
 struct monostate;

 // ?.10, monostate relational operators
 constexpr bool operator<(monostate, monostate) noexcept;
 constexpr bool operator>(monostate, monostate) noexcept;
 constexpr bool operator<=(monostate, monostate) noexcept;
 constexpr bool operator>=(monostate, monostate) noexcept;
 constexpr bool operator==(monostate, monostate) noexcept;
 constexpr bool operator!=(monostate, monostate) noexcept;

 // ?.11, Specialized algorithms
 template <class... Types>
 void swap(variant<Types...>&, variant<Types...>&) noexcept(see below);

 // ?.12, class bad_variant_access
 class bad_variant_access;

 // ?.13, Hash support
 template <class T> struct hash;
 template <class... Types> struct hash<variant<Types...>>;
 template <> struct hash<monostate>;

 // ?.14, Allocator-related traits
 template <class T, class Alloc> struct uses_allocator;
 template <class... Types, class Alloc>
 struct uses_allocator<variant<Types...>, Alloc>;
} // namespace std
?.3 variant of value types [variant.variant]
namespace std {
 template <class... Types>
 class variant {
 public:

 // ?.3.1 Constructors
 constexpr variant() noexcept(see below);
 variant(const variant&);
 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&&...);

 // allocator-extended constructors
 template <class Alloc>
 variant(allocator_arg_t, const Alloc&);
 template <class Alloc>
 variant(allocator_arg_t, const Alloc&, const variant&);
 template <class Alloc>
 variant(allocator_arg_t, const Alloc&, variant&&);
 template <class Alloc, class T>
 variant(allocator_arg_t, const Alloc&, T&&);
 template <class Alloc, class T, class... Args>
 variant(allocator_arg_t, const Alloc&, in_place_type_t<T>, Args&&...);
 template <class Alloc, class T, class U, class... Args>
 variant(allocator_arg_t, const Alloc&, in_place_type_t<T>, initializer_list, Args&&...);
 template <class Alloc, size_t I, class... Args>
 variant(allocator_arg_t, const Alloc&, in_place_index_t, Args&&...);
 template <class Alloc, size_t I, class U, class... Args>
 variant(allocator_arg_t, const Alloc&, in_place_index_t, initializer_list, Args&&...);

 // ?.3.2, Destructor
 ~variant();

 // ?.3.3, Assignment
 variant& operator=(const variant&);
 variant& operator=(variant&&) noexcept(see below);

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

 // ?.3.4, Modifiers
 template <class T, class... Args> void emplace(Args&&...);
 template <class T, class U, class... Args>
 void emplace(initializer_list, Args&&...);
 template <size_t I, class... Args> void emplace(Args&&...);
 template <size_t I, class U, class... Args>
 void emplace(initializer_list, Args&&...);

 // ?.3.5, Value status
 constexpr bool valueless_by_exception() const noexcept;
 constexpr size_t index() const noexcept;

 // ?.3.6, Swap
 void swap(variant&) noexcept(see below);
 };
} // namespace std
Any instance of variant at any given time either holds a value of one of its alternative types, or it 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. The contained value shall be allocated in a region of the variant storage suitably aligned for all types in Types.... It is implementation defined whether over-aligned types are supported.

All types in Types... shall be (possibly cv-qualified) object types, (possibly cv-qualified) void, or references. [Note: Implementations could decide to store references in a wrapper. — end note]

?.3.1 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);

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 shall be constexpr if and only if the value initialization of the alternative type T_0 would satisfy the requirements for a constexpr function. The expression inside noexcept is equivalent to is_nothrow_default_constructible_v<T_0>. This function shall not participate in overload resolution unless is_default_constructible_v<T_0> is true. [Note: see also class monostate. — end note]

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 function shall not participate in overload resolution unless is_copy_constructible_v<T_i> is true for all i.

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.

Throws:

Any exception thrown by move-constructing any T_i for all i.

Remarks:

The expression inside noexcept is equivalent to the logical AND of is_nothrow_move_constructible_v<T_i> for all i. This function shall not participate in overload resolution unless is_move_constructible_v<T_i> is true for all 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. 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.

Effects:

Initializes *this to hold the alternative type T_j and direct-initializes the contained value as if direct-non-list-initializing it 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:
This function shall not participate in overload resolution unless is_same_v<decay_t<T>, variant> is false, unless is_constructible_v<T_j, T> is true, and unless the expression FUN(std::forward<T>(t)) (with FUN being the above-mentioned set of imaginary functions) is well formed. [Note:
variant<string, string> v("abc");
is ill-formed, as both alternative types have an equally viable constructor for the argument. — end note] The expression inside noexcept is equivalent to is_nothrow_constructible_v<T_j, T>. If T_j's selected constructor is a constexpr constructor, this constructor shall be a constexpr constructor.
template <class T, class... Args> constexpr explicit variant(in_place_type_t<T>, Args&&... args);

Effects:

Initializes the contained value of type T with the arguments std::forward<Args>(args)....

Postcondition:

holds_alternative<T>(*this) is true.

Throws:

Any exception thrown by calling the selected constructor of T.

Remarks:

This function shall not participate in overload resolution unless there is exactly one occurrence of T in Types... and is_constructible_v<T, Args...> is true. If T's selected constructor is a constexpr constructor, this constructor shall be a constexpr constructor.

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

Effects:

Initializes the contained value as if constructing an object of type T with the arguments il, std::forward<Args>(args)....

Postcondition:

holds_alternative<T>(*this) is true.

Throws:

Any exception thrown by calling the selected constructor of T.

Remarks:

This function shall not participate in overload resolution unless there is exactly one occurrences of T in Types... and is_constructible_v<T, initializer_list&, Args...> is true. If T's selected constructor is a constexpr constructor, this constructor shall be a constexpr constructor.

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

Effects:

Initializes the contained value as if constructing an object of type T_I with the arguments std::forward<Args>(args)....

Postcondition:

index() is I.

Throws:

Any exception thrown by calling the selected constructor of T_I.

Remarks:

This function shall not participate in overload resolution unless I is less than sizeof...(Types) and is_constructible_v<T_I, Args...> is true. If T_I's selected constructor is a constexpr constructor, this constructor shall be a constexpr constructor.

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

Effects:

Initializes the contained value as if constructing an object of type T_I with the arguments il, std::forward<Args>(args)....

Postcondition:

index() is I.

Remarks:

This function shall not participate in overload resolution unless I is less than sizeof...(Types) and is_constructible_v<T_I, initializer_list&, Args...> is true. If T_I's selected constructor is a constexpr constructor, this constructor shall be a constexpr constructor.

// allocator-extended constructors template <class Alloc> variant(allocator_arg_t, const Alloc& a); template <class Alloc> variant(allocator_arg_t, const Alloc& a, const variant& v); template <class Alloc> variant(allocator_arg_t, const Alloc& a, variant&& v); template <class Alloc, class T> variant(allocator_arg_t, const Alloc& a, T&& t); template <class Alloc, class T, class... Args> variant(allocator_arg_t, const Alloc& a, in_place_type_t<T>, Args&&... args); template <class Alloc, class T, class U, class... Args> variant(allocator_arg_t, const Alloc& a, in_place_type_t<T>, initializer_list il, Args&&... args); template <class Alloc, size_t I, class... Args> variant(allocator_arg_t, const Alloc& a, in_place_index_t, Args&&... args); template <class Alloc, size_t I, class U, class... Args> variant(allocator_arg_t, const Alloc& a, in_place_index_t, initializer_list il, Args&&... args);

Requires:

Alloc shall meet the requirements for an Allocator (17.6.3.5).

Effects:

Equivalent to the preceding constructors except that the contained value is constructed with uses-allocator construction (20.7.7.2).

?.3.2 Destructor [variant.dtor]

~variant();

Effects:

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

Remarks:

If is_trivially_destructible_v<T_i> == true for all T_i then this destructor shall be a trivial destructor.

?.3.3 Assignment [variant.assign]

variant& operator=(const variant& rhs);

Effects:

If neither *this nor rhs holds a value, there is no effect. Otherwise,

if *this holds a value but rhs does not, destroys the value contained in *this and sets *this to not hold a value. Otherwise,

if index() == rhs.index(), assigns the value contained in rhs to the value contained in *this. Otherwise,

copies the value contained in rhs to a temporary, then destroys any value contained in *this. Sets *this to hold the same alternative index as rhs and initializes the value contained in *this as if direct-non-list-initializing an object of type T_j with std::forward<T_j>(TMP), with TMP being the temporary and j being rhs.index().

Returns:

*this.

Postconditions:

index() == rhs.index()

Remarks:

This function shall not participate in overload resolution unless is_copy_constructible_v<T_i> && is_move_constructible_v<T_i> && is_copy_assignable_v<T_i> is true for all i.

If an exception is thrown during the call to T_j's copy assignment, the state of the contained value is as defined by the exception safety guarantee of T_j's copy assignment; index() will be j.

If an exception is thrown during the call to T_j's copy construction (with j being rhs.index()), *this will remain unchanged.

If an exception is thrown during the call to T_j's move construction, the variant will hold no value.

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

Effects:

If neither *this nor rhs holds a value, there is no effect. Otherwise,

if *this holds a value but rhs does not, destroys the value contained in *this and sets *this to not hold a value. Otherwise,

if index() == rhs.index(), assigns get<j>(std::move(rhs)) to the value contained in *this, with j being index(). Otherwise,

destroys any value contained in *this. Sets *this to hold the same alternative index as rhs and initializes the value contained in *this as if direct-non-list-initializing an object of type T_j with get<j>(std::move(rhs)) with j being rhs.index().

Returns:

*this.

Remarks:

This function shall not participate in overload resolution unless is_move_constructible_v<T_i> && is_move_assignable_v<T_i> is true for all i. The expression inside noexcept is equivalent to: is_nothrow_move_constructible_v<T_i> && is_nothrow_move_assignable_v<T_i> for all i. 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. 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> 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. 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.

Effects:

If *this holds a T_j, assigns std::forward<T>(t) to the value contained in *this. Otherwise, destroys any value contained in *this, sets *this to hold the alternative type T_j as selected by the imaginary function overload resolution described above, and direct-initializes the contained value as if direct-non-list-initializing it with std::forward<T>(t).

Postcondition:

holds_alternative<T_j>(*this) is true, with T_j selected by the imaginary function overload resolution described above.

Returns:

*this.

Remarks:
This function shall not participate in overload resolution unless is_same_v<decay_t<T>, variant> is false, unless is_assignable_v<T_j&, T> && is_constructible_v<T_j, T> is true, and unless the expression FUN(std::forward<T>(t)) (with FUN being the above-mentioned set of imaginary functions) is well formed. [Note:
variant<string, string> v;
v = "abc";
is ill-formed, as both alternative types have an equally viable constructor for the argument. — end note] The expression inside noexcept is equivalent to: is_nothrow_assignable_v<T_j&, T> && is_nothrow_constructible_v<T_j, T>. 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. If an exception is thrown during the initialization of the contained value, the variant object might not hold a value.
?.3.4 Modifiers [variant.mod]

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

Effects:

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

Remarks:

This function shall not participate in overload resolution unless is_constructible_v<T, Args...> is true, and T occurs exactly once in Types....

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

Effects:

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

Remarks:

This function shall not participate in overload resolution unless is_constructible_v<T, initializer_list&, Args...> is true, and T occurs exactly once in Types....

template <size_t I, class... Args> void emplace(Args&&... args);

Requires:

I < sizeof...(Types)

Effects:

Destroys the currently contained value if valueless_by_exception() is false. Then direct-initializes the contained value as if constructing a value of type T_I with the arguments std::forward<Args>(args)....

Postcondition:

index() is I.

Throws:

Any exception thrown during the initialization of the contained value.

Remarks:

This function shall not participate in overload resolution unless is_constructible_v<T_I, Args...> is true. If an exception is thrown during the initialization of the contained value, the variant might not hold a value.

template <size_t I, class U, class... Args> void emplace(initializer_list il, Args&&... args);

Requires:

I < sizeof...(Types)

Effects:

Destroys the currently contained value if valueless_by_exception() is false. Then direct-initializes the contained value as if constructing an object of type T_I with the arguments il, std::forward<Args>(args)....

Postcondition:

index() is I.

Throws:

Any exception thrown during the initialization of the contained value.

Remarks:

This function shall not participate in overload resolution unless is_constructible_v<T_I, initializer_list&, Args...> is true. If an exception is thrown during the initialization of the contained value, the variant might not hold a value.

?.3.5 Value status [variant.status]

constexpr bool valueless_by_exception() const noexcept;
Effects:
Returns false if and only if the variant holds a value. [Note: A variant might not hold a 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.

?.3.6 Swap [variant.swap]

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

Effects:

if valueless_by_exception() && rhs.valueless_by_exception() no effect. Otherwise,

if index() == rhs.index(), calls swap(get(*this), get(rhs)) where i is index(). Otherwise,

exchanges values of rhs and *this.

Throws:

Any exception thrown by swap(get(*this), get(rhs)) with i being index() and variant's move constructor and move assignment operator.

Remarks:

This function shall not participate in overload resolution unless is_swappable_v<T_i> is true for all i. 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 and move assignment operator. The expression inside noexcept is equivalent to the logical AND of is_nothrow_move_constructible_v<T_i> && is_nothrow_swappable_v<T_i> for all i.

?.4 variant helper classes [variant.helper]

template <class T> struct variant_size;

Remarks:

All specializations of variant_size<T> shall meet the UnaryTypeTrait requirements (20.10.1) with a BaseCharacteristic of integral_constant<size_t, N> for some N.

template <class T> class variant_size<const T>; template <class T> class variant_size<volatile T>; template <class T> class variant_size<const volatile T>;

Let VS denote variant_size<T> of the cv-unqualified type T. Then each of the three templates shall meet the UnaryTypeTrait requirements (20.10.1) with a BaseCharacteristic of integral_constant<size_t, VS::value>.

template <class... Types> struct variant_size<variant<Types...>> : integral_constant<size_t, sizeof...(Types)> { };

template <size_t I, class T> class variant_alternative<I, const T>; template <size_t I, class T> class variant_alternative<I, volatile T>; template <size_t I, class T> class variant_alternative<I, const volatile T>;

Let VA denote variant_alternative<I, T> of the cv-unqualified type T. Then each of the three templates shall meet the TransformationTrait requirements (20.10.1) with a member typedef type that names the following type:

for the first specialization, add_const_t<VA::type>,

for the second specialization, add_volatile_t<VA::type>, and

for the third specialization, add_cv_t<VA::type>.

variant_alternative<I, variant<Types...>>::type

Requires:

I < sizeof...(Types)

Value:

The type T_I.

?.5 In-place construction [variant.in_place]

template <class T> struct in_place_type_t{ explicit in_place_type_t() = default; }; template <class T> constexpr in_place_type_t<T> in_place_type{}; template <size_t I> struct in_place_index_t{ explicit in_place_index_t() = default; }; template <size_t I> constexpr in_place_index_t in_place_index{};
Template specializations of in_place_type_t are empty structure types used as unique types to disambiguate constructor overloading. They signal (through the template parameter) the alternative to be constructed. Specifically, variant has a constructor with in_place_type_t<T> as the first argument followed by an argument pack; this indicates that T should be constructed in-place (as if by a call to a placement new expression) with the forwarded argument pack as parameters. If a variant's Types... has multiple occurrences of T, in_place_index_t shall be used.

Template specializations of in_place_index_t are empty structure types used as unique types to disambiguate constructor overloading, and signaling (through the template parameter) the alternative to be constructed. Specifically, variant has a constructor with in_place_index_t as the first argument followed by an argument pack; this indicates that T_I should be constructed in-place (as if by a call to a placement new expression) with the forwarded argument pack as parameters.

?.6 Value access [variant.get]

template <class T, class... Types> constexpr bool holds_alternative(const variant<Types...>& v) noexcept;

Requires:

The type T occurs exactly once in Types.... Otherwise, the program is ill-formed.

Returns:

true if index() is equal to the zero-based index of T in Types....

template <size_t I, class... Types> constexpr variant_alternative_t<I, variant<Types...>>& get(variant<Types...>& v); template <size_t I, class... Types> constexpr variant_alternative_t<I, variant<Types...>>&& get(variant<Types...>&& v); template <size_t I, class... Types> constexpr variant_alternative_t<I, variant<Types...>> const& get(const variant<Types...>& v); template <size_t I, class... Types> constexpr variant_alternative_t<I, variant<Types...>> const&& get(const variant<Types...>&& v);

Requires:

I < sizeof...(Types), and T_I is not (possibly cv-qualified) void. Otherwise the program is ill-formed.

Effects:

If v.index() is I, returns a reference to the object stored in the variant. Otherwise, throws an exception of type bad_variant_access.

template <class T, class... Types> constexpr T& get(variant<Types...>& v); template <class T, class... Types> constexpr T&& get(variant<Types...>&& v); template <class T, class... Types> constexpr const T& get(const variant<Types...>& v); template <class T, class... Types> constexpr const T&& get(const variant<Types...>&& v);

Requires:

The type T occurs exactly once in Types..., and T is not (possibly cv-qualified) void. Otherwise, the program is ill-formed.

Effects:

If v holds a value of type T, returns a reference to that value. Otherwise, throws an exception of type bad_variant_access.

template <size_t I, class... Types> constexpr add_pointer_t<variant_alternative_t<I, variant<Types...>>> get_if(variant<Types...>* v) noexcept; template <size_t I, class... Types> constexpr add_pointer_t<const variant_alternative_t<I, variant<Types...>>> get_if(const variant<Types...>* v) noexcept;

Requires:

I < sizeof...(Types) and T_I is not (possibly cv-qualified) void; otherwise the program is ill-formed.

Returns:

A pointer to the value stored in the variant, if v != nullptr and v->index() == I. Otherwise, returns nullptr.

template <class T, class... Types> constexpr add_pointer_t<T> get_if(variant<Types...>* v) noexcept; template <class T, class... Types> constexpr add_pointer_t<const T> get_if(const variant<Types...>* v) noexcept;

Requires:

The type T occurs exactly once in Types..., and T is not (possibly cv-qualified) void. Otherwise, the program is ill-formed.

Effects:

Equivalent to return get_if(v) with i being the zero-based index of T in Types....

?.7 Relational operators [variant.relops]

template <class... Types> constexpr bool operator==(const variant<Types...>& v, const variant<Types...>& w);

Requires:

get(v) == get(w) is a valid expression returning a type that is convertible to bool, for all i.

Effects:

Equivalent to return (v.valueless_by_exception() && w.valueless_by_exception()) || (v.index() == w.index() && get(v) == get(w)) with i being v.index().

template <class... Types> constexpr bool operator!=(const variant<Types...>& v, const variant<Types...>& w);

Effects:

Equivalent to return !(v == w).

template <class... Types> constexpr bool operator<(const variant<Types...>& v, const variant<Types...>& w);

Requires:

get(v) < get(w) is a valid expression returning a type that is convertible to bool, for all i.

Effects:

Equivalent to return (v.index() < w.index()) || (v.index() == w.index() && !v.valueless_by_exception() && get(v) < get(w)) with i being v.index().

template <class... Types> constexpr bool operator>(const variant<Types...>& v, const variant<Types...>& w);

Effects:

Equivalent to return w < v.

template <class... Types> constexpr bool operator<=(const variant<Types...>& v, const variant<Types...>& w);

Effects:

Equivalent to return !(v > w).

template <class... Types> constexpr bool operator>=(const variant<Types...>& v, const variant<Types...>& w);

Effects:

Equivalent to return !(v < w).

?.8 Visitation [variant.visit]

template <class Visitor, class... Variants> constexpr see below visit(Visitor&& vis, Variants&&... vars);

Requires:

The expression in the Effects element shall be a valid expression of the same type and value category, for all combinations of alternative types of all variants. Otherwise, the program is ill-formed.

Effects:

Let is... be vars.index().... Returns INVOKE(forward<Visitor>(vis), get<is>(forward<Variants>(vars))...);.

Remarks:

The return type is the common type of all possible INVOKE expressions of the Effects element.

Throws:

bad_variant_access if any variant in vars is valueless_by_exception().

Complexity:

For sizeof...(Variants) <= 1, the invocation of the callable object is implemented in constant time, i.e. it does not depend on sizeof...(Types). For sizeof...(Variants) > 1, the invocation of the callable object has no complexity requirements.

?.9 Class monostate [variant.monostate]
struct monostate{};
The class monostate can serve as a first alternative type for a variant to make the variant type default constructible.

?.10 monostate relational operators [variant.monostate.relops]

constexpr bool operator<(monostate, monostate) noexcept { return false; } constexpr bool operator>(monostate, monostate) noexcept { return false; } constexpr bool operator<=(monostate, monostate) noexcept { return true; } constexpr bool operator>=(monostate, monostate) noexcept { return true; } constexpr bool operator==(monostate, monostate) noexcept { return true; } constexpr bool operator!=(monostate, monostate) noexcept { return false; }

[Note:

monostate object have only a single state; they thus always compare equal.— end note]

?.11 Specialized algorithms [variant.specalg]

template <class... Types> void swap(variant<Types...>& v, variant<Types...>& w) noexcept(see below);

Effects:

Equivalent to v.swap(w).

Remarks:

The expression inside noexcept is equivalent to noexcept(v.swap(w)).

?.12 Class bad_variant_access [variant.bad_variant_access]
class bad_variant_access : public exception {
public:
 bad_variant_access() noexcept;
 virtual const char* what() const noexcept;
};
Objects of type bad_variant_access are thrown to report invalid accesses to the value of a variant object.
bad_variant_access() noexcept;

Effects:

Constructs a bad_variant_access object.

const char* what() const noexcept override;

Returns:

an implementation-defined NTBS.

?.13 Hash support [variant.hash]

template <class... Types> struct hash<variant<Types...>>;

The template specialization hash<T> shall meet the requirements of class template hash (C++14 §20.9.13) for all T in Types.... The template specialization hash<variant<Types...>> shall meet the requirements of class template hash.

template <> struct hash<monostate>;

The template specialization hash<monostate> shall meet the requirements of class template hash.

?.14 Allocator-related traits [variant.traits]

template <class... Types, class Alloc> struct uses_allocator<variant<Types...>, Alloc> : true_type { };

Requires:

Alloc shall be an Allocator (17.6.3.5).

[Note:

Specialization of this trait informs other library components that variant can be constructed with an allocator, even though it does not have a nested allocator_type. — end note]

Conclusion

A variant has proven to be a useful tool. This paper proposes the necessary ingredients.

Acknowledgments

Thank you, Nevin ":-)" Liber, for bringing sanity to this proposal. Agustín K-ballo Bergé and Antony Polukhin provided very valuable feedback, criticism and suggestions. Thanks also to Vincenzo Innocente and Philippe Canal for their comments.

References

1. Working Draft, Technical Specification on C++ Extensions for Library Fundamentals. N4335

2. Improving pair and tuple, revision 2. N4064

Variant: a type-safe union for C++17 (v8).

Table of Contents

Introduction

Results of the LEWG review in Urbana

Results of the LEWG review in Lenexa

Results of the second LEWG review in Lenexa

Results of Evening Session review in Kona

Results of LEWG Session in Kona

Revision history

Differences to revision 1 (N4218)

Differences to revision 2 (N4450)

Differences to revision 3 (N4516)

Differences to revision 4 (N4542)

Differences to revision 5 (P0088R0)

Differences to revision 6 (P0088R1)

Differences to revision 7 (P0088R2)

Discussion

Additional empty state

Visibility of the Invalid State

Empty state and default construction

Feature Test

Proposed wording

Variant Objects

? Variants [variant]

?.1 In general [variant.general]

?.2 Header <variant> synopsis [variant.synopsis]

?.3 variant of value types [variant.variant]

?.3.1 Constructors [variant.ctor]

?.3.2 Destructor [variant.dtor]

?.3.3 Assignment [variant.assign]

?.3.4 Modifiers [variant.mod]

?.3.5 Value status [variant.status]

?.3.6 Swap [variant.swap]

?.4 variant helper classes [variant.helper]

?.5 In-place construction [variant.in_place]

?.6 Value access [variant.get]

?.7 Relational operators [variant.relops]

?.8 Visitation [variant.visit]

?.9 Class monostate [variant.monostate]

?.10 monostate relational operators [variant.monostate.relops]

?.11 Specialized algorithms [variant.specalg]

?.12 Class bad_variant_access [variant.bad_variant_access]

?.13 Hash support [variant.hash]

?.14 Allocator-related traits [variant.traits]

Conclusion

Acknowledgments

References

?.2 Header `<variant>` synopsis [variant.synopsis]

?.3 `variant` of value types [variant.variant]

?.4 `variant` helper classes [variant.helper]

?.9 Class `monostate` [variant.monostate]

?.10 `monostate` relational operators [variant.monostate.relops]

?.12 Class `bad_variant_access` [variant.bad_variant_access]