What is std::expected in C++?

by

Actually, the best way to learn about std::expected is a funny talk by the (in)famous Andrei Alexandrescu: “Expect the Expected!”

What std::expected is, and when it’s used

Here are three complementing explanations of what an std::expected<T, E> is:

  • It is the return type of a function which is supposed to return a T value – but which may encounter some error, in which case it will return a descriptor of that error, of type E.

    An example:

    std::expected<ParsedData, ParsingError> parse_input(Input input);

  • It’s an error-handling mechanism, being an alternative to throwing exceptions (in which case you always return the value you were supposed to), and to returning status/error codes (in which case you never return the value you want to, and have to use an out-parameter).

    Here are the two alternative error-handling mechanisms applied to the function from the previous example:

    ParsedData    parse_input_2(Input input) noexcept(false);
ParsingError  parse_input_3(ParsedData& result, Input input);

  • It’s a discriminated union of types T and E with some convenience methods.

“How is it better than just an std::variant<T,E>?”

It behaves somewhat like std::optional<T>, giving focus to the expected, rather than the unexpected, case:

  • result.has_value() – true if we got a value rather than an error.
  • if (result) – checks for the same thing
  • *result – gives us the T value if it exists, undefined behavior otherwise (same as std::optional, although many don’t like this).
  • result.value(), gives us the T value if it exists, or throws otherwise.

Actually, that last mode of access behaves differently than std::optional if we got an error: What it throws is a bad_expected_access<E>, with the returned error. This behavior can be thought of as a way to switch from expected-based to exception-based error-handling.

“Hey, I looked for it in the standard and it isn’t there!”

std::expected will be part of the upcoming C++23 standard. The proposal (P0323) has recently been accepted.

This being said – it is quite usable already, since it requires no new language facilities:

  • I can recommend one Sy Brand (tartanllama)’s implementation, which can be used with C++11 or later. It also has some neat functional-style extensions (which may not be standardized).
  • @Malachi recommends estd::expected, part of a standard library implementation intended for embedded environments.

Leave a Comment

tech