std::unordered_multimap insert() 方法

自 C++17 起

// (1) Non const version only
std::pair<iterator,bool> insert( value_type&& value );

// (2) Non const version only
template< class P >
std::pair<iterator,bool> insert( P&& value );

// (3) Non const version only
iterator insert( const_iterator hint, value_type&& value );

// (4) Non const version only
template< class P >
iterator insert( const_iterator hint, P&& value );

// (5) Non const version only
template< class InputIt >
void insert( InputIt first, InputIt last );

// (6) Non const version only
void insert( std::initializer_list<value_type> ilist );

// (7) Non const version only
insert_return_type insert( node_type&& nh );

// (8) Non const version only
iterator insert( const_iterator hint, node_type&& nh );

C++17 之前

// (1) Non const version only
std::pair<iterator,bool> insert( const value_type& value );

// (2) Non const version only
template< class P >
std::pair<iterator,bool> insert( P&& value );

// (3) Non const version only
iterator insert( const_iterator hint, const value_type& value );

// (4) Non const version only
template< class P >
iterator insert( const_iterator hint, P&& value );

// (5) Non const version only
template< class InputIt >
void insert( InputIt first, InputIt last );

// (6) Non const version only
void insert( std::initializer_list<value_type> ilist );

将元素插入到容器中，如果容器中还没有包含具有等效键的元素。

• (1-2) 插入值。

  重载 **(2)** 等价于 emplace(std::forward<P>(value))，并且仅当 std::is_constructible<value_type, P&&>::value == true 时才参与重载解析。

• (3-4) 插入值，使用提示作为非强制性建议来指示搜索应从何处开始。

  重载 **(4)** 等价于 emplace_hint(hint, std::forward<P>(value))，并且仅当 std::is_constructible<value_type, P&&>::value == true 时才参与重载解析。

• (5) 从范围 [ first; last ) 插入元素。

• (6) 从初始化列表 ilist 中插入元素。

• (7) 如果 nh 是一个空的节点句柄，则不执行任何操作。

  否则，如果容器中尚不包含与 nh.key() 等效键的元素，则将 nh 所拥有的元素插入到容器中。

未定义行为

如果 nh 不为空且 get_allocator() != nh.get_allocator()，则行为未定义。

• (8) 如果 nh 是一个空的节点句柄，则不执行任何操作并返回结束迭代器。

  否则，如果容器不包含具有与 nh.key() 等效的键的元素，则将 nh 所拥有的元素插入到容器中，并返回指向具有与 nh.key() 等效的键的元素的迭代器（无论插入成功与否）。

  如果插入成功，则 nh 被移动，否则它保留对元素的拥有权。元素尽可能接近 hint 插入。

未定义行为

如果 nh 不为空且 get_allocator() != nh.get_allocator()，则行为未定义。

自 C++17 起

失效

如果插入成功，则在节点句柄中持有时获得的指向元素的指针和引用将失效，并且在提取之前获得的指向该元素的指针和引用将变为有效。

C++17 之前

失效

如果由于插入而发生重新散列，则所有迭代器都将失效。否则，迭代器不受影响。

引用不会失效。重新散列仅在新元素数量大于 max_load_factor()*bucket_count() 时发生。

参数

• hint - 迭代器，用作插入内容的建议位置
• value - 要插入的元素值
• first, last - 要插入的元素范围
• ilist - 要从中插入值的初始化列表
• nh - 兼容的节点句柄

类型要求

• (5) - InputIt 必须满足 LegacyInputIterator 的要求。

返回值

• (1-4) - 返回指向已插入元素的迭代器。
• (5-6) - (无)
• (7-8) - 如果 nh 为空，则为结束迭代器，否则为指向已插入元素的迭代器。

复杂度

• (1-4)
  平均情况，常数 - O(1)。
  最坏情况：O(size())。

• (5-6)
  平均情况，与要插入的元素数量成线性关系 - O(N)，其中 N 是要插入的元素数量。
  最坏情况 - O(N * size() + N)。

• (7-8)
  平均情况，常数 - O(1)。
  最坏情况，与容器大小呈线性关系 - O(size())。

异常

• (1-4) 如果任何操作抛出异常，插入无效。

重要

本节需要改进。您可以通过编辑此文档页面来帮助我们。

备注

带提示的插入 (3-4) 不返回布尔值，以便与顺序容器（如 std::vector::insert()）的位置插入具有签名兼容性。这使得创建通用插入器（如 std::inserter()）成为可能。检查带提示插入成功的一种方法是比较插入前后的 size()。

示例

Main.cpp

#include <string>
#include <iostream>
#include <unordered_map>
 
int main ()
{
	std::unordered_multimap<int, std::string> dict = {{1, "one"}, {2, "two"}};
	dict.insert({3, "three"});
	dict.insert(std::make_pair(4, "four"));
	dict.insert({{4, "another four"}, {5, "five"}});

	std::cout << "contents:\n";
	for(auto& p: dict)
			std::cout << " " << p.first << " => " << p.second << '\n';
}

可能输出

contents:
 5 => five
 2 => two
 1 => one
 3 => three
 4 => another four
 4 => four