public member function
<unordered_map>

std::unordered_map::insert

(1)
pair<iterator,bool> insert ( const value_type& val );
(2)
template <class P>
    pair<iterator,bool> 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_map.

Each element is inserted only if its key is not equivalent to the key of any other element already in the container (keys in an unordered_map are unique).

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_map 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).
The signatures taking an argument of type P&& are only called if P is a type implicitly convertible to value_type.
The signatures taking an argument of type P&& are only called if std::is_constructible<value_type,P&&> is true.
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_map 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_map 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 versions (1) and (2), the function returns a pair object whose first element is an iterator pointing either to the newly inserted element in the container or to the element whose key is equivalent, and a bool value indicating whether the element was successfully inserted or not.

In versions (3) and (4), the function returns an iterator pointing either to the newly inserted element in the container or to the element whose key is equivalent.

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_map::insert
#include <iostream>
#include <string>
#include <unordered_map>

int main ()
{
  std::unordered_map<std::string,double>
              myrecipe,
              mypantry = {{"milk",2.0},{"flour",1.5}};

  std::pair<std::string,double> myshopping ("baking powder",0.3);

  myrecipe.insert (myshopping);                        // copy insertion
  myrecipe.insert (std::make_pair<std::string,double>("eggs",6.0)); // move insertion
  myrecipe.insert (mypantry.begin(), mypantry.end());  // range insertion
  myrecipe.insert ( {{"sugar",0.8},{"salt",0.1}} );    // initializer list insertion

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

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


Possible output:
myrecipe contains:
salt: 0.1
eggs: 6
sugar: 0.8
baking powder: 0.3
flour: 1.5
milk: 2

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 in the complexity above).

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

unordered_map::emplace
Construct and insert element (public member function )
unordered_map::emplace_hint
Construct and insert element with hint (public member function )
unordered_map::operator[]
Access element (public member function )
unordered_map::at
Access element (public member function)

C++