cppdraft_translate/cppdraft/expected/void.md

[expected.void]

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_vclass expected<T, E> {public:using value_type = T; using error_type = E; using unexpected_type = unexpected; templateusing rebind = expected<U, error_type>; // [expected.void.cons], constructorsconstexpr 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>&&); templateconstexpr explicit(see below) expected(const unexpected&); templateconstexpr explicit(see below) expected(unexpected&&); 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, Args&&...); // [expected.void.dtor], destructorconstexpr ~expected(); // [expected.void.assign], assignmentconstexpr expected& operator=(const expected&); constexpr expected& operator=(expected&&) noexcept(see below); templateconstexpr expected& operator=(const unexpected&); templateconstexpr expected& operator=(unexpected&&); constexpr void emplace() noexcept; // [expected.void.swap], swapconstexpr void swap(expected&) noexcept(see below); friend constexpr void swap(expected& x, expected& y) noexcept(noexcept(x.swap(y))); // [expected.void.obs], observersconstexpr explicit operator bool() const noexcept; constexpr bool has_value() const noexcept; constexpr void operator*() const noexcept; constexpr void value() const &; // freestanding-deletedconstexpr void value() &&; // freestanding-deletedconstexpr const E& error() const & noexcept; constexpr E& error() & noexcept; constexpr const E&& error() const && noexcept; constexpr E&& error() && noexcept; template constexpr E error_or(G&&) const &; template constexpr E error_or(G&&) &&; // [expected.void.monadic], monadic operationstemplate constexpr auto and_then(F&& f) &; template constexpr auto and_then(F&& f) &&; template constexpr auto and_then(F&& f) const &; template constexpr auto and_then(F&& f) const &&; template constexpr auto or_else(F&& f) &; template constexpr auto or_else(F&& f) &&; template constexpr auto or_else(F&& f) const &; template constexpr auto or_else(F&& f) const &&; template constexpr auto transform(F&& f) &; template constexpr auto transform(F&& f) &&; template constexpr auto transform(F&& f) const &; template constexpr auto transform(F&& f) const &&; template constexpr auto transform_error(F&& f) &; template constexpr auto transform_error(F&& f) &&; template constexpr auto transform_error(F&& f) const &; template constexpr auto transform_error(F&& f) const &&; // [expected.void.eq], equality operatorstemplate<class T2, class E2> requires is_void_vfriend constexpr bool operator==(const expected& x, const expected<T2, E2>& y); templatefriend constexpr bool operator==(const expected&, const unexpected&);

private:bool has_val; // exposition onlyunion { E unex; // exposition only};};

1

#

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

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

2

#

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.

3

#

E shall meet the requirements ofCpp17Destructible (Table 35).

22.8.7.2 Constructors [expected.void.cons]

🔗

constexpr expected() noexcept;

1

#

Postconditions: has_value() is true.

🔗

constexpr expected(const expected& rhs);

2

#

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

3

#

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

4

#

Throws: Any exception thrown by the initialization of unex.

5

#

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

6

#

This constructor is trivial if is_trivially_copy_constructible_v is true.

🔗

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

7

#

Constraints: is_move_constructible_v is true.

8

#

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

9

#

Postconditions: rhs.has_value() is unchanged;rhs.has_value() == this->has_value() is true.

10

#

Throws: Any exception thrown by the initialization of unex.

11

#

Remarks: This constructor is trivial if is_trivially_move_constructible_v 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);

12

#

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

13

#

Constraints:

• (13.1)

is_void_v is true; and

• (13.2)

is_constructible_v<E, GF> is true; and

• (13.3)

is_constructible_v<unexpected, expected<U, G>&> is false; and

• (13.4)

is_constructible_v<unexpected, expected<U, G>> is false; and

• (13.5)

is_constructible_v<unexpected, const expected<U, G>&> is false; and

• (13.6)

is_constructible_v<unexpected, const expected<U, G>> is false.

14

#

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

15

#

Postconditions: rhs.has_value() is unchanged;rhs.has_value() == this->has_value() is true.

16

#

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);

17

#

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

18

#

Constraints: is_constructible_v<E, GF> is true.

19

#

Effects: Direct-non-list-initializes unex with std​::​forward(e.error()).

20

#

Postconditions: has_value() is false.

21

#

Throws: Any exception thrown by the initialization of unex.

🔗

constexpr explicit expected(in_place_t) noexcept;

22

#

Postconditions: has_value() is true.

🔗

template<class... Args> constexpr explicit expected(unexpect_t, Args&&... args);

23

#

Constraints: is_constructible_v<E, Args...> is true.

24

#

Effects: Direct-non-list-initializes unex with std​::​forward(args)....

25

#

Postconditions: has_value() is false.

26

#

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);

27

#

Constraints: is_constructible_v<E, initializer_list&, Args...> is true.

28

#

Effects: Direct-non-list-initializes unex with il, std​::​forward(args)....

29

#

Postconditions: has_value() is false.

30

#

Throws: Any exception thrown by the initialization of unex.

22.8.7.3 Destructor [expected.void.dtor]

🔗

constexpr ~expected();

1

#

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

2

#

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

22.8.7.4 Assignment [expected.void.assign]

🔗

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

1

#

Effects:

• (1.1)

  If this->has_value() && rhs.has_value() is true, no effects.

• (1.2)

  Otherwise, if this->has_value() is true, equivalent to: construct_at(addressof(unex), rhs.unex); has_val = false;

• (1.3)

  Otherwise, if rhs.has_value() is true, destroys unex and sets has_val to true.

• (1.4)

  Otherwise, equivalent to unex = rhs.error().

2

#

Returns: *this.

3

#

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

🔗

constexpr expected& operator=(expected&& rhs) noexcept(see below);

4

#

Constraints: is_move_constructible_v is true andis_move_assignable_v is true.

5

#

Effects:

• (5.1)

  If this->has_value() && rhs.has_value() is true, no effects.

• (5.2)

  Otherwise, if this->has_value() is true, equivalent to:construct_at(addressof(unex), std::move(rhs.unex));has_val = false;

• (5.3)

  Otherwise, if rhs.has_value() is true, destroys unex and sets has_val to true.

• (5.4)

  Otherwise, equivalent to unex = std​::​move(rhs.error()).

6

#

Returns: *this.

7

#

Remarks: The exception specification is equivalent tois_nothrow_move_constructible_v && is_nothrow_move_assignable_v.

🔗

template<class G> constexpr expected& operator=(const unexpected<G>& e); template<class G> constexpr expected& operator=(unexpected<G>&& e);

8

#

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

9

#

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

10

#

Effects:

• (10.1)

If has_value() is true, equivalent to:construct_at(addressof(unex), std::forward(e.error()));has_val = false;

• (10.2)

Otherwise, equivalent to:unex = std​::​forward(e.error());

11

#

Returns: *this.

🔗

constexpr void emplace() noexcept;

12

#

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);

1

#

Constraints: is_swappable_v is true andis_move_constructible_v is true.

2

#

Effects: See Table 73.

Table 73 — swap(expected&) effects [tab:expected.void.swap]

🔗	this->has_value()	!this->has_value()
🔗 rhs.has_value()	no effects	calls rhs.swap(*this)
🔗 !rhs.has_value()	see below	equivalent to: using std​::​swap; swap(unex, rhs.unex);

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;

3

#

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

4

#

Remarks: The exception specification is equivalent tois_nothrow_move_constructible_v && is_nothrow_swappable_v.

🔗

friend constexpr void swap(expected& x, expected& y) noexcept(noexcept(x.swap(y)));

5

#

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;

1

#

Returns: has_val.

🔗

constexpr void operator*() const noexcept;

2

#

Hardened preconditions: has_value() is true.

🔗

constexpr void value() const &;

3

#

Mandates: is_copy_constructible_v is true.

4

#

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

🔗

constexpr void value() &&;

5

#

Mandates: is_copy_constructible_v is true andis_move_constructible_v is true.

6

#

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

🔗

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

7

#

Hardened preconditions: has_value() is false.

8

#

Returns: unex.

🔗

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

9

#

Hardened preconditions: has_value() is false.

10

#

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

🔗

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

11

#

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

12

#

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

🔗

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

13

#

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

14

#

Returns: std​::​forward(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 &;

1

#

Let U be remove_cvref_t<invoke_result_t>.

2

#

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

3

#

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

4

#

Effects: Equivalent to:if (has_value())return invoke(std::forward(f));elsereturn U(unexpect, error());

🔗

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

5

#

Let U be remove_cvref_t<invoke_result_t>.

6

#

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

7

#

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

8

#

Effects: Equivalent to:if (has_value())return invoke(std::forward(f));elsereturn U(unexpect, std::move(error()));

🔗

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

9

#

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

10

#

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

11

#

Effects: Equivalent to:if (has_value())return G();elsereturn invoke(std::forward(f), error());

🔗

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

12

#

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

13

#

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

14

#

Effects: Equivalent to:if (has_value())return G();elsereturn invoke(std::forward(f), std::move(error()));

🔗

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

15

#

Let U be remove_cv_t<invoke_result_t>.

16

#

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

17

#

Mandates: U is a valid value type for expected.

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

18

#

Effects:

• (18.1)

  If has_value() is false, returnsexpected<U, E>(unexpect, error()).

• (18.2)

  Otherwise, if is_void_v is false, returns anexpected<U, E> object whose has_val member is true andval member is direct-non-list-initialized withinvoke(std​::​forward(f)).

• (18.3)

  Otherwise, evaluates invoke(std​::​forward(f)) and then returnsexpected<U, E>().

🔗

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

19

#

Let U be remove_cv_t<invoke_result_t>.

20

#

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

21

#

Mandates: U is a valid value type for expected.

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

22

#

Effects:

• (22.1)

  If has_value() is false, returnsexpected<U, E>(unexpect, std​::​move(error())).

• (22.2)

  Otherwise, if is_void_v is false, returns anexpected<U, E> object whose has_val member is true andval member is direct-non-list-initialized withinvoke(std​::​forward(f)).

• (22.3)

  Otherwise, evaluates invoke(std​::​forward(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 &;

23

#

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

24

#

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

25

#

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

🔗

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

26

#

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

27

#

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

28

#

Returns: If has_value() is true, expected<T, G>(); otherwise, anexpected<T, G> object whose has_val member is false and unex member is direct-non-list-initialized withinvoke(std​::​forward(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);

1

#

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

2

#

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

🔗

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

3

#

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

4

#

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