std::expected<T,E>::operator=

 

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)

Diagnostics library

Memory management library

Metaprogramming library (C++11)

General utilities library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Strings library

Text processing library

Numerics library

Date and time library

Input/output library

Filesystem library (C++17)

Concurrency support library (C++11)

Execution control library (C++26)

Technical specifications

Symbols index

External libraries

 

Utilities library

Language support Type support (basic types, RTTI) Library feature-test macros (C++20) Program utilities Variadic functions initializer_list (C++11) is_constant_evaluated (C++20) is_within_lifetime (C++26) source_location (C++20) Coroutine support (C++20) Contract support (C++26) Three-way comparison 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_ltis_lteq (C++20)(C++20)(C++20)   is_neqis_gtis_gteq (C++20)(C++20)(C++20)

General utilities Function objects Bit manipulation (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)

 

std::expected

Member functions

expected::expected

expected::~expected

expected::operator=

Observers

expected::operator->expected::operator*

expected::operator boolexpected::has_value

expected::value

expected::error

expected::value_or

expected::error_or

Monadic operations

expected::and_then

expected::or_else

expected::transform

expected::transform_error

Modifiers

expected::emplace

expected::swap

Non-member functions

operator==(std::expected)

swap(std::expected)

Helper classes

unexpected

bad_expected_access

unexpect_tunexpect

 

constexpr expected& operator=( const expected& other );	(1)	(since C++23)
constexpr expected& operator=( expected&& other ) noexcept(/*see below*/);	(2)	(since C++23)
template< class U = std::remove_cv_t<T> > constexpr expected& operator=( U&& v );	(3)	(since C++23) (T is not cv void)
template< class G > constexpr expected& operator=( const unexpected<G>& other );	(4)	(since C++23)
template< class G > constexpr expected& operator=( unexpected<G>&& other );	(5)	(since C++23)

Assigns a new value to an existing expected object.

1,2) Assigns the state of other.

• If this->has_value() equals other.has_value(), assigns the value contained in other. Does nothing if T is (possibly cv-qualified) void and other.has_value() is true.
• Otherwise, destroys the currently contained value (does nothing if this->has_value() is true and T is (possibly cv-qualified) void), and makes *this contain a copy of the value contained in other.

If other.has_value() is true and T is (possibly cv-qualified) void, does not construct the new value. Otherwise, the new value is copy-constructed (1) or move-constructed (2) from *other or other.error(), as appropriate. If an exception is thrown, the old value is retained; *this does not become valueless.

If no exception was thrown, after assignment, has_value() is equal to other.has_value().

• Overload (1) is defined as deleted unless
  • either T is (possibly cv-qualified) void or std::is_copy_assignable_v<T> is true, and
  • either T is (possibly cv-qualified) void or std::is_copy_constructible_v<T> is true, and
  • std::is_copy_assignable_v<E> is true, and
  • std::is_copy_constructible_v<E> is true, and
  • at least one of the following is true:
    • T is (possibly cv-qualified) void
    • std::is_nothrow_move_constructible_v<T>
    • std::is_nothrow_move_constructible_v<E>
• Overload (2) participates in overload resolution only if
  • either T is (possibly cv-qualified) void or std::is_move_assignable_v<T> is true, and
  • either T is (possibly cv-qualified) void or std::is_move_constructible_v<T> is true, and
  • std::is_move_assignable_v<E> is true, and
  • std::is_move_constructible_v<E> is true, and
  • at least one of the following is true:
    • T is (possibly cv-qualified) void
    • std::is_nothrow_move_constructible_v<T>
    • std::is_nothrow_move_constructible_v<E>

3) Assigns from expected value.

• If this->has_value() is true, equivalent to **this = std::forward<U>(v).
• Otherwise, destroys the value contained in *this, and makes *this contain a value initialized from std::forward<U>(v). If an exception is thrown, the old value is retained; *this does not become valueless.

If no exception was thrown, after assignment, this->has_value() is true.

• This overload participates in overload resolution only if
  • std::is_same_v<expected, std::remove_cvref_t<U>> is false, and
  • std::remove_cvref_t<U> is not a specialization of std::unexpected, and
  • std::is_constructible_v<T, U> is true, and
  • std::is_assignable_v<T&, U> is true, and
  • at least one of the following is true:
    • std::is_nothrow_constructible_v<T, U>
    • std::is_nothrow_move_constructible_v<T>
    • std::is_nothrow_move_constructible_v<E>

4,5) Assigns from unexpected value.

Let GF be const G& for overload (4), and G for overload (5).

• If this->has_value() is true, destroys the value contained in *this (does nothing if T is (possibly cv-qualified) void), and makes *this contain a value initialized from std::forward<GF>(e.error()). If an exception is thrown, the old value is retained; *this does not become valueless.
• Otherwise, equivalent to this->error() = std::forward<GF>(e.error()).

If no exception was thrown, after assignment, this->has_value() is false.

• This overload participates in overload resolution only if
  • std::is_constructible_v<E, GF> is true, and
  • std::is_assignable_v<E&, GF> is true, and
  • at least one of the following is true:
    • T is (possibly cv-qualified) void
    • std::is_nothrow_constructible_v<E, GF>
    • std::is_nothrow_move_constructible_v<T>
    • std::is_nothrow_move_constructible_v<E>

In all cases, if T is not (possibly cv-qualified) void, the destruction of old value and construction of new value is performed as if by the following exposition-only function reinit_expected.

template<class NewType, class OldType, class... Args>
constexpr void reinit_expected(NewType& new_val, OldType& old_val, Args&&... args)
{
    if constexpr (std::is_nothrow_constructible_v<NewType, Args...>)
    {
        std::destroy_at(std::addressof(old_val));
        std::construct_at(std::addressof(new_val), std::forward<Args>(args)...);
    }
    else if constexpr (std::is_nothrow_move_constructible_v<NewType>)
    {
        NewType temp(std::forward<Args>(args)...); // may throw
        std::destroy_at(std::addressof(old_val));
        std::construct_at(std::addressof(new_val), std::move(temp));
    }
    else
    {
        OldType temp(std::move(old_val));
        std::destroy_at(std::addressof(old_val));
        try
        {
            std::construct_at(std::addressof(new_val), std::forward<Args>(args)...); // may throw
        }
        catch (...)
        {
            std::construct_at(std::addressof(old_val), std::move(temp));
            throw;
        }
    }
}

Parameters

other	-	another expected object whose contained value to assign
value	-	value to assign to the contained value
e	-	std::unexpected object whose contained value to assign

Return value

*this

Exceptions

1) Throws any exception thrown by the copy constructor or copy assignment operator of T or E.

2) If T is (possibly cv-qualified) void,

noexcept specification:  

noexcept(std::is_nothrow_move_constructible_v<E> && std::is_nothrow_move_assignable_v<E>)

Otherwise,

noexcept specification:  

noexcept( std::is_nothrow_move_constructible_v<T> && std::is_nothrow_move_assignable_v<T> && std::is_nothrow_move_constructible_v<E> && std::is_nothrow_move_assignable_v<E>)

3) Throws any exception thrown by the constructor or assignment operator of T.

4,5) Throws any exception thrown by the constructor or assignment operator of E.

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR	Applied to	Behavior as published	Correct behavior
LWG 3886	C++23	the default template argument of overload (3) was T	changed to std::remove_cv_t<T>
LWG 4025	C++23	the move assignment (2) of std::expected<void, E> was defined as deleted if E is not move constructible or not move assignable	it does not participate in overload resolution in this case

See also

emplace

constructs the expected value in-place (public member function)