[optional.optional.ref] - C++23 → Trunk

Files changed (1) hide show

tmp/tmp1339qvqd/{from.md → to.md} +422 -0

tmp/tmp1339qvqd/{from.md → to.md} RENAMED Viewed

	@@ -0,0 +1,422 @@

+### Partial specialization of `optional` for reference types <a id="optional.optional.ref">[[optional.optional.ref]]</a>
+#### General <a id="optional.optional.ref.general">[[optional.optional.ref.general]]</a>
+``` cpp
+namespace std {
+  template<class T>
+  class optional<T&> {
+  public:
+    using value_type     = T;
+    using iterator       = implementation-defined;              // 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<U>& rhs) noexcept(see below);
+    template<class U>
+      constexpr explicit(see below) optional(const optional<U>& rhs) noexcept(see below);
+    template<class U>
+      constexpr explicit(see below) optional(optional<U>&& rhs) noexcept(see below);
+    template<class U>
+      constexpr explicit(see below) optional(const optional<U>&& 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 iterator begin() const noexcept;
+    constexpr iterator 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`.
+#### Constructors <a id="optional.ref.ctor">[[optional.ref.ctor]]</a>
+``` cpp
+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>(arg))`.
+*Ensures:* `*this` contains a value.
+``` cpp
+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<U>, optional>` is `false`,
+- `is_same_v<remove_cvref_t<U>, in_place_t>` is `false`, and
+- `is_constructible_v<T&, U>` is `true`.
+*Effects:* Equivalent to:
+*`convert-ref-init-val`*`(std::forward<U>(u))`.
+*Ensures:* `*this` contains a value.
+*Remarks:* This constructor is defined as deleted if
+``` cpp
+reference_constructs_from_temporary_v<T&, U>
+```
+is `true`.
+``` cpp
+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<T>, optional<U>>` is `false`,
+- `is_same_v<T&, U>` is `false`, and
+- `is_constructible_v<T&, U&>` is `true`.
+*Effects:* Equivalent to:
+``` cpp
+if (rhs.has_value()) convert-ref-init-val(*rhs);
+```
+*Remarks:* This constructor is defined as deleted if
+``` cpp
+reference_constructs_from_temporary_v<T&, U&>
+```
+is `true`.
+``` cpp
+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<T>, optional<U>>` is `false`,
+- `is_same_v<T&, U>` is `false`, and
+- `is_constructible_v<T&, const U&>` is `true`.
+*Effects:* Equivalent to:
+``` cpp
+if (rhs.has_value()) convert-ref-init-val(*rhs);
+```
+*Remarks:* This constructor is defined as deleted if
+``` cpp
+reference_constructs_from_temporary_v<T&, const U&>
+```
+is `true`.
+``` cpp
+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<T>, optional<U>>` is `false`,
+- `is_same_v<T&, U>` is `false`, and
+- `is_constructible_v<T&, U>` is `true`.
+*Effects:* Equivalent to:
+``` cpp
+if (rhs.has_value()) convert-ref-init-val(*std::move(rhs));
+```
+*Remarks:* This constructor is defined as deleted if
+``` cpp
+reference_constructs_from_temporary_v<T&, U>
+```
+is `true`.
+``` cpp
+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<T>, optional<U>>` is `false`,
+- `is_same_v<T&, U>` is `false`, and
+- `is_constructible_v<T&, const U>` is `true`.
+*Effects:* Equivalent to:
+``` cpp
+if (rhs.has_value()) convert-ref-init-val(*std::move(rhs));
+```
+*Remarks:* This constructor is defined as deleted if
+``` cpp
+reference_constructs_from_temporary_v<T&, const U>
+```
+is `true`.
+#### Assignment <a id="optional.ref.assign">[[optional.ref.assign]]</a>
+``` cpp
+constexpr optional& operator=(nullopt_t) noexcept;
+```
+*Effects:* Assigns `nullptr` to *val*.
+*Ensures:* `*this` does not contain a value.
+*Returns:* `*this`.
+``` cpp
+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>(u))`.
+*Returns:* `*`*`val`*.
+#### Swap <a id="optional.ref.swap">[[optional.ref.swap]]</a>
+``` cpp
+constexpr void swap(optional& rhs) noexcept;
+```
+*Effects:* Equivalent to: `swap(`*`val`*`, rhs.`*`val`*`)`.
+#### Iterator support <a id="optional.ref.iterators">[[optional.ref.iterators]]</a>
+``` cpp
+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<T>`. The reference type is `T&` for `iterator`.
+All requirements on container iterators [[container.reqmts]] apply to
+`optional::iterator`.
+``` cpp
+constexpr iterator begin() const noexcept;
+```
+*Returns:* If `has_value()` is `true`, an iterator referring to
+`*`*`val`*. Otherwise, a past-the-end iterator value.
+``` cpp
+constexpr iterator end() const noexcept;
+```
+*Returns:* `begin() + has_value()`.
+#### Observers <a id="optional.ref.observe">[[optional.ref.observe]]</a>
+``` cpp
+constexpr T* operator->() const noexcept;
+```
+`has_value()` is `true`.
+*Returns:* *val*.
+``` cpp
+constexpr T& operator*() const noexcept;
+```
+`has_value()` is `true`.
+*Returns:* `*`*`val`*.
+``` cpp
+constexpr explicit operator bool() const noexcept;
+```
+*Returns:* *`val`*` != nullptr`.
+``` cpp
+constexpr bool has_value() const noexcept;
+```
+*Returns:* *`val`*` != nullptr`.
+``` cpp
+constexpr T& value() const;
+```
+*Effects:* Equivalent to:
+``` cpp
+return has_value() ? *val : throw bad_optional_access();
+```
+``` cpp
+template<class U = remove_cv_t<T>> constexpr remove_cv_t<T> value_or(U&& u) const;
+```
+Let `X` be `remove_cv_t<T>`.
+*Mandates:* `is_constructible_v<X, T&> && is_convertible_v<U, X>` is
+`true`.
+*Effects:* Equivalent to:
+``` cpp
+return has_value() ? *val : static_cast<X>(std::forward<U>(u));
+```
+#### Monadic operations <a id="optional.ref.monadic">[[optional.ref.monadic]]</a>
+``` cpp
+template<class F> constexpr auto and_then(F&& f) const;
+```
+Let `U` be `invoke_result_t<F, T&>`.
+*Mandates:* `remove_cvref_t<U>` is a specialization of `optional`.
+*Effects:* Equivalent to:
+``` cpp
+if (has_value()) {
+  return invoke(std::forward<F>(f), *val);
+} else {
+  return remove_cvref_t<U>();
+}
+```
+``` cpp
+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 declaration
+``` cpp
+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<U>` object whose
+contained value is direct-non-list-initialized with
+`invoke(std::forward<F>(f), *`*`val`*`)`; otherwise, `optional<U>()`.
+``` cpp
+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:
+``` cpp
+if (has_value()) {
+  return *val;
+} else {
+  return std::forward<F>(f)();
+}
+```
+#### Modifiers <a id="optional.ref.mod">[[optional.ref.mod]]</a>
+``` cpp
+constexpr void reset() noexcept;
+```
+*Effects:* Assigns `nullptr` to *val*.
+*Ensures:* `*this` does not contain a value.
+#### Exposition only helper functions <a id="optional.ref.expos">[[optional.ref.expos]]</a>
+``` cpp
+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>(u));`
+and then initializes *val* with `addressof(r)`.

Diff to HTML by rtfpessoa