From cppreference.com
Defined in header
template<classT,classE>classexpected; (1) (since C++23)template<classT,classE>requiresstd::is_void_v<T>classexpected<T,E>; (2) (since C++23)The class template std::expected provides a way to represent either of two values: an expected value of type T, or an unexpected value of type E. expected is never valueless.
1) The main template. Contains the expected or unexpected value within its own storage, which is
the expected object.
2) The void partial specialization. Represents an expected void value or contains an unexpected value. If it contains an unexpected value, it is nested within the expected object.
A program is ill-formed if it instantiates an expected with a reference type, a function type, or a specialization of
. In addition, T must not be
or
.
Template parameters
T - the type of the expected value. The type must either be (possibly cv-qualified) void, or meet the
requirements (in particular, array and reference types are not allowed). E - the type of the unexpected value. The type must meet the
requirements, and must be a valid template argument for
(in particular, arrays, non-object types, and cv-qualified types are not allowed). Nested types
Member templates
Template Definition rebind<U>std::expected<U,error_type>Data members
Member Description boolhas_valwhether the expected object currently represents the expected value
(exposition-only member object*)Tval(main template only)the expected value
(exposition-only variant member object*)Eunexthe unexpected value
(exposition-only variant member object*)Member functions
constructs the expected object
(public member function)
destroys the expected object, along with its contained value
(public member function)
assigns contents
(public member function)
Observers
accesses the expected value
(public member function)
checks whether the object contains an expected value
(public member function)
returns the expected value
(public member function)
returns the unexpected value
(public member function)
returns the expected value if present, another value otherwise
(public member function)
returns the unexpected value if present, another value otherwise
(public member function)
Monadic operations
returns the result of the given function on the expected value if it exists; otherwise, returns the expected itself
(public member function)
returns an expected containing the transformed expected value if it exists; otherwise, returns the expected itself
(public member function)
returns the expected itself if it contains an expected value; otherwise, returns the result of the given function on the unexpected value
(public member function)
returns the expected itself if it contains an expected value; otherwise, returns an expected containing the transformed unexpected value
(public member function)
Modifiers
constructs the expected value in-place
(public member function)
exchanges the contents
(public member function)
Non-member functions
Helper classes
Notes
Types with the same functionality are called
in Rust and
in Haskell.
macro ValueStdFeature
(C++23)class template std::expected and associated
(C++23)Monadic functions for std::expectedExample
Run this code
#include<cmath>#include<expected>#include<iomanip>#include<iostream>#include<string_view>enumclassparse_error{invalid_input,overflow};autoparse_number(std::string_view&str)->std::expected<double,parse_error>{constchar*begin=str.data();char*end;doubleretval=std::strtod(begin,&end);if(begin==end)returnstd::unexpected(parse_error::invalid_input);elseif(std::isinf(retval))returnstd::unexpected(parse_error::overflow);str.remove_prefix(end-begin);returnretval;}intmain(){autoprocess=[](std::string_viewstr){std::cout<<"str: "<<std::quoted(str)<<", ";if(constautonum=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.elseif(num.error()==parse_error::invalid_input)std::cout<<"error: invalid input\n";elseif(num.error()==parse_error::overflow)std::cout<<"error: overflow\n";elsestd::cout<<"unexpected!\n";// or invoke std::unreachable();};for(autosrc:{"42","42abc","meow","inf"})process(src);}Output:
str: "42", value: 42 str: "42abc", value: 42 str: "meow", error: invalid input str: "inf", error: overflow Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR Applied to Behavior as published Correct behavior
C++23 the requirement of storage
allocation was confusing the contained object must be
nested within the expected object References
C++23 standard (ISO/IEC 14882:2024):
22.8 Expected objects [expected]
See also
(C++17)
a type-safe discriminated union
(class template)
(C++17)
a wrapper that may or may not hold an object
(class template)