NAME¶

std::expected - std::expected

Synopsis¶

Defined in header <expected>
template< class T, class E > (since C++23)
class expected;

The class template std::expected provides a way to store either of two values. An
object of std::expected at any given time either holds an expected value of type T,
or an unexpected value of type E. std::expected is never valueless.

The stored value is allocated directly within the storage occupied by the expected
object. No dynamic memory allocation takes place.

A program is ill-formed if it instantiates an expected with a reference type, a
function type, or a specialization of std::unexpected. In addition, T must not be
std::in_place_t or std::unexpect_t.

Template parameters¶

the type of the expected value. The type must either be (possibly cv-qualified)
T - void, or meet the Destructible requirements (in particular, array and reference
types are not allowed).
the type of the unexpected value. The type must meet the Destructible
E - requirements, and must be a valid template argument for std::unexpected (in
particular, arrays, non-object types, and cv-qualified types are not allowed).

Member types¶

Member type Definition
value_type T
error_type E
unexpected_type std::unexpected<E>

Member alias templates¶

Type Definition
rebind<U> expected<U, error_type>

Member functions¶

constructor constructs the expected object
(public member function)
destructor destroys the expected object, along with its contained value
(public member function)
operator= assigns contents
(public member function)

Observers¶

operator-> accesses the expected value
operator* (public member function)
operator bool checks whether the object contains an expected value
has_value (public member function)
value returns the expected value
(public member function)
error returns the unexpected value
(public member function)
value_or returns the expected value if present, another value otherwise
(public member function)
Monadic operations
returns the result of the given function on the expected value if it
and_then exists; otherwise, returns the expected itself
(public member function)
returns an expected containing the transformed expected value if it
transform exists; otherwise, returns the expected itself
(public member function)
returns the expected itself if it contains an expected value;
or_else 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;
transform_error otherwise, returns an expected containing the transformed unexpected
value
(public member function)

Modifiers¶

emplace constructs the expected value in-place
(public member function)
swap exchanges the contents
(public member function)

Non-member functions¶

operator== compares expected objects
(C++23) (function template)
swap(std::expected) specializes the std::swap algorithm
(C++23) (function)

Helper classes¶

unexpected represented as an unexpected value
(C++23) (class template)
bad_expected_access exception indicating checked access to an expected that contains
(C++23) an unexpected value
(class template)
unexpect in-place construction tag for unexpected value in expected
unexpect_t (tag)
(C++23)

Notes¶

Types with the same functionality are called Result in Rust and Either in Haskell.

Feature-test macro Value Std Feature
202202L (C++23) class template std::expected and associated
__cpp_lib_expected helper classes
202211L (C++23) Monadic functions for std::expected

Example¶

// Run this code

#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);
}

Output:¶

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

References¶

* C++23 standard (ISO/IEC 14882:2023):

* 22.8 Expected objects [expected]

See also¶

variant a type-safe discriminated union
(C++17) (class template)
optional a wrapper that may or may not hold an object
(C++17) (class template)