[expected.void] (original) (raw)

22 General utilities library [utilities]

22.8 Expected objects [expected]

22.8.7 Partial specialization of expected for void types [expected.void]

22.8.7.1 General [expected.void.general]

template<class T, class E> requires is_void_v<T> class expected<T, E> { public: using value_type = T;using error_type = E;using unexpected_type = unexpected<E>;template<class U> using rebind = expected<U, error_type>;constexpr expected() noexcept;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 G> constexpr explicit(see below) expected(const unexpected<G>&);template<class G> constexpr explicit(see below) expected(unexpected<G>&&);constexpr explicit expected(in_place_t) noexcept;template<class... Args> constexpr explicit expected(unexpect_t, Args&&...);template<class U, class... Args> constexpr explicit expected(unexpect_t, initializer_list<U>, Args&&...);constexpr ~expected();constexpr expected& operator=(const expected&);constexpr expected& operator=(expected&&) noexcept(see below);template<class G> constexpr expected& operator=(const unexpected<G>&);template<class G> constexpr expected& operator=(unexpected<G>&&);constexpr void emplace() noexcept;constexpr void swap(expected&) noexcept(see below);friend constexpr void swap(expected& x, expected& y) noexcept(noexcept(x.swap(y)));constexpr explicit operator bool() const noexcept;constexpr bool has_value() const noexcept;constexpr void operator*() const noexcept;constexpr void value() const &; constexpr void value() &&; constexpr const E& error() const & noexcept;constexpr E& error() & noexcept;constexpr const E&& error() const && noexcept;constexpr E&& error() && noexcept;template<class G = E> constexpr E error_or(G&&) const &;template<class G = E> constexpr E error_or(G&&) &&;template<class F> constexpr auto and_then(F&& f) &;template<class F> constexpr auto and_then(F&& f) &&;template<class F> constexpr auto and_then(F&& f) const &;template<class F> constexpr auto and_then(F&& f) const &&;template<class F> constexpr auto or_else(F&& f) &;template<class F> constexpr auto or_else(F&& f) &&;template<class F> constexpr auto or_else(F&& f) const &;template<class F> constexpr auto or_else(F&& f) const &&;template<class F> constexpr auto transform(F&& f) &;template<class F> constexpr auto transform(F&& f) &&;template<class F> constexpr auto transform(F&& f) const &;template<class F> constexpr auto transform(F&& f) const &&;template<class F> constexpr auto transform_error(F&& f) &;template<class F> constexpr auto transform_error(F&& f) &&;template<class F> constexpr auto transform_error(F&& f) const &;template<class F> constexpr auto transform_error(F&& f) const &&;template<class T2, class E2> requires is_void_v<T2> friend constexpr bool operator==(const expected& x, const expected<T2, E2>& y);template<class E2> friend constexpr bool operator==(const expected&, const unexpected<E2>&);private: bool has_val; union { E unex; };};

Any object of type expected<T, E> either represents a value of type T, or contains a value of type Enested within ([intro.object]) it.

Member has_val indicates whether the expected<T, E> object represents a value of type T.

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.

22.8.7.2 Constructors [expected.void.cons]

constexpr expected() noexcept;

Postconditions: has_value() is true.

constexpr expected(const expected& rhs);

Effects: If rhs.has_value() is false, direct-non-list-initializes unex with rhs.error().

Postconditions: rhs.has_value() == this->has_value().

Throws: Any exception thrown by the initialization of unex.

Remarks: This constructor is defined as deleted unless is_copy_constructible_v<E> is true.

This constructor is trivial if is_trivially_copy_constructible_v<E> is true.

constexpr expected(expected&& rhs) noexcept(is_nothrow_move_constructible_v<E>);

Constraints: is_move_constructible_v<E> is true.

Effects: If rhs.has_value() is false, 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 unex.

Remarks: This constructor is trivial if is_trivially_move_constructible_v<E> is true.

template<class U, class G> constexpr explicit(!is_convertible_v<const G&, E>) expected(const expected<U, G>& rhs);template<class U, class G> constexpr explicit(!is_convertible_v<G, E>) expected(expected<U, G>&& rhs);

Let GF be const G& for the first overload andG for the second overload.

Constraints:

• is_void_v<U> is true; and
• is_constructible_v<E, GF> is true; 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() is false, 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 unex.

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 andG for the second overload.

Constraints: is_constructible_v<E, GF> is true.

Effects: Direct-non-list-initializes _unex_with std​::​forward<GF>(e.error()).

Postconditions: has_value() is false.

Throws: Any exception thrown by the initialization of unex.

constexpr explicit expected(in_place_t) noexcept;

Postconditions: has_value() is true.

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.7.3 Destructor [expected.void.dtor]

Effects: If has_value() is false, destroys unex.

Remarks: If is_trivially_destructible_v<E> is true, then this destructor is a trivial destructor.

22.8.7.4 Assignment [expected.void.assign]

constexpr expected& operator=(const expected& rhs);

Effects:

• If this->has_value() && rhs.has_value() is true, no effects.
• Otherwise, if this->has_value() is true, equivalent to: construct_at(addressof(unex), rhs.unex); has_val = false;
• Otherwise, if rhs.has_value() is true, destroys unex and sets has_val to true.
• Otherwise, equivalent to unex = rhs.error().

Remarks: This operator is defined as deleted unlessis_copy_assignable_v<E> is true andis_copy_constructible_v<E> is true.

constexpr expected& operator=(expected&& rhs) noexcept(_see below_);

Constraints: is_move_constructible_v<E> is true andis_move_assignable_v<E> is true.

Effects:

• If this->has_value() && rhs.has_value() is true, no effects.
• Otherwise, if this->has_value() is true, equivalent to:construct_at(addressof(unex), std::move(rhs.unex));has_val = false;
• Otherwise, if rhs.has_value() is true, destroys unex and sets has_val to true.
• Otherwise, equivalent to unex = std​::​move(rhs.error()).

Remarks: The exception specification is equivalent tois_nothrow_move_constructible_v<E> && is_nothrow_move_assignable_v<E>.

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 andG for the second overload.

Constraints: is_constructible_v<E, GF> is true andis_assignable_v<E&, GF> is true.

Effects:

• If has_value() is true, equivalent to:construct_at(addressof(unex), std::forward<GF>(e.error()));has_val = false;
• Otherwise, equivalent to:unex = std​::​forward<GF>(e.error());

constexpr void emplace() noexcept;

Effects: If has_value() is false, destroys unex and sets has_val to true.

22.8.7.5 Swap [expected.void.swap]

constexpr void swap(expected& rhs) noexcept(_see below_);

Constraints: is_swappable_v<E> is true andis_move_constructible_v<E> is true.

For the case where rhs.has_value() is false andthis->has_value() is true, equivalent to:construct_at(addressof(unex), std::move(rhs.unex)); destroy_at(addressof(rhs.unex));has_val = false; rhs.has_val = true;

Throws: Any exception thrown by the expressions in the Effects.

Remarks: The exception specification is equivalent tois_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.7.6 Observers [expected.void.obs]

constexpr explicit operator bool() const noexcept;constexpr bool has_value() const noexcept;

constexpr void operator*() const noexcept;

Hardened preconditions: has_value() is true.

constexpr void value() const &;

Mandates: is_copy_constructible_v<E> is true.

Throws: bad_expected_access(error()) if has_value() is false.

constexpr void value() &&;

Mandates: is_copy_constructible_v<E> is true andis_move_constructible_v<E> is true.

Throws: bad_expected_access(std​::​move(error()))if has_value() is false.

constexpr const E& error() const & noexcept;constexpr E& error() & noexcept;

Hardened preconditions: has_value() is false.

constexpr E&& error() && noexcept;constexpr const E&& error() const && noexcept;

Hardened preconditions: has_value() is false.

Returns: std​::​move(unex).

template<class G = E> constexpr E error_or(G&& e) const &;

Mandates: is_copy_constructible_v<E> is true andis_convertible_v<G, E> is true.

Returns: std​::​forward<G>(e) if has_value() is true,error() otherwise.

template<class G = E> constexpr E error_or(G&& e) &&;

Mandates: is_move_constructible_v<E> is true andis_convertible_v<G, E> is true.

Returns: std​::​forward<G>(e) if has_value() is true,std​::​move(error()) otherwise.

22.8.7.7 Monadic operations [expected.void.monadic]

template<class F> constexpr auto and_then(F&& f) &;template<class F> constexpr auto and_then(F&& f) const &;

Let U be remove_cvref_t<invoke_result_t<F>>.

Constraints: is_constructible_v<E, decltype(error())>> is true.

Mandates: U is a specialization of expected andis_same_v<U​::​error_type, E> is true.

Effects: Equivalent to:if (has_value()) return invoke(std::forward<F>(f));else return U(unexpect, error());

template<class F> constexpr auto and_then(F&& f) &&;template<class F> constexpr auto and_then(F&& f) const &&;

Let U be remove_cvref_t<invoke_result_t<F>>.

Constraints: is_constructible_v<E, decltype(std​::​move(error()))> is true.

Mandates: U is a specialization of expected andis_same_v<U​::​error_type, E> is true.

Effects: Equivalent to:if (has_value()) return invoke(std::forward<F>(f));else return U(unexpect, std::move(error()));

template<class F> constexpr auto or_else(F&& f) &;template<class F> constexpr auto or_else(F&& f) const &;

Let G be remove_cvref_t<invoke_result_t<F, decltype(error())>>.

Mandates: G is a specialization of expected andis_same_v<G​::​value_type, T> is true.

Effects: Equivalent to:if (has_value()) return G();else return invoke(std::forward<F>(f), error());

template<class F> constexpr auto or_else(F&& f) &&;template<class F> constexpr auto or_else(F&& f) const &&;

Let G beremove_cvref_t<invoke_result_t<F, decltype(std​::​move(error()))>>.

Mandates: G is a specialization of expected andis_same_v<G​::​value_type, T> is true.

Effects: Equivalent to:if (has_value()) return G();else return invoke(std::forward<F>(f), std::move(error()));

template<class F> constexpr auto transform(F&& f) &;template<class F> constexpr auto transform(F&& f) const &;

Let U be remove_cv_t<invoke_result_t<F>>.

Constraints: is_constructible_v<E, decltype(error())> is true.

Mandates: U is a valid value type for expected.

If is_void_v<U> isfalse, the declarationU u(invoke(std::forward<F>(f)));is well-formed.

Effects:

• If has_value() is false, returnsexpected<U, E>(unexpect, error()).
• Otherwise, if is_void_v<U> is false, returns anexpected<U, E> object whose has_val member is true and_val_ member is direct-non-list-initialized withinvoke(std​::​forward<F>(f)).
• Otherwise, evaluates invoke(std​::​forward<F>(f)) and then returnsexpected<U, E>().

template<class F> constexpr auto transform(F&& f) &&;template<class F> constexpr auto transform(F&& f) const &&;

Let U be remove_cv_t<invoke_result_t<F>>.

Constraints: is_constructible_v<E, decltype(std​::​move(error()))> is true.

Mandates: U is a valid value type for expected.

If is_void_v<U> isfalse, the declarationU u(invoke(std::forward<F>(f)));is well-formed.

Effects:

• If has_value() is false, returnsexpected<U, E>(unexpect, std​::​move(error())).
• Otherwise, if is_void_v<U> is false, returns anexpected<U, E> object whose has_val member is true and_val_ member is direct-non-list-initialized withinvoke(std​::​forward<F>(f)).
• Otherwise, evaluates invoke(std​::​forward<F>(f)) and then returnsexpected<U, E>().

template<class F> constexpr auto transform_error(F&& f) &;template<class F> constexpr auto transform_error(F&& f) const &;

Let G be remove_cv_t<invoke_result_t<F, decltype(error())>>.

Mandates: G is a valid template argument for unexpected ([expected.un.general]) and the declarationG g(invoke(std::forward<F>(f), error()));is well-formed.

Returns: If has_value() is true, expected<T, G>(); otherwise, anexpected<T, G> object whose has_val member is falseand unex member is direct-non-list-initialized withinvoke(std​::​forward<F>(f), error()).

template<class F> constexpr auto transform_error(F&& f) &&;template<class F> constexpr auto transform_error(F&& f) const &&;

Let G beremove_cv_t<invoke_result_t<F, decltype(std​::​move(error()))>>.

Mandates: G is a valid template argument for unexpected ([expected.un.general]) and the declarationG g(invoke(std::forward<F>(f), std::move(error())));is well-formed.

Returns: If has_value() is true, expected<T, G>(); otherwise, anexpected<T, G> object whose has_val member is falseand unex member is direct-non-list-initialized withinvoke(std​::​forward<F>(f), std​::​move(error())).

22.8.7.8 Equality operators [expected.void.eq]

template<class T2, class E2> requires is_void_v<T2> friend constexpr bool operator==(const expected& x, const expected<T2, E2>& y);

Constraints: The expression x.error() == y.error() is well-formed and its result is convertible to bool.

Returns: If x.has_value() does not equal y.has_value(), false; otherwise x.has_value() || static_cast<bool>(x.error() == y.error()).

template<class E2> friend constexpr bool operator==(const expected& x, const unexpected<E2>& e);

Constraints: The expression x.error() == e.error() is well-formed and its result is convertible to bool.

Returns: !x.has_value() && static_cast<bool>(x.error() == e.error()).