Standard library header <variant> (C++17)

 

C++

Compiler support

Freestanding and hosted

Language

Standard library

Standard library headers

Named requirements

Feature test macros(C++20)

Language support library

Concepts library(C++20)

Diagnostics library

Memory management library

Metaprogramming library(C++11)

General utilities library

Containers library

Iterators library

Ranges library(C++20)

Algorithms library

Strings library

Text processing library

Numerics library

Date and time library

Input/output library

Filesystem library(C++17)

Concurrency support library(C++11)

Execution control library(C++26)

Technical specifications

Symbols index

External libraries

 

Standard library headers

Language support <cfloat> <climits> <compare>(C++20) <contracts>(C++26) <coroutine>(C++20) <csetjmp> <csignal> <cstdarg> <cstddef> <cstdint>(C++11) <cstdlib> <exception> <initializer_list>(C++11)    <limits> <new> <source_location>(C++20) <stdfloat>(C++23) <typeinfo> <version>(C++20) Concepts <concepts>(C++20) Diagnostics <cassert> <cerrno> <debugging>(C++26) <stacktrace>(C++23) <stdexcept> <system_error>(C++11) Memory management <memory> <memory_resource>(C++17) <scoped_allocator>(C++11) Metaprogramming <type_traits>(C++11) <ratio>(C++11)

General utilities <any>(C++17) <bitset> <bit>(C++20) <charconv>(C++17) <expected>(C++23) <format>(C++20) <functional> <optional>(C++17) <stdbit.h>(C++26) <tuple>(C++11) <typeindex>(C++11) <utility> <variant>(C++17) Containers <array>(C++11) <deque> <flat_map>(C++23) <flat_set>(C++23) <forward_list>(C++11) <hive>(C++26) <inplace_vector>(C++26)    <list> <map> <mdspan>(C++23) <queue> <set> <span>(C++20) <stack> <unordered_map>(C++11) <unordered_set>(C++11) <vector> Iterators <iterator> Ranges <generator>(C++23) <ranges>(C++20)

Algorithms <algorithm> <numeric> Strings <cctype> <cstring> <cuchar>(C++11) <cwchar> <cwctype> <string_view>(C++17) <string> Text processing <clocale> <codecvt>(C++11/17/26*) <locale> <regex>(C++11) <text_encoding>(C++26)    Numerics <cfenv>(C++11) <cmath> <complex> <linalg>(C++26) <numbers>(C++20) <random>(C++11) <simd>(C++26) <stdckdint.h>(C++26) <valarray> Time <chrono>(C++11) <ctime> C compatibility <ccomplex>(C++11/17/20*) <ciso646>(until C++20) <cstdalign>(C++11/17/20*) <cstdbool>(C++11/17/20*) <ctgmath>(C++11/17/20*)

Input/output <cinttypes>(C++11) <cstdio> <filesystem>(C++17) <fstream> <iomanip> <iosfwd> <iostream> <ios> <istream> <ostream> <print>(C++23) <spanstream>(C++23) <sstream> <streambuf> <strstream>(C++98/26*) <syncstream>(C++20) Concurrency support <atomic>(C++11) <barrier>(C++20) <condition_variable>(C++11) <future>(C++11) <hazard_pointer>(C++26) <latch>(C++20) <mutex>(C++11) <rcu>(C++26) <semaphore>(C++20) <shared_mutex>(C++14) <stdatomic.h>(C++23) <stop_token>(C++20) <thread>(C++11) Execution support <execution>(C++17)

 

This header is part of the general utility library.

Includes
<compare> (C++20)	Three-way comparison operator support
Classes
variant (C++17)	a type-safe discriminated union (class template)
monostate (C++17)	placeholder type for use as the first alternative in a variant of non-default-constructible types (class)
bad_variant_access (C++17)	exception thrown on invalid accesses to the value of a variant (class)
variant_sizevariant_size_v (C++17)	obtains the size of the variant's list of alternatives at compile time (class template)(variable template)
variant_alternativevariant_alternative_t (C++17)	obtains the type of the alternative specified by its index, at compile time (class template)(alias template)
std::hash<std::variant> (C++17)	hash support for std::variant (class template specialization)
Constants
variant_npos (C++17)	index of the variant in the invalid state (constant)
Functions
visit (C++17)	calls the provided functor with the arguments held by one or more variants (function template)
holds_alternative (C++17)	checks if a variant currently holds a given type (function template)
get(std::variant) (C++17)	reads the value of the variant given the index or the type (if the type is unique), throws on error (function template)
get_if (C++17)	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)
operator==operator!=operator<operator<=operator>operator>=operator<=> (C++17)(C++17)(C++17)(C++17)(C++17)(C++17)(C++20)	compares variant objects as their contained values (function template)
std::swap(std::variant) (C++17)	specializes the std::swap algorithm (function template)

Synopsis

#include <compare>   namespace std {// class template varianttemplate<class... Types>class variant;   // variant helper classestemplate<class T>struct variant_size;// not definedtemplate<class T>struct variant_size<const T>;template<class T>inlineconstexpr 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;// not definedtemplate<size_t I, class T>struct variant_alternative<I, const 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...>>;   inlineconstexpr size_t variant_npos =-1;   // value accesstemplate<class T, class... Types>constexprbool 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>constexprconst variant_alternative_t<I, variant<Types...>>& get(const variant<Types...>&);template<size_t I, class... Types>constexprconst variant_alternative_t<I, variant<Types...>>&& 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>constexprconst T& get(const variant<Types...>&);template<class T, class... Types>constexprconst 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;   // relational operatorstemplate<class... Types>constexprbool operator==(const variant<Types...>&, const variant<Types...>&);template<class... Types>constexprbool operator!=(const variant<Types...>&, const variant<Types...>&);template<class... Types>constexprbool operator<(const variant<Types...>&, const variant<Types...>&);template<class... Types>constexprbool operator>(const variant<Types...>&, const variant<Types...>&);template<class... Types>constexprbool operator<=(const variant<Types...>&, const variant<Types...>&);template<class... Types>constexprbool operator>=(const variant<Types...>&, const variant<Types...>&);template<class... Types> requires (three_way_comparable<Types>&& ...)constexpr common_comparison_category_t<compare_three_way_result_t<Types>...> operator<=>(const variant<Types...>&, const variant<Types...>&);   // visitationtemplate<class Visitor, class... Variants>constexpr/* see description */ visit(Visitor&&, Variants&&...);template<class R, class Visitor, class... Variants>constexpr R visit(Visitor&&, Variants&&...);   // class monostatestruct monostate;   // monostate relational operatorsconstexprbool operator==(monostate, monostate)noexcept;constexpr strong_ordering operator<=>(monostate, monostate)noexcept;   // specialized algorithmstemplate<class... Types>constexprvoid swap(variant<Types...>&, variant<Types...>&)noexcept(/* see description */);   // class bad_variant_accessclass bad_variant_access;   // hash supporttemplate<class T>struct hash;template<class... Types>struct hash<variant<Types...>>;template<>struct hash<monostate>;}   // deprecatednamespace std {template<class T>struct variant_size<volatile T>;template<class T>struct variant_size<constvolatile T>;   template<size_t I, class T>struct variant_alternative<I, volatile T>;template<size_t I, class T>struct variant_alternative<I, constvolatile T>;}

Class template std::variant

namespace std {template<class... Types>class variant {public:// constructorsconstexpr variant()noexcept(/* see description */);constexpr variant(const variant&);constexpr variant(variant&&)noexcept(/* see description */);   template<class T>constexpr variant(T&&)noexcept(/* see description */);   template<class T, class... Args>constexprexplicit variant(in_place_type_t<T>, Args&&...);template<class T, class U, class... Args>constexprexplicit variant(in_place_type_t<T>, initializer_list<U>, Args&&...);   template<size_t I, class... Args>constexprexplicit variant(in_place_index_t<I>, Args&&...);template<size_t I, class U, class... Args>constexprexplicit variant(in_place_index_t<I>, initializer_list<U>, Args&&...);   // destructorconstexpr ~variant();   // assignmentconstexpr variant& operator=(const variant&);constexpr variant& operator=(variant&&)noexcept(/* see description */);   template<class T>constexpr variant& operator=(T&&)noexcept(/* see description */);   // modifierstemplate<class T, class... Args>constexpr T& emplace(Args&&...);template<class T, class U, class... Args>constexpr T& emplace(initializer_list<U>, 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<U>, Args&&...);   // value statusconstexprbool valueless_by_exception()constnoexcept;constexpr size_t index()constnoexcept;   // swapconstexprvoid swap(variant&)noexcept(/* see description */);};}

Class std::monostate

struct monostate{};

Class std::bad_variant_access

class bad_variant_access :public exception {public:// see [exception] for the specification of the special member functionsconstchar* what()constnoexcept override;};