cpp/container/node handle

Associative containers std, std, std, std, std, std, std, std are node-based data structures, and their nodes can be extracted as an object of unspecified type known as node handle.

Node handle is a move-only type that owns and provides access to the element (the ) stored in the node, and provides non-const access to the key part of the element (the ) and the mapped part of the element (the ). If the node handle destructs while holding the node, the node is properly destructed using the appropriate allocator for the container. The node handle contains a copy of the container’s allocator. This is necessary so that the node handle can outlive the container.

The exact type of node handle (shown here as ) is unspecified, but each container exposes its node handle type as the member.

Node handles can be used to transfer ownership of an element between two associative containers with the same key, value, and allocator type (ignoring comparison or hash/equality), without invoking any copy/move operations on the container element (this kind of operation is known as "splicing"). Transfer between unique and non-unique containers is also permitted: a node handle from a std can be inserted into an std, but not into std or std.

A node handle may be empty, in which case it holds no element and no allocator. The default-constructed and moved-from node handle is empty. In addition, an empty node handle can be produced by a failed call to container member function.

Pointers and references to an element that are obtained while it is owned by a node handle are invalidated if the element is successfully inserted into a container.

For all map containers (std, std, std, and std) whose is  and  is, the behavior of operations involving node handles is undefined if a user-defined specialization of std exists for  or.

Member functions
{{member|constructors|2= {{dcl begin}} {{dcl|num=1| constexpr /* node-handle */ noexcept; }} {{dcl|num=2| /* node-handle */ (/* node-handle */&& nh) noexcept; }} {{dcl end}} @1@ The default constructor initializes the node handle to the empty state. @2@ The move constructor takes ownership of the container element from {{c|nh}}, move-constructs the member allocator, and leaves {{c|nh}} in the empty state.

Exceptions
Throws nothing.

Exceptions
Throws nothing. }}

{{member|value|2= {{dcl begin}} {{dcl|notes={{mark|set containers only}}| value_type& value const; }} {{dcl end}}

Returns a reference to the {{tt|value_type}} subobject in the container element object managed by this node handle. The behavior is undefined if the node handle is empty.

Exceptions
Throws nothing. }}

{{member|key|2= {{dcl begin}} {{dcl|notes={{mark|map containers only}}| key_type& key const; }} {{dcl end}}

Returns a non-const reference to the {{tt|key_type}} member of the {{tt|value_type}} subobject in the container element object managed by this node handle. The behavior is undefined if the node handle is empty.

Exceptions
Throws nothing.

Exceptions
Throws nothing. }}

{{member|swap|2= {{dcl begin}} {{dcl| void swap(/* node-handle */& nh) noexcept(/* see below */); }} {{dcl end}}


 * swaps ownership of container nodes;
 * if one node is empty or if both nodes are non-empty and {{c/core|std::allocator_traits::propagate_on_container_swap}} is {{c|true}}, swaps the allocators as well.

The behavior is undefined if both nodes are not empty and {{c/core|std::allocator_traits::propagate_on_container_swap}} is {{c|false}} and the allocators do not compare equal.

Exceptions
}}