[container.node] - C++17 → C++20

Files changed (1) hide show

tmp/tmpdrkp9k_4/{from.md → to.md} +46 -42

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

@@ -1,18 +1,18 @@
 ### Node handles <a id="container.node">[[container.node]]</a>
-#### `node_handle` overview <a id="container.node.overview">[[container.node.overview]]</a>
 A *node handle* is an object that accepts ownership of a single element
-from an associative container ([[associative.reqmts]]) or an unordered
-associative container ([[unord.req]]). It may be used to transfer that
 ownership to another container with compatible nodes. Containers with
 compatible nodes have the same node handle type. Elements may be
 transferred in either direction between container types in the same row
-of Table  [[tab:containers.node.compat]].
-**Table: Container types with compatible nodes** <a id="tab:containers.node.compat">[tab:containers.node.compat]</a>
 |                                  |                                       |
 | -------------------------------- | ------------------------------------- |
 | `map<K, T, C1, A>`               | `map<K, T, C2, A>`                    |
 | `map<K, T, C1, A>`               | `multimap<K, T, C2, A>`               |
@@ -26,122 +26,126 @@ of Table  [[tab:containers.node.compat]].
 If a node handle is not empty, then it contains an allocator that is
 equal to the allocator of the container when the element was extracted.
 If a node handle is empty, it contains no allocator.
-Class `node_handle` is for exposition only. An implementation is
-permitted to provide equivalent functionality without providing a class
-with this name.
 If a user-defined specialization of `pair` exists for
 `pair<const Key, T>` or `pair<Key, T>`, where `Key` is the container’s
 `key_type` and `T` is the container’s `mapped_type`, the behavior of
 operations involving node handles is undefined.
 ``` cpp
 template<unspecified>
- class node_handle {
 public:
- // These type declarations are described in Tables [tab:containers.associative.requirements] and [tab:HashRequirements].
   using value_type     = see below;     // not present for map containers
   using key_type       = see below;     // not present for set containers
   using mapped_type    = see below;     // not present for set containers
   using allocator_type = see below;
 private:
   using container_node_type = unspecified;
   using ator_traits = allocator_traits<allocator_type>;
- typename ator_traits::rebind_traits<container_node_type>::pointer ptr_;
   optional<allocator_type> alloc_;
 public:
-    constexpr node_handle() noexcept : ptr_(), alloc_() {}
-    ~node_handle();
-    node_handle(node_handle&&) noexcept;
-    node_handle& operator=(node_handle&&);
   value_type& value() const;            // not present for map containers
   key_type& key() const;                // not present for set containers
   mapped_type& mapped() const;          // not present for set containers
   allocator_type get_allocator() const;
   explicit operator bool() const noexcept;
- bool empty() const noexcept;
-    void swap(node_handle&)
     noexcept(ator_traits::propagate_on_container_swap::value ||
              ator_traits::is_always_equal::value);
- friend void swap(node_handle& x, node_handle& y) noexcept(noexcept(x.swap(y))) {
     x.swap(y);
   }
 };
 ```
-#### `node_handle` constructors, copy, and assignment <a id="container.node.cons">[[container.node.cons]]</a>
 ``` cpp
-node_handle(node_handle&& nh) noexcept;
 ```
-*Effects:* Constructs a *`node_handle`* object initializing `ptr_` with
 `nh.ptr_`. Move constructs `alloc_` with `nh.alloc_`. Assigns `nullptr`
 to `nh.ptr_` and assigns `nullopt` to `nh.alloc_`.
 ``` cpp
-node_handle& operator=(node_handle&& nh);
 ```
-*Requires:* Either `!alloc_`, or
-`ator_traits::propagate_on_container_move_assignment` is `true`, or
-`alloc_ == nh.alloc_`.
 *Effects:*
 - If `ptr_ != nullptr`, destroys the `value_type` subobject in the
   `container_node_type` object pointed to by `ptr_` by calling
   `ator_traits::destroy`, then deallocates `ptr_` by calling
-  `ator_traits::rebind_traits<container_node_type>::deallocate`.
 - Assigns `nh.ptr_` to `ptr_`.
-- If `!alloc` or `ator_traits::propagate_on_container_move_assignment`
- is `true`, move assigns `nh.alloc_` to `alloc_`.
 - Assigns `nullptr` to `nh.ptr_` and assigns `nullopt` to `nh.alloc_`.
 *Returns:* `*this`.
 *Throws:* Nothing.
-#### `node_handle` destructor <a id="container.node.dtor">[[container.node.dtor]]</a>
 ``` cpp
-~node_handle();
 ```
 *Effects:* If `ptr_ != nullptr`, destroys the `value_type` subobject in
 the `container_node_type` object pointed to by `ptr_` by calling
 `ator_traits::destroy`, then deallocates `ptr_` by calling
-`ator_traits::rebind_traits<container_node_type>::deallocate`.
-#### `node_handle` observers <a id="container.node.observers">[[container.node.observers]]</a>
 ``` cpp
 value_type& value() const;
 ```
-*Requires:* `empty() == false`.
 *Returns:* A reference to the `value_type` subobject in the
 `container_node_type` object pointed to by `ptr_`.
 *Throws:* Nothing.
 ``` cpp
 key_type& key() const;
 ```
-*Requires:* `empty() == false`.
 *Returns:* A non-const reference to the `key_type` member of the
 `value_type` subobject in the `container_node_type` object pointed to by
 `ptr_`.
@@ -152,22 +156,22 @@ permitted.
 ``` cpp
 mapped_type& mapped() const;
 ```
-*Requires:* `empty() == false`.
 *Returns:* A reference to the `mapped_type` member of the `value_type`
 subobject in the `container_node_type` object pointed to by `ptr_`.
 *Throws:* Nothing.
 ``` cpp
 allocator_type get_allocator() const;
 ```
-*Requires:* `empty() == false`.
 *Returns:* `*alloc_`.
 *Throws:* Nothing.
@@ -176,26 +180,26 @@ explicit operator bool() const noexcept;
 ```
 *Returns:* `ptr_ != nullptr`.
 ``` cpp
-bool empty() const noexcept;
 ```
 *Returns:* `ptr_ == nullptr`.
-#### `node_handle` modifiers <a id="container.node.modifiers">[[container.node.modifiers]]</a>
 ``` cpp
-void swap(node_handle& nh)
   noexcept(ator_traits::propagate_on_container_swap::value ||
            ator_traits::is_always_equal::value);
 ```
-*Requires:* `!alloc_`, or `!nh.alloc_`, or
-`ator_traits::propagate_on_container_swap` is `true`, or
 `alloc_ == nh.alloc_`.
 *Effects:* Calls `swap(ptr_, nh.ptr_)`. If `!alloc_`, or `!nh.alloc_`,
-or `ator_traits::propagate_on_container_swap` is `true` calls
 `swap(alloc_, nh.alloc_)`.

 ### Node handles <a id="container.node">[[container.node]]</a>
+#### Overview <a id="container.node.overview">[[container.node.overview]]</a>
 A *node handle* is an object that accepts ownership of a single element
+from an associative container [[associative.reqmts]] or an unordered
+associative container [[unord.req]]. It may be used to transfer that
 ownership to another container with compatible nodes. Containers with
 compatible nodes have the same node handle type. Elements may be
 transferred in either direction between container types in the same row
+of [[container.node.compat]].
+**Table: Container types with compatible nodes** <a id="container.node.compat">[container.node.compat]</a>
 |                                  |                                       |
 | -------------------------------- | ------------------------------------- |
 | `map<K, T, C1, A>`               | `map<K, T, C2, A>`                    |
 | `map<K, T, C1, A>`               | `multimap<K, T, C2, A>`               |
 If a node handle is not empty, then it contains an allocator that is
 equal to the allocator of the container when the element was extracted.
 If a node handle is empty, it contains no allocator.
+Class *`node-handle`* is for exposition only.
 If a user-defined specialization of `pair` exists for
 `pair<const Key, T>` or `pair<Key, T>`, where `Key` is the container’s
 `key_type` and `T` is the container’s `mapped_type`, the behavior of
 operations involving node handles is undefined.
 ``` cpp
 template<unspecified>
+class node-handle {
 public:
+ // These type declarations are described in Tables [tab:container.assoc.req] and [tab:container.hash.req].
   using value_type     = see below;     // not present for map containers
   using key_type       = see below;     // not present for set containers
   using mapped_type    = see below;     // not present for set containers
   using allocator_type = see below;
 private:
   using container_node_type = unspecified;
   using ator_traits = allocator_traits<allocator_type>;
+ typename ator_traits::template rebind_traits<container_node_type>::pointer ptr_;
   optional<allocator_type> alloc_;
 public:
+  // [container.node.cons], constructors, copy, and assignment
+  constexpr node-handle() noexcept : ptr_(), alloc_() {}
+  node-handle(node-handle&&) noexcept;
+  node-handle& operator=(node-handle&&);
+  // [container.node.dtor], destructor
+  ~node-handle();
+  // [container.node.observers], observers
   value_type& value() const;            // not present for map containers
   key_type& key() const;                // not present for set containers
   mapped_type& mapped() const;          // not present for set containers
   allocator_type get_allocator() const;
   explicit operator bool() const noexcept;
+  [[nodiscard]] bool empty() const noexcept;
+  // [container.node.modifiers], modifiers
+  void swap(node-handle&)
     noexcept(ator_traits::propagate_on_container_swap::value ||
              ator_traits::is_always_equal::value);
+ friend void swap(node-handle& x, node-handle& y) noexcept(noexcept(x.swap(y))) {
     x.swap(y);
   }
 };
 ```
+#### Constructors, copy, and assignment <a id="container.node.cons">[[container.node.cons]]</a>
 ``` cpp
+node-handle(node-handle&& nh) noexcept;
 ```
+*Effects:* Constructs a *node-handle* object initializing `ptr_` with
 `nh.ptr_`. Move constructs `alloc_` with `nh.alloc_`. Assigns `nullptr`
 to `nh.ptr_` and assigns `nullopt` to `nh.alloc_`.
 ``` cpp
+node-handle& operator=(node-handle&& nh);
 ```
+*Preconditions:* Either `!alloc_`, or
+`ator_traits::propagate_on_container_move_assignment::value` is `true`,
+or `alloc_ == nh.alloc_`.
 *Effects:*
 - If `ptr_ != nullptr`, destroys the `value_type` subobject in the
   `container_node_type` object pointed to by `ptr_` by calling
   `ator_traits::destroy`, then deallocates `ptr_` by calling
+  `ator_traits::template rebind_traits<container_node_type>::deallocate`.
 - Assigns `nh.ptr_` to `ptr_`.
+- If `!alloc` or
+  `ator_traits::propagate_on_container_move_assignment::value` is
+  `true`, move assigns `nh.alloc_` to `alloc_`.
 - Assigns `nullptr` to `nh.ptr_` and assigns `nullopt` to `nh.alloc_`.
 *Returns:* `*this`.
 *Throws:* Nothing.
+#### Destructor <a id="container.node.dtor">[[container.node.dtor]]</a>
 ``` cpp
+~node-handle();
 ```
 *Effects:* If `ptr_ != nullptr`, destroys the `value_type` subobject in
 the `container_node_type` object pointed to by `ptr_` by calling
 `ator_traits::destroy`, then deallocates `ptr_` by calling
+`ator_traits::template rebind_traits<container_node_type>::deallocate`.
+#### Observers <a id="container.node.observers">[[container.node.observers]]</a>
 ``` cpp
 value_type& value() const;
 ```
+*Preconditions:* `empty() == false`.
 *Returns:* A reference to the `value_type` subobject in the
 `container_node_type` object pointed to by `ptr_`.
 *Throws:* Nothing.
 ``` cpp
 key_type& key() const;
 ```
+*Preconditions:* `empty() == false`.
 *Returns:* A non-const reference to the `key_type` member of the
 `value_type` subobject in the `container_node_type` object pointed to by
 `ptr_`.
 ``` cpp
 mapped_type& mapped() const;
 ```
+*Preconditions:* `empty() == false`.
 *Returns:* A reference to the `mapped_type` member of the `value_type`
 subobject in the `container_node_type` object pointed to by `ptr_`.
 *Throws:* Nothing.
 ``` cpp
 allocator_type get_allocator() const;
 ```
+*Preconditions:* `empty() == false`.
 *Returns:* `*alloc_`.
 *Throws:* Nothing.
 ```
 *Returns:* `ptr_ != nullptr`.
 ``` cpp
+[[nodiscard]] bool empty() const noexcept;
 ```
 *Returns:* `ptr_ == nullptr`.
+#### Modifiers <a id="container.node.modifiers">[[container.node.modifiers]]</a>
 ``` cpp
+void swap(node-handle& nh)
   noexcept(ator_traits::propagate_on_container_swap::value ||
            ator_traits::is_always_equal::value);
 ```
+*Preconditions:* `!alloc_`, or `!nh.alloc_`, or
+`ator_traits::propagate_on_container_swap::value` is `true`, or
 `alloc_ == nh.alloc_`.
 *Effects:* Calls `swap(ptr_, nh.ptr_)`. If `!alloc_`, or `!nh.alloc_`,
+or `ator_traits::propagate_on_container_swap::value` is `true` calls
 `swap(alloc_, nh.alloc_)`.

Diff to HTML by rtfpessoa