Namespaces
Variants
Views
Actions

std::unexpected

From cppreference.com
< cpp‎ | utility‎ | expected
 
 
Utilities library
General utilities
Date and time
Function objects
Formatting library (C++20)
(C++11)
Relational operators (deprecated in C++20)
Integer comparison functions
(C++20)(C++20)(C++20)   
(C++20)
Swap and type operations
(C++14)
(C++11)
(C++11)
(C++11)
(C++17)
Common vocabulary types
(C++11)
(C++17)
(C++17)
(C++17)
(C++11)
(C++17)
(C++23)
Elementary string conversions
(C++17)
(C++17)
 
 
Defined in header <expected>
template< class E >
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.

Contents

[edit] 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.

[edit] Member functions

(constructor)
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)
error
accesses the stored value
(public member function)
swap
swaps the stored value
(public member function)

[edit] Non-member functions

operator==
compares the stored value
(function template)
swap(std::unexpected)
(C++23)
specializes the std::swap algorithm
(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 >
constexpr explicit unexpected( Err&& e );
(3) (since C++23)
template< class... Args >
constexpr explicit unexpected( std::in_place_t, Args&&... args );
(4) (since C++23)
template< class U, class... Args >

constexpr explicit unexpected( std::in_place_t,

                               std::initializer_list<U> il, Args&&... args );
(5) (since C++23)

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

Returns a reference to the stored value.

std::unexpected::swap

constexpr void swap( unexpected& other ) noexcept(std::is_nothrow_swappable_v<E>);
(since C++23)

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

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

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.

[edit] 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.

[edit] Notes

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

[edit] Example

#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

[edit] See also

constructs the expected object
(public member function) [edit]
compares expected objects
(function template) [edit]