Namespaces
Variants
Views
Actions

std::expected

From cppreference.com
< cpp‎ | utility
 
 
Utilities library
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 (possible 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>
rebind template< class U >

using rebind = 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]
(C++23)
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]
(C++23)
returns the expected value
(public member function) [edit]
(C++23)
returns the unexpected value
(public member function) [edit]
(C++23)
returns the expected value if present, another value otherwise
(public member function) [edit]
Modifiers
(C++23)
constructs the expected value in-place
(public member function) [edit]
(C++23)
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
(class) (constant) [edit]

[edit] Notes

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

Feature-test macro Value Std
__cpp_lib_expected 202202L (C++23)

[edit] Example

[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]