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

履歴 編集

function template
<flat_map>

# std::flat_map::emplace(C++23)

    template <class... Args>
    pair<iterator, bool>
      emplace(Args&&... args); // (1) C++23
    template <class... Args>
    constexpr pair<iterator, bool>
      emplace(Args&&... args); // (1) C++26

## 概要

コンテナに新しい要素を挿入する。要素は直接構築される（コピーもムーブもされない）。要素のコンストラクタはこの関数に渡された引数を与えることによって呼ばれる。

## パラメータ

- `args...` : 要素のコンストラクタへ転送される引数パック。

## テンプレートパラメータ制約

- `is_constructible_v<pair<key_type, mapped_type>, Arg...>`が`true`であること

## 効果

`pair<key_type, mapped_type>`型の変数`t`を`std::forward<Args>(args)...`で初期化する。このコンテナが`t.first`と等価なキーをすでにもっている場合、`*this`を変更しない。そうでない場合、以下と等価：

    auto key_it = ranges::upper_bound(c.keys, t.first, compare);
    auto value_it = c.values.begin() + distance(c.keys.begin(), key_it);
    c.keys.insert(key_it, std::move(t.first));
    c.values.insert(value_it, std::move(t.second));

## 戻り値

挿入されたかどうかを示す `bool` と、挿入された要素へのイテレータからなる `pair` を返す。挿入されなかったときは、既存要素へのイテレータを返す。

## 計算量

操作の前のコンテナサイズ（`size()`）を`N`とすると

- 新しい要素が挿入された場合: `N`に対して線形
- 要素の挿入が行われなかった場合: `N`に対して対数

## 例

### 単純なキー・値を挿入する例

    #include <iostream>
    #include <flat_map>

    int main()
    {
      std::flat_map<int, char> fm;

      // キーと値のpairを作ることなく挿入できる
      fm.emplace(3, 'A'); // キー3と、値'A'を挿入
      fm.emplace(1, 'B');
      fm.emplace(4, 'C');

      for (const auto& [key, value] : fm) {
        std::cout << key << " : " << value << std::endl;
      }
    }

#### 出力

    1 : B
    3 : A
    4 : C

### キーと値もそれぞれコンストラクタ引数を渡す例

    #include <iostream>
    #include <flat_map>
    #include <string>
    #include <tuple>

    struct Point {
      int x, y;
      Point(int x, int y) : x(x), y(y) {}
    };

    int main()
    {
      std::flat_map<std::string, Point> fm;

      fm.emplace(std::piecewise_construct,
                 std::forward_as_tuple(3, 'C'), // キーの型std::stringのコンストラクタ引数を渡す
                 std::forward_as_tuple(1, 2));  // 値の型Pointのコンストラクタ引数を渡す

      fm.emplace(std::piecewise_construct,
                 std::forward_as_tuple(3, 'A'),
                 std::forward_as_tuple(3, 4));

      fm.emplace(std::piecewise_construct,
                 std::forward_as_tuple(3, 'B'),
                 std::forward_as_tuple(5, 6));

      for (const auto& [key, value] : fm) {
        std::cout << key << " : (" << value.x << ", " << value.y << ')' << std::endl;
      }
    }

#### 出力

    AAA : (3, 4)
    BBB : (5, 6)
    CCC : (1, 2)

## バージョン

### 言語

- C++23

### 処理系

- Clang: ??
- GCC: ??
- Visual C++: ??

## 関連項目

名前 | 説明
--- | ---
`flat_map::insert` | 要素を挿入する
`flat_map::insert_range` | Rangeを挿入する
`flat_map::insert_or_assign` | 要素を挿入、あるいは代入する
`flat_map::emplace_hint` | ヒントを使って要素を直接構築する
`flat_map::try_emplace` | キーが存在しない場合のみ要素を直接構築する

## 参照

- P3372R3 constexpr containers and adaptors