std::unexpected(3)

NAME
std::unexpected - std::unexpected

Synopsis
   Defined in header <expected>
   template< class E > (since C++23)
   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.

Template parameters
   E - the type of the unexpected value. The type must not be an array type, a
       non-object type, a specialization of std::unexpected, or a cv-qualified type.

Member functions
   constructor constructs the unexpected object
   (C++23) (public member function)
   destructor destroys the unexpected object, along with the stored
   (implicitly declared) (C++23) value
                        (public member function)
   operator= assigns the stored value
   (implicitly declared) (C++23) (public member function)
   error accesses the stored value
   (C++23) (public member function)
   swap swaps the stored value
   (C++23) (public member function)

Non-member functions
   operator== compares the stored value
   (C++23) (function template)
   swap(std::unexpected) specializes the std::swap algorithm
   (C++23) (function template) std::unexpected::unexpected
   constexpr unexpected( const unexpected& ) = default; (1) (since C++23)
   constexpr unexpected( unexpected&& ) = default; (2) (since C++23)
   template< class Err = E > (3) (since C++23)
   constexpr explicit unexpected( Err&& e );
   template< class... Args > (4) (since C++23)
   constexpr explicit unexpected( std::in_place_t, Args&&... args );
   template< class U, class... Args >
   constexpr explicit unexpected( std::in_place_t, (5) (since C++23)
                        std::initializer_list<U> il,
   Args&&... args );
   Constructs a std::unexpected object.
   1,2) Copy/move constructor. Copies or moves the stored value, respectively.
   3) 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.
   4) Constructs the stored value, as if by direct-initializing a value of type E from
   the arguments std::forward<Args>(args)....
     * This overload participates in overload resolution only if
       std::is_constructible_v<E, Args...> is true.
   5) Constructs the stored value, as if by direct-initializing a value of type 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
   e - value with which to initialize the contained value
   args... - arguments with which to initialize the contained value
   il - initializer list with which to initialize the contained value

Exceptions
   Throws any exception thrown by the constructor of E. std::unexpected::error
   constexpr const E& error() const& noexcept;
   constexpr E& error() & noexcept; (since C++23)
   constexpr const E&& error() const&& noexcept;
   constexpr E&& error() && noexcept;
   Returns a reference to the stored value. std::unexpected::swap
   constexpr void swap( unexpected& other ) (since C++23)
   noexcept(std::is_nothrow_swappable_v<E>);
   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>& (since C++23)
   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 void (since C++23)
   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.
   Deduction guides
   template< class E > (since C++23)
   unexpected(E) -> unexpected<E>;
   The deduction guide is provided for unexpected to allow deduction from the
   constructor argument.

Notes
   Prior to C++17, the name std::unexpected denoted the function called by the C++
   runtime when a dynamic exception specification was violated.

Example
// Run this code
 #include <expected>
 #include <iostream>
 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";
 }

Output:
 ex contains an error value
 The error value is equal to 3
   Example with enum // Run this code
 #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()
 {
     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 {};
     });
     return 0;
 }

Output:
 or_else: 1

See also
   constructor constructs the expected object
                 (public member function)
   operator== compares expected objects
   (C++23) (function template)