# std::expected

> C++ Atlas: `cppatlas.com/w/cpp/utility/expected` | Source: https://en.cppreference.com/w/cpp/utility/expected | Domain: Utility | Standards: C++17, 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.

## Official Specification Summary (cppreference)

```cpp
// Defined in header <expected>

template< class T, class E >
class expected; // (1) (since C++23)

template< class T, class E >
    requires std::is_void_v<T>
class expected<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`. `std::expected` is never valueless.

1) The main template. Contains the expected or unexpected value within its own storage. No dynamic memory allocation takes place.

2) The `void` partial specialization. Represents an expected `void` value or contains the unexpected value within its own storage. 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

- `T` - the type of the expected value. The type must either be (possibly cv-qualified) `void`, or meet the *Destructible* requirements (in particular, array and reference types are not allowed).
- `E` - the type of the unexpected value. The type must meet the *Destructible* 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>`: `std::expected<U, error_type>`

### Data members

**Member — Definition**

- `bool` `has_val`: whether the `expected` object currently represents the expected value (exposition-only member object*)
- `T` `val` (main template only): the expected value (exposition-only variant member object*)
- `E` `unex`: the unexpected value (exposition-only variant member object*)

### 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->`, `operator*`: accesses the expected value (public member function)
- `operator bool`, `has_value`: checks whether the object contains an expected 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)
- `error_or`: returns the unexpected value if present, another value otherwise (public member function)

**Monadic operations**

- `and_then`: returns the result of the given function on the expected value if it exists; otherwise, returns the `expected` itself (public member function)
- `transform`: returns an `expected` containing the transformed expected value if it exists; otherwise, returns the `expected` itself (public member function)
- `or_else`: 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)
- `transform_error`: returns the `expected` itself if it contains an expected value; 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==` (C++23): compares `expected` objects (function template)
- `swap(std::expected)` (C++23): specializes the `std::swap` algorithm (function)

### Helper classes

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

### Notes

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

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

### Example

```cpp
#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:

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

### References

- C++23 standard (ISO/IEC 14882:2024):

  - 22.8 Expected objects [expected]

### See also

- [`variant`](https://en.cppreference.com/w/cpp/utility/variant) (C++17): a type-safe discriminated union (class template)
- [`optional`](https://en.cppreference.com/w/cpp/utility/optional) (C++17): a wrapper that may or may not hold an object (class template)

---
Attribution: content from https://en.cppreference.com/w/cpp/utility/expected (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.