Namespaces
Variants

std::map<Key,T,Compare,Allocator>:: emplace_hint

From cppreference.net

C++
Containers library
std::map
Member functions
Non-member functions
(until C++20) (until C++20) (until C++20) (until C++20) (until C++20)
Deduction guides (C++17)
template < class ... Args >
iterator emplace_hint ( const_iterator hint, Args && ... args ) ;
(C++11以降)
(constexprはC++26以降)

コンテナに新しい要素を、できるだけ hint の直前の位置に近い場所に挿入します。

value_type のコンストラクタ（すなわち、 std:: pair < const Key, T > ）は、関数に供給された引数と全く同じ引数で呼び出され、 std:: forward < Args > ( args ) ... によって転送されます。

イテレータや参照は無効化されません。

目次

パラメータ

hint - 新しい要素が挿入される位置の前を指すイテレータ
args - 要素のコンストラクタに転送される引数

戻り値

挿入された要素、または挿入を妨げた要素へのイテレータ。

例外

何らかの理由で例外がスローされた場合、この関数は何も効果を持ちません（ strong exception safety guarantee ）。

計算量

一般的にはコンテナのサイズに対して対数的ですが、新しい要素が hint の直前に挿入される場合は償却定数時間となります。

例

このコードを実行 
#include <chrono>
#include <cstddef>
#include <functional>
#include <iomanip>
#include <iostream>
#include <map>
const int n_operations = 100'500'0;
std::size_t map_emplace()
{
    std::map<int, char> map;
    for (int i = 0; i < n_operations; ++i)
        map.emplace(i, 'a');
    return map.size();
}
std::size_t map_emplace_hint()
{
    std::map<int, char> map;
    auto it = map.begin();
    for (int i = 0; i < n_operations; ++i)
    {
        map.emplace_hint(it, i, 'b');
        it = map.end();
    }
    return map.size();
}
std::size_t map_emplace_hint_wrong()
{
    std::map<int, char> map;
    auto it = map.begin();
    for (int i = n_operations; i > 0; --i)
    {
        map.emplace_hint(it, i, 'c');
        it = map.end();
    }
    return map.size();
}
std::size_t map_emplace_hint_corrected()
{
    std::map<int, char> map;
    auto it = map.begin();
    for (int i = n_operations; i > 0; --i)
    {
        map.emplace_hint(it, i, 'd');
        it = map.begin();
    }
    return map.size();
}
std::size_t map_emplace_hint_closest()
{
    std::map<int, char> map;
    auto it = map.begin();
    for (int i = 0; i < n_operations; ++i)
        it = map.emplace_hint(it, i, 'e');
    return map.size();
}
double time_it(std::function<std::size_t()> map_test,
               std::string what = "", double ratio = 0.0)
{
    const auto start = std::chrono::system_clock::now();
    const std::size_t map_size = map_test();
    const auto stop = std::chrono::system_clock::now
（注：HTMLタグ・属性、タグ内のテキスト、C++固有の用語は翻訳対象外のため、元のまま保持されています）();
    std::chrono::duration<double, std::milli> time = stop - start;
    if (what.size() && map_size)
        std::cout << std::setw(8) << time << " for " << what << " (比率: "
                  << (ratio == 0.0 ? 1.0 : ratio / time.count()) << ")\n";
    return time.count();
}
int main()
{
    std::cout << std::fixed << std::setprecision(2);
    time_it(map_emplace); // キャッシュのウォームアップ
    const auto x = time_it(map_emplace, "プレーン emplace");
    time_it(map_emplace_hint, "正しいヒントを用いた emplace", x);
    time_it(map_emplace_hint_wrong, "間違ったヒントでの emplace", x);
    time_it(map_emplace_hint_corrected, "修正済み emplace", x);
    time_it(map_emplace_hint_closest, "返されたイテレータを使用したemplace", x);
}

出力例: 

365.08ms for plain emplace (ratio: 1.00)
 96.54ms for emplace with correct hint (ratio: 3.78)
409.40ms for emplace with wrong hint (ratio: 0.89)
 85.57ms for corrected emplace (ratio: 4.27)
 84.31ms for emplace using returned iterator (ratio: 4.33)

関連項目

(C++11)
要素をその場で構築する
(公開メンバ関数)
要素を挿入する またはノード (C++17以降)
(公開メンバ関数)