cppdraft_translate/cppdraft/container/node.md

[container.node]

23 Containers library [containers]

23.2 Requirements [container.requirements]

23.2.5 Node handles [container.node]

23.2.5.1 Overview [container.node.overview]

1

#

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 75.

Table 75 — Container types with compatible nodes [tab:container.node.compat]

🔗 map<K, T, C1, A>	map<K, T, C2, A>
🔗 map<K, T, C1, A>	multimap<K, T, C2, A>
🔗 set<K, C1, A>	set<K, C2, A>
🔗 set<K, C1, A>	multiset<K, C2, A>
🔗 unordered_map<K, T, H1, E1, A>	unordered_map<K, T, H2, E2, A>
🔗 unordered_map<K, T, H1, E1, A>	unordered_multimap<K, T, H2, E2, A>
🔗 unordered_set<K, H1, E1, A>	unordered_set<K, H2, E2, A>
🔗 unordered_set<K, H1, E1, A>	unordered_multiset<K, H2, E2, A>

2

#

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.

3

#

Class node-handle is for exposition only.

4

#

If a user-defined specialization of pair exists forpair<const Key, T> or pair<Key, T>, where Key is the container's key_type and T is the container'smapped_type, the behavior of operations involving node handles is undefined.

template<unspecified>class node-handle {public:// These type declarations are described in [associative.reqmts] and [unord.req].using value_type = see below; // not present for map containersusing key_type = see below; // not present for set containersusing mapped_type = see below; // not present for set containersusing allocator_type = see below;

private:using container_node_type = unspecified; // exposition onlyusing ator_traits = allocator_traits<allocator_type>; // exposition onlytypename ator_traits::template rebind_traits<container_node_type>::pointer ptr_; // exposition only optional<allocator_type> alloc_; // exposition onlypublic:// [container.node.cons], constructors, copy, and assignmentconstexpr node-handle() noexcept : ptr_(), alloc_() {}constexpr node-handle(node-handle&&) noexcept; constexpr node-handle& operator=(node-handle&&); // [container.node.dtor], destructorconstexpr ~node-handle(); // [container.node.observers], observersconstexpr value_type& value() const; // not present for map containers key_type& key() const; // not present for set containersconstexpr mapped_type& mapped() const; // not present for set containersconstexpr allocator_type get_allocator() const; constexpr explicit operator bool() const noexcept; constexpr bool empty() const noexcept; // [container.node.modifiers], modifiersconstexpr void swap(node-handle&)noexcept(ator_traits::propagate_on_container_swap::value || ator_traits::is_always_equal::value); friend constexpr void swap(node-handle& x, node-handle& y) noexcept(noexcept(x.swap(y))) { x.swap(y); }};

23.2.5.2 Constructors, copy, and assignment [container.node.cons]

🔗

constexpr node-handle(node-handle&& nh) noexcept;

1

#

Effects: Constructs a node-handle object initializingptr_ with nh.ptr_.

Move constructs alloc_ withnh.alloc_.

Assigns nullptr to nh.ptr_ and assignsnullopt to nh.alloc_.

🔗

constexpr node-handle& operator=(node-handle&& nh);

2

#

Preconditions: Either !alloc_, orator_traits​::​propagate_on_container_move_assignment​::​value is true, or alloc_ == nh.alloc_.

3

#

Effects:

• (3.1)

  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.

• (3.2)

  Assigns nh.ptr_ to ptr_.

• (3.3)

  If !alloc_ or ator_traits​::​propagate_on_container_move_assignment​::​value is true, move assigns nh.alloc_ to alloc_.

• (3.4)

  Assignsnullptr to nh.ptr_ and assigns nullopt tonh.alloc_.

4

#

Returns: *this.

5

#

Throws: Nothing.

23.2.5.3 Destructor [container.node.dtor]

🔗

constexpr ~node-handle();

1

#

Effects: If ptr_ != nullptr, destroys the value_type subobject in the container_node_type object pointed to by ptr_ by callingator_traits​::​destroy, then deallocates ptr_ by callingator_traits​::​template rebind_traits<container_node_type>​::​deallocate.

23.2.5.4 Observers [container.node.observers]

🔗

constexpr value_type& value() const;

1

#

Preconditions: empty() == false.

2

#

Returns: A reference to the value_type subobject in thecontainer_node_type object pointed to by ptr_.

3

#

Throws: Nothing.

🔗

key_type& key() const;

4

#

Preconditions: empty() == false.

5

#

Returns: A non-const reference to the key_type member of thevalue_type subobject in the container_node_type object pointed to by ptr_.

6

#

Throws: Nothing.

7

#

Remarks: Modifying the key through the returned reference is permitted.

🔗

constexpr mapped_type& mapped() const;

8

#

Preconditions: empty() == false.

9

#

Returns: A reference to the mapped_type member of thevalue_type subobject in the container_node_type object pointed to by ptr_.

10

#

Throws: Nothing.

🔗

constexpr allocator_type get_allocator() const;

11

#

Preconditions: empty() == false.

12

#

Returns: *alloc_.

13

#

Throws: Nothing.

🔗

constexpr explicit operator bool() const noexcept;

14

#

Returns: ptr_ != nullptr.

🔗

constexpr bool empty() const noexcept;

15

#

Returns: ptr_ == nullptr.

23.2.5.5 Modifiers [container.node.modifiers]

🔗

constexpr void swap(node-handle& nh) noexcept(ator_traits::propagate_on_container_swap::value || ator_traits::is_always_equal::value);

1

#

Preconditions: !alloc_, or !nh.alloc_, orator_traits​::​propagate_on_container_swap​::​value is true, or alloc_ == nh.alloc_.

2

#

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_).