5. insert_or_assign

最終更新日時(UTC):
が更新

履歴 編集

function template
<map>

std::map::insert_or_assign(C++17)

template <class M>
pair<iterator, bool>
  insert_or_assign(const key_type& k,
                   M&& obj);          // (1) C++17
template <class M>
pair<iterator, bool>
  insert_or_assign(key_type&& k,
                   M&& obj);          // (2) C++17
template <class K, class M>
pair<iterator, bool>
  insert_or_assign(K&& k,
                   M&& obj);          // (3) C++26
template <class M>
iterator
  insert_or_assign(const_iterator hint,
                   const key_type& k,
                   M&& obj);          // (4) C++17
template <class M>
iterator
  insert_or_assign(const_iterator hint,
                   key_type&& k,
                   M&& obj);          // (5) C++17
template <class K, class M>
iterator
  insert_or_assign(const_iterator hint,
                   K&& k,
                   M&& obj);          // (6) C++26

概要

引数 k で指定されたキーが存在しなければ対応する値を引数 obj の値として要素を挿入し（insert）、さもなければ（or）、そのキーに対応する値に引数 obj を代入する（assign）。

引数 hint は、k を検索する際のヒントに使用される。

  • (1) : key_type型のキーをとって挿入もしくは代入する
  • (2) : key_type型の一時オブジェクトのキーをとって挿入もしくは代入する
  • (3) : key_typeと比較可能なK型のキーをとって挿入もしくは代入する
  • (4) : 挿入位置のヒントをともない、key_type型のキーをとって挿入もしくは代入する
  • (5) : 挿入位置のヒントをともない、key_type型の一時オブジェクトのキーをとって挿入もしくは代入する
  • (6) : 挿入位置のヒントをともない、key_typeと比較可能なK型のキーをとって挿入もしくは代入する

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

  • (3), (6) : key_compare::is_transparent が妥当な式であること

適格要件

  • (1), (3), (4), (6) : is_assignable_v<mapped_type&, M&&> が true であること。value_type は、k, forward<M>(obj) から map に直接構築可能であること
  • (2), (5) : is_assignable_v<mapped_type&, M&&> が true であること。value_type は、move(k), forward<M>(obj) から map に直接構築可能であること

なお、規格に記載はないが、hint は emplace_hint と同様、コンテナの有効な読み取り専用イテレータである必要があるものと思われる。

効果

  • (1), (3), (4), (6) : map が k と同値のキーを持つ要素 e を持っている場合、e.second に forward<M>(obj) を代入する。そうでなければ、k, forward<M>(obj) から構築した value_type 型のオブジェクトを挿入する。
  • (2), (5) : map が k と同値のキーを持つ要素 e を持っている場合、e.second に forward<M>(obj) を代入する。そうでなければ、move(k), forward<M>(obj) から構築した value_type 型のオブジェクトを挿入する。

戻り値

  • (1), (2), (3) : イテレータと bool 値の pair を返す。
    • 挿入された場合には、first に挿入された要素へのイテレータ、second に true が設定される。
    • 代入された場合には、first に代入された要素へのイテレータ、second に false が設定される。
  • (4), (5), (6) :
    • 挿入された場合には、挿入された要素へのイテレータを返す。
    • 代入された場合には、代入された要素へのイテレータを返す。

計算量

備考

  • (3), (6) :
    • is_transparentは、標準ライブラリのstd::less、std::greaterといった関数オブジェクトの、voidに対する特殊化で定義される。それ以外のテンプレートパラメータでis_transparentが定義されないのは、互換性のためである。
    • これらのオーバーロードは、map<string, int>のようなコンテナに対し、検索操作で文字列リテラルを渡した際に、キー型の一時オブジェクトが生成されるコストを減らすためにある。

例

#include <iostream>
#include <map>
#include <string>

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

  auto [it1, b1] = m.insert_or_assign("foo", 42);
  std::cout << '(' << it1->first << ", " << it1->second << "), " << std::boolalpha << b1 << '\n';

  auto [it2, b2] = m.insert_or_assign("foo", 0);
  std::cout << '(' << it2->first << ", " << it2->second << "), " << std::boolalpha << b2 << '\n';
}

出力

(foo, 42), true
(foo, 0), false

バージョン

言語

  • C++17

処理系

関連項目

名前 説明
map::insert 要素を挿入する
map::emplace 要素を直接構築する
map::emplace_hint ヒントを使って要素を直接構築する
map::try_emplace キーが存在しない場合のみ要素を直接構築する

参照