std:: unexpected

From cppreference.com
C++
Utilities library
General utilities
Relational operators (deprecated in C++20)
std::expected
Defined in header <expected>
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.

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

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)

Non-member functions

(C++23)
compares the stored value
(function template)
(C++23)
specializes the std::swap algorithm
(function template)

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.
3) Constructs the stored value, as if by direct-initializing a value of type E from std:: forward < Err > ( e ) .
4) Constructs the stored value, as if by direct-initializing a value of type E from the arguments std:: forward < Args > ( args ) ... .
5) Constructs the stored value, as if by direct-initializing a value of type E from the arguments il, std:: forward < Args > ( args ) ... .

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 ;
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 ) 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 > & 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
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 >
unexpected ( E ) - > unexpected < E > ;
(since C++23)

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

See also

constructs the expected object
(public member function)
(C++23)
compares expected objects
(function template)
Retrieved from " https://en.cppreference.com/mwiki/index.php?title=cpp/utility/expected/unexpected&oldid=177369 "