std::variant

 

C++

Compiler-Unterstützung

Freestanding und gehostet

Sprache

Standardbibliothek

Header der Standardbibliothek

Benannte Anforderungen

Feature-Test-Makros (C++20)

Bibliothek für Sprachunterstützung

Konzepte-Bibliothek (C++20)

Diagnostik-Bibliothek

Speicherverwaltungsbibliothek

Metaprogrammierungsbibliothek (C++11)

Allgemeine Dienstprogramme-Bibliothek

Container-Bibliothek

Iterator-Bibliothek

Ranges-Bibliothek (C++20)

Algorithmen-Bibliothek

Bibliothek für Zeichenketten

Textverarbeitungsbibliothek

Numerik-Bibliothek

Datums- und Zeitbibliothek

Ein-/Ausgabe-Bibliothek

Dateisystembibliothek (C++17)

Unterstützung für nebenläufige Programmierung (C++11)

Ausführungssteuerungsbibliothek (C++26)

Technische Spezifikationen

Symbolverzeichnis

Externe Bibliotheken

 

Dienstprogramm-Bibliotheken

Sprachunterstützung Typunterstützung (Basistypen, RTTI) Bibliotheks-Feature-Test-Makros (C++20) Programm-Dienstprogramme Variadische Funktionen initializer_list (C++11) is_constant_evaluated (C++20) is_within_lifetime (C++26) source_location (C++20) Coroutine-Unterstützung (C++20) Vertragsunterstützung (C++26) Drei-Wege-Vergleich three_way_comparablethree_way_comparable_with (C++20)(C++20) strong_ordering (C++20) weak_ordering (C++20) partial_ordering (C++20) common_comparison_category (C++20) compare_three_way_result (C++20) compare_three_way (C++20) strong_order (C++20) weak_order (C++20) partial_order (C++20) compare_strong_order_fallback (C++20) compare_weak_order_fallback (C++20) compare_partial_order_fallback (C++20)   is_eqis_ltis_lteq (C++20)(C++20)(C++20)   is_neqis_gtis_gteq (C++20)(C++20)(C++20)

Allgemeine Hilfsmittel Funktionsobjekte Bit-Manipulation (C++20) bitset hash (C++11) Relationale Operatoren (in C++20 veraltet) rel_ops::operator!=rel_ops::operator>    rel_ops::operator<=rel_ops::operator>= Ganzzahl-Vergleichsfunktionen cmp_equalcmp_lesscmp_less_than (C++20)(C++20)(C++20)   cmp_not_equalcmp_greatercmp_greater_than (C++20)(C++20)(C++20) in_range (C++20) Swap und Typ-Operationen swap ranges::swap (C++20) exchange (C++14) declval (C++11) to_underlying (C++23) forward (C++11) forward_like (C++23) move (C++11) move_if_noexcept (C++11) as_const (C++17) Gemeinsame Vokabulartypen pair tuple (C++11) optional (C++17) any (C++17) variant (C++17) tuple_size (C++11) tuple_element (C++11) apply (C++17) make_from_tuple (C++17) expected (C++23)

 

std::variant

Memberfunktionen

variant::variant

variant::~variant

variant::operator=

Observer

variant::index

variant::valueless_by_exception

Modifizierer

variant::emplace

variant::swap

Besuch

variant::visit (C++26)

Nicht-Member-Funktionen

visit(std::variant)

holds_alternative

get(std::variant)

get_if

operator==operator!=operator<operator<=operator>operator>=operator<=> (C++20)

swap(std::variant)

Hilfsklassen

monostate

bad_variant_access

variant_size

variant_alternative

hash<std::variant>

Hilfsobjekte

variant_npos

 

Definiert in der Header-Datei <variant>
template< class... Types > class variant;		(seit C++17)

Die Klassenschablone std::variant stellt eine typsichere union dar.

Eine Instanz von variant hält zu jedem Zeitpunkt entweder einen Wert eines ihrer alternativen Typen oder – im Fehlerfall – keinen Wert (dieser Zustand ist schwer zu erreichen, siehe valueless_by_exception).

Wie bei unions wird, wenn ein variant einen Wert eines Objekttyps T enthält, das T-Objekt innerhalb des variant-Objekts verschachtelt.

Ein variant darf keine Referenzen, Arrays oder den Typ void enthalten.

Ein variant darf denselben Typ mehrmals und unterschiedlich cv-qualifizierte Versionen desselben Typs enthalten.

Im Einklang mit dem Verhalten von Unions während der Aggregatinitialisierung enthält ein standardkonstruierter variant einen Wert seiner ersten Alternative, es sei denn, diese Alternative ist nicht standardkonstruierbar (in diesem Fall ist der variant auch nicht standardkonstruierbar). Die Hilfsklasse std::monostate kann verwendet werden, um solche variants standardkonstruierbar zu machen.

Ein Programm, das die Definition von std::variant ohne Schablonenargumente instanziiert, ist fehlerhaft. stattdessen kann std::variant<std::monostate> verwendet werden.

Wenn ein Programm eine explizite oder partielle Spezialisierung von std::variant deklariert, ist das Programm fehlerhaft, ohne Diagnose.

Schablonenparameter

Typen

-

die Typen, die in diesem variant gespeichert werden können. Alle Typen müssen die Destructible-Anforderungen erfüllen (insbesondere sind Array-Typen und Nicht-Objekttypen nicht erlaubt).

Memberfunktionen

(Konstruktor)	konstruiert das variant-Objekt (public member function)
(Destruktor)	zerstört das variant zusammen mit seinem enthaltenen Wert (public member function)
operator=	weist einem variant zu (public member function)
Observer
index	gibt den nullbasierten Index der vom variant gehaltenen Alternative zurück (public member function)
valueless_by_exception	prüft, ob sich der variant im ungültigen Zustand befindet (public member function)
Modifizierer
emplace	konstruiert einen Wert im variant, direkt (public member function)
swap	tauscht mit einem anderen variant (public member function)
Besuch
visit (C++26)	ruft den bereitgestellten Funktor mit dem vom variant gehaltenen Argument auf (public member function)

Nicht-Member-Funktionen

visit (C++17)	ruft den bereitgestellten Funktor mit den von einem oder mehreren variants gehaltenen Argumenten auf (function template)
holds_alternative (C++17)	prüft, ob ein variant derzeit einen gegebenen Typ hält (function template)
get(std::variant) (C++17)	liest den Wert des variants anhand des Index oder des Typs (wenn der Typ eindeutig ist), wirft bei Fehler (function template)
get_if (C++17)	erhält einen Zeiger auf den Wert eines aufgerufenen variant anhand des Index oder des Typs (wenn eindeutig), gibt bei Fehler null zurück (function template)
operator==operator!=operator<operator<=operator>operator>=operator<=> (C++17)(C++17)(C++17)(C++17)(C++17)(C++17)(C++20)	vergleicht variant-Objekte als ihre enthaltenen Werte (function template)
std::swap(std::variant) (C++17)	spezialisiert den Algorithmus std::swap (function template)

Hilfsklassen

monostate (C++17)	Platzhaltertyp zur Verwendung als erste Alternative in einem variant von nicht standardkonstruierbaren Typen (class)
bad_variant_access (C++17)	Ausnahme, die bei ungültigen Zugriffen auf den Wert eines variant geworfen wird (class)
variant_sizevariant_size_v (C++17)	erhält zur Kompilierzeit die Größe der Alternativenliste des variant (class template) (variable template)
variant_alternativevariant_alternative_t (C++17)	erhält zur Kompilierzeit den Typ der durch ihren Index angegebenen Alternative (class template) (alias template)
std::hash<std::variant> (C++17)	Hash-Unterstützung für std::variant (Klassentemplate-Spezialisierung)

Hilfsobjekte

variant_npos (C++17)

Index des variant im ungültigen Zustand (constant)

Notizen

Feature-Test-Makro	Wert	Std	Feature
__cpp_lib_variant	201606L	(C++17)	std::variant: eine typsichere union
	202102L	(C++23) (DR17)	std::visit für von std::variant abgeleitete Klassen
	202106L	(C++23) (DR20)	Vollständig constexpr std::variant
	202306L	(C++26)	Member visit

Beispiel

Führen Sie diesen Code aus

#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
}

Mögliche Ausgabe

std::get: wrong index for variant

Fehlerberichte

Die folgenden Verhaltensändernden Fehlerberichte wurden rückwirkend auf zuvor veröffentlichte C++-Standards angewendet.

DR	angewendet auf	Verhalten wie veröffentlicht	Korrigiertes Verhalten
LWG 2901	C++17	Spezialisierung von std::uses_allocator bereitgestellt, aber variant kann Allocatoren nicht ordnungsgemäß unterstützen	Spezialisierung entfernt
LWG 3990	C++17	ein Programm könnte eine explizite oder partielle Spezialisierung von std::variant deklarieren	das Programm ist in diesem Fall fehlerhaft (keine Diagnose erforderlich)
LWG 4141	C++17	die Anforderung für die Speicherung Allokation war verwirrend	Das enthaltene Objekt muss innerhalb des variant-Objekts

Siehe auch

in_placein_place_typein_place_indexin_place_tin_place_type_tin_place_index_t (C++17)	Tag für In-Place-Konstruktion (Tag)
optional (C++17)	ein Wrapper, der möglicherweise ein Objekt enthält oder auch nicht (Klassenvorlage)
any (C++17)	Objekte, die Instanzen eines beliebigen CopyConstructible-Typs enthalten (Klasse)