Namespaces
Variants
Views
Actions

std::expected

From cppreference.com
< cpp‎ | utility
 
 
Utilities library
Language support
Type support (basic types, RTTI)
Library feature-test macros (C++20)
Dynamic memory management
Program utilities
Coroutine support (C++20)
Variadic functions
Debugging support
(C++26)
Three-way comparison
(C++20)
(C++20)(C++20)(C++20)
(C++20)(C++20)(C++20)
General utilities
Date and time
Function objects
Formatting library (C++20)
(C++11)
Relational operators (deprecated in C++20)
Integer comparison functions
(C++20)(C++20)(C++20)   
(C++20)
Swap and type operations
(C++14)
(C++11)
(C++11)
(C++11)
(C++17)
Common vocabulary types
(C++11)
(C++17)
(C++17)
(C++17)
(C++11)
(C++17)
expected
(C++23)
Elementary string conversions
(C++17)
(C++17)

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

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.

Contents

[edit] 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).

[edit] Member types

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

[edit] Member alias templates

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

[edit] Member functions

constructs the expected object
(public member function) [edit]
destroys the expected object, along with its contained value
(public member function) [edit]
assigns contents
(public member function) [edit]
Observers
accesses the expected value
(public member function) [edit]
checks whether the object contains an expected value
(public member function) [edit]
returns the expected value
(public member function) [edit]
returns the unexpected value
(public member function) [edit]
returns the expected value if present, another value otherwise
(public member function) [edit]
Monadic operations
returns the result of the given function on the expected value if it exists; otherwise, returns the expected itself
(public member function) [edit]
returns an expected containing the transformed expected value if it exists; otherwise, returns the expected itself
(public member function) [edit]
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) [edit]
returns the expected itself if it contains an expected value; otherwise, returns an expected containing the transformed unexpected value
(public member function) [edit]
Modifiers
constructs the expected value in-place
(public member function) [edit]
exchanges the contents
(public member function) [edit]

[edit] Non-member functions

compares expected objects
(function template) [edit]
specializes the std::swap algorithm
(function) [edit]

[edit] Helper classes

represented as an unexpected value
(class template) [edit]
exception indicating checked access to an expected that contains an unexpected value
(class template) [edit]
in-place construction tag for unexpected value in expected
(tag)[edit]

[edit] 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
202211L (C++23) Monadic functions for std::expected

[edit] Example

#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

[edit] References

  • C++23 standard (ISO/IEC 14882:2023):
  • 22.8 Expected objects [expected]

[edit] See also

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