22 General utilities library [utilities]

22.5 Optional objects [optional]

22.5.4 Partial specialization of optional for reference types [optional.optional.ref]

22.5.4.1 General [optional.optional.ref.general]

22.5.4.2 Constructors [optional.ref.ctor]

22.5.4.3 Assignment [optional.ref.assign]

22.5.4.4 Swap [optional.ref.swap]

22.5.4.5 Iterator support [optional.ref.iterators]

22.5.4.6 Observers [optional.ref.observe]

22.5.4.7 Monadic operations [optional.ref.monadic]

22.5.4.8 Modifiers [optional.ref.mod]

22.5.4.9 Exposition only helper functions [optional.ref.expos]

22.5.4.1 General [optional.optional.ref.general]

namespace std { template<class T> class optional<T&> { public: using value_type = T; using iterator = implementation-defined; // present only if T is an object type other than an array // of unknown bound; see [optional.ref.iterators] public: // [optional.ref.ctor], constructors constexpr optional() noexcept = default; constexpr optional(nullopt_t) noexcept : optional() {} constexpr optional(const optional& rhs) noexcept = default; template<class Arg> constexpr explicit optional(in_place_t, Arg&& arg); template<class U> constexpr explicit(see below) optional(U&& u) noexcept(see below); template<class U> constexpr explicit(see below) optional(optional& rhs) noexcept(see below); template<class U> constexpr explicit(see below) optional(const optional& rhs) noexcept(see below); template<class U> constexpr explicit(see below) optional(optional&& rhs) noexcept(see below); template<class U> constexpr explicit(see below) optional(const optional&& rhs) noexcept(see below); constexpr ~optional() = default; // [optional.ref.assign], assignment constexpr optional& operator=(nullopt_t) noexcept; constexpr optional& operator=(const optional& rhs) noexcept = default; template<class U> constexpr T& emplace(U&& u) noexcept(see below); // [optional.ref.swap], swap constexpr void swap(optional& rhs) noexcept; // [optional.ref.iterators], iterator support constexpr auto begin() const noexcept; constexpr auto end() const noexcept; // [optional.ref.observe], observers constexpr T* operator->() const noexcept; constexpr T& operator*() const noexcept; constexpr explicit operator bool() const noexcept; constexpr bool has_value() const noexcept; constexpr T& value() const; // freestanding-deleted template<class U = remove_cv_t<T>> constexpr remove_cv_t<T> value_or(U&& u) const; // [optional.ref.monadic], monadic operations template<class F> constexpr auto and_then(F&& f) const; template<class F> constexpr optional<invoke_result_t<F, T&>> transform(F&& f) const; template<class F> constexpr optional or_else(F&& f) const; // [optional.ref.mod], modifiers constexpr void reset() noexcept; private: T* val = nullptr; // exposition only // [optional.ref.expos], exposition only helper functions template<class U> constexpr void convert-ref-init-val(U&& u); // exposition only }; }

An object of type optional<T&> contains a value if and only if val != nullptr is true.

When an optional<T&> contains a value, the contained value is a reference to *val.

Each type optional<T&> is a trivially copyable class ([class.prop]).

22.5.4.2 Constructors [optional.ref.ctor]

🔗

template<class Arg>
constexpr explicit optional(in_place_t, Arg&& arg);

Constraints:

(1.1)
is_constructible_v<T&, Arg> is true, and
(1.2)
reference_constructs_from_temporary_v<T&, Arg> is false.

Effects: Equivalent to: convert-ref-init-val(std::forward<Arg>(arg)).

Postconditions: *this contains a value.

🔗

template<class U>
constexpr explicit(!is_convertible_v<U, T&>)
  optional(U&& u) noexcept(is_nothrow_constructible_v<T&, U>);

Constraints:

(4.1)
is_same_v<remove_cvref_t, optional> is false,
(4.2)
is_same_v<remove_cvref_t, in_place_t> is false, and
(4.3)
is_constructible_v<T&, U> is true.

Effects: Equivalent to: convert-ref-init-val(std::forward(u)).

Postconditions: *this contains a value.

Remarks: This constructor is defined as deleted if reference_constructs_from_temporary_v<T&, U> is true.

🔗

template<class U>
constexpr explicit(!is_convertible_v<U&, T&>)
  optional(optional<U>& rhs) noexcept(is_nothrow_constructible_v<T&, U&>);

Constraints:

(8.1)
is_same_v<remove_cv_t<T>, optional> is false,
(8.2)
is_same_v<T&, U> is false, and
(8.3)
is_constructible_v<T&, U&> is true.

Effects: Equivalent to: if (rhs.has_value()) convert-ref-init-val(rhs.operator*());

Remarks: This constructor is defined as deleted if reference_constructs_from_temporary_v<T&, U&> is true.

🔗

template<class U>
constexpr explicit(!is_convertible_v<const U&, T&>)
  optional(const optional<U>& rhs) noexcept(is_nothrow_constructible_v<T&, const U&>);

Constraints:

(11.1)
is_same_v<remove_cv_t<T>, optional> is false,
(11.2)
is_same_v<T&, U> is false, and
(11.3)
is_constructible_v<T&, const U&> is true.

Effects: Equivalent to: if (rhs.has_value()) convert-ref-init-val(rhs.operator*());

Remarks: This constructor is defined as deleted if reference_constructs_from_temporary_v<T&, const U&> is true.

🔗

template<class U>
constexpr explicit(!is_convertible_v<U, T&>)
  optional(optional<U>&& rhs) noexcept(is_nothrow_constructible_v<T&, U>);

Constraints:

(14.1)
is_same_v<remove_cv_t<T>, optional> is false,
(14.2)
is_same_v<T&, U> is false, and
(14.3)
is_constructible_v<T&, U> is true.

Effects: Equivalent to: if (rhs.has_value()) convert-ref-init-val(std::move(rhs).operator*());

Remarks: This constructor is defined as deleted if reference_constructs_from_temporary_v<T&, U> is true.

🔗

template<class U>
constexpr explicit(!is_convertible_v<const U, T&>)
  optional(const optional<U>&& rhs) noexcept(is_nothrow_constructible_v<T&, const U>);

Constraints:

(17.1)
is_same_v<remove_cv_t<T>, optional> is false,
(17.2)
is_same_v<T&, U> is false, and
(17.3)
is_constructible_v<T&, const U> is true.

Effects: Equivalent to: if (rhs.has_value()) convert-ref-init-val(std::move(rhs).operator*());

Remarks: This constructor is defined as deleted if reference_constructs_from_temporary_v<T&, const U> is true.

22.5.4.3 Assignment [optional.ref.assign]

🔗

constexpr optional& operator=(nullopt_t) noexcept;

Effects: Assigns nullptr to val.

Postconditions: *this does not contain a value.

Returns: *this.

🔗

template<class U>
constexpr T& emplace(U&& u) noexcept(is_nothrow_constructible_v<T&, U>);

Constraints:

(4.1)
is_constructible_v<T&, U> is true, and
(4.2)
reference_constructs_from_temporary_v<T&, U> is false.

Effects: Equivalent to: convert-ref-init-val(std::forward(u)).

Returns: *val.

22.5.4.4 Swap [optional.ref.swap]

🔗

constexpr void swap(optional& rhs) noexcept;

Effects: Equivalent to: std::swap(val, rhs.val).

22.5.4.5 Iterator support [optional.ref.iterators]

🔗

using iterator = implementation-defined;        // present only if T is an object type other than an array
// of unknown bound

This type models contiguous_iterator ([iterator.concept.contiguous]), meets the Cpp17RandomAccessIterator requirements ([random.access.iterators]), and meets the requirements for constexpr iterators ([iterator.requirements.general]), with value type remove_cv_t<T>.

The reference type is T& for iterator.

All requirements on container iterators ([container.reqmts]) apply to optional::iterator.

🔗

constexpr auto begin() const noexcept;

Constraints: T is an object type other than an array of unknown bound.

Returns: An object i of type iterator, such that i is an iterator referring to *val if has_value() is true, and a past-the-end iterator value otherwise.

🔗

constexpr auto end() const noexcept;

Constraints: T is an object type other than an array of unknown bound.

Returns: begin() + has_value().

22.5.4.6 Observers [optional.ref.observe]

🔗

constexpr T* operator->() const noexcept;

Hardened preconditions: has_value() is true.

Returns: val.

🔗

constexpr T& operator*() const noexcept;

Hardened preconditions: has_value() is true.

Returns: *val.

🔗

constexpr explicit operator bool() const noexcept;

Returns: val != nullptr.

🔗

constexpr bool has_value() const noexcept;

Returns: val != nullptr.

🔗

constexpr T& value() const;

Effects: Equivalent to: return has_value() ? *val : throw bad_optional_access();

🔗

template<class U = remove_cv_t<T>> constexpr remove_cv_t<T> value_or(U&& u) const;

Constraints: T is a non-array object type.

Let X be remove_cv_t<T>.

Mandates: is_constructible_v<X, T&> && is_convertible_v<U, X> is true.

Effects: Equivalent to: return has_value() ? *val : static_cast<X>(std::forward(u));

Remarks: The return type is unspecified if T is an array type or a non-object type.

[Note 1:

This is to avoid the declaration being ill-formed.

— end note]

22.5.4.7 Monadic operations [optional.ref.monadic]

🔗

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

Let U be invoke_result_t<F, T&>.

Mandates: remove_cvref_t is a specialization of optional.

Effects: Equivalent to: if (has_value()) { return invoke(std::forward<F>(f), *val); } else { return remove_cvref_t(); }

🔗

template<class F>
constexpr optional<remove_cv_t<invoke_result_t<F, T&>>> transform(F&& f) const;

Let U be remove_cv_t<invoke_result_t<F, T&>>.

Mandates: U is a valid contained type for optional.

The declaration U u(invoke(std::forward<F>(f), *val)); is well-formed for some invented variable u.

[Note 1:

There is no requirement that U is movable ([dcl.init.general]).

— end note]

Returns: If *this contains a value, an optional object whose contained value is direct-non-list-initialized with invoke(std::forward<F>(f), *val); otherwise, optional().

🔗

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

Constraints: F models invocable.

Mandates: is_same_v<remove_cvref_t<invoke_result_t<F>>, optional> is true.

Effects: Equivalent to: if (has_value()) { return *val; } else { return std::forward<F>(f)(); }

22.5.4.8 Modifiers [optional.ref.mod]

🔗

constexpr void reset() noexcept;

Effects: Assigns nullptr to val.

Postconditions: *this does not contain a value.

22.5.4.9 Exposition only helper functions [optional.ref.expos]

🔗

template<class U>
constexpr void convert-ref-init-val(U&& u);  // exposition only

Effects: Creates a variable r as if by T& r(std::forward(u)); and then initializes val with addressof(r).