節點控制代碼 (C++17)
template</* 未指定 */> class /*node-handle*/; |
(C++17 起) (僅作說明*) |
|
關聯容器 std::set, std::map, std::multiset, std::multimap, std::unordered_set, std::unordered_map, std::unordered_multiset, std::unordered_multimap 是基於節點的D資料結構，它們的節點可以作為一種未指定型別的物件提取，這種物件被稱為 *節點控制代碼*。
節點控制代碼是一種僅可移動的型別，它擁有並提供對節點中儲存的元素（value_type）的訪問，並提供對元素的鍵部分（key_type）和對映部分（mapped_type）的非 const 訪問。如果節點控制代碼在持有節點時被銷燬，則會使用容器的相應分配器正確銷燬節點。節點控制代碼包含容器分配器的副本。這是必要的，以便節點控制代碼可以比容器壽命更長。
節點控制代碼的確切型別（此處顯示為 /*node-handle*/）未指定，但每個容器都將其節點控制代碼型別公開為成員 node_type。
節點控制代碼可用於在兩個關聯容器之間傳輸元素的擁有權，這兩個容器具有相同的鍵、值和分配器型別（忽略比較或雜湊/相等），而無需對容器元素呼叫任何複製/移動操作（這種操作被稱為“拼接”）。也允許在唯一和非唯一容器之間進行傳輸：來自 std::map 的節點控制代碼可以插入到 std::multimap 中，但不能插入到 std::unordered_map 或 std::set 中。
節點控制代碼可以為空，在這種情況下，它不持有任何元素或分配器。預設構造和移動構造的節點控制代碼為空。此外，透過呼叫容器成員函式 extract 失敗也可以生成空節點控制代碼。
如果元素成功插入到容器中，則在節點控制代碼擁有元素時獲得的指向元素的指標和引用將失效。
對於所有 map 容器（std::map、std::multimap、std::unordered_map 和 std::unordered_multimap），如果其 key_type 為 K 且 mapped_type 為 T，並且存在 std::pair<K, T> 或 std::pair<const K, T> 的使用者定義特化，則涉及節點控制代碼的操作行為未定義。
目錄 |
[編輯] 成員型別
| 型別 | 定義 |
key_type (僅限 map 容器) |
儲存在節點中的鍵 |
mapped_type (僅限 map 容器) |
儲存在節點中的元素的對映部分 |
value_type (僅限 set 容器) |
儲存在節點中的元素 |
allocator_type
|
銷燬元素時要使用的分配器 |
container_node_type (私有) |
容器節點，型別未指定 (僅供說明的成員型別*) |
ator_traits (私有) |
型別為 std::allocator_traits<allocator_type> 的分配器特性 (僅供說明的成員型別*) |
[編輯] 資料成員
| 成員 | 定義 |
| typename ator_traits::template rebind_traits<container_node_type>::pointer ptr_(有條件存在) |
待辦 (僅用於闡釋的成員物件*) |
std::optional<allocator_type> alloc_(有條件存在) |
待辦 (僅用於闡釋的成員物件*) |
[編輯] 成員函式
建構函式
| constexpr /*node-handle*/() noexcept; |
(1) | |
| /*node-handle*/(/*node-handle*/&& nh) noexcept; |
(2) | |
引數
| nh | - | 具有相同型別（不一定是相同容器）的節點控制代碼 |
注意
節點控制代碼是僅可移動的，未定義複製建構函式。
operator=
| /*node-handle*/& operator=(/*node-handle*/&& nh); |
||
- 如果節點控制代碼不為空，則
- 透過呼叫
ator_traits::destroy銷燬此節點控制代碼管理的容器元素物件中的value_type子物件； - 透過呼叫 ator_traits::rebind_traits</*container-node-type*/>::deallocate 解分配容器元素；
- 透過呼叫
- 從 nh 獲得容器元素的擁有權；
- 如果節點控制代碼為空（因此不包含分配器）或如果 ator_traits::propagate_on_container_move_assignment 為 true，則從 nh 移動賦值分配器；
- 將 nh 設定為空狀態。
如果節點不為空且 ator_traits::propagate_on_container_move_assignment 為 false 並且分配器不相等，則行為未定義。
引數
| nh | - | 具有相同型別（不一定是相同容器）的節點控制代碼 |
返回
*this
異常
不丟擲任何異常。
注意
節點控制代碼是僅可移動的，未定義複製賦值。
解構函式
| ~/*node-handle*/(); |
||
- 如果節點控制代碼不為空，則
- 透過呼叫 ator_traits::destroy 銷燬此節點控制代碼管理的容器元素物件中的
value_type子物件； - 透過呼叫 ator_traits::rebind_traits</*container-node-type*/>::deallocate 解分配容器元素。
- 透過呼叫 ator_traits::destroy 銷燬此節點控制代碼管理的容器元素物件中的
empty
| bool empty() const noexcept; |
||
如果節點控制代碼為空，則返回 true，否則返回 false。
operator bool
| explicit operator bool() const noexcept; |
||
如果節點控制代碼為空，則轉換為 false，否則轉換為 true。
get_allocator
| allocator_type get_allocator() const; |
||
返回儲存的分配器（源容器分配器的副本）。如果節點控制代碼為空，則行為未定義。
異常
不丟擲任何異常。
value
| value_type& value() const; |
(僅限 set 容器) | |
返回對此節點控制代碼管理的容器元素物件中的 value_type 子物件的引用。如果節點控制代碼為空，則行為未定義。
異常
不丟擲任何異常。
key
| key_type& key() const; |
(僅限 map 容器) | |
返回對此節點控制代碼管理的容器元素物件中的 value_type 子物件的 key_type 成員的非 const 引用。如果節點控制代碼為空，則行為未定義。
異常
不丟擲任何異常。
注意
此函式使得修改從 map 中提取的節點的鍵成為可能，然後將其重新插入到 map 中，而無需複製或移動元素。
mapped
| mapped_type& mapped() const; |
(僅限 map 容器) | |
返回對此節點控制代碼管理的容器元素物件中的 value_type 子物件的 mapped_type 成員的引用。如果節點控制代碼為空，則行為未定義。
異常
不丟擲任何異常。
swap
| void swap(/*node-handle*/& nh) noexcept(/* 見下文 */); |
||
- 交換容器節點的擁有權；
- 如果一個節點為空或者兩個節點都不為空且 ator_traits::propagate_on_container_swap 為 true，則也交換分配器。
如果兩個節點都不為空且 ator_traits::propagate_on_container_swap 為 false 並且分配器不相等，則行為未定義。
異常
ator_traits::is_always_equal::value)
