node-handle
template</* 未指定 */> class /*node-handle*/; |
(C++17 起) (仅用于阐述*) |
|
节点把柄 是可以从关联容器和无序关联容器接受单个元素的所有权的对象。它可以用来将该所有权转移给具有兼容节点的另一容器。
节点把柄可以有以下两种状态之一：
- 指代从容器提取的某个元素
- 空
如果节点把柄非空，那么它同时会包含一个与先前被提取的容器的分配器相等的分配器。
对于所有 key_type 是 K 而 mapped_type 是 T 的映射容器（std::map、std::multimap、std::unordered_map 及 std::unordered_multimap），如果对 std::pair<K, T> 或 std::pair<const K, T> 存在 std::pair 的用户定义特化，那么涉及节点把柄的操作行为未定义。
嵌套类型
| 类型 | 定义 |
key_type (仅限 map 容器)
|
在节点存储的关键 |
mapped_type (仅限 map 容器)
|
在节点存储的元素的被映射部分 |
value_type (仅限集合容器)
|
节点中存储的元素 |
allocator_type
|
销毁元素时使用的分配器 |
container_node_type
|
未指定 (仅用于阐述的成员类型*) |
ator_traits
|
std::allocator_traits<allocator_type>(仅用于阐述的成员类型*) |
不是仅用于阐述的嵌套类型的实际定义见关联容器 (AssociativeContainer) 和无序关联容器 (UnorderedAssociativeContainer) 。
数据成员
| 成员 | 定义 |
|
|
指向包含被指代对象的容器节点[1]的指针 (仅用于阐述的成员对象*) |
std::optional<allocator_type> alloc_
|
储存的分配器 (仅用于阐述的成员对象*) |
- ↑ 指向的容器节点的所有权已经在提取元素时从源容器脱离。源容器的生存期结束后依然可以访问容器节点和它包含的元素。
成员函数
node-handle ::node-handle
<tbody> </tbody> constexpr /*node-handle*/() noexcept; |
(1) | |
/*node-handle*/( /*node-handle*/&& other ) noexcept; |
(2) | (C++26 起为 constexpr) |
other 取走容器元素所有权。
- 以
other.ptr_初始化ptr_。 - 以
other.alloc_移动构造alloc_。 - 将
nullptr赋给other.ptr_。 - 将
std::nullopt赋给other.ptr_。
参数
| other | - | 另一节点把柄 |
注解
没有用户定义的复制构造函数。node-handle 不可复制构造 (CopyConstructible) 。
除了移动构造和移动赋值以外，只有通过调用（无序）关联容器的 extract 成员函数才能创造非空的 node-handle。
node-handle ::operator=
<tbody> </tbody>/*node-handle*/& operator=( /*node-handle*/&& other ); |
(C++26 起为 constexpr) | |
移动赋值运算符用移动语义以 other 的状态替换 *this 的状态。
- 如果
ptr_!= nullptr是true，通过调用ator_traits::destroy销毁*this指代的元素，然后通过调用ator_traits::rebind_traits<container-node-type>::deallocate解分配指代的元素使用的存储。 - 将
other.ptr_赋给ptr_。 - 如果
ator_traits::propagate_on_container_move_assignment是true，那么将other.alloc_移动赋值给alloc_。 - 将
nullptr赋给other.ptr_，并将std::nullopt赋给other.alloc_。
如果以下所有值都是 false，那么行为未定义：
ator_traits::propagate_on_container_move_assignment!alloc_alloc_== other.alloc_
参数
| other | - | 另一节点把柄 |
返回值
*this
异常
不抛出。
注解
没有用户定义的复制赋值运算符。node-handle 不可复制赋值 (CopyAssignable) 。
node-handle ::~node-handle
<tbody> </tbody>~/*node-handle*/(); |
(C++26 起为 constexpr) | |
如果 ptr_ != nullptr 是 true，通过调用 ator_traits ::destroy 销毁 *this 指代的元素，然后通过调用 ator_traits ::rebind_traits<container-node-type >::deallocate 解分配指代的元素使用的存储。
node-handle ::empty
<tbody> </tbody>bool empty() const noexcept; |
(C++26 起为 constexpr) | |
节点把柄为空时返回 true，否则返回 false。
返回值
ptr_ == nullptr
node-handle ::operator bool
<tbody> </tbody>explicit operator bool() const noexcept; |
(C++26 起为 constexpr) | |
节点把柄为空时转换成 false，否则转换成 true。
返回值
ptr_ != nullptr
node-handle ::get_allocator
<tbody> </tbody>allocator_type get_allocator() const; |
(C++26 起为 constexpr) | |
返回存储的分配器的副本。
如果 empty() 是 true，那么行为未定义。
返回值
*alloc_
异常
不抛出。
node-handle ::value (仅限集合容器)
<tbody> </tbody>value_type& value() const; |
(C++26 起为 constexpr) | |
返回到 *this 指代的元素的引用。
如果 empty() 是 true，那么行为未定义。
返回值
如上所述。
异常
不抛出。
node-handle ::key (仅限映射容器)
<tbody> </tbody>key_type& key() const; |
(C++26 起为 constexpr) | |
返回到 *this 指代的元素的 key_type 成员的非 const 引用。
如果 empty() 是 true，那么行为未定义。
返回值
如上所述。
异常
不抛出。
注解
此函数使得能够在不复制或移动元素的情况下直接修改从映射提取的节点的键，再重新插入到映射。
node-handle ::mapped (仅限映射容器)
<tbody> </tbody>mapped_type& mapped() const; |
(C++26 起为 constexpr) | |
返回到 *this 指代的元素的 mapped_type 成员的非 const 引用。
如果 empty() 是 true，那么行为未定义。
返回值
如上所述。
异常
不抛出。
node-handle ::swap
<tbody> </tbody>void swap( /*node-handle*/& other ) noexcept(/* 见下文 */); |
(C++26 起为 constexpr) | |
调用 swap(ptr_ , nh.ptr_ )。如果以下任意值是 true，那么也会调用 swap(alloc_ , nh.alloc_ )：
ator_traits::propagate_on_container_swap!alloc_!other.alloc_
如果以下所有值都是 false，那么行为未定义：
ator_traits::propagate_on_container_swap!alloc_!other.alloc_alloc_== other.alloc_
异常
noexcept(ator_traits::propagate_on_container_swap::value || ator_traits::is_always_equal::value)