Difference between revisions of "cpp/utility/variant"

Latest revision as of 23:29, 18 September 2024

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 in the case of error - 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 T object is nested within the variant object itself. Variant is not allowed to allocate additional (dynamic) memory.

A variant is not permitted to hold references, arrays, or the type void.

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

Consistent with the behavior of unions during aggregate initialization, a default-constructed variant holds a value of its first alternative, unless that alternative is not default-constructible (in which case the variant is not default-constructible either). The helper class std::monostate can be used to make such variants default-constructible.

A program that instantiates the definition of std::variant with no template arguments is ill-formed. std::variant<std::monostate> can be used instead.

If a program declares an explicit or partial specialization of std::variant, the program is ill-formed, no diagnostic required.

(constructor)	constructs the `variant` object (public member function) [edit]
(destructor)	destroys the `variant`, along with its contained value (public member function) [edit]
operator=	assigns a `variant` (public member function) [edit]
Observers
index	returns the zero-based index of the alternative held by the `variant` (public member function) [edit]
valueless_by_exception	checks if the `variant` is in the invalid state (public member function) [edit]
Modifiers
emplace	constructs a value in the `variant`, in place (public member function) [edit]
swap	swaps with another `variant` (public member function) [edit]
Visitation
visit (C++26)	calls the provided functor with the argument held by the `variant` (public member function) [edit]

[edit] Non-member functions

visit (C++17)	calls the provided functor with the arguments held by one or more `variant`s (function template) [edit]
holds_alternative (C++17)	checks if a `variant` currently holds a given type (function template) [edit]
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) [edit]
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) [edit]
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) [edit]
std::swap(std::variant) (C++17)	specializes the std::swap algorithm (function template) [edit]

[edit] Helper classes

monostate (C++17)	placeholder type for use as the first alternative in a `variant` of non-default-constructible types (class) [edit]
bad_variant_access (C++17)	exception thrown on invalid accesses to the value of a `variant` (class) [edit]
variant_sizevariant_size_v (C++17)	obtains the size of the `variant`'s list of alternatives at compile time (class template) (variable template)[edit]
variant_alternativevariant_alternative_t (C++17)	obtains the type of the alternative specified by its index, at compile time (class template) (alias template)[edit]
std::hash<std::variant> (C++17)	hash support for `std::variant` (class template specialization) [edit]

[edit] Helper objects

variant_npos

(C++17)

index of the variant in the invalid state
(constant) [edit]

[edit] Notes

Feature-test macro	Value	Std	Feature
`__cpp_lib_variant`	201606L	(C++17)	`std::variant`: a type-safe union
	202102L	(C++17) (DR)	std::visit for classes derived from `std::variant`
	202106L	(C++20) (DR)	Fully `constexpr` `std::variant`
	202306L	(C++26)	Member `visit`

[edit] Example

Run this code

#include <cassert>
#include <iostream>
#include <string>
#include <variant>
 
int main()
{
    std::variant<int, float> v, w;
    v = 42; // v contains int
    int i = std::get<int>(v);
    assert(42 == i); // succeeds
    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 (const std::bad_variant_access& ex)
    {
        std::cout << ex.what() << '\n';
    }
 
    using namespace std::literals;
 
    std::variant<std::string> x("abc");
    // converting constructors work when unambiguous
    x = "def"; // converting assignment also works when unambiguous
 
    std::variant<std::string, void const*> y("abc");
    // casts to void const* when passed a char const*
    assert(std::holds_alternative<void const*>(y)); // succeeds
    y = "xyz"s;
    assert(std::holds_alternative<std::string>(y)); // succeeds
}

Possible output:

std::get: wrong index for variant

[edit] Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR	Applied to	Behavior as published	Correct behavior
LWG 2901	C++17	specialization of std::uses_allocator provided, but `std::variant` cannot properly support allocators	specialization removed
LWG 3990	C++17	a program could declare an explicit or partial specialization of `std::variant`	the program is ill-formed in this case (no diagnostic required)

[edit] See also

in_placein_place_typein_place_indexin_place_tin_place_type_tin_place_index_t (C++17)	in-place construction tag (tag)[edit]
optional (C++17)	a wrapper that may or may not hold an object (class template) [edit]
any (C++17)	objects that hold instances of any CopyConstructible type (class) [edit]

@@ Line 1: / Line 1: @@
 {{cpp/title|variant}}
 {{cpp/utility/variant/navbar}}
-{{ddcl | header=variant | since=c++17 |
+{{ddcl|header=variant|since=c++17|
-template <class... Types>
+template< class... Types >
 class variant;
 }}
-The class template {{tt|std::variant}} represents a type-safe [[cpp/language/union|union]]. An instance of {{tt|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 {{ltt|cpp/utility/variant/valueless_by_exception}}).
+The class template {{tt|std::variant}} represents a type-safe {{lt|cpp/language/union}}. An instance of {{tt|std::variant}} at any given time either holds a value of one of its alternative types, or in the case of error - no value (this state is hard to achieve, see {{ltt|cpp/utility/variant/valueless_by_exception}}).
-As with unions, if a variant holds a value of some object type {{tt|T}}, the object representation of {{tt|T}} is allocated directly within the object representation of the variant itself. Variant is not allowed to allocate additional (dynamic) memory.
+As with unions, if a variant holds a value of some object type {{tt|T}}, the {{tt|T}} object is [[cpp/language/object#Address|nested within]] the {{tt|variant}} object 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 such as {{lc|std::reference_wrapper}}.
+A variant is not permitted to hold references, arrays, or the type {{c/core|void}}.
-A variant is permitted to hold the type {{tt|void}}, to hold the same type more than once, and to hold differently cv-qualified versions of the same type.
+A variant is permitted 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 {{ltt|cpp/utility/variant/monostate|std::monostate}} can be used to make such variants default-constructible)
+Consistent with the behavior of unions during [[cpp/language/aggregate_initialization|aggregate initialization]], a default-constructed variant holds a value of its first alternative, unless that alternative is not default-constructible (in which case the variant is not default-constructible either). The helper class {{ltt std|cpp/utility/variant/monostate}} can be used to make such variants default-constructible.
+A program that instantiates the definition of {{tt|std::variant}} with no template arguments is ill-formed. {{c/core|std::variant<std::monostate>}} can be used instead.
+If a program declares an [[cpp/language/template specialization|explicit]] or [[cpp/language/partial specialization|partial]] specialization of {{tt|std::variant}}, the program is ill-formed, no diagnostic required.
 ===Template parameters===
 {{par begin}}
-{{par | 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.}}
+{{par|Types|the types that may be stored in this variant. All types must meet the {{named req|Destructible}} requirements (in particular, array types and non-object types are not allowed).}}
 {{par end}}
 ===Member functions===
 {{dsc begin}}
-{{dsc inc | cpp/utility/variant/dsc constructor}}
+{{dsc inc|cpp/utility/variant/dsc constructor}}
-{{dsc inc | cpp/utility/variant/dsc destructor}}
+{{dsc inc|cpp/utility/variant/dsc destructor}}
-{{dsc inc | cpp/utility/variant/dsc operator{{=}}}}
+{{dsc inc|cpp/utility/variant/dsc operator{{=}}}}
-{{dsc h2 | Observers}}
+{{dsc h2|Observers}}
-{{dsc inc | cpp/utility/variant/dsc index}}
+{{dsc inc|cpp/utility/variant/dsc index}}
-{{dsc inc | cpp/utility/variant/dsc valueless_by_exception}}
+{{dsc inc|cpp/utility/variant/dsc valueless_by_exception}}
-{{dsc h2 | Modifiers}}
+{{dsc h2|Modifiers}}
-{{dsc inc | cpp/utility/variant/dsc emplace}}
+{{dsc inc|cpp/utility/variant/dsc emplace}}
-{{dsc inc | cpp/utility/variant/dsc swap}}
+{{dsc inc|cpp/utility/variant/dsc swap}}
+{{dsc h2|Visitation}}
+{{dsc inc|cpp/utility/variant/dsc visit2}}
 {{dsc end}}
 ===Non-member functions===
 {{dsc begin}}
-{{dsc inc | cpp/utility/variant/dsc visit}}
+{{dsc inc|cpp/utility/variant/dsc visit}}
-{{dsc inc | cpp/utility/variant/dsc holds_alternative}}
+{{dsc inc|cpp/utility/variant/dsc holds_alternative}}
-{{dsc inc | cpp/utility/variant/dsc get}}
+{{dsc inc|cpp/utility/variant/dsc get}}
-{{dsc inc | cpp/utility/variant/dsc get_if}}
+{{dsc inc|cpp/utility/variant/dsc get_if}}
-{{dsc inc | cpp/utility/variant/dsc operator_cmp}}
+{{dsc inc|cpp/utility/variant/dsc operator_cmp}}
-{{dsc inc | cpp/utility/variant/dsc swap}}
+{{dsc inc|cpp/utility/variant/dsc swap2}}
 {{dsc end}}
 ===Helper classes===
 {{dsc begin}}
-{{dsc inc | cpp/utility/variant/dsc monostate}} <!-- including monostate's comparisons and hash -->
+{{dsc inc|cpp/utility/variant/dsc monostate}}<!--including monostate's comparisons and hash-->
-{{dsc inc | cpp/utility/variant/dsc bad_variant_access}}
+{{dsc inc|cpp/utility/variant/dsc bad_variant_access}}
-{{dsc inc | cpp/utility/variant/dsc variant_size}}
+{{dsc inc|cpp/utility/variant/dsc variant_size}}
-{{dsc inc | cpp/utility/variant/dsc variant_alternative}}
+{{dsc inc|cpp/utility/variant/dsc variant_alternative}}
-{{dsc inc | cpp/utility/variant/dsc hash}}
+{{dsc inc|cpp/utility/variant/dsc hash}}
-{{dsc inc | cpp/utility/variant/dsc uses_allocator}}
 {{dsc end}}
 ===Helper objects===
 {{dsc begin}}
-{{dsc inc | cpp/utility/variant/dsc variant_npos}}
+{{dsc inc|cpp/utility/variant/dsc variant_npos}}
 {{dsc end}}
-===Example===
+===Notes===
+{{ftm begin|sort=1}}
+{{ftm|std=C++17|value=201606L|__cpp_lib_variant|{{ttt|std::variant}}: a type-safe union|rowspan="4"}}
+{{ftm|std=C++17|dr=yes|value=202102L|-|{{lc|std::visit}} for classes derived from {{ttt|std::variant}}}}
+{{ftm|std=C++20|dr=yes|value=202106L|-|Fully {{tt|constexpr}} {{ttt|std::variant}}}}
+{{ftm|std=C++26|-|value=202306L|Member {{rlt|visit2|visit}}}}
+{{ftm end}}
+===Example===
 {{example
- |
+|code=
- | code=
+#include <cassert>
-#include <variant>
+#include <iostream>
 #include <string>
+#include <variant>
 int main()
 {
      std::variant<int, float> v, w;
-     v = 12; // v contains int
+     v = 42; // v contains int
      int i = std::get<int>(v);
+    assert(42 == i); // succeeds
      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 {
+     try
-      std::get<float>(w); // w contains int, not float: will throw
+    {
+        std::get<float>(w); // w contains int, not float: will throw
      }
-     catch (std::bad_variant_access&) {}
+     catch (const std::bad_variant_access& ex)
+    {
-     std::variant<std::string> v("abc"); // converting constructors work when unambiguous
+        std::cout << ex.what() << '\n';
-     v = "def"; // converting assignment also works when unambiguous
+    }
+    using namespace std::literals;
+     std::variant<std::string> x("abc");
+    // converting constructors work when unambiguous
+     x = "def"; // converting assignment also works when unambiguous
+    std::variant<std::string, void const*> y("abc");
+    // casts to void const* when passed a char const*
+    assert(std::holds_alternative<void const*>(y)); // succeeds
+    y = "xyz"s;
+    assert(std::holds_alternative<std::string>(y)); // succeeds
 }
-| output=
+|p=true
+|output=
+std::get: wrong index for variant
 }}
+===Defect reports===
+{{dr list begin}}
+{{dr list item|wg=lwg|dr=2901|std=C++17|before=specialization of {{lc|std::uses_allocator}} provided,<br>but {{tt|std::variant}} cannot properly support allocators|after=specialization removed}}
+{{dr list item|wg=lwg|dr=3990|std=C++17|before=a program could declare an explicit or<br>partial specialization of {{tt|std::variant}}|after=the program is ill-formed in this<br>case (no diagnostic required)}}
+{{dr list end}}
 ===See also===
 {{dsc begin}}
-{{dsc inc | cpp/utility/dsc in_place}}
+{{dsc inc|cpp/utility/dsc in_place}}
-{{dsc inc | cpp/utility/dsc optional}}
+{{dsc inc|cpp/utility/dsc optional}}
-{{dsc inc | cpp/utility/dsc any}}
+{{dsc inc|cpp/utility/dsc any}}
 {{dsc end}}
+{{langlinks|es|ja|ru|zh}}

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)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Execution support library (C++26)
Technical specifications
Symbols index
External libraries

cppreference.com

Namespaces

Variants

Views

Actions

Difference between revisions of "cpp/utility/variant"

Latest revision as of 23:29, 18 September 2024

Contents

[edit] Template parameters

[edit] Member functions

Observers

Modifiers

Visitation