From cppreference.com
template</* unspecified */>class/*node-handle*/;(since C++17)
(exposition only*)A node handle is an object that accepts ownership of a single element from an
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 (
,
,
, and
) 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
exists for std::pair<Key,T> or std::pair<constKey,T>.
Nested types
Type Definition key_type(map containers only)the key stored in the node
mapped_type(map containers only)the mapped part of the element stored in the node
value_type(set containers only)the element stored in the node
allocator_typethe allocator to be used when destroying the element
container_node_typeunspecified
(exposition-only member type*)ator_traitsstd::allocator_traits<allocator_type>
(exposition-only member type*)See
and
for the actual definitions of the non-exposition-only nested types.
Data members
Member Description typenameator_traits::template
rebind_traits<container_node_type>::pointerptr_
a pointer to a container node containing the referred object
(exposition-only member object*)std::optional<allocator_type>alloc_the allocator stored
(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.
Member functions
node-handle ::node-handle
constexpr/*node-handle*/()noexcept; (1) /*node-handle*/(/*node-handle*/&&other)noexcept; (2)(constexpr since C++26)1) The default constructor initializes the node handle to the empty state.
2) The move constructor takes ownership of the container element from other.
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
other - another node handle Notes
There is no user-provided copy destructor. node-handle is not
.
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=
/*node-handle*/&operator=(/*node-handle*/&&other);(constexpr since C++26)The move assignment operator replaces state of *this with the state of other using move semantics.
If ptr_!=nullptr is true, destroys the element referred to by *this by calling ator_traits::destroy, then deallocates the storage for the referred element by calling ator_traits::rebind_traits<container-node-type>::deallocate.
Assigns other.ptr_ to ptr_ .
If ator_traits::propagate_on_container_move_assignment is true, move assigns other.alloc_ to alloc_ .
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_==other.alloc_
Parameters
other - another node handle Return
*this
Exceptions
Throws nothing.
Notes
There is no user-provided copy assignment operator. node-handle is not
.
node-handle ::~node-handle
~/*node-handle*/();(constexpr since C++26)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
boolempty()constnoexcept;(constexpr since C++26)Returns true if the node handle is empty, false otherwise.
Return value
ptr_==nullptr
node-handle ::operator bool
explicitoperatorbool()constnoexcept;(constexpr since C++26)Converts to false if the node handle is empty, true otherwise.
Return value
ptr_!=nullptr
node-handle ::get_allocator
allocator_typeget_allocator()const;(constexpr since C++26)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)
value_type&value()const;(constexpr since C++26)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)
key_type&key()const;(constexpr since C++26)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)
mapped_type&mapped()const;(constexpr since C++26)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
voidswap(/*node-handle*/&other)noexcept(/* see below */);(constexpr since C++26)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_==other.alloc_
Exceptions
specification:
noexcept(ator_traits::propagate_on_container_swap::value||ator_traits::is_always_equal::value)Non-member functions
std::swap(node-handle )
friendvoidswap(/*node-handle*/&lhs,/*node-handle*/&rhs)noexcept(noexcept(lhs.swap(rhs)));(constexpr since C++26)Effectively executes x.swap(y).
This function is not visible to ordinary
or
, and can only be found by
when node-handle is an associated class of the arguments.