node-handle

 

C++

编译器支持

自立实现与有宿主实现

语言

标准库

标准库标头

具名要求

功能特性测试宏(C++20)

语言支持库

概念库(C++20)

诊断库

内存管理库

元编程库(C++11)

通用工具库

容器库

迭代器库

范围库(C++20)

算法库

字符串库

文本处理库

数值库

日期和时间库

输入/输出库

文件系统库(C++17)

并发支持库(C++11)

执行控制库(C++26)

技术规范

符号索引

外部库

 

容器库

node-handle (C++17)

序列容器

array (C++11)

vector

vector<bool>

inplace_vector (C++26)

hive (C++26)

deque

forward_list (C++11)

list

关联容器

set

multiset

map

multimap

无序关联容器

unordered_set (C++11)

unordered_multiset (C++11)

unordered_map (C++11)

unordered_multimap (C++11)

容器适配器

stack

queue

priority_queue

flat_set (C++23)

flat_multiset (C++23)

flat_map (C++23)

flat_multimap (C++23)

视图

span (C++20)

mdspan (C++23)

表格

迭代器失效

成员函数表格

非成员函数表格

 

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(仅限映射容器)	在节点存储的关键
mapped_type(仅限映射容器)	在节点存储的元素的被映射部分
value_type(仅限集合容器)	节点中存储的元素
allocator_type	销毁元素时使用的分配器
container_node_type	未指定 (仅用于阐述的成员类型*)
ator_traits	std::allocator_traits<allocator_type> (仅用于阐述的成员类型*)

不是仅用于阐述的嵌套类型的实际定义见关联容器(AssociativeContainer) 和无序关联容器(UnorderedAssociativeContainer) 。

数据成员

成员	定义
typename ator_traits ::template     rebind_traits<container_node_type >::pointerptr_	指向包含被指代对象的容器节点的指针 (仅用于阐述的成员对象*)
std::optional<allocator_type>alloc_	储存的分配器 (仅用于阐述的成员对象*)

成员函数

node-handle ::node-handle

constexpr/*node-handle*/()noexcept;	(1)
/*node-handle*/(/*node-handle*/&& other )noexcept;	(2)	(C++26 起为 constexpr)

1) 默认构造函数初始化节点把柄为空状态。

2) 移动构造函数从 other 取走容器元素所有权。

• 以 other.ptr_ 初始化 ptr_。
• 以 other.alloc_ 移动构造 alloc_。
• 将 nullptr 赋给 other.ptr_。
• 将 std::nullopt 赋给 other.ptr_。

参数

other

-

另一节点把柄

注解

没有用户定义的复制构造函数。node-handle 不可复制构造(CopyConstructible) 。

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

node-handle ::operator=

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

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

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 不可复制赋值(CopyAssignable) 。

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()constnoexcept;		(C++26 起为 constexpr)

节点把柄为空时返回 true，否则返回 false。

返回值

ptr_ == nullptr

node-handle ::operator bool

explicit operator bool()constnoexcept;		(C++26 起为 constexpr)

节点把柄为空时转换成 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 (仅限映射容器)

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

返回到 *this 指代的元素的 key_type 成员的非 const 引用。

如果 empty() 是 true，那么行为未定义。

返回值

如上所述。

异常

不抛出。

注解

此函数使得能够在不复制或移动元素的情况下直接修改从映射提取的节点的键，再重新插入到映射。

node-handle ::mapped (仅限映射容器)

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

返回到 *this 指代的元素的 mapped_type 成员的非 const 引用。

如果 empty() 是 true，那么行为未定义。

返回值

如上所述。

异常

不抛出。

node-handle ::swap

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 说明：  

noexcept(ator_traits::propagate_on_container_swap::value||
         ator_traits::is_always_equal::value)

非成员函数

std::swap(node-handle )

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

实际上执行 x.swap(y)。

此函数对常规的无限定或有限定查找不可见，而只能在 node-handle 为实参的关联类时由实参依赖查找找到。