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_hint

Inserts an element constructed in place (no copy or move operations are performed), with a placement hint.

template<class... Args>
   iterator emplace_hint(
      const_iterator where,
      Args&&... args);

Parameter

Description

args

The arguments forwarded to construct an element to be inserted into the map unless the map already contains that element or, more generally, unless it already contains an element whose key is equivalently ordered.

where

The place to start searching for the correct point of insertion. (If that point immediately precedes where, insertion can occur in amortized constant time instead of logarithmic time.)

An iterator to the newly inserted element.

If the insertion failed because the element already exists, returns an iterator to the existing element with its key.

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: " << endl;

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

    cout << endl;
}

int main()
{
    map<string, string> m1;

    // Emplace some test data
    m1.emplace("Anna", "Accounting");
    m1.emplace("Bob", "Accounting");
    m1.emplace("Carmine", "Engineering");

    cout << "map starting data: ";
    print(m1);
    cout << endl;

    // Emplace with hint
    // m1.end() should be the "next" element after this emplacement
    m1.emplace_hint(m1.end(), "Doug", "Engineering");

    cout << "map modified, now contains ";
    print(m1);
    cout << endl;
}
map starting data: 3 elements:
(Anna,Accounting) (Bob,Accounting) (Carmine,Engineering)

map modified, now contains 4 elements:
(Anna,Accounting) (Bob,Accounting) (Carmine,Engineering) (Doug,Engineering)

Header: <map>

Namespace: std

Show:
© 2014 Microsoft. All rights reserved.