std::unordered_map<Key,T,Hash,KeyEqual,Allocator>::try_emplace

来自cppreference.com
See More

[编辑模板]
 
C++
 
容器库
 
std::unordered_map
成员类型
成员函数
非成员函数
推导指引(C++17)
 
<tbody> </tbody>
template< class... Args > std::pair<iterator, bool> try_emplace( const Key& k, Args&&... args );
 (1) (C++17 起)
template< class... Args > std::pair<iterator, bool> try_emplace( Key&& k, Args&&... args );
 (2) (C++17 起)
template< class K, class... Args > std::pair<iterator, bool> try_emplace( K&& k, Args&&... args );
 (3) (C++26 起)
template< class... Args > iterator try_emplace( const_iterator hint, const Key& k, Args&&... args );
 (4) (C++17 起)
template< class... Args > iterator try_emplace( const_iterator hint, Key&& k, Args&&... args );
 (5) (C++17 起)
template< class K, class... Args > iterator try_emplace( const_iterator hint, K&& k, Args&&... args );
 (6) (C++26 起)

如果容器中已经存在等价于 k 的键，则不做任何事。否则，向容器插入具有键 k 和以 args 构造的值的新元素。这种情况下：

1) 行为类似 emplace，但以
value_type(std::piecewise_construct, std::forward_as_tuple(k), std::forward_as_tuple(std::forward<Args>(args)...)) 构造元素。
2) 行为类似 emplace，但以
value_type(std::piecewise_construct, std::forward_as_tuple(std::move(k)), std::forward_as_tuple(std::forward<Args>(args)...)) 构造元素。
3) 行为类似 emplace，但以
value_type(std::piecewise_construct, std::forward_as_tuple(std::forward<K>(k)), std::forward_as_tuple(std::forward<Args>(args)...)) 构造元素。
4) 行为类似 emplace_hint，但以
value_type(std::piecewise_construct, std::forward_as_tuple(k), std::forward_as_tuple(std::forward<Args>(args)...)) 构造元素。
5) 行为类似 emplace_hint，但以
value_type(std::piecewise_construct, std::forward_as_tuple(std::move(k)), std::forward_as_tuple(std::forward<Args>(args)...)) 构造元素。
6) 行为类似 emplace_hint，但以
value_type(std::piecewise_construct, std::forward_as_tuple(std::forward<K>(k)), std::forward_as_tuple(std::forward<Args>(args)...)) 构造元素。
1-6) 如果 value_type 从对应表达式不可就位构造 (EmplaceConstructible) 到 unordered_map 中，那么行为未定义。
3) 此重载只有在满足以下所有条件时才会参与重载决议：
  • std::is_convertible_v<K&&, const_iterator> 和 std::is_convertible_v<K&&, iterator> 都是 false。
  • Hash::is_transparent 和 KeyEqual::is_transparent 都有效并各自代表某个类型。
如果 hash_function()(u.first) != hash_function()(k) || contains(u.first) 是 true，那么行为未定义，其中 u 是待插入的新元素。
6) 此重载只有在 Hash::is_transparent 和 KeyEqual::is_transparent 都有效并各自代表某个类型时才会参与重载决议。
如果 hash_function()(u.first) != hash_function()(k) || contains(u.first) 是 true，那么行为未定义，其中 u 是待插入的新元素。

如果操作后新的元素数量大于原 max_load_factor() * bucket_count() 则会发生重散列。
如果（因插入而）发生了重散列，所有迭代器均会失效。否则（未发生重散列），则迭代器不会失效。

参数

k - 用于查找和在找不到时插入的键
hint - 指向位置的迭代器，新元素将插入到它之前
args - 转发给元素构造函数的实参

返回值

1-3) 同 emplace:
由一个指向被插入元素（或指向妨碍插入的元素）的迭代器和一个当且仅当发生插入时被设为 true 的 bool 值构成的对偶。
4-6) 同 emplace_hint:
指向被插入元素或指向妨碍插入的元素的迭代器。

复杂度

1-3) 同 emplace:

平均为均摊常数，最差情况为与容器大小成线性。

4-6) 同 emplace_hint:

平均为均摊常数，最差情况为与容器大小成线性。

注解

与 insert 或 emplace 不同，如果没有插入，那么这些函数不会移动右值实参，这样操纵仅移动类型的值的映射会更容易，例如 std::unordered_map<std::string, std::unique_ptr<foo>>。另外，try_emplace 分开处理键和给 mapped_type 的实参，这点与要求实参构造 value_type（即一个 std::pair）的 emplace 不同。

重载 (3,6) 在不构造 Key 类型对象的情况下也可以调用。

功能特性测试宏 值 标准 功能特性
__cpp_lib_unordered_map_try_emplace 201411L (C++17) std::unordered_map::try_emplace,
std::unordered_map::insert_or_assign
__cpp_lib_associative_heterogeneous_insertion 202311L (C++26) 有序和无序关联容器中剩余成员函数的异质重载。重载 (3) 和 (6)。

示例

运行此代码
#include <iostream>
#include <string>
#include <unordered_map>
#include <utility>

void print_node(const auto& node)
{
    std::cout << '[' << node.first << "] = " << node.second << '\n';
}

void print_result(auto const& pair)
{
    std::cout << (pair.second ? "插入：" : "忽略：");
    print_node(*pair.first);
}

int main()
{
    using namespace std::literals;
    std::unordered_map<std::string, std::string> m;
    
    print_result(m.try_emplace("a", "a"s));
    print_result(m.try_emplace("b", "abcd"));
    print_result(m.try_emplace("c", 10, 'c'));
    print_result(m.try_emplace("c", "Won't be inserted"));
    
    for (const auto& p : m)
        print_node(p);
}

可能的输出： 

插入：[a] = a
插入：[b] = abcd
插入：[c] = cccccccccc
忽略：[c] = cccccccccc
[a] = a
[b] = abcd
[c] = cccccccccc

参阅

 原位构造元素
(公开成员函数) [编辑]
使用提示原位构造元素
(公开成员函数) [编辑]
插入元素或节点(C++17 起)
(公开成员函数) [编辑]