C++ Reference ยท Containers
C++ std::variant class
Reference for std::variant: a type-safe tagged union with index, get, get_if, holds_alternative, std::visit, overloaded lambdas and valueless states.
std::variant<Ts...> (C++17, header <variant>) holds a value of exactly one of the listed alternative types at any time. It is a type-safe replacement for a union plus a manual tag: the variant knows which alternative is active, constructs and destroys it correctly, and never lets you read the wrong one silently.
The storage is inline (the size of the largest alternative plus the index), with no heap allocation. The usual way to consume a variant is std::visit, which calls a function with whichever alternative is active and forces you to handle every case.
#include <variant> std::variant<int, double, std::string> v = 42;
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Syntax
template<class... Types> class variant; template<class T> constexpr T& get(variant<Types...>& v); template<std::size_t I> constexpr auto& get(variant<Types...>& v); template<class T> constexpr T* get_if(variant<Types...>* v) noexcept; template<class Visitor, class... Vars> constexpr decltype(auto) visit(Visitor&& vis, Vars&&... vars);
| Name | Description |
|---|---|
Types |
The alternatives. They must be non-array, non-reference object types that are not void. The same type may appear twice, but then you can only select by index. |
T, I |
The alternative to access, by type (must occur once) or zero-based index. |
vis |
A callable that accepts every alternative; all calls must return the same type. |
Members and helpers: index, valueless_by_exception, emplace<T> / emplace<I>, swap, std::holds_alternative<T>, std::variant_size_v, std::variant_alternative_t, std::monostate. std::visit<R> with an explicit return type exists since C++20.
Returns: get returns a reference to the active alternative. get_if returns a pointer, or nullptr if the alternative is not active. index() is the zero-based position, or std::variant_npos if valueless.
Errors / undefined behavior: get throws std::bad_variant_access for the wrong alternative. A variant becomes valueless_by_exception if an assignment or emplace throws after the old value was destroyed; visit then throws bad_variant_access.
Usage notes
- Default construction value-initializes the first alternative. If that type is not default-constructible, put
std::monostatefirst. - Conversion rules:
std::variant<int, std::string> v = "text";picksstd::string, but with alternatives such asboolandstd::stringolder compilers once pickedboolfor a string literal, and several numeric alternatives makev = 1ambiguous. Usestd::in_place_type<T>oremplacewhen a conversion is unclear. std::visitis exhaustive: adding an alternative breaks every visitor that does not handle it at compile time, which is what you want for a closed set of cases.- Overloaded-lambda helper: the
overloadedstruct in the example is not in the standard library; you write it (two lines) once per project. - Comparison:
==and<compare the index first, then the values. Variants with a different active alternative are never equal. - Recursion (a tree or JSON value) needs indirection through
std::vector,std::unique_ptrorstd::map, because a variant cannot contain itself directly. - Compared with inheritance: a variant suits a closed, known set of types with value semantics; virtual functions suit an open set.
- Cost: visiting is typically a jump table; there is no allocation and no virtual dispatch.