< cpp‎ | utility
Defined in header <variant>
template <class... Types>
class variant;
(since C++17)

The class template std::variant represents a type-safe union. An instance of std::variant at any given time either holds a value of one of its alternative types, or it holds no value (this state is hard to achieve, see valueless_by_exception).

As with unions, if a variant holds a value of some object type T, the object representation of T is allocated directly within the object representation of the variant itself. Variant is not allowed to allocate additional (dynamic) memory.

If a variant holds a value of a reference type, the implementation may choose to store it in the form of a wrapper type.

A variant is permitted to hold the type void, to hold the same type more than once, and to hold differently cv-qualified versions of the same type.

As with unions, the default-initialized variant holds a value of its first alternative, unless that alternative is not default-constructible (in which case default constructor won't compile: the helper class std::monostate can be used to make such variants default-constructible)


[edit] Template parameters

Types - the types that may be stored in this variant. All types must be (possibly cv-qualified) object types, (possibly cv-qualified) void, or reference types.

[edit] Member functions

constructs the variant object
(public member function)
destroys the variant, along with its contained value
(public member function)
assigns a variant
(public member function)
returns the zero-based index of the alternative held by the variant
(public member function)
checks if the variant is in the invalid state
(public member function)
constructs a value in the variant, in place
(public member function)
swaps with another variant
(public member function)

[edit] Non-member functions

calls the provided functor with the arguments held by one or more variants
(function template)
checks if a given type appears exactly once in a variant
(function template)
reads the value of the variant given the index or the type (if the type is unique), throws on error
(function template)
obtains a pointer to the value of a pointed-to variant given the index or the type (if unique), returns null on error
(function template)
compares variant objects as their contained values
(function template)
specializes the std::swap algorithm

[edit] Helper classes

placeholder type for use as the first alternative in a variant of non-default-contructible types
exception thrown on invalid accesses to the value of a variant
obtains the size of the variant's list of alternatives at compile time
(class template) (variable template)
obtains the type of the alternative specified by its index, at compile time
(class template) (alias template)
specializes the std::hash algorithm
(class template specialization)
specializes the std::uses_allocator type trait
(class template specialization)

[edit] Helper objects

index of the variant in the invalid state

[edit] Example

#include <variant>
#include <string>
int main()
    std::variant<int, float> v, w;
    v = 12; // v contains int
    int i = std::get<int>(v);
    w = std::get<int>(v);
    w = std::get<0>(v); // same effect as the previous line
    w = v; // same effect as the previous line
//  std::get<double>(v); // error: no double in [int, float]
//  std::get<3>(v);      // error: valid index values are 0 and 1
    try {
      std::get<float>(w); // w contains int, not float: will throw
    catch (std::bad_variant_access&) {}
    std::variant<std::string> v("abc"); // converting constructors work when unambiguous
    v = "def"; // converting assignment also works when unambiguous

[edit] See also

in-place construction tag
(function template)
(since C++17)
a wrapper that may or may not hold an object
(class template)
(since C++17)
Objects that hold instances of any CopyConstructible type.