std::optional

 

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::optional

Memberfunktionen

optional::optional

optional::~optional

optional::operator=

Observer

optional::operator->optional::operator*

optional::operator booloptional::has_value

optional::value

optional::value_or

Iteratoren

optional::begin (C++26)

optional::end (C++26)

Monadische Operationen

optional::and_then (C++23)

optional::transform (C++23)

optional::or_else (C++23)

Modifizierer

optional::emplace

optional::swap

optional::reset

Nicht-Member-Funktionen

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

make_optional

swap(std::optional)

Deduction Guides

Hilfsklassen

hash<std::optional>

nullopt_t

in_place_t

bad_optional_access

Hilfsobjekte

nullopt

in_place

 

Definiert in der Header-Datei <optional>
template< class T > class optional;		(seit C++17)

Die Klassenschablone std::optional verwaltet einen optionalen enthaltenen Wert, d.h. einen Wert, der vorhanden sein kann oder auch nicht.

Ein häufiger Anwendungsfall für optional ist der Rückgabewert einer Funktion, die fehlschlagen kann. Im Gegensatz zu anderen Ansätzen, wie z.B. std::pair<T, bool>, behandelt optional teure zu konstruierende Objekte gut und ist lesbarer, da die Absicht explizit ausgedrückt wird.

Jede Instanz von optional enthält zu jedem Zeitpunkt entweder einen Wert oder keinen Wert.

Wenn ein optional einen Wert enthält, ist garantiert, dass der Wert innerhalb des optional-Objekts verschachtelt ist. Somit modelliert ein optional-Objekt ein Objekt und keinen Zeiger, auch wenn operator*() und operator->() definiert sind.

Wenn ein Objekt vom Typ optional<T> kontextbezogen in bool umgewandelt wird, gibt die Konvertierung true zurück, wenn das Objekt einen Wert enthält, und false, wenn es keinen Wert enthält.

Das optional-Objekt enthält unter folgenden Bedingungen einen Wert:

• Das Objekt wird mit/aus einem Wert vom Typ T oder einem anderen optional, das einen Wert enthält, initialisiert/zugewiesen.

Das Objekt enthält unter folgenden Bedingungen keinen Wert:

• Das Objekt wird default-initialisiert.
• Das Objekt wird mit/aus einem Wert vom Typ std::nullopt_t oder einem optional-Objekt, das keinen Wert enthält, initialisiert/zugewiesen.
• Die Memberfunktion reset() wird aufgerufen.

Das optional-Objekt ist eine view, die entweder ein Element enthält, wenn es einen Wert enthält, oder andernfalls null Elemente, wenn es keinen Wert enthält. Die Lebensdauer des enthaltenen Elements ist an das Objekt gebunden.

(seit C++26)

Es gibt keine optionalen Referenzen, Funktionen, Arrays oder (möglicherweise cv-qualifiziertes) void; ein Programm ist ill-formed, wenn es ein optional mit einem solchen Typ instanziiert. Darüber hinaus ist ein Programm ill-formed, wenn es ein optional mit den (möglicherweise cv-qualifizierten) Tag-Typen std::nullopt_t oder std::in_place_t instanziiert.

Template-Parameter

T

-

der Typ des zu verwaltenden Werts für den Initialisierungszustand. Der Typ muss die Anforderungen von Destructible erfüllen (insbesondere sind Array- und Referenztypen nicht erlaubt).

Verschachtelte Typen

Typ	Definition
value_type	T
iterator (seit C++26)	implementierungsabhängiger LegacyRandomAccessIterator, ConstexprIterator und contiguous_iterator, deren value_type und reference std::remove_cv_t<T> bzw. T& sind.
const_iterator (seit C++26)	implementierungsabhängiger LegacyRandomAccessIterator, ConstexprIterator und contiguous_iterator, deren value_type und reference std::remove_cv_t<T> bzw. const T& sind.

Alle Anforderungen an die Iteratortypen eines Containers gelten auch für den iterator-Typ von optional.

Datenmember

T* val

ein Zeiger auf das enthaltene Objekt (falls vorhanden) ((exposition-only member object*)

Memberfunktionen

(Konstruktor)	konstruiert das optional-Objekt (public member function)
(Destruktor)	zerstört den enthaltenen Wert, falls vorhanden (public member function)
operator=	weist Inhalte zu (public member function)
Iteratoren
begin (C++26)	gibt einen Iterator zum Anfang zurück (public member function)
end (C++26)	gibt einen Iterator zum Ende zurück (public member function)
Observer
operator->operator*	greift auf den enthaltenen Wert zu (public member function)
operator boolhas_value	prüft, ob das Objekt einen Wert enthält (public member function)
value	gibt den enthaltenen Wert zurück (public member function)
value_or	gibt den enthaltenen Wert zurück, falls vorhanden, sonst einen anderen Wert (public member function)
Monadische Operationen
and_then (C++23)	gibt das Ergebnis der gegebenen Funktion auf dem enthaltenen Wert zurück, falls dieser existiert, andernfalls ein leeres optional (public member function)
transform (C++23)	gibt ein optional zurück, das den transformierten enthaltenen Wert enthält, falls dieser existiert, andernfalls ein leeres optional (public member function)
or_else (C++23)	gibt das optional selbst zurück, wenn es einen Wert enthält, andernfalls das Ergebnis der gegebenen Funktion (public member function)
Modifizierer
swap	tauscht die Inhalte (public member function)
reset	zerstört jeden enthaltenen Wert (public member function)
emplace	konstruiert den enthaltenen Wert in-place (public member function)

Non-Member-Funktionen

operator==operator!=operator<operator<=operator>operator>=operator<=> (C++17)(C++17)(C++17)(C++17)(C++17)(C++17)(C++20)	vergleicht optional-Objekte (function template)
make_optional (C++17)	erzeugt ein optional-Objekt (function template)
std::swap(std::optional) (C++17)	spezialisiert den Algorithmus std::swap (function template)

Hilfsklassen

std::hash<std::optional> (C++17)	Hash-Unterstützung für std::optional (Klassentemplate-Spezialisierung)
nullopt_t (C++17)	Anzeiger für ein std::optional, das keinen Wert enthält (class)
bad_optional_access (C++17)	Ausnahme, die auf einen geprüften Zugriff auf ein optionales Element hinweist, das keinen Wert enthält (class)

Hilfsmittel

nullopt (C++17)	ein Objekt vom Typ nullopt_t (constant)
in_placein_place_typein_place_indexin_place_tin_place_type_tin_place_index_t (C++17)	Tag für In-Place-Konstruktion (tag)

Hilfsspezialisierungen

template< class T > constexpr bool ranges::enable_view<std::optional<T>> = true;		(seit C++26)

Diese Spezialisierung von ranges::enable_view lässt optional view erfüllen.

template< class T > constexpr auto format_kind<std::optional<T>> = range_format::disabled;		(seit C++26)

Diese Spezialisierung von format_kind deaktiviert die Bereichsformatierungsunterstützung von optional.

Hinweise

Feature-Test-Makro	Wert	Std	Feature
__cpp_lib_optional	201606L	(C++17)	std::optional
	202106L	(C++23) (DR20)	Vollständig constexpr
	202110L	(C++23)	Monadische Operationen
__cpp_lib_optional_range_support	202406L	(C++26)	Bereichsunterstützung für std::optional

Beispiel

Führen Sie diesen Code aus

#include <iostream>
#include <optional>
#include <string>
 
// optional can be used as the return type of a factory that may fail
std::optional<std::string> create(bool b)
{
    if (b)
        return "Godzilla";
    return {};
}
 
// std::nullopt can be used to create any (empty) std::optional
auto create2(bool b)
{
    return b ? std::optional<std::string>{"Godzilla"} : std::nullopt;
}
 
int main()
{
    std::cout << "create(false) returned "
              << create(false).value_or("empty") << '\n';
 
    // optional-returning factory functions are usable as conditions of while and if
    if (auto str = create2(true))
        std::cout << "create2(true) returned " << *str << '\n';
}

Ausgabe

create(false) returned empty
create2(true) returned Godzilla

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 4141	C++17	Die Anforderung an die Speicherung Allokation war verwirrend	Das enthaltene Objekt muss innerhalb des optional-Objekts verschachtelt sein

Siehe auch

variant (C++17)	eine typsichere diskriminierte Union (Klassentemplate)
any (C++17)	Objekte, die Instanzen eines beliebigen CopyConstructible-Typs enthalten (Klasse)
expected (C++23)	ein Wrapper, der entweder einen erwarteten oder einen Fehlerwert enthält (Klassenvorlage)
ranges::single_viewviews::single (C++20)	eine view, die ein einzelnes Element eines bestimmten Wertes enthält (class template) (customization point object)
ranges::empty_viewviews::empty (C++20)	eine leere view ohne Elemente (class template) (variable template)