22 General utilities library [utilities]

22.8 Expected objects [expected]

22.8.6 Class template expected [expected.expected]

22.8.6.1 General [expected.object.general]

namespace std { template<class T, class E> class expected { public: using value_type = T; using error_type = E; using unexpected_type = unexpected<E>; template<class U> using rebind = expected<U, error_type>; // [expected.object.ctor], constructors constexpr expected(); constexpr expected(const expected&); constexpr expected(expected&&) noexcept(see below); template<class U, class G> constexpr explicit(see below) expected(const expected<U, G>&); template<class U, class G> constexpr explicit(see below) expected(expected<U, G>&&); template<class U = T> constexpr explicit(see below) expected(U&& v); template<class G> constexpr expected(const unexpected<G>&); template<class G> constexpr expected(unexpected<G>&&); template<class... Args> constexpr explicit expected(in_place_t, Args&&...); template<class U, class... Args> constexpr explicit expected(in_place_t, initializer_list<U>, Args&&...); template<class... Args> constexpr explicit expected(unexpect_t, Args&&...); template<class U, class... Args> constexpr explicit expected(unexpect_t, initializer_list<U>, Args&&...); // [expected.object.dtor], destructor constexpr ~expected(); // [expected.object.assign], assignment constexpr expected& operator=(const expected&); constexpr expected& operator=(expected&&) noexcept(see below); template<class U = T> constexpr expected& operator=(U&&); template<class G> constexpr expected& operator=(const unexpected<G>&); template<class G> constexpr expected& operator=(unexpected<G>&&); template<class... Args> constexpr T& emplace(Args&&...) noexcept; template<class U, class... Args> constexpr T& emplace(initializer_list<U>, Args&&...) noexcept; // [expected.object.swap], swap constexpr void swap(expected&) noexcept(see below); friend constexpr void swap(expected& x, expected& y) noexcept(noexcept(x.swap(y))); // [expected.object.obs], observers constexpr const T* operator->() const noexcept; constexpr T* operator->() noexcept; constexpr const T& operator*() const & noexcept; constexpr T& operator*() & noexcept; constexpr const T&& operator*() const && noexcept; constexpr T&& operator*() && noexcept; constexpr explicit operator bool() const noexcept; constexpr bool has_value() const noexcept; constexpr const T& value() const &; constexpr T& value() &; constexpr const T&& value() const &&; constexpr T&& value() &&; constexpr const E& error() const & noexcept; constexpr E& error() & noexcept; constexpr const E&& error() const && noexcept; constexpr E&& error() && noexcept; template<class U> constexpr T value_or(U&&) const &; template<class U> constexpr T value_or(U&&) &&; // [expected.object.eq], equality operators template<class T2, class E2> requires (!is_void_v<T2>) friend constexpr bool operator==(const expected& x, const expected<T2, E2>& y); template<class T2> friend constexpr bool operator==(const expected&, const T2&); template<class E2> friend constexpr bool operator==(const expected&, const unexpected<E2>&); private: bool has_val; // exposition only union { T val; // exposition only E unex; // exposition only }; }; }
Any object of type expected<T, E> either contains a value of type T or a value of type E within its own storage.
Implementations are not permitted to use additional storage, such as dynamic memory, to allocate the object of type T or the object of type E.
These objects are allocated in a region of the expected<T, E> storage suitably aligned for the types T and E.
Members has_­val, val, and unex are provided for exposition only.
has_­val indicates whether the expected<T, E> object contains an object of type T.
A program that instantiates the definition of template expected<T, E> for a reference type, a function type, or for possibly cv-qualified types in_­place_­t, unexpect_­t, or a specialization of unexpected for the T parameter is ill-formed.
A program that instantiates the definition of the template expected<T, E> with a type for the E parameter that is not a valid template argument for unexpected is ill-formed.
When T is not cv void, it shall meet the Cpp17Destructible requirements (Table 36).
E shall meet the Cpp17Destructible requirements.

22.8.6.2 Constructors [expected.object.ctor]

constexpr expected();
Constraints: is_­default_­constructible_­v<T> is true.
Effects: Value-initializes val.
Postconditions: has_­value() is true.
Throws: Any exception thrown by the initialization of val.
constexpr expected(const expected& rhs);
Effects: If rhs.has_­value() is true, direct-non-list-initializes val with *rhs.
Otherwise, direct-non-list-initializes unex with rhs.error().
Postconditions: rhs.has_­value() == this->has_­value().
Throws: Any exception thrown by the initialization of val or unex.
Remarks: This constructor is defined as deleted unless
  • is_­copy_­constructible_­v<T> is true and
  • is_­copy_­constructible_­v<E> is true.
This constructor is trivial if
  • is_­trivially_­copy_­constructible_­v<T> is true and
  • is_­trivially_­copy_­constructible_­v<E> is true.
constexpr expected(expected&& rhs) noexcept(see below);
Constraints:
  • is_­move_­constructible_­v<T> is true and
  • is_­move_­constructible_­v<E> is true.
Effects: If rhs.has_­value() is true, direct-non-list-initializes val with std​::​move(*rhs).
Otherwise, direct-non-list-initializes unex with std​::​move(rhs.error()).
Postconditions: rhs.has_­value() is unchanged; rhs.has_­value() == this->has_­value() is true.
Throws: Any exception thrown by the initialization of val or unex.
Remarks: The exception specification is equivalent to is_­nothrow_­move_­constructible_­v<T> && is_­nothrow_­move_­constructible_­v<E>.
This constructor is trivial if
  • is_­trivially_­move_­constructible_­v<T> is true and
  • is_­trivially_­move_­constructible_­v<E> is true.
template<class U, class G> constexpr explicit(see below) expected(const expected<U, G>& rhs); template<class U, class G> constexpr explicit(see below) expected(expected<U, G>&& rhs);
Let:
  • UF be const U& for the first overload and U for the second overload.
  • GF be const G& for the first overload and G for the second overload.
Constraints:
  • is_­constructible_­v<T, UF> is true; and
  • is_­constructible_­v<E, GF> is true; and
  • is_­constructible_­v<T, expected<U, G>&> is false; and
  • is_­constructible_­v<T, expected<U, G>> is false; and
  • is_­constructible_­v<T, const expected<U, G>&> is false; and
  • is_­constructible_­v<T, const expected<U, G>> is false; and
  • is_­convertible_­v<expected<U, G>&, T> is false; and
  • is_­convertible_­v<expected<U, G>&&, T> is false; and
  • is_­convertible_­v<const expected<U, G>&, T> is false; and
  • is_­convertible_­v<const expected<U, G>&&, T> is false; and
  • is_­constructible_­v<unexpected<E>, expected<U, G>&> is false; and
  • is_­constructible_­v<unexpected<E>, expected<U, G>> is false; and
  • is_­constructible_­v<unexpected<E>, const expected<U, G>&> is false; and
  • is_­constructible_­v<unexpected<E>, const expected<U, G>> is false.
Effects: If rhs.has_­value(), direct-non-list-initializes val with std​::​forward<UF>(*rhs).
Otherwise, direct-non-list-initializes unex with std​::​forward<GF>(rhs.error()).
Postconditions: rhs.has_­value() is unchanged; rhs.has_­value() == this->has_­value() is true.
Throws: Any exception thrown by the initialization of val or unex.
Remarks: The expression inside explicit is equivalent to !is_­convertible_­v<UF, T> || !is_­convertible_­v<GF, E>.
template<class U = T> constexpr explicit(!is_convertible_v<U, T>) expected(U&& v);
Constraints:
  • is_­same_­v<remove_­cvref_­t<U>, in_­place_­t> is false; and
  • is_­same_­v<expected, remove_­cvref_­t<U>> is false; and
  • remove_­cvref_­t<U> is not a specialization of unexpected; and
  • is_­constructible_­v<T, U> is true.
Effects: Direct-non-list-initializes val with std​::​forward<U>(v).
Postconditions: has_­value() is true.
Throws: Any exception thrown by the initialization of val.
template<class G> constexpr explicit(!is_convertible_v<const G&, E>) expected(const unexpected<G>& e); template<class G> constexpr explicit(!is_convertible_v<G, E>) expected(unexpected<G>&& e);
Let GF be const G& for the first overload and G for the second overload.
Constraints: is_­constructible_­v<E, GF> is true.
Effects: Direct-non-list-initializes unex with std​::​forward<GF>(e.value()).
Postconditions: has_­value() is false.
Throws: Any exception thrown by the initialization of unex.
template<class... Args> constexpr explicit expected(in_place_t, Args&&... args);
Constraints: is_­constructible_­v<T, Args...> is true.
Effects: Direct-non-list-initializes val with std​::​forward<Args>(args)....
Postconditions: has_­value() is true.
Throws: Any exception thrown by the initialization of val.
template<class U, class... Args> constexpr explicit expected(in_place_t, initializer_list<U> il, Args&&... args);
Constraints: is_­constructible_­v<T, initializer_­list<U>&, Args...> is true.
Effects: Direct-non-list-initializes val with il, std​::​forward<Args>(args)....
Postconditions: has_­value() is true.
Throws: Any exception thrown by the initialization of val.
template<class... Args> constexpr explicit expected(unexpect_t, Args&&... args);
Constraints: is_­constructible_­v<E, Args...> is true.
Effects: Direct-non-list-initializes unex with std​::​forward<Args>(args)....
Postconditions: has_­value() is false.
Throws: Any exception thrown by the initialization of unex.
template<class U, class... Args> constexpr explicit expected(unexpect_t, initializer_list<U> il, Args&&... args);
Constraints: is_­constructible_­v<E, initializer_­list<U>&, Args...> is true.
Effects: Direct-non-list-initializes unex with il, std​::​forward<Args>(args)....
Postconditions: has_­value() is false.
Throws: Any exception thrown by the initialization of unex.

22.8.6.3 Destructor [expected.object.dtor]

constexpr ~expected();
Effects: If has_­value() is true, destroys val, otherwise destroys unex.
Remarks: If is_­trivially_­destructible_­v<T> is true, and is_­trivially_­destructible_­v<E> is true, then this destructor is a trivial destructor.

22.8.6.4 Assignment [expected.object.assign]

This subclause makes use of the following exposition-only function: template<class T, class U, class... Args> constexpr void reinit-expected(T& newval, U& oldval, Args&&... args) { // exposition only if constexpr (is_nothrow_constructible_v<T, Args...>) { destroy_at(addressof(oldval)); construct_at(addressof(newval), std::forward<Args>(args)...); } else if constexpr (is_nothrow_move_constructible_v<T>) { T tmp(std::forward<Args>(args)...); destroy_at(addressof(oldval)); construct_at(addressof(newval), std::move(tmp)); } else { U tmp(std::move(oldval)); destroy_at(addressof(oldval)); try { construct_at(addressof(newval), std::forward<Args>(args)...); } catch (...) { construct_at(addressof(oldval), std::move(tmp)); throw; } } }
constexpr expected& operator=(const expected& rhs);
Effects:
  • If this->has_­value() && rhs.has_­value() is true, equivalent to val = *rhs.
  • Otherwise, if this->has_­value() is true, equivalent to: reinit-expected(unex, val, rhs.error())
  • Otherwise, if rhs.has_­value() is true, equivalent to: reinit-expected(val, unex, *rhs)
  • Otherwise, equivalent to unex = rhs.error().
Then, if no exception was thrown, equivalent to: has_­val = rhs.has_­value(); return *this;
Remarks: This operator is defined as deleted unless:
  • is_­copy_­assignable_­v<T> is true and
  • is_­copy_­constructible_­v<T> is true and
  • is_­copy_­assignable_­v<E> is true and
  • is_­copy_­constructible_­v<E> is true and
  • is_­nothrow_­move_­constructible_­v<T> || is_­nothrow_­move_­constructible_­v<E> is true.
constexpr expected& operator=(expected&& rhs) noexcept(see below);
Constraints:
  • is_­move_­constructible_­v<T> is true and
  • is_­move_­assignable_­v<T> is true and
  • is_­move_­constructible_­v<E> is true and
  • is_­move_­assignable_­v<E> is true and
  • is_­nothrow_­move_­constructible_­v<T> || is_­nothrow_­move_­constructible_­v<E> is true.
Effects:
  • If this->has_­value() && rhs.has_­value() is true, equivalent to val = std​::​move(*rhs).
  • Otherwise, if this->has_­value() is true, equivalent to: reinit-expected(unex, val, std::move(rhs.error()))
  • Otherwise, if rhs.has_­value() is true, equivalent to: reinit-expected(val, unex, std::move(*rhs))
  • Otherwise, equivalent to unex = std​::​move(rhs.error()).
Then, if no exception was thrown, equivalent to: has_­val = rhs.has_­value(); return *this;
Remarks: The exception specification is equivalent to: is_nothrow_move_assignable_v<T> && is_nothrow_move_constructible_v<T> && is_nothrow_move_assignable_v<E> && is_nothrow_move_constructible_v<E>
template<class U = T> constexpr expected& operator=(U&& v);
Constraints:
  • is_­same_­v<expected, remove_­cvref_­t<U>> is false; and
  • remove_­cvref_­t<U> is not a specialization of unexpected; and
  • is_­constructible_­v<T, U> is true; and
  • is_­assignable_­v<T&, U> is true; and
  • is_­nothrow_­constructible_­v<T, U> || is_­nothrow_­move_­constructible_­v<T> ||
    is_­nothrow_­move_­constructible_­v<E>
    is true.
Effects:
  • If has_­value() is true, equivalent to: val = std​::​forward<U>(v);
  • Otherwise, equivalent to: reinit-expected(val, unex, std::forward<U>(v)); has_val = true;
Returns: *this.
template<class G> constexpr expected& operator=(const unexpected<G>& e); template<class G> constexpr expected& operator=(unexpected<G>&& e);
Let GF be const G& for the first overload and G for the second overload.
Constraints:
  • is_­constructible_­v<E, GF> is true; and
  • is_­assignable_­v<E&, GF> is true; and
  • is_­nothrow_­constructible_­v<E, GF> || is_­nothrow_­move_­constructible_­v<T> ||
    is_­nothrow_­move_­constructible_­v<E>
    is true.
Effects:
  • If has_­value() is true, equivalent to: reinit-expected(unex, val, std::forward<GF>(e.value())); has_val = false;
  • Otherwise, equivalent to: unex = std​::​forward<GF>(e.value());
Returns: *this.
template<class... Args> constexpr T& emplace(Args&&... args) noexcept;
Constraints: is_­nothrow_­constructible_­v<T, Args...> is true.
Effects: Equivalent to: if (has_value()) { destroy_at(addressof(val)); } else { destroy_at(addressof(unex)); has_val = true; } return *construct_at(addressof(val), std::forward<Args>(args)...);
template<class U, class... Args> constexpr T& emplace(initializer_list<U> il, Args&&... args) noexcept;
Constraints: is_­nothrow_­constructible_­v<T, initializer_­list<U>&, Args...> is true.
Effects: Equivalent to: if (has_value()) { destroy_at(addressof(val)); } else { destroy_at(addressof(unex)); has_val = true; } return *construct_at(addressof(val), il, std::forward<Args>(args)...);

22.8.6.5 Swap [expected.object.swap]

constexpr void swap(expected& rhs) noexcept(see below);
Constraints:
  • is_­swappable_­v<T> is true and
  • is_­swappable_­v<E> is true and
  • is_­move_­constructible_­v<T> && is_­move_­constructible_­v<E> is true, and
  • is_­nothrow_­move_­constructible_­v<T> || is_­nothrow_­move_­constructible_­v<E> is true.
Effects: See Table 64.
Table 64: swap(expected&) effects [tab:expected.object.swap]
this->has_­value()
!this->has_­value()
rhs.has_­value()
equivalent to: using std​::​swap; swap(val, rhs.val);
calls rhs.swap(*this)
!rhs.has_­value()
see below
equivalent to: using std​::​swap; swap(unex, rhs.unex);
For the case where rhs.value() is false and this->has_­value() is true, equivalent to: if constexpr (is_nothrow_move_constructible_v<E>) { E tmp(std::move(rhs.unex)); destroy_at(addressof(rhs.unex)); try { construct_at(addressof(rhs.val), std::move(val)); destroy_at(addressof(val)); construct_at(addressof(unex), std::move(tmp)); } catch(...) { construct_at(addressof(rhs.unex), std::move(tmp)); throw; } } else { T tmp(std::move(val)); destroy_at(addressof(val)); try { construct_at(addressof(unex), std::move(rhs.unex)); destroy_at(addressof(rhs.unex)); construct_at(addressof(rhs.val), std::move(tmp)); } catch (...) { construct_at(addressof(val), std::move(tmp)); throw; } } has_val = false; rhs.has_val = true;
Throws: Any exception thrown by the expressions in the Effects.
Remarks: The exception specification is equivalent to: is_nothrow_move_constructible_v<T> && is_nothrow_swappable_v<T> && is_nothrow_move_constructible_v<E> && is_nothrow_swappable_v<E>
friend constexpr void swap(expected& x, expected& y) noexcept(noexcept(x.swap(y)));
Effects: Equivalent to x.swap(y).

22.8.6.6 Observers [expected.object.obs]

constexpr const T* operator->() const noexcept; constexpr T* operator->() noexcept;
Preconditions: has_­value() is true.
Returns: addressof(val).
constexpr const T& operator*() const & noexcept; constexpr T& operator*() & noexcept;
Preconditions: has_­value() is true.
Returns: val.
constexpr T&& operator*() && noexcept; constexpr const T&& operator*() const && noexcept;
Preconditions: has_­value() is true.
Returns: std​::​move(val).
constexpr explicit operator bool() const noexcept; constexpr bool has_value() const noexcept;
Returns: has_­val.
constexpr const T& value() const &; constexpr T& value() &;
Returns: val, if has_­value() is true.
Throws: bad_­expected_­access(error()) if has_­value() is false.
constexpr T&& value() &&; constexpr const T&& value() const &&;
Returns: std​::​move(val), if has_­value() is true.
Throws: bad_­expected_­access(std​::​move(error())) if has_­value() is false.
constexpr const E& error() const & noexcept; constexpr E& error() & noexcept;
Preconditions: has_­value() is false.
Returns: unex.
constexpr E&& error() && noexcept; constexpr const E&& error() const && noexcept;
Preconditions: has_­value() is false.
Returns: std​::​move(unex).
template<class U> constexpr T value_or(U&& v) const &;
Mandates: is_­copy_­constructible_­v<T> is true and is_­convertible_­v<U, T> is true.
Returns: has_­value() ? **this : static_­cast<T>(std​::​forward<U>(v)).
template<class U> constexpr T value_or(U&& v) &&;
Mandates: is_­move_­constructible_­v<T> is true and is_­convertible_­v<U, T> is true.
Returns: has_­value() ? std​::​move(**this) : static_­cast<T>(std​::​forward<U>(v)).

22.8.6.7 Equality operators [expected.object.eq]

template<class T2, class E2> requires (!is_void_v<T2>) friend constexpr bool operator==(const expected& x, const expected<T2, E2>& y);
Mandates: The expressions *x == *y and x.error() == y.error() are well-formed and their results are convertible to bool.
Returns: If x.has_­value() does not equal y.has_­value(), false; otherwise if x.has_­value() is true, *x == *y; otherwise x.error() == y.error().
template<class T2> friend constexpr bool operator==(const expected& x, const T2& v);
Mandates: The expression *x == v is well-formed and its result is convertible to bool.
[Note 1:
T1 need not be Cpp17EqualityComparable.
— end note]
Returns: x.has_­value() && static_­cast<bool>(*x == v).
template<class E2> friend constexpr bool operator==(const expected& x, const unexpected<E2>& e);
Mandates: The expression x.error() == e.value() is well-formed and its result is convertible to bool.
Returns: !x.has_­value() && static_­cast<bool>(x.error() == e.value()).