std::expected

 

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

Memberfunktionen

expected::expected

expected::~expected

expected::operator=

Observer

expected::operator->expected::operator*

expected::operator boolexpected::has_value

expected::value

expected::error

expected::value_or

expected::error_or

Monadische Operationen

expected::and_then

expected::or_else

expected::transform

expected::transform_error

Modifizierer

expected::emplace

expected::swap

Nicht-Member-Funktionen

operator==(std::expected)

swap(std::expected)

Hilfsklassen

unexpected

bad_expected_access

unexpect_tunexpect

 

Definiert in der Header-Datei <expected>
template< class T, class E > class expected;	(1)	(seit C++23)
template< class T, class E >     requires std::is_void_v<T> class expected<T, E>;	(2)	(seit C++23)

Die Klassenschablone std::expected bietet eine Möglichkeit, entweder einen von zwei Werten darzustellen: einen *erwarteten* Wert vom Typ T oder einen *unerwarteten* Wert vom Typ E. expected ist niemals wertlos.

1) Die Hauptschablone. Enthält den erwarteten oder unerwarteten Wert innerhalb ihres eigenen Speichers, der sich innerhalb des expected-Objekts befindet.

2) Die partielle Spezialisierung für void. Repräsentiert einen erwarteten void-Wert oder enthält einen unerwarteten Wert. Wenn sie einen unerwarteten Wert enthält, ist dieser im expected-Objekt verschachtelt.

Ein Programm ist schlecht geformt, wenn es ein expected mit einem Referenztyp, einem Funktionstyp oder einer Spezialisierung von std::unexpected instanziiert. Zusätzlich darf T nicht std::in_place_t oder std::unexpect_t sein.

Template-Parameter

T	-	der Typ des erwarteten Wertes. Der Typ muss entweder (möglicherweise cv-qualifiziert) void sein oder die Destructible-Anforderungen erfüllen (insbesondere sind Array- und Referenztypen nicht erlaubt).
E	-	der Typ des unerwarteten Wertes. Der Typ muss die Destructible-Anforderungen erfüllen und ein gültiges Argument für die Schablone std::unexpected sein (insbesondere sind Arrays, Nicht-Objekttypen und cv-qualifizierte Typen nicht erlaubt).

Mitgliedstypen

Mitgliedertyp	Definition
value_type	T
error_type	E
unexpected_type	std::unexpected<E>

Mitglieds-Alias-Schablonen

Typ	Definition
rebind<U>	std::expected<U, error_type>

Datenelemente

Mitglied	Definition
bool has_val	ob, ob das expected-Objekt derzeit den erwarteten Wert repräsentiert ((exposition-only member object*)
T val (nur Hauptschablone)	der erwartete Wert ((nur exposition-Variantenmitgliedsobjekt*)
E unex	der unerwartete Wert ((nur exposition-Variantenmitgliedsobjekt*)

Mitgliedsfunktionen

(Konstruktor)	konstruiert das expected-Objekt (öffentliche Mitgliedsfunktion)
(Destruktor)	zerstört das expected-Objekt zusammen mit seinem enthaltenen Wert (öffentliche Mitgliedsfunktion)
operator=	weist Inhalte zu (öffentliche Mitgliedsfunktion)
Observer
operator->operator*	greift auf den erwarteten Wert zu (öffentliche Mitgliedsfunktion)
operator boolhas_value	prüft, ob das Objekt einen erwarteten Wert enthält (öffentliche Mitgliedsfunktion)
value	gibt den erwarteten Wert zurück (öffentliche Mitgliedsfunktion)
error	gibt den unerwarteten Wert zurück (öffentliche Mitgliedsfunktion)
value_or	gibt den erwarteten Wert zurück, falls vorhanden, andernfalls einen anderen Wert (öffentliche Mitgliedsfunktion)
error_or	gibt den unerwarteten Wert zurück, falls vorhanden, andernfalls einen anderen Wert (öffentliche Mitgliedsfunktion)
Monadische Operationen
and_then	gibt das Ergebnis der gegebenen Funktion auf dem erwarteten Wert zurück, falls dieser existiert; andernfalls gibt es das expected selbst zurück (öffentliche Mitgliedsfunktion)
transform	gibt ein expected mit dem transformierten erwarteten Wert zurück, falls dieser existiert; andernfalls gibt es das expected selbst zurück (öffentliche Mitgliedsfunktion)
or_else	gibt das expected selbst zurück, wenn es einen erwarteten Wert enthält; andernfalls gibt es das Ergebnis der gegebenen Funktion auf dem unerwarteten Wert zurück (öffentliche Mitgliedsfunktion)
transform_error	gibt das expected selbst zurück, wenn es einen erwarteten Wert enthält; andernfalls gibt es ein expected mit dem transformierten unerwarteten Wert zurück (öffentliche Mitgliedsfunktion)
Modifizierer
emplace	konstruiert den erwarteten Wert an Ort und Stelle (öffentliche Mitgliedsfunktion)
swap	tauscht die Inhalte (öffentliche Mitgliedsfunktion)

Nicht-Mitgliedsfunktionen

operator== (C++23)	vergleicht expected-Objekte (Funktionsschablone)
swap(std::expected) (C++23)	spezialisiert den Algorithmus std::swap (Funktion)

Hilfsklassen

unexpected (C++23)	als unerwarteter Wert dargestellt (Klassenschablone)
bad_expected_access (C++23)	Ausnahme, die den geprüften Zugriff auf ein expected anzeigt, das einen unerwarteten Wert enthält (Klassenschablone)
unexpectunexpect_t (C++23)	Tag für die In-Place-Konstruktion eines unerwarteten Wertes in expected (Tag)

Anmerkungen

Typen mit derselben Funktionalität werden in Rust als Result und in Haskell als Either bezeichnet.

Feature-Test-Makro	Wert	Std	Feature
__cpp_lib_expected	202202L	(C++23)	Klassenschablone std::expected und zugehörige Hilfsklassen
	202211L	(C++23)	Monadische Funktionen für std::expected

Beispiel

Führen Sie diesen Code aus

#include <cmath>
#include <expected>
#include <iomanip>
#include <iostream>
#include <string_view>
 
enum class parse_error
{
    invalid_input,
    overflow
};
 
auto parse_number(std::string_view& str) -> std::expected<double, parse_error>
{
    const char* begin = str.data();
    char* end;
    double retval = std::strtod(begin, &end);
 
    if (begin == end)
        return std::unexpected(parse_error::invalid_input);
    else if (std::isinf(retval))
        return std::unexpected(parse_error::overflow);
 
    str.remove_prefix(end - begin);
    return retval;
}
 
int main()
{
    auto process = [](std::string_view str)
    {
        std::cout << "str: " << std::quoted(str) << ", ";
        if (const auto num = parse_number(str); num.has_value())
            std::cout << "value: " << *num << '\n';
            // If num did not have a value, dereferencing num
            // would cause an undefined behavior, and
            // num.value() would throw std::bad_expected_access.
            // num.value_or(123) uses specified default value 123.
        else if (num.error() == parse_error::invalid_input)
            std::cout << "error: invalid input\n";
        else if (num.error() == parse_error::overflow)
            std::cout << "error: overflow\n";
        else
            std::cout << "unexpected!\n"; // or invoke std::unreachable();
    };
 
    for (auto src : {"42", "42abc", "meow", "inf"})
        process(src);
}

Ausgabe

str: "42", value: 42
str: "42abc", value: 42
str: "meow", error: invalid input
str: "inf", error: overflow

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++23	die Anforderung an Speicher Allokation war verwirrend	Das enthaltene Objekt muss innerhalb des expected-Objekts verschachtelt

Referenzen

• C++23 Standard (ISO/IEC 14882:2024)

• 22.8 Expected objects [expected]

Siehe auch

variant (C++17)	eine typsichere diskriminierte Union (Klassentemplate)
optional (C++17)	ein Wrapper, der möglicherweise ein Objekt enthält oder auch nicht (Klassenvorlage)