home | help 
std::expected(3)	       C++ Standard Libary		std::expected(3)

NAME
     std::expected - std::expected

Synopsis
	Defined in header <expected>
	template< class T, class E >  (since C++23)
	class expected;

	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.

Template parameters
	    the  type  of  the expected value. The type must either be (possibly
     cv-qualified)
	T - void, or meet the Destructible requirements  (in  particular,  array
     and reference
	    types are not allowed).
	    the  type  of  the unexpected value. The type must meet the Destruc-
     tible
	E - requirements, and must be a valid template argument  for  std::unex-
     pected (in
	    particular, arrays, non-object types, and cv-qualified types are not
     allowed).

Member types
	Member type	Definition
	value_type	T
	error_type	E
	unexpected_type std::unexpected<E>

Member alias templates
	Type	  Definition
	rebind<U> expected<U, error_type>

Member functions
	constructor	constructs the expected object
			(public member function)
	destructor	 destroys  the expected object, along with its contained
     value
			(public member function)
	operator=	assigns contents
			(public member function)

Observers
	operator->	accesses the expected value
	operator*	(public member function)
	operator bool	checks whether the object contains an expected value
	has_value	(public member function)
	value		returns the expected value
			(public member function)
	error		returns the unexpected value
			(public member function)
	value_or	returns the expected value  if	present,  another  value
     otherwise
			(public member function)
	      Monadic operations
			returns the result of the given function on the expected
     value if it
	and_then	exists; otherwise, returns the expected itself
			(public member function)
			returns  an expected containing the transformed expected
     value if it
	transform	exists; otherwise, returns the expected itself
			(public member function)
			returns the expected itself if it contains  an	expected
     value;
	or_else 	 otherwise,  returns the result of the given function on
     the
			unexpected value
			(public member function)
			returns the expected itself if it contains  an	expected
     value;
	transform_error  otherwise,  returns  an  expected containing the trans-
     formed unexpected
			value
			(public member function)

Modifiers
	emplace 	constructs the expected value in-place
			(public member function)
	swap		exchanges the contents
			(public member function)

Non-member functions
	operator==	    compares expected objects
	(C++23) 	    (function template)
	swap(std::expected) specializes the std::swap algorithm
	(C++23) 	    (function)

Helper classes
	unexpected	    represented as an unexpected value
	(C++23) 	    (class template)
	bad_expected_access exception indicating checked access to  an	expected
     that contains
	(C++23) 	    an unexpected value
			    (class template)
	unexpect	     in-place  construction  tag for unexpected value in
     expected
	unexpect_t	    (tag)
	(C++23)

Notes
	Types with the same functionality are called Result in Rust  and  Either
     in Haskell.

	Feature-test macro  Value    Std			Feature
			   202202L  (C++23) class template std::expected and as-
     sociated
	__cpp_lib_expected		   helper classes
			   202211L (C++23) Monadic functions for std::expected

Example
     // Run this code

      #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

References
	  * C++23 standard (ISO/IEC 14882:2023):

	  * 22.8 Expected objects [expected]

See also
	variant  a type-safe discriminated union
	(C++17)  (class template)
	optional a wrapper that may or may not hold an object
	(C++17)  (class template)

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