std::unexpected
<expected>
class unexpected;
The class template std::unexpected represents an unexpected value stored in std::expected. In particular, std::expected has constructors with std::unexpected as a single argument, which creates an expected object that contains an unexpected value.
A program is ill-formed if it instantiates an unexpected with a non-object type, an array type, a specialization of std::unexpected, or a cv-qualified type.
Contents
[edit] Template parameters
std::unexpected, or a cv-qualified type.
[edit] Member functions
unexpected object, along with the stored value (public member function)
(public member function)
[edit] Non-member functions
std::unexpected::unexpected
constexpr explicit unexpected( Err&& e );
constexpr explicit unexpected( std::in_place_t, Args&&... args );
constexpr explicit unexpected( std::in_place_t,
Constructs a std::unexpected object.
E from std::forward <Err>(e).
- This overload participates in overload resolution only if
- std::is_same_v <std::remove_cvref_t <Err>, unexpected> is false, and
- std::is_same_v <std::remove_cvref_t <Err>, std::in_place_t > is false, and
- std::is_constructible_v <E, Err> is true.
E from the arguments std::forward <Args>(args)....
- This overload participates in overload resolution only if std::is_constructible_v <E, Args...> is true.
E from the arguments il, std::forward <Args>(args)....
- This overload participates in overload resolution only if std::is_constructible_v <E, std::initializer_list <U>&, Args...> is true.
Parameters
Exceptions
Throws any exception thrown by the constructor of E.
std::unexpected::error
constexpr E& error() & noexcept;
constexpr const E&& error() const&& noexcept;
Returns a reference to the stored value.
std::unexpected::swap
Swaps the stored values, as if by using std::swap ; swap(error(), other.error());.
The program is ill-formed if std::is_swappable_v <E> is false.
operator==(std::unexpected)
friend constexpr bool operator==( unexpected& x, std::unexpected<E2>& y );
Compares the stored values, as if by return x.error() == y.error().
If the expression x.error() == e.error() is not well-formed, or if its result is not convertible to bool, the program is ill-formed.
This function is not visible to ordinary unqualified or qualified lookup, and can only be found by argument-dependent lookup when std::unexpected<E> is an associated class of the arguments.
swap(std::unexpected)
swap( unexpected& x, unexpected& y ) noexcept(noexcept(x.swap(y)));
Equivalent to x.swap(y).
This overload participates in overload resolution only if std::is_swappable_v <E> is true.
This function is not visible to ordinary unqualified or qualified lookup, and can only be found by argument-dependent lookup when std::unexpected<E> is an associated class of the arguments.
[edit] Deduction guides
unexpected(E) -> unexpected<E>;
The deduction guide is provided for unexpected to allow deduction from the constructor argument.
[edit] Notes
Prior to C++17, the name std::unexpected denoted the function called by the C++ runtime when a dynamic exception specification was violated.
[edit] Example
#include <expected> #include <iostream> enum class error { compile_time_error, runtime_error }; [[nodiscard]] auto unexpected_runtime_error() -> std::expected <int, error> { return std::unexpected(error::runtime_error); } int main() { std::expected <double, int> ex = std::unexpected(3); if (!ex) std::cout << "ex contains an error value\n"; if (ex == std::unexpected(3)) std::cout << "The error value is equal to 3\n"; const auto e = unexpected_runtime_error(); e.and_then([](const auto& e) -> std::expected <int, error> { std::cout << "and_then: " << int(e); // not printed return {}; }) .or_else([](const auto& e) -> std::expected <int, error> { std::cout << "or_else: " << int(e); // prints this line return {}; }); }
Output:
ex contains an error value The error value is equal to 3 or_else: 1