Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

map::emplace

Inserts an element constructed in place (no copy or move operations are performed) into a map.

template<class... Args>
   pair<iterator, bool> emplace(
      Args&&... args);

Parameter

Description

args

The arguments forwarded to construct an element to be inserted into the map unless it already contains an element whose value is equivalently ordered.

A pair whose bool component is true if an insertion was made, and false if the map already contained an element of 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.

To access the iterator component of a pair pr, use pr.first; to dereference it, use *pr.first. To access the bool component, use pr.second. For an example, see the sample code later in this article.

No iterators or references are invalidated by this function.

During emplacement, if an exception is thrown, the container's state is not modified.

The value_type of an element is a pair, so that the value of an element will be an ordered pair with the first component equal to the key value and the second component equal to the data value of the element.

// map_emplace.cpp
// compile with: /EHsc
#include <map>
#include <string>
#include <iostream>

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()
{
    map<int, string> m1;

    auto ret = m1.emplace(10, "ten");

    if (!ret.second){
        auto pr = *ret.first;
        cout << "Emplace failed, element with key 10 already exists."
            << endl << "  The existing element is (" << pr.first << ", " << pr.second << ")"
            << endl;
        cout << "map not modified" << endl;
    }
    else{
        cout << "map modified, now contains ";
        print(m1);
    }
    cout << endl;

    ret = m1.emplace(10, "one zero");

    if (!ret.second){
        auto pr = *ret.first;
        cout << "Emplace failed, element with key 10 already exists."
            << endl << "  The existing element is (" << pr.first << ", " << pr.second << ")"
            << endl;
    }
    else{
        cout << "map modified, now contains ";
        print(m1);
    }
    cout << endl;
}

map modified, now contains 1 elements: (10, ten)

Emplace failed, element with key 10 already exists.
  The existing element is (10, ten)

Header: <map>

Namespace: std

Show:
© 2014 Microsoft