最終更新日時: 2026年02月17日 23時22分33秒 (JST)
Akira Takahashi が更新

履歴 編集

function template
<map>

# std::map::emplace_hint(C++11)

    template <class... Args>
    iterator
      emplace_hint(const_iterator hint,
                   Args&&... args);     // (1) C++11
    template <class... Args>
    constexpr iterator
      emplace_hint(const_iterator hint,
                   Args&&... args);     // (1) C++26

## 概要

要素が配置されるべき場所を示唆するパラメータ `hint` を使って、コンテナに新しい要素を挿入する。要素は直接構築される（コピーもムーブもされない）。要素のコンストラクタはこの関数に渡された引数と同じ引数で呼ばれる。

## パラメータ

- `hint` : 新しい要素をどこへ挿入するかを示唆するために使われるイテレータ
- `args...` : 要素のコンストラクタへ転送される引数パック

## 戻り値

新たな要素が追加された場合、その追加された要素を指すイテレータ。新たな要素が追加されなかった場合、既にあった要素を指すイテレータ。

## 計算量

一般にコンテナのサイズについて対数時間だが、新しい要素が `hint` の前に挿入された場合は償却定数時間。

## 備考

- この関数が呼ばれた後も、当該コンテナ内の要素を指す参照やイテレータは無効にはならない。
  なお、規格書に明確な記載は無いが、当該コンテナ内の要素を指すポインタも無効にはならない。
- C++17 で導入された `try_emplace` と異なり、たとえ要素が挿入されなかった場合でも `value_type` 型のオブジェクトが構築される可能性があり、結果として引数 `args` が `move` の対象となって変更されてしまっている可能性があるため、注意が必要である。

## 例

    #include <iostream>
    #include <map>
    #include <utility>

    int main()
    {
      std::map<int, char> m;

      m.emplace( 1, 'A' );

      // キー2の要素が最後尾に追加されることが事前にわかっているので、m.end()をヒントとして与える
      m.emplace_hint( m.end(), 2, 'B' );

      for( const auto& pr : m ) {
        std::cout << std::get<0>( pr ) << " " << std::get<1>( pr ) << std::endl;
      }

      return 0;
    }

### 出力

    1 A
    2 B

## バージョン

### 言語

- C++11

### 処理系

- Clang: 3.2 ✅
- GCC: 4.8.5 ✅
- ICC: ??
- Visual C++: 2012 ✅

## 関連項目

名前 | 説明
--- | ---
`map::insert` | 要素を挿入する
`map::insert_or_assign` | 要素を挿入、あるいは代入する
`map::emplace` | 要素を直接構築する
`map::try_emplace` | キーが存在しない場合のみ要素を直接構築する

## 参照

- N2680 Proposed Wording for Placement Insert (Revision 1)
- P3372R3 constexpr containers and adaptors