21 KiB
[optional.optional.ref]
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]
namespace std {templateclass optional<T&> {public:using value_type = T; using iterator = implementation-defined; // see [optional.ref.iterators]public:// [optional.ref.ctor], constructorsconstexpr optional() noexcept = default; constexpr optional(nullopt_t) noexcept : optional() {}constexpr optional(const optional& rhs) noexcept = default; templateconstexpr explicit optional(in_place_t, Arg&& arg); templateconstexpr explicit(see below) optional(U&& u) noexcept(see below); templateconstexpr explicit(see below) optional(optional& rhs) noexcept(see below); templateconstexpr explicit(see below) optional(const optional& rhs) noexcept(see below); templateconstexpr explicit(see below) optional(optional&& rhs) noexcept(see below); templateconstexpr explicit(see below) optional(const optional&& rhs) noexcept(see below); constexpr ~optional() = default; // [optional.ref.assign], assignmentconstexpr optional& operator=(nullopt_t) noexcept; constexpr optional& operator=(const optional& rhs) noexcept = default; template constexpr T& emplace(U&& u) noexcept(see below); // [optional.ref.swap], swapconstexpr void swap(optional& rhs) noexcept; // [optional.ref.iterators], iterator supportconstexpr iterator begin() const noexcept; constexpr iterator end() const noexcept; // [optional.ref.observe], observersconstexpr 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-deletedtemplate<class U = remove_cv_t>constexpr remove_cv_t value_or(U&& u) const; // [optional.ref.monadic], monadic operationstemplate constexpr auto and_then(F&& f) const; template constexpr optional<invoke_result_t<F, T&>> transform(F&& f) const; template constexpr optional or_else(F&& f) const; // [optional.ref.mod], modifiersconstexpr void reset() noexcept; private: T* val = nullptr; // exposition only// [optional.ref.expos], exposition only helper functionstemplateconstexpr void convert-ref-init-val(U&& u); // exposition only};}
An object of 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.
22.5.4.2 Constructors [optional.ref.ctor]
template<class Arg> constexpr explicit optional(in_place_t, Arg&& arg);
Constraints:
is_constructible_v<T&, Arg> is true, and
reference_constructs_from_temporary_v<T&, Arg> is false.
Effects: Equivalent to: convert-ref-init-val(std::forward(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:
is_same_v<remove_cvref_t, optional> is false,
is_same_v<remove_cvref_t, in_place_t> is false, and
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 ifreference_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:
is_same_v<remove_cv_t, optional> is false,
is_same_v<T&, U> is false, and
is_constructible_v<T&, U&> is true.
Effects: Equivalent to:if (rhs.has_value()) convert-ref-init-val(*rhs);
Remarks: This constructor is defined as deleted ifreference_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:
is_same_v<remove_cv_t, optional> is false,
is_same_v<T&, U> is false, and
is_constructible_v<T&, const U&> is true.
Effects: Equivalent to:if (rhs.has_value()) convert-ref-init-val(*rhs);
Remarks: This constructor is defined as deleted ifreference_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:
is_same_v<remove_cv_t, optional> is false,
is_same_v<T&, U> is false, and
is_constructible_v<T&, U> is true.
Effects: Equivalent to:if (rhs.has_value()) convert-ref-init-val(*std::move(rhs));
Remarks: This constructor is defined as deleted ifreference_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:
is_same_v<remove_cv_t, optional> is false,
is_same_v<T&, U> is false, and
is_constructible_v<T&, const U> is true.
Effects: Equivalent to:if (rhs.has_value()) convert-ref-init-val(*std::move(rhs));
Remarks: This constructor is defined as deleted ifreference_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:
is_constructible_v<T&, U> is true, and
reference_constructs_from_temporary_v<T&, U> is false.
Effects: Equivalent to: convert-ref-init-val(std::forward(u)).
22.5.4.4 Swap [optional.ref.swap]
constexpr void swap(optional& rhs) noexcept;
Effects: Equivalent to: swap(val, rhs.val).
22.5.4.5 Iterator support [optional.ref.iterators]
using iterator = implementation-defined;
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.
The reference type is T& for iterator.
All requirements on container iterators ([container.reqmts]) apply tooptional::iterator.
constexpr iterator begin() const noexcept;
Returns: If has_value() is true, an iterator referring to *val.
Otherwise, a past-the-end iterator value.
constexpr iterator end() const noexcept;
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;
Let X be remove_cv_t.
Mandates: is_constructible_v<X, T&> && is_convertible_v<U, X> is true.
Effects: Equivalent to:return has_value() ? *val : static_cast(std::forward(u));
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), *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: The declarationU u(invoke(std::forward(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 withinvoke(std::forward(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>, optional> is true.
Effects: Equivalent to:if (has_value()) {return *val;} else {return std::forward(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).