Skip to content
Tutorials Center
My learning

Topics

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.

C++
#include <variant>

std::variant<int, double, std::string> v = 42;

Try it

C++ Storing, checking and reading alternatives

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.

C++ std::visit with overloaded lambdas

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

C++
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::monostate first.
  • Conversion rules: std::variant<int, std::string> v = "text"; picks std::string, but with alternatives such as bool and std::string older compilers once picked bool for a string literal, and several numeric alternatives make v = 1 ambiguous. Use std::in_place_type<T> or emplace when a conversion is unclear.
  • std::visit is 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 overloaded struct 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_ptr or std::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.