public member function
<unordered_map>

std::unordered_multimap::emplace

template <class... Args> iterator emplace ( Args&&... args );
Construct and insert element
Inserts a new element in the unordered_multimap. This new element is constructed in place using args as the arguments for the element's constructor.

This effectively increases the container size by one.

A similar member function exists, insert, which either copies or moves existing objects into the container.

Parameters

args
Arguments used to construct a new object of the mapped type for the inserted element.
Arguments forwarded to construct the new element (of type pair<const key_type, mapped_type>).
This can be one of:
- A single argument of a pair type with a value for the key as first member, and a value for the mapped value as second.
- Two arguments: one for the key, the other for the mapped value.
- piecewise_construct as first argument, and two additional arguments with tuples to be forwarded as arguments for the key value and for the mapped value respectivelly.
See pair::pair for more info.

Return value

An iterator to the newly inserted element.

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
// unordered_multimap::emplace
#include <iostream>
#include <string>
#include <unordered_map>

int main ()
{
  std::unordered_multimap<std::string,std::string> myumm;

  myumm.emplace ("NCC-1701", "C. Pike");
  myumm.emplace ("NCC-1701", "J.T. Kirk");
  myumm.emplace ("NCC-1701-D", "J.L. Picard");
  myumm.emplace ("NCC-74656", "K. Janeway");

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

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


Possible output:
mymap contains:
NCC-1701: C. Pike
NCC-1701: J.T. Kirk
NCC-1701-D: J.L. Picard
NCC-74656: K. Janeway

Complexity

Average case: constant.
Worst case: linear in container size.
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