public member function
<unordered_map>

std::unordered_multimap::insert

(1)
iterator insert ( const value_type& val );
(2)
template <class P>
    iterator insert ( P&& val );
(3)
iterator insert ( const_iterator hint, const value_type& val );
(4)
template <class P>
    iterator insert ( const_iterator hint, P&& val );
(5)
template <class InputIterator>
    void insert ( InputIterator first, InputIterator last );
(6)
void insert ( initializer_list<value_type> il );
Insert elements
Inserts new elements in the unordered_multimap.

This effectively increases the container size by the number of elements inserted.

The parameters determine how many elements are inserted and to which values they are initialized:

Parameters

val
Object to be copied to (or moved as) the value of the new element.
Versions (1) and (3) copy the element (i.e., val preserves its contents, the container keeps a copy).
Versions (2) and (4) move the element (i.e., val loses its content, which is acquired by the new element in the container).
Member type value_type is the type of the elements in the container, defined in unordered_multimap as pair<const key_type,mapped_type>, where member type key_type is an alias of the first template parameter (the key type), and mapped_type is an alias of the second template parameter (the mapped type, T).
Template parameter P is a type such that value_type is move-constructible from an rvalue of type P.
hint
Iterator to a position suggested as a hint on where to start the search for the proper insertion point. This value may or may not be used by the container to optimize the operation. The element will be stored in its corresponding bucket, no matter what is passed as hint.
Member type const_iterator is a forward iterator type.
first, last
Iterators specifying a range of elements. Copies of the elements in the range [first,last) are inserted in the unordered_multimap container.
Notice that the range includes all the elements between first and last, including the element pointed by first but not the one pointed by last.
Neither first nor last shall be iterators in the destination container.
The template type can be any type of input iterator.
il
An initializer_list object. The compiler will automatically construct such objects from initializer list declarators.
Member type value_type is the type of the elements contained in the container, defined in unordered_multimap as pair<const key_type,mapped_type>, where member type key_type is an alias of the first template parameter (the key type), and mapped_type is an alias of the second template parameter (the mapped type, T).

Return value

In the versions returning a value ((1),(2),(3) and (4)), the function returns an iterator to the newly inserted element.

Versions (5) and (6) return no value.

Member type iterator is a forward iterator type.

The storage for the new element is allocated using allocator_traits<allocator_type>::construct(), which may throw exceptions on failure (for the default allocator, bad_alloc is thrown if the allocation request does not succeed).

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
 
// unordered_multimap::insert
#include <iostream>
#include <string>
#include <unordered_map>

int main ()
{
  std::unordered_multimap<std::string,int>
              first,
              second = {{"AAPL",200},{"GOOG",100}};

  std::pair<std::string,int> mypair ("MSFT",500);

  first.insert (mypair);                            // copy insertion
  first.insert (std::make_pair<std::string,int>("GOOG",50)); // move insertion
  first.insert (second.begin(), second.end());  // range insertion
  first.insert ( {{"ORCL",100},{"GOOG",100}} );    // initializer list insertion

  std::cout << "first contains:" << std::endl;
  for (auto& x: first)
    std::cout << x.first << ": " << x.second << std::endl;

  std::cout << std::endl;
  return 0;
}


Possible output:
first contains:
AAPL: 200
MSFT: 500
ORCL: 100
GOOG: 50
GOOG: 100
GOOG: 100

Complexity

Single element insertions:
Average case: constant.
Worst case: linear in container size.
Multiple elements insertion:
Average case: linear in the number of elements inserted.
Worst case: N*(size+1): number of elements inserted times the container size plus one.
May trigger a rehash (not included).

Iterator validity

On most cases, all iterators in the container remain valid after the insertion. The only exception being when the growth of the container forces a rehash. In this case, all iterators in the container are invalidated.

A rehash is forced if the new container size after the insertion operation would increase above its capacity threshold (calculated as the container's bucket_count multiplied by its max_load_factor).

References to elements in the unordered_multimap container remain valid in all cases, even after a rehash.

See also

unordered_multimap::emplace
Construct and insert element (public member function)
unordered_multimap::emplace_hint
Construct and insert element with hint (public member function)
unordered_multimap::find
Get iterator to element (public member function)

C++