std::unexpected

 

C++

Compiler support

Freestanding and hosted

Language

Standard library

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Metaprogramming library (C++11)

Diagnostics library

General utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Concurrency support library (C++11)

Technical specifications

Symbols index

External libraries

 

Utilities library

Language support Type support (basic types, RTTI) Library feature-test macros (C++20) Dynamic memory management Program utilities Coroutine support (C++20) Variadic functions is_constant_evaluated (C++20) is_within_lifetime (C++26) initializer_list (C++11) source_location (C++20) Three-way comparison (C++20) three_way_comparablethree_way_comparable_with (C++20)(C++20) strong_ordering (C++20) weak_ordering (C++20) partial_ordering (C++20) common_comparison_category (C++20) compare_three_way_result (C++20) compare_three_way (C++20) strong_order (C++20) weak_order (C++20) partial_order (C++20) compare_strong_order_fallback (C++20) compare_weak_order_fallback (C++20) compare_partial_order_fallback (C++20)    is_eqis_neqis_ltis_lteqis_gtis_gteq (C++20)(C++20)(C++20)(C++20)(C++20)(C++20)

General utilities Date and time Function objects Formatting library (C++20) bitset hash (C++11) Relational operators (deprecated in C++20) rel_ops::operator!=rel_ops::operator> rel_ops::operator<=rel_ops::operator>= Integer comparison functions cmp_equalcmp_lesscmp_less_than (C++20)(C++20)(C++20)    cmp_not_equalcmp_greatercmp_greater_than (C++20)(C++20)(C++20) in_range (C++20) Swap and type operations swap ranges::swap (C++20) exchange (C++14) declval (C++11) to_underlying (C++23) forward (C++11) forward_like (C++23) move (C++11) move_if_noexcept (C++11) as_const (C++17) Common vocabulary types pair tuple (C++11) optional (C++17) any (C++17) variant (C++17) tuple_size (C++11) tuple_element (C++11) apply (C++17) make_from_tuple (C++17) expected (C++23) Elementary string conversions to_chars (C++17) from_chars (C++17) chars_format (C++17)

 

std::expected

Member functions

expected::expected (C++23)

expected::~expected (C++23)

expected::operator= (C++23)

Observers

expected::operator->expected::operator* (C++23)(C++23)

expected::operator boolexpected::has_value (C++23)(C++23)

expected::value (C++23)

expected::error (C++23)

expected::value_or (C++23)

Monadic operations

expected::and_then (C++23)

expected::or_else (C++23)

expected::transform (C++23)

expected::transform_error (C++23)

Modifiers

expected::emplace (C++23)

expected::swap (C++23)

Non-member functions

operator== (C++23)

swap (C++23)

Helper classes

unexpected (C++23)

bad_expected_access (C++23)

unexpect_tunexpect (C++23)(C++23)

 

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

(constructor) (C++23)	constructs the unexpected object (public member function)
(destructor) (implicitly declared) (C++23)	destroys the unexpected object, along with the stored value (public member function)
operator= (implicitly declared) (C++23)	assigns the stored value (public member function)
error (C++23)	accesses the stored value (public member function)
swap (C++23)	swaps the stored value (public member function)

Non-member functions

operator== (C++23)	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).

• 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; 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.

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>
 
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) (C++23)	constructs the expected object (public member function)
operator== (C++23)	compares expected objects (function template)