std::map::try_emplace

 

C++

Language

Standard library headers

Concepts

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Technical Specifications

 

Containers library

array (C++11)

vector

deque

forward_list (C++11)

list

set

multiset

map

multimap

unordered_set (C++11)

unordered_multiset (C++11)

unordered_map (C++11)

unordered_multimap (C++11)

stack

queue

priority_queue

 

std::map

Member functions

map::map

map::~map

map::operator=

map::get_allocator

Element access

map::at

map::operator[]

Iterators

map::beginmap::cbegin (C++11)

map::endmap::cend (C++11)

map::rbeginmap::crbegin (C++11)

map::rendmap::crend (C++11)

Capacity

map::empty

map::size

map::max_size

Modifiers

map::clear

map::insert

map::insert_or_assign (C++17)

map::emplace (C++11)

map::emplace_hint (C++11)

map::try_emplace (C++17)

map::erase

map::swap

Lookup

map::count

map::find

map::equal_range

map::lower_bound

map::upper_bound

Observers

map::key_comp

map::value_comp

 

template <class... Args> pair<iterator, bool> try_emplace(const key_type& k, Args&&... args);	(1)	(since C++17)
template <class... Args> pair<iterator, bool> try_emplace(key_type&& k, Args&&... args);	(2)	(since C++17)
template <class... Args> iterator try_emplace(const_iterator hint, const key_type& k, Args&&... args);	(3)	(since C++17)
template <class... Args> iterator try_emplace(const_iterator hint, key_type&& k, Args&&... args);	(4)	(since C++17)

1) If a key equivalent to k already exists in the container, does nothing. Otherwise, behaves like emplace except that the element is constructed as value_type(std::piecewise_construct, std::forward_as_tuple(k), std::forward_as_tuple(forward<Args>(args)...))

2) If a key equivalent to k already exists in the container, does nothing. Otherwise, behaves like emplace except that the element is constructed as value_type(std::piecewise_construct, std::forward_as_tuple(std::move(k)), std::forward_as_tuple(forward<Args>(args)...))

3) If a key equivalent to k already exists in the container, does nothing. Otherwise, behaves like emplace_hint except that the element is constructed as value_type(std::piecewise_construct, std::forward_as_tuple(k), std::forward_as_tuple(forward<Args>(args)...))

4) If a key equivalent to k already exists in the container, does nothing. Otherwise, behaves like emplace_hint except that the element is constructed as value_type(std::piecewise_construct, std::forward_as_tuple(std::move(k)), std::forward_as_tuple(forward<Args>(args)...))

No iterators or references are invalidated.

Parameters

k	-	the key used both to look up and to insert if not found
hint	-	iterator to the position before which the new element will be inserted
args	-	arguments to forward to the constructor of the element

Return value

1,2) Same as for emplace

3,4) Same as for emplace_hint

Complexity

1,2) Same as for emplace

3,4) Same as for emplace_hint

Notes

Unlike insert or emplace, these functions do not steal from move-only arguments if the insertion does not happen, which makes it easy to manipulate maps whose values are move-only types, such as std::map<std::string, std::unique_ptr<foo>>. In addition, try_emplace treats the key and the arguments to the mapped_type separately, unlike emplace, which requires the arguments to construct a value_type (that is, a std::pair)

See also

emplace (C++11)	constructs element in-place (public member function)
emplace_hint (C++11)	constructs elements in-place using a hint (public member function)
insert	inserts elements (public member function)