template <class... Args>
pair<iterator, bool> try_emplace(const key_type& k, Args&&... args); // (1)
template <class... Args>
pair<iterator, bool> try_emplace(key_type&& k, Args&&... args); // (2)
template <class... Args>
iterator try_emplace(const_iterator hint, const key_type& k, Args&&... args); // (3)
template <class... Args>
iterator try_emplace(const_iterator hint, key_type&& k, Args&&... args); // (4)
概要
引数 k
と等価のキーを持つ要素が存在しない場合、コンテナに新しい要素を挿入する。要素は引数からコンテナ内に直接構築されるため、構築されたオブジェクトはコピーもムーブもされない。
なお、本メンバ関数は emplace
や emplace_hint
等と異なり、引数 k
と等価のキーを持つ要素が既に存在する場合には、k
や args
がムーブされてしまうことはない。
引数 hint
は、k
を検索する際のヒントに使用される。
テンプレートパラメータ制約
- (1)、(3) :
value_type
は、piecewise_construct
,forward_as_tuple(k)
,forward_as_tuple(forward<Args>(args)...)
からmap
に直接構築可能であること - (2)、(4) :
value_type
は、piecewise_construct
,forward_as_tuple(move(k))
,forward_as_tuple(forward<Args>(args)...)
からmap
に直接構築可能であること
なお、規格に記載はないが、hint
は emplace_hint
と同様、コンテナの有効な読み取り専用イテレータである必要があるものと思われる。
効果
- (1)、(3) :
map
がk
と同値のキーを持つ要素を持っている場合、何もしない(引数への副作用もない)。そうでなければ、piecewise_construct
,forward_as_tuple(k)
,forward_as_tuple(forward<Args>(args)...)
から構築したvalue_type
型のオブジェクトを挿入する。 - (2)、(4) :
map
がk
と同値のキーを持つ要素を持っている場合、何もしない(引数への副作用もない)。そうでなければ、piecewise_construct
,forward_as_tuple(move(k))
,forward_as_tuple(forward<Args>(args)...)
から構築したvalue_type
型のオブジェクトを挿入する。
戻り値
- (1)、(2) : イテレータと
bool
値のpair
を返す。- 挿入された場合には、
first
に挿入された要素へのイテレータ、second
にtrue
が設定される。 - 挿入されなかった場合には、
first
にk
と等価のキーを持つ既存の要素へのイテレータ、second
にfalse
が設定される。
- 挿入された場合には、
- (3)、(4) :
- 挿入された場合には、挿入された要素へのイテレータを返す。
- 挿入されなかった場合には、
k
と等価のキーを持つ既存の要素へのイテレータを返す。
計算量
- (1)、(2) :
emplace
と同じ。 - (3)、(4) :
emplace_hint
と同じ。
備考
-
概要に記載されているように、本メンバ関数は指定されたキーと等価の要素が既に存在する場合には、引数に副作用が発生しない。
一方、emplace
、emplace_hint
、insert
にはそのような規定は無く、挿入がされなかった場合でも引数に副作用(引数からのムーブ)が発生してしまう可能性があるため、注意が必要である。 -
このメンバ関数の機能テストマクロは以下の通り。
マクロ名 値 __cpp_lib_map_try_emplace
201411
例
#include <iostream>
#include <map>
#include <memory>
#include <utility>
int main()
{
std::map<int, std::unique_ptr<int>> m;
auto u1 = std::make_unique<int>(114);
auto [it1, b1] = m.try_emplace(42, std::move(u1));
std::cout << std::boolalpha << (u1.get() == nullptr) << ", " << *it1->second << ", " << b1 << '\n';
auto u2 = std::make_unique<int>(514);
auto [it2, b2] = m.try_emplace(42, std::move(u2));
std::cout << std::boolalpha << (u2.get() == nullptr) << ", " << *it2->second << ", " << b2 << '\n';
}
出力
true, 114, true
false, 114, false
バージョン
言語
- C++17
処理系
- Clang: 3.7.0
- GCC: 6.1.0
- ICC: ??
- Visual C++: ??
関連項目
名前 | 説明 |
---|---|
map::insert |
要素を挿入する |
map::insert_or_assign |
要素を挿入、あるいは代入する |
map::emplace |
要素を直接構築する |
map::emplace_hint |
ヒントを使って要素を直接構築する |