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 Destructible
   E - requirements, and must be a valid template argument for std::unexpected (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 transformed 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 associated
   __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)