std::map::insert

Parameters

val

Value to be copied to (or moved as) the inserted element.
Member type value_type is the type of the elements in the container, defined in map as pair<const key_type,mapped_type> (see map member types).

The template parameter P shall be a type convertible to value_type.

The signatures taking an argument of type P&& are only called if std::is_constructible<value_type,P&&> is true.

If P is instantiated as a reference type, the argument is copied.

position

Hint for the position where the element can be inserted.

The function optimizes its insertion time if position points to the element that will precede the inserted element.

The function optimizes its insertion time if position points to the element that will follow the inserted element (or to the end, if it would be the last).

Notice that this is just a hint and does not force the new element to be inserted at that position within the map container (the elements in a map always follow a specific order depending on their key).
Member types iterator and const_iterator are defined in map as bidirectional iterator types that point to elements.

first, last

Iterators specifying a range of elements. Copies of the elements in the range [first,last) are inserted in the 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.
The function template argument InputIterator shall be an input iterator type that points to elements of a type from which value_type objects can be constructed.

il

An initializer_list object. Copies of these elements are inserted.
These objects are automatically constructed from initializer list declarators.
Member type value_type is the type of the elements contained in the container, defined in map as pair<const key_type,mapped_type> (see map member types).

Return value

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
26
27
28
29
30
31
32
33
34
35
36
37
38
39

// map::insert (C++98)
#include <iostream>
#include <map>
int main ()
{
  std::map<char,int> mymap;
  // first insert function version (single parameter):
  mymap.insert ( std::pair<char,int>('a',100) );
  mymap.insert ( std::pair<char,int>('z',200) );
  std::pair<std::map<char,int>::iterator,bool> ret;
  ret = mymap.insert ( std::pair<char,int>('z',500) );
  if (ret.second==false) {
    std::cout << "element 'z' already existed";
    std::cout << " with a value of " << ret.first->second << '\n';
  }
  // second insert function version (with hint position):
  std::map<char,int>::iterator it = mymap.begin();
  mymap.insert (it, std::pair<char,int>('b',300));  // max efficiency inserting
  mymap.insert (it, std::pair<char,int>('c',400));  // no max efficiency inserting
  // third insert function version (range insertion):
  std::map<char,int> anothermap;
  anothermap.insert(mymap.begin(),mymap.find('c'));
  // showing contents:
  std::cout << "mymap contains:\n";
  for (it=mymap.begin(); it!=mymap.end(); ++it)
    std::cout << it->first << " => " << it->second << '\n';
  std::cout << "anothermap contains:\n";
  for (it=anothermap.begin(); it!=anothermap.end(); ++it)
    std::cout << it->first << " => " << it->second << '\n';
  return 0;
}

element 'z' already existed with a value of 200
mymap contains:
a => 100
b => 300
c => 400
z => 200
anothermap contains:
a => 100
b => 300

Complexity

Iterator validity

Data races

Exception safety

See also

map::operator[]

Access element (public member function)

map::find

Get iterator to element (public member function)

map::erase

Erase elements (public member function)