Node handle (C++17)

 

C++

Compiler support

Freestanding and hosted

Language

Standard library

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Metaprogramming library (C++11)

Diagnostics library

General utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Concurrency support library (C++11)

Execution support library (C++26)

Technical specifications

Symbols index

External libraries

 

Containers library

Sequence

array (C++11)

vector

vector<bool>

inplace_vector (C++26)

deque

forward_list (C++11)

list

Associative

set

multiset

map

multimap

Unordered associative

unordered_set (C++11)

unordered_multiset (C++11)

unordered_map (C++11)

unordered_multimap (C++11)

Adaptors

stack

queue

priority_queue

flat_set (C++23)

flat_multiset (C++23)

flat_map (C++23)

flat_multimap (C++23)

Views

span (C++20)

mdspan (C++23)

Tables

Iterator invalidation

Member function table

Non-member function table

 

template</*unspecified*/> class /*unspecified*/		(since C++17)

Associative containers std::set, std::map, std::multiset, std::multimap, std::unordered_set, std::unordered_map, std::unordered_multiset, std::unordered_multimap 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 value_type) stored in the node, and provides non-const access to the key part of the element (the key_type) and the mapped part of the element (the mapped_type). If the node handle is allowed to destruct 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 is unspecified, but each container exposes its node handle type as the member node_type.

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::map can be inserted into an std::multimap, but not into std::unordered_map or std::set.

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 extract.

Member types

Member 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

Member functions

node handle::node_handle

constexpr node_handle()	(1)	(node_handle is implementation-defined)
node_handle(node_handle&& nh)	(2)	(node_handle is implementation-defined)

1) The default constructor initializes the node handle to the empty state.

2) The move constructor takes ownership of the container element from nh, move-constructs the member allocator, and leaves nh in the empty state.

Parameters

nh

-

a node handle with the same type (not necessarily the same container)

Exceptions

1)

noexcept specification:  

noexcept

  

2)

noexcept specification:  

noexcept

  

Notes

Node handles are move-only, the copy constructor is not defined.

node handle::operator=

node_handle& operator=(node_handle&& nh);		(node_handle is implementation-defined)

• If the node handle is not empty,

• destroys the value_type subobject in the container element object managed by this node handle by calling std::allocator_traits<allocator_type>::destroy
• deallocates the container element by calling allocator_traits<allocator_type>::rebind_traits<container-node-type>::deallocate

• Acquires ownership of the container element from nh
• If node handle was empty (and so did not contain an allocator) or if allocator_traits<allocator_type>::propagate_on_container_move_assignment is true, move-assigns the allocator from nh
• sets nh to the empty state

The behavior is undefined if the node is not empty and allocator_traits<allocator_type>::propagate_on_container_move_assignment is false and the allocators do not compare equal.

Parameters

nh

-

a node handle with the same type (not necessarily the same container)

Return

Exceptions

(none)

Notes

Node handles are move-only, the copy assignment is not defined.

node handle::~node_handle

~node_handle();

• If the node handle is not empty,

• destroys the value_type subobject in the container element object managed by this node handle by calling std::allocator_traits<allocator_type>::destroy
• deallocates the container element by calling allocator_traits<allocator_type>::rebind_traits<container-node-type>::deallocate

Exceptions

(none)

node handle::empty

bool empty() const;

Returns true if the node handle is empty, false otherwise.

Exceptions

noexcept specification:  

noexcept

  

node handle::operator bool

explicit operator bool() const;

Converts to false if the node handle is empty, true otherwise.

Exceptions

noexcept specification:  

noexcept

  

node handle::get_allocator

allocator_type get_allocator() const;

Returns a copy of the stored allocator (which is a copy of the allocator of the source container). The behavior is undefined if the node handle is empty.

Exceptions

(none)

node handle::value

value_type& value() const;		(set containers only)

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

Exceptions

(none)

node handle::key

key_type& key() const;		(map containers only)

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

Exceptions

(none)

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

mapped_type& mapped() const;		(map containers only)

Returns a reference to the mapped_type member of the value_type subobject in the container element object managed by this node handle. The behavior is undefined if the node handle is empty.

Exceptions

(none)

node handle::swap

void swap(node_handle& nh)

• swaps ownership of container nodes
• if one node is empty or if both nodes are non-empty and std::allocator_traits<allocator_type>::propagate_on_container_swap is true, swaps the allocators as well

The behavior is undefined if both nodes are not empty and allocator_traits<allocator_type>::propagate_on_container_swap is false and the allocators do not compare equal.

Exceptions

noexcept specification:  

noexcept(std::allocator_traits<allocator_type>::propagate_on_container_swap::value ||
 std::allocator_traits<allocator_type>::is_always_equal::value)

Non-member functions

swap

friend void swap(node_handle& x, node_handle& y)

Effectively executes x.swap(y)

Exceptions

noexcept specification:  

noexcept(noexcept(x.swap(y)))