node-handle
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 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>.
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_type
|
the allocator to be used when destroying the element |
container_node_type
|
unspecified (exposition-only member type*) |
ator_traits
|
std::allocator_traits<allocator_type>(exposition-only member type*) |
See AssociativeContainer and UnorderedAssociativeContainer for the actual definitions of the non-exposition-only nested types.
Data members
| Member | Description |
|
|
a pointer to a container node containing the referred object[1] (exposition-only member object*) |
std::optional<allocator_type> alloc_
|
the allocator stored (exposition-only member object*) |
Member functions
node-handle ::node-handle
constexpr /*node-handle*/() noexcept;
|
(1) | |
/*node-handle*/( /*node-handle*/&& other ) noexcept;
|
(2) | (constexpr since C++26) |
other.
ptr_is initialized withother.ptr_.alloc_is move constructed withother.alloc_.- Assigns
nullptrtoother.ptr_. - Assigns
std::nullopttoother.ptr_.
Parameters
| other | - | another node handle |
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=
/*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_!= nullptristrue, destroys the element referred to by*thisby callingator_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_assignmentistrue, move assignsother.alloc_toalloc_. - Assigns
nullptrtoother.ptr_and assignsstd::nullopttoother.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 CopyAssignable.
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
bool empty() const noexcept;
|
(constexpr since C++26) | |
Returns true if the node handle is empty, false otherwise.
Return value
ptr_ == nullptr
node-handle ::operator bool
explicit operator bool() const noexcept;
|
(constexpr since C++26) | |
Converts to false if the node handle is empty, true otherwise.
Return value
ptr_ != nullptr
node-handle ::get_allocator
allocator_type get_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
void swap( /*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
noexcept(ator_traits::propagate_on_container_swap::value || ator_traits::is_always_equal::value)
Non-member functions
std::swap(node-handle )
friend void swap(/*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 unqualified or qualified lookup, and can only be found by argument-dependent lookup when node-handle is an associated class of the arguments.