std::unexpected - cppreference.com (original) (raw)

| | | | | -------------------------------------- | | ------------- | | template< class E > class unexpected; | | (since C++23) |

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

• 1 Template parameters
• 2 Member functions
• 3 Non-member functions
• 4 std::unexpected::unexpected
  • 4.1 Parameters
  • 4.2 Exceptions
• 5 std::unexpected::error
• 6 std::unexpected::swap
• 7 operator==(std::unexpected)
• 8 swap(std::unexpected)
  • 8.1 Deduction guides
  • 8.2 Notes
  • 8.3 Example
  • 8.4 See also

[edit] Template parameters

[edit] Member functions

| | constructs the unexpected object (public member function) | | | ------------------------------------------------------------ | ------------------------------------------------------------------------------------ | | (destructor)(implicitly declared) | destroys the unexpected object, along with the stored value (public member function) | | operator=(implicitly declared) | assigns the stored value (public member function) | | | accesses the stored value (public member function) | | | | swaps the stored value (public member function) | |

[edit] Non-member functions

std::unexpected::unexpected

| constexpr unexpected( const unexpected& ) = default; | (1) | | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --- | | | constexpr unexpected( unexpected&& ) = default; | (2) | | | template< class Err = E > constexpr explicit unexpected( Err&& e ); | (3) | | | template< class... Args > constexpr explicit unexpected( std::in_place_t, Args&&... args ); | (4) | | | template< class U, class... Args > constexpr explicit unexpected( std::in_place_t, std::initializer_list<U> il, Args&&... args ); | (5) | |

Constructs a std::unexpected object.

1,2) Copy/move constructor. Copies or moves the stored value, respectively.

1. Constructs the stored value, as if by direct-initializing a value of type 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.

Parameters

Exceptions

Throws any exception thrown by the constructor of E.

std::unexpected::error

| constexpr const E& error() const& noexcept; constexpr E& error() & noexcept; constexpr const E&& error() const&& noexcept; constexpr E&& error() && 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)

| template< class E2 > 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)

| friend constexpr voidswap( 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

| template< class E >unexpected(E) -> unexpected<E>; | | (since C++23) | | ------------------------------------------------------ | | ------------- |

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 #include   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

[edit] See also