C++ Reference ยท Containers
C++ std::expected class
Reference for std::expected (C++23): return either a value or an error without exceptions, with unexpected, value_or, error, and_then, transform and or_else.
std::expected<T, E> (C++23, header <expected>) is the result of an operation that either succeeded with a value of type T or failed with an error of type E. It is a vocabulary type for error handling without exceptions: the failure is part of the function's signature, and the caller has to look at it before using the value.
It resembles std::optional<T>, but the empty state carries information (why it failed). The error is wrapped in std::unexpected when you construct a failed result, which avoids ambiguity when T and E are the same type.
#include <expected> std::expected<int, std::string> parse(std::string_view text);
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Syntax
template<class T, class E> class expected; template<class E> class unexpected; constexpr expected(); // value-initialized T template<class U = T> constexpr expected(U&& v); template<class G> constexpr expected(const unexpected<G>& e);
| Name | Description |
|---|---|
T |
Type of the success value. May be void (an expected<void, E> only reports success or an error). |
E |
Type of the error. It must be a valid unexpected argument: not an array, reference or cv-qualified type. |
v |
The success value. |
e |
An std::unexpected wrapping the error, created with std::unexpected(err). |
Members: has_value / operator bool, value, error, operator*, operator->, value_or, error_or, emplace, swap, and the monadic operations and_then, transform, or_else, transform_error.
Returns: value_or(x) returns the value or x. and_then(f) calls f(value) and returns its expected result, or propagates the error. transform(f) wraps f(value) in a new expected with the same error type.
Errors / undefined behavior: value() on a failed result throws std::bad_expected_access<E> holding the error. *e and e-> without a value, or error() on a successful result, are undefined behavior.
Usage notes
- GCC support:
std::expectedis available in GCC 12 and later in C++23 mode;and_then,transformand the other monadic operations came with it. - Choose the error type deliberately: an enum,
std::error_code, a small struct or astd::stringfor human text. Keep it cheap to copy and move. - No hidden control flow. Unlike exceptions, the type forces handling at each call site, but it also makes propagation verbose; the monadic operations reduce the boilerplate.
- Not a replacement for all exceptions. Use
expectedfor errors callers routinely expect (parsing, I/O, validation) and exceptions for truly exceptional conditions or constructors that cannot return a result. - Comparison: two
expectedvalues are equal when both hold equal values or both hold equal errors; comparing with a plainTor withunexpectedis also supported. - Same type for
TandEis allowed (expected<int, int>);std::unexpectedis what keeps the two states apart. [[nodiscard]]: mark functions returningexpectedas[[nodiscard]]so ignored errors are warned about.- Compared with
optional: usestd::optionalwhen the reason for absence is not interesting.