home | help 
std::unexpected(3)	       C++ Standard Libary	      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 un-
     expected
	value.

	A program is ill-formed if it instantiates an unexpected with a  non-ob-
     ject 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-quali-
     fied 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, respec-
     tively.
	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_swap-
     pable_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)

http://cppreference.com 	   2024.06.10		      std::unexpected(3)
home | help