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.
| 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 type | Definition |
|---|---|
value_type (C++23) | T |
error_type (C++23) | E |
unexpected_type (C++23) | std::unexpected<E> |
rebind (C++23) | template< class U > using rebind = expected<U, error_type>; |
|
(C++23) | constructs the expected object (public member function) |
|
(C++23) | destroys the expected object, along with its contained value (public member function) |
|
(C++23) | assigns contents (public member function) |
Observers |
|
|
(C++23) | accesses the expected value (public member function) |
|
(C++23) | checks whether the object contains an expected value (public member function) |
|
(C++23) | returns the expected value (public member function) |
|
(C++23) | returns the unexpected value (public member function) |
|
(C++23) | returns the expected value if present, another value otherwise (public member function) |
Monadic operations |
|
|
(C++23) | returns the result of the given function on the expected value if it exists; otherwise, returns the expected itself (public member function) |
|
(C++23) | returns an expected containing the transformed expected value if it exists; otherwise, returns the expected itself (public member function) |
|
(C++23) | 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) |
|
(C++23) | returns the expected itself if it contains an expected value; otherwise, returns an expected containing the transformed unexpected value (public member function) |
Modifiers |
|
|
(C++23) | constructs the expected value in-place (public member function) |
|
(C++23) | exchanges the contents (public member function) |
|
(C++23) | compares expected objects (function template) |
|
(C++23) | specializes the std::swap algorithm (function) |
|
(C++23) | represented as an unexpected value (class template) |
|
(C++23) | exception indicating checked access to an expected that contains an unexpected value (class template) |
|
(C++23) | in-place construction tag for unexpected value in expected (class) (constant) |
Types with the same functionality are called Result in Rust and Either in Haskell.
| Feature-test macro | Value | Std | Comment |
|---|---|---|---|
__cpp_lib_expected | 202202L | (C++23) | class template std::expected and associated helper classes |
| 202211L | (C++23) | Monadic functions for std::expected |
#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
|
(C++17) | a type-safe discriminated union (class template) |
|
(C++17) | a wrapper that may or may not hold an object (class template) |
© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/cpp/utility/expected