node-handle (C++17) | ||||
| Sequence | ||||
(C++11) | ||||
(C++26) | ||||
(C++26) | ||||
(C++11) | ||||
| Associative | ||||
| Unordered associative | ||||
(C++11) | ||||
(C++11) | ||||
(C++11) | ||||
(C++11) | ||||
| Adaptors | ||||
(C++23) | ||||
(C++23) | ||||
(C++23) | ||||
(C++23) | ||||
| Views | ||||
(C++20) | ||||
(C++23) | ||||
| Tables | ||||
| Iterator invalidation | ||||
| Member function table | ||||
| Non-member function table |
template</* unspecified */> class/*node-handle*/; | (since C++17) (exposition only*) | |
Anode handle is an object that accepts ownership of a single element from anassociative containers andunordered associative containers. It may be used to transfer that ownership to another container with compatible nodes.
A node handle has two possible states:
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, andstd::unordered_multimap) whosekey_type isKey andmapped_type isT, the behavior of operations involving node handles is undefined if a user-defined specialization ofstd::pair exists forstd::pair<Key, T> orstd::pair<const Key, T>.
| Type | Definition |
key_type(map containers only) | the key stored in the node[edit] |
mapped_type(map containers only) | the mapped part of the element stored in the node[edit] |
value_type(set containers only) | the element stored in the node[edit] |
allocator_type | the allocator to be used when destroying the element[edit] |
container_node_type | unspecified (exposition-only member type*) |
ator_traits | std::allocator_traits<allocator_type> (exposition-only member type*) |
SeeAssociativeContainer andUnorderedAssociativeContainer for the actual definitions of the non-exposition-only nested types.
| Member | Description |
typename ptr_ | 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*) |
constexpr/*node-handle*/()noexcept; | (1) | |
/*node-handle*/(/*node-handle*/&& other)noexcept; | (2) | (constexpr since C++26) |
ptr_ is initialized withother.ptr_.alloc_ is move constructed withother.alloc_.ptr_.ptr_.| other | - | another node handle |
There is no user-provided copy destructor.node-handle is notCopyConstructible.
Besides move construction and move assignment, a non-emptynode-handle can only be created by calling theextract member functions of (unordered) associative containers.
/*node-handle*/& operator=(/*node-handle*/&& other); | (constexpr since C++26) | |
The move assignment operator replaces state of*this with the state ofother using move semantics.
ptr_ != nullptr istrue, destroys the element referred to by*this by callingator_traits ::destroy, then deallocates the storage for the referred element by callingator_traits ::rebind_traits<container-node-type >::deallocate.ptr_ toptr_ .ator_traits ::propagate_on_container_move_assignment istrue, move assignsother.alloc_ toalloc_ .ptr_ and assignsstd::nullopt toother.alloc_.If the following values are allfalse, the behavior is undefined:
ator_traits ::propagate_on_container_move_assignmentalloc_alloc_ == other.alloc_| other | - | another node handle |
*this
Throws nothing.
There is no user-provided copy assignment operator.node-handle is notCopyAssignable.
~/*node-handle*/(); | (constexpr since C++26) | |
Ifptr_ != nullptr istrue, destroys the element referred to by*this by callingator_traits ::destroy, then deallocates the container element by callingator_traits ::rebind_traits<container-node-type >::deallocate.
Otherwise, does nothing.
bool empty()constnoexcept; | (constexpr since C++26) | |
Returnstrue if the node handle is empty,false otherwise.
ptr_ == nullptr
explicit operatorbool()constnoexcept; | (constexpr since C++26) | |
Converts tofalse if the node handle is empty,true otherwise.
ptr_ != nullptr
allocator_type get_allocator()const; | (constexpr since C++26) | |
Returns a copy of the stored allocator.
Ifempty() istrue, the behavior is undefined.
*alloc_
Throws nothing.
value_type& value()const; | (constexpr since C++26) | |
Returns a reference to the element referred to by*this.
Ifempty() istrue, the behavior is undefined.
As described above.
Throws nothing.
key_type& key()const; | (constexpr since C++26) | |
Returns a non-const reference to thekey_type member of the element referred to by*this.
Ifempty() istrue, the behavior is undefined.
As described above.
Throws nothing.
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.
mapped_type& mapped()const; | (constexpr since C++26) | |
Returns a reference to themapped_type member of the element referred to by*this.
Ifempty() istrue, the behavior is undefined.
As described above.
Throws nothing.
void swap(/*node-handle*/& other)noexcept(/* see below */); | (constexpr since C++26) | |
Callsswap(ptr_ , nh.ptr_ ). If any of the following values istrue, also callsswap(alloc_ , nh.alloc_ ):
ator_traits ::propagate_on_container_swapalloc_alloc_If the following values are allfalse, the behavior is undefined:
ator_traits ::propagate_on_container_swapalloc_alloc_alloc_ == other.alloc_friendvoid swap(/*node-handle*/& lhs,/*node-handle*/& rhs) noexcept(noexcept(lhs.swap(rhs))); | (constexpr since C++26) | |
Effectively executesx.swap(y).
This function is not visible to ordinaryunqualified orqualified lookup, and can only be found byargument-dependent lookup whennode-handle is an associated class of the arguments.
