node-handle
class /*node-handle*/;
(exposition only*)
A node handle is an object that accepts ownership of a single element from an associative containers and unordered associative containers. It may be used to transfer that ownership to another container with compatible nodes.
A node handle has two possible states:
- It refers to an element extracted from a container, or
- it is empty .
If a node handle is not empty, then it contains an allocator that is equal to the allocator of the previously extracted container.
For all map containers (std::map , std::multimap , std::unordered_map , and std::unordered_multimap ) whose key_type is Key and mapped_type is T, the behavior of operations involving node handles is undefined if a user-defined specialization of std::pair exists for std::pair <Key, T> or std::pair <const Key, T>.
Contents
- 1 Nested types
- 2 Data members
- 3 Member functions
- 4 node-handle ::node-handle
- 5 node-handle ::operator=
- 6 node-handle ::~node-handle
- 7 node-handle ::empty
- 8 node-handle ::operator bool
- 9 node-handle ::get_allocator
- 10 node-handle ::value (set containers only)
- 11 node-handle ::key (map containers only)
- 12 node-handle ::mapped (map containers only)
- 13 node-handle ::swap
- 14 std::swap(node-handle )
[edit] Nested types
allocator_type
the allocator to be used when destroying the element[edit]
container_node_type
unspecified(exposition-only member type*)
See AssociativeContainer and UnorderedAssociativeContainer for the actual definitions of the non-exposition-only nested types.
[edit] Data members
typename ator_traits ::template
rebind_traits<container_node_type >::pointer
ptr_
a pointer to a container node containing the referred object[1] (exposition-only member object*)
- ↑ The ownership of the pointed-to container node was already detached from the source container while extracting the element. Even if the lifetime of the source container has ended, the container node and the contained element are still accessible.
[edit] Member functions
node-handle ::node-handle
-
ptr_is initialized with other.ptr_. -
alloc_is move constructed with other.alloc_. - Assigns nullptr to other.
ptr_. - Assigns std::nullopt to other.
ptr_.
Parameters
Notes
There is no user-provided copy destructor. node-handle is not CopyConstructible.
Besides move construction and move assignment, a non-empty node-handle can only be created by calling the extract member functions of (unordered) associative containers.
node-handle ::operator=
The move assignment operator replaces state of *this with the state of other using move semantics.
- If
ptr_ator_traits::destroy, then deallocates the storage for the referred element by callingator_traits::rebind_traits<container-node-type>::deallocate. - Assigns other.
ptr_toptr_. - If
ator_traits::propagate_on_container_move_assignment is true, move assigns other.alloc_toalloc_. - Assigns nullptr to other.
ptr_and assigns std::nullopt to other.alloc_.
If the following values are all false, the behavior is undefined:
-
ator_traits::propagate_on_container_move_assignment - !
alloc_ -
alloc_alloc_
Parameters
Return
*this
Exceptions
Throws nothing.
Notes
There is no user-provided copy assignment operator. node-handle is not CopyAssignable.
node-handle ::~node-handle
If ptr_ != nullptr is true, destroys the element referred to by *this by calling ator_traits ::destroy, then deallocates the container element by calling ator_traits ::rebind_traits<container-node-type >::deallocate.
Otherwise, does nothing.
node-handle ::empty
Returns true if the node handle is empty, false otherwise.
Return value
ptr_ == nullptr
node-handle ::operator bool
Converts to false if the node handle is empty, true otherwise.
Return value
ptr_ != nullptr
node-handle ::get_allocator
Returns a copy of the stored allocator.
If empty() is true, the behavior is undefined.
Return value
*alloc_
Exceptions
Throws nothing.
node-handle ::value (set containers only)
Returns a reference to the element referred to by *this.
If empty() is true, the behavior is undefined.
Return value
As described above.
Exceptions
Throws nothing.
node-handle ::key (map containers only)
Returns a non-const reference to the key_type member of the element referred to by *this.
If empty() is true, the behavior is undefined.
Return value
As described above.
Exceptions
Throws nothing.
Notes
This function makes it possible to modify the key of a node extracted from a map, and then re-insert it into the map, without ever copying or moving the element.
node-handle ::mapped (map containers only)
Returns a reference to the mapped_type member of the element referred to by *this.
If empty() is true, the behavior is undefined.
Return value
As described above.
Exceptions
Throws nothing.
node-handle ::swap
Calls swap(ptr_ , nh.ptr_ ). If any of the following values is true, also calls swap(alloc_ , nh.alloc_ ):
-
ator_traits::propagate_on_container_swap - !
alloc_ - !other.
alloc_
If the following values are all false, the behavior is undefined:
-
ator_traits::propagate_on_container_swap - !
alloc_ - !other.
alloc_ -
alloc_alloc_
Exceptions
ator_traits::is_always_equal::value)
[edit] Non-member functions
std::swap(node-handle )
noexcept(noexcept(lhs.swap(rhs)));
Effectively executes x.swap(y).
This function is not visible to ordinary unqualified or qualified lookup, and can only be found by argument-dependent lookup when node-handle is an associated class of the arguments.