public member function
<unordered_map>

std::unordered_map::emplace

template <class... Args>
pair<iterator, bool> emplace ( Args&&... args );
Construct and insert element
Inserts a new element in the unordered_map if its key is unique. This new element is constructed in place using args as the arguments for the element's constructor.

The insertion only takes place if no element in the container has a key equivalent to the one being emplaced (keys in an unordered_map are unique).

If inserted, 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.
Because the mapped type is only part of the value type, the standard specification is ambiguous here. If implemented by your library, it may have been interpreted as either:
  • The first argument in the list is treated as the key and the remaining arguments are used to construct an object of the mapped type in place.
  • The arguments are used to construct a new object of the value type and passed to the pair constructor.

Return value

If the insertion takes place (because no other element existed with the same key), the function returns a pair object, whose first component is an iterator to the inserted element, and whose second component is true.

Otherwise, the pair object returned has as first component an iterator pointing to the element in the container with the same key, and false as its second component.

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

int main ()
{
  std::unordered_map<std::string,std::string> mymap;

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

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

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


Possible output:
mymap contains:
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_map container remain valid in all cases, even after a rehash.

See also