Namespaces
Variants

std::unordered_multimap<Key,T,Hash,KeyEqual,Allocator>:: extract

From cppreference.net

C++
Containers library
std::unordered_multimap
Member types
Member functions
Non-member functions
Deduction guides (C++17)
node_type extract ( const_iterator pos ) ;
(1) (自 C++17 起)
(自 C++26 起为 constexpr)
node_type extract ( const Key & k ) ;
(2) (自 C++17 起)
(自 C++26 起为 constexpr)
template < class K >
node_type extract ( K && x ) ;
(3) (自 C++23 起)
(自 C++26 起为 constexpr)
1) 解除包含由 pos 指向元素的节点链接，并返回拥有该节点的 node handle 。
2,3) 若容器中存在键等价于 k 或 x (since C++23) 的元素，则从容器解链包含该首个元素的节点，并返回拥有该节点的 node handle 。否则返回空节点句柄。
3) 此重载仅当 Hash 与 KeyEqual 均为 透明函数对象 ，且 iterator 与 const_iterator 均不能从 K 隐式转换时，才参与重载决议。该设计假定此类 Hash 可同时被 K 和 Key 类型调用，且 KeyEqual 具有透明性，二者结合使得无需构造 Key 的实例即可调用此函数。

无论哪种情况，都不会复制或移动元素，仅重新指向容器节点的内部指针。

提取节点只会使指向被提取元素的迭代器失效，同时保持未被擦除元素的相对顺序。指向被提取元素的指针和引用仍然有效，但在元素由节点句柄拥有期间不可使用：若该元素被插入到容器中，这些指针和引用将恢复可用性。

目录

参数

pos - 指向该容器的有效迭代器
k - 用于标识待提取节点的键
x - 可与标识待提取节点的键进行透明比较的任意类型值

返回值

一个 node handle ，它拥有被提取的元素，或者在 (2,3) 中未找到该元素的情况下返回空的node handle。

异常

1) 不抛出任何异常。
2,3) 由 Hash 和 KeyEqual 对象抛出的任何异常。

复杂度

1-3) 平均情况 O(1)，最坏情况 O( size() )。

注释

extract 是无需重新分配即可更改映射元素键的唯一方式： 

std::map<int, std::string> m{{1, "mango"}, {2, "papaya"}, {3, "guava"}};
auto nh = m.extract(2);
nh.key() = 4;
m.insert(std::move(nh));
// m == {{1, "mango"}, {3, "guava"}, {4, "papaya"}}
功能测试 宏 值 标准 功能特性
__cpp_lib_associative_heterogeneous_erasure 202110L (C++23) 关联容器 和 无序关联容器 中的异构擦除， ( 3 )

示例

运行此代码 
#include <algorithm>
#include <iostream>
#include <string_view>
#include <unordered_map>
void print(std::string_view comment, const auto& data)
{
    std::cout << comment;
    for (auto [k, v] : data)
        std::cout << ' ' << k << '(' << v << ')';
    std::cout << '\n';
}
int main()
{
    std::unordered_multimap<int, char> cont{{1, 'a'}, {2, 'b'}, {3, 'c'}};
    print("Start:", cont);
    // 提取节点句柄并修改键
    auto nh = cont.extract(1);
    nh.key() = 4;
    print("After extract and before insert:", cont);
    // 将节点句柄插回
    cont.insert(std::move(nh));
    print("End:", cont);
}

可能的输出： 

Start: 1(a) 2(b) 3(c)
After extract and before insert: 2(b) 3(c)
End: 2(b) 3(c) 4(a)

另请参阅

(C++17)
从另一容器接合节点
(公开成员函数)
插入元素 或节点 (C++17 起)
(公开成员函数)
擦除元素
(公开成员函数)