Skip to content
Tutorials Center
My learning

Topics

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.

C++
#include <expected>

std::expected<int, std::string> parse(std::string_view text);

Try it

C++ Returning a value or an error

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.

C++ Chaining with and_then, transform and or_else

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

C++
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::expected is available in GCC 12 and later in C++23 mode; and_then, transform and the other monadic operations came with it.
  • Choose the error type deliberately: an enum, std::error_code, a small struct or a std::string for 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 expected for errors callers routinely expect (parsing, I/O, validation) and exceptions for truly exceptional conditions or constructors that cannot return a result.
  • Comparison: two expected values are equal when both hold equal values or both hold equal errors; comparing with a plain T or with unexpected is also supported.
  • Same type for T and E is allowed (expected<int, int>); std::unexpected is what keeps the two states apart.
  • [[nodiscard]]: mark functions returning expected as [[nodiscard]] so ignored errors are warned about.
  • Compared with optional: use std::optional when the reason for absence is not interesting.