[indirect] - C++23 → Trunk

Files changed (1) hide show

tmp/tmp17mghs_y/{from.md → to.md} +531 -0

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

	@@ -0,0 +1,531 @@

+### Class template `indirect` <a id="indirect">[[indirect]]</a>
+#### General <a id="indirect.general">[[indirect.general]]</a>
+An indirect object manages the lifetime of an owned object. An indirect
+object is *valueless* if it has no owned object. An indirect object may
+become valueless only after it has been moved from.
+In every specialization `indirect<T, Allocator>`, if the type
+`allocator_traits<Allocator>::value_type` is not the same type as `T`,
+the program is ill-formed. Every object of type `indirect<T, Allocator>`
+uses an object of type `Allocator` to allocate and free storage for the
+owned object as needed.
+Constructing an owned object with `args...` using the allocator `a`
+means calling `allocator_traits<Allocator>::construct(a, p, args...)`
+where `args` is an expression pack, `a` is an allocator, and *`p`* is a
+pointer obtained by calling `allocator_traits<Allocator>::allocate`.
+The member *`alloc`* is used for any memory allocation and element
+construction performed by member functions during the lifetime of each
+indirect object. The allocator *`alloc`* may be replaced only via
+assignment or `swap()`. `Allocator` replacement is performed by copy
+assignment, move assignment, or swapping of the allocator only if
+[[container.reqmts]]:
+- `allocator_traits<Allocator>::propagate_on_container_copy_assignment::value`,
+  or
+- `allocator_traits<Allocator>::propagate_on_container_move_assignment::value`,
+  or
+- `allocator_traits<Allocator>::propagate_on_container_swap::value`
+is `true` within the implementation of the corresponding `indirect`
+operation.
+A program that instantiates the definition of the template
+`indirect<T, Allocator>` with a type for the `T` parameter that is a
+non-object type, an array type, `in_place_t`, a specialization of
+`in_place_type_t`, or a cv-qualified type is ill-formed.
+The template parameter `T` of `indirect` may be an incomplete type.
+The template parameter `Allocator` of `indirect` shall meet the
+*Cpp17Allocator* requirements.
+If a program declares an explicit or partial specialization of
+`indirect`, the behavior is undefined.
+#### Synopsis <a id="indirect.syn">[[indirect.syn]]</a>
+``` cpp
+namespace std {
+  template<class T, class Allocator = allocator<T>>
+  class indirect {
+  public:
+    using value_type = T;
+    using allocator_type = Allocator;
+    using pointer = allocator_traits<Allocator>::pointer;
+    using const_pointer = allocator_traits<Allocator>::const_pointer;
+    // [indirect.ctor], constructors
+    constexpr explicit indirect();
+    constexpr explicit indirect(allocator_arg_t, const Allocator& a);
+    constexpr indirect(const indirect& other);
+    constexpr indirect(allocator_arg_t, const Allocator& a, const indirect& other);
+    constexpr indirect(indirect&& other) noexcept;
+    constexpr indirect(allocator_arg_t, const Allocator& a, indirect&& other)
+      noexcept(see below);
+    template<class U = T>
+      constexpr explicit indirect(U&& u);
+    template<class U = T>
+      constexpr explicit indirect(allocator_arg_t, const Allocator& a, U&& u);
+    template<class... Us>
+      constexpr explicit indirect(in_place_t, Us&&... us);
+    template<class... Us>
+      constexpr explicit indirect(allocator_arg_t, const Allocator& a,
+                                  in_place_t, Us&&... us);
+    template<class I, class... Us>
+      constexpr explicit indirect(in_place_t, initializer_list<I> ilist, Us&&... us);
+    template<class I, class... Us>
+      constexpr explicit indirect(allocator_arg_t, const Allocator& a,
+                                  in_place_t, initializer_list<I> ilist, Us&&... us);
+    // [indirect.dtor], destructor
+    constexpr ~indirect();
+    // [indirect.assign], assignment
+    constexpr indirect& operator=(const indirect& other);
+    constexpr indirect& operator=(indirect&& other) noexcept(see below);
+    template<class U = T>
+      constexpr indirect& operator=(U&& u);
+    // [indirect.obs], observers
+    constexpr const T& operator*() const & noexcept;
+    constexpr T& operator*() & noexcept;
+    constexpr const T&& operator*() const && noexcept;
+    constexpr T&& operator*() && noexcept;
+    constexpr const_pointer operator->() const noexcept;
+    constexpr pointer operator->() noexcept;
+    constexpr bool valueless_after_move() const noexcept;
+    constexpr allocator_type get_allocator() const noexcept;
+    // [indirect.swap], swap
+    constexpr void swap(indirect& other) noexcept(see below);
+    friend constexpr void swap(indirect& lhs, indirect& rhs) noexcept(see below);
+    // [indirect.relops], relational operators
+    template<class U, class AA>
+      friend constexpr bool operator==(const indirect& lhs, const indirect<U, AA>& rhs)
+        noexcept(see below);
+    template<class U, class AA>
+      friend constexpr auto operator<=>(const indirect& lhs, const indirect<U, AA>& rhs)
+        -> synth-three-way-result<T, U>;
+    // [indirect.comp.with.t], comparison with T
+    template<class U>
+      friend constexpr bool operator==(const indirect& lhs, const U& rhs) noexcept(see below);
+    template<class U>
+      friend constexpr auto operator<=>(const indirect& lhs, const U& rhs)
+        -> synth-three-way-result<T, U>;
+  private:
+    pointer p;                          // exposition only
+    Allocator alloc = Allocator();      // exposition only
+  };
+  template<class Value>
+    indirect(Value) -> indirect<Value>;
+  template<class Allocator, class Value>
+    indirect(allocator_arg_t, Allocator, Value)
+      -> indirect<Value, typename allocator_traits<Allocator>::template rebind_alloc<Value>>;
+}
+```
+#### Constructors <a id="indirect.ctor">[[indirect.ctor]]</a>
+The following element applies to all functions in  [[indirect.ctor]]:
+*Throws:* Nothing unless `allocator_traits<Allocator>::allocate` or
+`allocator_traits<Allocator>::construct` throws.
+``` cpp
+constexpr explicit indirect();
+```
+*Constraints:* `is_default_constructible_v<Allocator>` is `true`.
+*Mandates:* `is_default_constructible_v<T>` is `true`.
+*Effects:* Constructs an owned object of type `T` with an empty argument
+list, using the allocator *alloc*.
+``` cpp
+constexpr explicit indirect(allocator_arg_t, const Allocator& a);
+```
+*Mandates:* `is_default_constructible_v<T>` is `true`.
+*Effects:* *alloc* is direct-non-list-initialized with `a`. Constructs
+an owned object of type `T` with an empty argument list, using the
+allocator *alloc*.
+``` cpp
+constexpr indirect(const indirect& other);
+```
+*Mandates:* `is_copy_constructible_v<T>` is `true`.
+*Effects:* *alloc* is direct-non-list-initialized with
+`allocator_traits<Allocator>::select_on_container_copy_construction(other.`*`alloc`*`)`.
+If `other` is valueless, `*this` is valueless. Otherwise, constructs an
+owned object of type `T` with `*other`, using the allocator *alloc*.
+``` cpp
+constexpr indirect(allocator_arg_t, const Allocator& a, const indirect& other);
+```
+*Mandates:* `is_copy_constructible_v<T>` is `true`.
+*Effects:* *alloc* is direct-non-list-initialized with `a`. If `other`
+is valueless, `*this` is valueless. Otherwise, constructs an owned
+object of type `T` with `*other`, using the allocator *alloc*.
+``` cpp
+constexpr indirect(indirect&& other) noexcept;
+```
+*Effects:* *alloc* is direct-non-list-initialized from
+`std::move(other.`*`alloc`*`)`. If `other` is valueless, `*this` is
+valueless. Otherwise `*this` takes ownership of the owned object of
+`other`.
+*Ensures:* `other` is valueless.
+``` cpp
+constexpr indirect(allocator_arg_t, const Allocator& a, indirect&& other)
+  noexcept(allocator_traits<Allocator>::is_always_equal::value);
+```
+*Mandates:* If `allocator_traits<Allocator>::is_always_equal::value` is
+`false` then `T` is a complete type.
+*Effects:* *alloc* is direct-non-list-initialized with `a`. If `other`
+is valueless, `*this` is valueless. Otherwise, if
+*`alloc`*` == other.`*`alloc`* is `true`, constructs an object of type
+`indirect` that takes ownership of the owned object of `other`.
+Otherwise, constructs an owned object of type `T` with
+`*std::move(other)`, using the allocator *alloc*.
+*Ensures:* `other` is valueless.
+``` cpp
+template<class U = T>
+  constexpr explicit indirect(U&& u);
+```
+*Constraints:*
+- `is_same_v<remove_cvref_t<U>, indirect>` is `false`,
+- `is_same_v<remove_cvref_t<U>, in_place_t>` is `false`,
+- `is_constructible_v<T, U>` is `true`, and
+- `is_default_constructible_v<Allocator>` is `true`.
+*Effects:* Constructs an owned object of type `T` with
+`std::forward<U>(u)`, using the allocator *alloc*.
+``` cpp
+template<class U = T>
+  constexpr explicit indirect(allocator_arg_t, const Allocator& a, U&& u);
+```
+*Constraints:*
+- `is_same_v<remove_cvref_t<U>, indirect>` is `false`,
+- `is_same_v<remove_cvref_t<U>, in_place_t>` is `false`, and
+- `is_constructible_v<T, U>` is `true`.
+*Effects:* *alloc* is direct-non-list-initialized with `a`. Constructs
+an owned object of type `T` with `std::forward<U>(u)`, using the
+allocator *alloc*.
+``` cpp
+template<class... Us>
+  constexpr explicit indirect(in_place_t, Us&&... us);
+```
+*Constraints:*
+- `is_constructible_v<T, Us...>` is `true`, and
+- `is_default_constructible_v<Allocator>` is `true`.
+*Effects:* Constructs an owned object of type `T` with
+`std::forward<Us>(us)...`, using the allocator *alloc*.
+``` cpp
+template<class... Us>
+  constexpr explicit indirect(allocator_arg_t, const Allocator& a,
+                              in_place_t, Us&& ...us);
+```
+*Constraints:* `is_constructible_v<T, Us...>` is `true`.
+*Effects:* *alloc* is direct-non-list-initialized with `a`. Constructs
+an owned object of type `T` with `std::forward<Us>(us)...`, using the
+allocator *alloc*.
+``` cpp
+template<class I, class... Us>
+  constexpr explicit indirect(in_place_t, initializer_list<I> ilist, Us&&... us);
+```
+*Constraints:*
+- `is_constructible_v<T, initializer_list<I>&, Us...>` is `true`, and
+- `is_default_constructible_v<Allocator>` is `true`.
+*Effects:* Constructs an owned object of type `T` with the arguments
+`ilist, std::forward<Us>(us)...`, using the allocator *alloc*.
+``` cpp
+template<class I, class... Us>
+  constexpr explicit indirect(allocator_arg_t, const Allocator& a,
+                              in_place_t, initializer_list<I> ilist, Us&&... us);
+```
+*Constraints:* `is_constructible_v<T, initializer_list<I>&, Us...>` is
+`true`.
+*Effects:* *alloc* is direct-non-list-initialized with `a`. Constructs
+an owned object of type `T` with the arguments
+`ilist, std::forward<Us>(us)...`, using the allocator *alloc*.
+#### Destructor <a id="indirect.dtor">[[indirect.dtor]]</a>
+``` cpp
+constexpr ~indirect();
+```
+*Mandates:* `T` is a complete type.
+*Effects:* If `*this` is not valueless, destroys the owned object using
+`allocator_traits<Allocator>::destroy` and then the storage is
+deallocated.
+#### Assignment <a id="indirect.assign">[[indirect.assign]]</a>
+``` cpp
+constexpr indirect& operator=(const indirect& other);
+```
+*Mandates:*
+- `is_copy_assignable_v<T>` is `true`, and
+- `is_copy_constructible_v<T>` is `true`.
+*Effects:* If `addressof(other) == this` is `true`, there are no
+effects. Otherwise:
+- The allocator needs updating if
+  `allocator_traits<Allocator>::propagate_on_container_copy_assignment::value`
+  is `true`.
+- If `other` is valueless, `*this` becomes valueless and the owned
+  object in `*this`, if any, is destroyed using
+  `allocator_traits<Allocator>::destroy` and then the storage is
+  deallocated.
+- Otherwise, if *`alloc`*` == other.`*`alloc`* is `true` and `*this` is
+  not valueless, equivalent to `**this = *other`.
+- Otherwise a new owned object is constructed in `*this` using
+  `allocator_traits<Allocator>::construct` with the owned object from
+  `other` as the argument, using either the allocator in `*this` or the
+  allocator in `other` if the allocator needs updating.
+- The previously owned object in `*this`, if any, is destroyed using
+  `allocator_traits<Allocator>::destroy` and then the storage is
+  deallocated.
+- If the allocator needs updating, the allocator in `*this` is replaced
+  with a copy of the allocator in `other`.
+*Returns:* A reference to `*this`.
+*Remarks:* If any exception is thrown, the result of the expression
+`this->valueless_after_move()` remains unchanged. If an exception is
+thrown during the call to `T`’s selected copy constructor, no effect. If
+an exception is thrown during the call to `T`’s copy assignment, the
+state of its owned object is as defined by the exception safety
+guarantee of `T`’s copy assignment.
+``` cpp
+constexpr indirect& operator=(indirect&& other)
+  noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
+           allocator_traits<Allocator>::is_always_equal::value);
+```
+*Mandates:* `is_copy_constructible_v<T>` is `true`.
+*Effects:* If `addressof(other) == this` is `true`, there are no
+effects. Otherwise:
+- The allocator needs updating if
+  `allocator_traits<Allocator>::propagate_on_container_move_assignment::value`
+  is `true`.
+- If `other` is valueless, `*this` becomes valueless and the owned
+  object in `*this`, if any, is destroyed using
+  `allocator_traits<Allocator>::destroy` and then the storage is
+  deallocated.
+- Otherwise, if *`alloc`*` == other.`*`alloc`* is `true`, swaps the
+  owned objects in `*this` and `other`; the owned object in `other`, if
+  any, is then destroyed using `allocator_traits<Allocator>::destroy`
+  and then the storage is deallocated.
+- Otherwise, constructs a new owned object with the owned object of
+  `other` as the argument as an rvalue, using either the allocator in
+  `*this` or the allocator in `other` if the allocator needs updating.
+- The previously owned object in `*this`, if any, is destroyed using
+  `allocator_traits<Allocator>::destroy` and then the storage is
+  deallocated.
+- If the allocator needs updating, the allocator in `*this` is replaced
+  with a copy of the allocator in `other`.
+*Ensures:* `other` is valueless.
+*Returns:* A reference to `*this`.
+*Remarks:* If any exception is thrown, there are no effects on `*this`
+or `other`.
+``` cpp
+template<class U = T>
+  constexpr indirect& operator=(U&& u);
+```
+*Constraints:*
+- `is_same_v<remove_cvref_t<U>, indirect>` is `false`,
+- `is_constructible_v<T, U>` is `true`, and
+- `is_assignable_v<T&, U>` is `true`.
+*Effects:* If `*this` is valueless then constructs an owned object of
+type `T` with `std::forward<U>(u)` using the allocator *alloc*.
+Otherwise, equivalent to `**this = std::forward<U>(u)`.
+*Returns:* A reference to `*this`.
+#### Observers <a id="indirect.obs">[[indirect.obs]]</a>
+``` cpp
+constexpr const T& operator*() const & noexcept;
+constexpr T& operator*() & noexcept;
+```
+*Preconditions:* `*this` is not valueless.
+*Returns:* `*`*`p`*.
+``` cpp
+constexpr const T&& operator*() const && noexcept;
+constexpr T&& operator*() && noexcept;
+```
+*Preconditions:* `*this` is not valueless.
+*Returns:* `std::move(*`*`p`*`)`.
+``` cpp
+constexpr const_pointer operator->() const noexcept;
+constexpr pointer operator->() noexcept;
+```
+*Preconditions:* `*this` is not valueless.
+*Returns:* *p*.
+``` cpp
+constexpr bool valueless_after_move() const noexcept;
+```
+*Returns:* `true` if `*this` is valueless, otherwise `false`.
+``` cpp
+constexpr allocator_type get_allocator() const noexcept;
+```
+*Returns:* *alloc*.
+#### Swap <a id="indirect.swap">[[indirect.swap]]</a>
+``` cpp
+constexpr void swap(indirect& other)
+  noexcept(allocator_traits<Allocator>::propagate_on_container_swap::value ||
+           allocator_traits<Allocator>::is_always_equal::value);
+```
+*Preconditions:* If
+`allocator_traits<Allocator>::propagate_on_container_swap::value` is
+`true`, then `Allocator` meets the *Cpp17Swappable* requirements.
+Otherwise `get_allocator() == other.get_allocator()` is `true`.
+*Effects:* Swaps the states of `*this` and `other`, exchanging owned
+objects or valueless states. If
+`allocator_traits<Allocator>::propagate_on_container_swap::value` is
+`true`, then the allocators of `*this` and `other` are exchanged by
+calling `swap` as described in  [[swappable.requirements]]. Otherwise,
+the allocators are not swapped.
+[*Note 1*: Does not call `swap` on the owned objects
+directly. — *end note*]
+``` cpp
+constexpr void swap(indirect& lhs, indirect& rhs) noexcept(noexcept(lhs.swap(rhs)));
+```
+*Effects:* Equivalent to `lhs.swap(rhs)`.
+#### Relational operators <a id="indirect.relops">[[indirect.relops]]</a>
+``` cpp
+template<class U, class AA>
+  constexpr bool operator==(const indirect& lhs, const indirect<U, AA>& rhs)
+    noexcept(noexcept(*lhs == *rhs));
+```
+*Mandates:* The expression `*lhs == *rhs` is well-formed and its result
+is convertible to `bool`.
+*Returns:* If `lhs` is valueless or `rhs` is valueless,
+`lhs.valueless_after_move() == rhs.valueless_after_move()`; otherwise
+`*lhs == *rhs`.
+``` cpp
+template<class U, class AA>
+  constexpr synth-three-way-result<T, U>
+    operator<=>(const indirect& lhs, const indirect<U, AA>& rhs);
+```
+*Returns:* If `lhs` is valueless or `rhs` is valueless,
+`!lhs.valueless_after_move() <=> !rhs.valueless_after_move()`; otherwise
+*`synth-three-way`*`(*lhs, *rhs)`.
+#### Comparison with `T` <a id="indirect.comp.with.t">[[indirect.comp.with.t]]</a>
+``` cpp
+template<class U>
+  constexpr bool operator==(const indirect& lhs, const U& rhs) noexcept(noexcept(*lhs == rhs));
+```
+*Mandates:* The expression `*lhs == rhs` is well-formed and its result
+is convertible to `bool`.
+*Returns:* If `lhs` is valueless, `false`; otherwise `*lhs == rhs`.
+``` cpp
+template<class U>
+  constexpr synth-three-way-result<T, U>
+    operator<=>(const indirect& lhs, const U& rhs);
+```
+*Returns:* If `lhs` is valueless, `strong_ordering::less`; otherwise
+*`synth-three-way`*`(*lhs, rhs)`.
+#### Hash support <a id="indirect.hash">[[indirect.hash]]</a>
+``` cpp
+template<class T, class Allocator>
+struct hash<indirect<T, Allocator>>;
+```
+The specialization `hash<indirect<T, Allocator>>` is
+enabled [[unord.hash]] if and only if `hash<T>` is enabled. When enabled
+for an object `i` of type `indirect<T, Allocator>`,
+`hash<indirect<T, Allocator>>()(i)` evaluates to either the same value
+as `hash<T>()(*i)`, if `i` is not valueless; otherwise to an
+*implementation-defined* value. The member functions are not guaranteed
+to be `noexcept`.

Diff to HTML by rtfpessoa