Namespaces
Variants

node-handle

From cppreference.net
C++
Containers library
template < /* 未指定 */ >
class /*节点句柄*/ ;
(C++17 起)
( 仅用于说明* )

节点句柄 是一种对象，它接受来自 关联容器 和 无序关联容器 中单个元素的所有权。它可用于将该所有权转移至具有兼容节点的其他容器。

节点句柄有两种可能状态：

  • 它指代从容器中提取的元素，或
  • 它是 空  的。

如果节点句柄非空，则其包含的分配器与先前被提取容器的分配器相等。

对于所有键类型为 Key 、映射类型为 T 的映射容器（ std::map 、 std::multimap 、 std::unordered_map 和 std::unordered_multimap ），若存在针对 std:: pair < Key, T > 或 std:: pair < const Key, T > 的用户自定义 std::pair 特化，则涉及节点句柄的操作行为是未定义的。

目录

嵌套类型

类型 定义
key_type (仅限 map 容器) 节点中存储的键
mapped_type (仅限 map 容器) 节点中存储元素的映射部分
value_type (仅限 set 容器) 节点中存储的元素
allocator_type 销毁元素时使用的分配器
container_node_type 未指定
( 仅用于说明的成员类型* )
ator_traits std:: allocator_traits < allocator_type >
( 仅用于说明的成员类型* )

请参阅 AssociativeContainer 和 UnorderedAssociativeContainer 以了解非仅用于说明的嵌套类型的实际定义。

数据成员

成员 描述

typename ator_traits  :: template
rebind_traits < container_node_type  > :: pointer

ptr_ 		指向包含被引用对象的容器节点的指针 [1]
( 仅用于说明的成员对象* )
std:: optional < allocator_type > alloc_ 存储的分配器
( 仅用于说明的成员对象* )
  1. ↑ 在提取元素时，指向容器节点的所有权已从源容器分离。即使源容器的生命周期已结束，容器节点及其包含的元素仍然可访问。

成员函数

node-handle  :: node-handle

constexpr /*node-handle*/ ( ) noexcept ;
(1)
/*node-handle*/ ( /*node-handle*/ && other ) noexcept ;
(2) (constexpr since C++26)
1) 默认构造函数将节点句柄初始化为空状态。
2) 移动构造函数从 other 获取容器元素的所有权。
  • ptr_ 由 other. ptr_ 初始化。
  • alloc_ 通过移动构造从 other. alloc_ 获得。
  • 将 nullptr 赋值给 other. ptr_ 。
  • 将 std:: nullopt 赋值给 other. ptr_ 。

参数

other - 另一个节点句柄

备注

不存在用户提供的复制析构函数。 node-handle 不满足 CopyConstructible 要求。

除了移动构造和移动赋值外，非空的 node-handle 只能通过调用（无序）关联容器的 extract 成员函数创建。

node-handle  :: operator=

/*node-handle*/ & operator = ( /*node-handle*/ && other ) ;
(自 C++26 起为 constexpr)

移动赋值运算符使用移动语义将 * this 的状态替换为 other 的状态。

  1. 若 ptr_ ! = nullptr 为 true ，则通过调用 ator_traits  :: destroy 销毁 * this 所引用的元素，随后通过调用 ator_traits  :: rebind_traits < container-node-type  > :: deallocate 释放所引用元素的存储空间。
  2. 将 other. ptr_ 赋值给 ptr_ 。
  3. 若 ator_traits  :: propagate_on_container_move_assignment 为 true ，则移动赋值 other. alloc_ 给 alloc_ 。
  4. 将 nullptr 赋值给 other. ptr_ ，并将 std:: nullopt 赋值给 other. alloc_ 。

若以下值均为 false ，则行为未定义：

  • ator_traits  :: propagate_on_container_move_assignment
  • ! alloc_
  • alloc_ == other. alloc_

参数

other - 另一个节点句柄

返回值

* this

异常

不抛出任何异常。

注解

不存在用户提供的复制赋值运算符。 node-handle 不满足 可复制赋值 要求。

node-handle  :: ~ node-handle

~ /*node-handle*/ ( ) ;
(自 C++26 起为 constexpr)

若 ptr_ ! = nullptr 为 true ，则通过调用 ator_traits  :: destroy 销毁由 * this 所引用的元素，随后通过调用 ator_traits  :: rebind_traits < container-node-type  > :: deallocate 释放容器元素的内存。

否则，不执行任何操作。

node-handle  :: empty

bool empty ( ) const noexcept ;
(constexpr since C++26)

若节点句柄为空则返回 true ，否则返回 false 。

返回值

ptr_ == nullptr

node-handle  :: operator bool

explicit operator bool ( ) const noexcept ;
(constexpr since C++26)

当节点句柄为空时转换为 false ，否则转换为 true 。

返回值

ptr_ ! = nullptr

node-handle  :: get_allocator

allocator_type get_allocator ( ) const ;
(自 C++26 起为 constexpr)

返回存储的分配器的副本。

如果 empty ( ( ) 为 true ，则行为未定义。

返回值

* alloc_

异常

不抛出任何异常。

node-handle  :: value (仅限集合容器)

value_type & value ( ) const ;
(自 C++26 起为 constexpr)

返回指向 * this 所引用元素的引用。

若 empty ( ) 为 true ，则行为未定义。

返回值

如上所述。

异常

不抛出任何异常。

node-handle  :: key (仅限 map 容器)

key_type & key ( ) const ;
(自 C++26 起为 constexpr)

返回对 * this 所引用元素的 key_type 成员的非 const 引用。

若 empty ( ) 为 true ，则行为未定义。

返回值

如上所述。

异常

不抛出任何异常。

注解

此函数使得可以修改从 map 中提取的节点的键，然后将其重新插入到 map 中，而无需复制或移动元素。

node-handle  :: mapped (仅限 map 容器)

mapped_type & mapped ( ) const ;
(自 C++26 起为 constexpr)

返回指向由 * this 所引用元素的 mapped_type 成员的引用。

若 empty ( ) 为 true ，则行为未定义。

返回值

如上所述。

异常

不抛出任何异常。

node-handle  :: swap

void swap ( /*node-handle*/ & other ) noexcept ( /* see below */ ) ;
(constexpr since C++26)

调用 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 规范：
noexcept ( ator_traits :: propagate_on_container_swap :: value ||
ator_traits :: is_always_equal :: value )

非成员函数

std::swap ( node-handle  )

friend void swap ( /*node-handle*/ & lhs, /*node-handle*/ & rhs )
noexcept ( noexcept ( lhs. swap ( rhs ) ) ) ;
(自 C++26 起为 constexpr)

效果上等同于执行 x. swap ( y ) 。

此函数对普通的 非限定查找 或 限定查找 不可见，仅当 node-handle 是实参的关联类时，才能通过 实参依赖查找 找到。