map::insert

Inserts an element or a range of elements into a map.

// (1) single element
pair<iterator, bool> insert(
    const value_type& Val
); 

// (2) single element, perfect forwarded
template<class ValTy>
pair<iterator, bool> insert(
    ValTy&& Val
);

// (3) single element with hint
iterator insert(
    const_iterator Where,
    const value_type& Val
); 

// (4) single element, perfect forwarded, with hint
template<class ValTy>
iterator insert(
    const_iterator Where,
    ValTy&& Val
);

// (5) range 
template<class InputIterator> 
void insert(
    InputIterator First,
    InputIterator Last
); 

// (6) initializer list
void insert(
    initializer_list<value_type> IList
);

Parameters

Return Value

The single-element member functions, (1) and (2), return a pair whose bool component is true if an insertion was made, and false if the map already contained an element whose key had an equivalent value in the ordering. The iterator component of the return-value pair points to the newly inserted element if the bool component is true, or to the existing element if the bool component is false.

The single-element-with-hint member functions, (3) and (4), return an iterator that points to the position where the new element was inserted into the map or, if an element with an equivalent key already exists, to the existing element.

Remarks

No iterators, pointers, or references are invalidated by this function.

During the insertion of just one element, if an exception is thrown, the container's state is not modified. During the insertion of multiple elements, if an exception is thrown, the container is left in an unspecified but valid state.

To access the iterator component of a pairpr that's returned by the single-element member functions, use pr.first; to dereference the iterator within the returned pair, use *pr.first, giving you an element. To access the bool component, use pr.second. For an example, see the sample code later in this article.

The value_type of a container is a typedef that belongs to the container, and for map, map<K, V>::value_type is pair<const K, V>. The value of an element is an ordered pair in which the first component is equal to the key value and the second component is equal to the data value of the element.

The range member function (5) inserts the sequence of element values into a map that corresponds to each element addressed by an iterator in the range [First, Last); therefore, Last does not get inserted. The container member function end() refers to the position just after the last element in the container—for example, the statement m.insert(v.begin(), v.end()); attempts to insert all elements of v into m. Only elements that have unique values in the range are inserted; duplicates are ignored. To observe which elements are rejected, use the single-element versions of insert.

The initializer list member function (6) uses an initializer_list to copy elements into the map.

For insertion of an element constructed in place—that is, no copy or move operations are performed—see map::emplace and map::emplace_hint.

Example

// map_insert.cpp
// compile with: /EHsc
#include <map>
#include <iostream>
#include <string>
#include <vector>
#include <utility>  // make_pair()

using namespace std;

template <typename M> void print(const M& m) {
    cout << m.size() << " elements: ";

    for (const auto& p : m) {
        cout << "(" << p.first << ", " << p.second << ") ";
    }

    cout << endl;
}

int main()
{

    // insert single values 
    map<int, int> m1;
    // call insert(const value_type&) version
    m1.insert({ 1, 10 });
    // call insert(ValTy&&) version 
    m1.insert(make_pair(2, 20));

    cout << "The original key and mapped values of m1 are:" << endl;
    print(m1);

    // intentionally attempt a duplicate, single element
    auto ret = m1.insert(make_pair(1, 111));
    if (!ret.second){
        auto pr = *ret.first;
        cout << "Insert failed, element with key value 1 already exists."
            << endl << "  The existing element is (" << pr.first << ", " << pr.second << ")"
            << endl;
    }
    else{
        cout << "The modified key and mapped values of m1 are:" << endl;
        print(m1);
    }
    cout << endl;

    // single element, with hint
    m1.insert(m1.end(), make_pair(3, 30));
    cout << "The modified key and mapped values of m1 are:" << endl;
    print(m1);
    cout << endl;


    // The templatized version inserting a jumbled range
    map<int, int> m2;
    vector<pair<int, int>> v;
    v.push_back(make_pair(43, 294));
    v.push_back(make_pair(41, 262));
    v.push_back(make_pair(45, 330));
    v.push_back(make_pair(42, 277));
    v.push_back(make_pair(44, 311));

    cout << "Inserting the following vector data into m2:" << endl;
    print(v);

    m2.insert(v.begin(), v.end());

    cout << "The modified key and mapped values of m2 are:" << endl;
    print(m2);
    cout << endl;

    // The templatized versions move-constructing elements
    map<int, string>  m3;
    pair<int, string> ip1(475, "blue"), ip2(510, "green");

    // single element
    m3.insert(move(ip1));
    cout << "After the first move insertion, m3 contains:" << endl;
    print(m3);

    // single element with hint
    m3.insert(m3.end(), move(ip2));
    cout << "After the second move insertion, m3 contains:" << endl;
    print(m3);
    cout << endl;

    map<int, int> m4;
    // Insert the elements from an initializer_list
    m4.insert({ { 4, 44 }, { 2, 22 }, { 3, 33 }, { 1, 11 }, { 5, 55 } });
    cout << "After initializer_list insertion, m4 contains:" << endl;
    print(m4);
    cout << endl;
}

Output

The original key and mapped values of m1 are:
2 elements: (1, 10) (2, 20)
Insert failed, element with key value 1 already exists.
  The existing element is (1, 10)

The modified key and mapped values of m1 are:
3 elements: (1, 10) (2, 20) (3, 30)

Inserting the following vector data into m2:
5 elements: (43, 294) (41, 262) (45, 330) (42, 277) (44, 311)
The modified key and mapped values of m2 are:
5 elements: (41, 262) (42, 277) (43, 294) (44, 311) (45, 330)

After the first move insertion, m3 contains:
1 elements: (475, blue)
After the second move insertion, m3 contains:
2 elements: (475, blue) (510, green)

After initializer_list insertion, m4 contains:
5 elements: (1, 11) (2, 22) (3, 33) (4, 44) (5, 55)

Requirements

Header: <map>

Namespace: std

See Also

Reference

map Class

map::insert, map::find, and map::end

multimap::insert

Standard Template Library