std::map try_emplace() method
- since C++17
// (1) Non const version only
template< class... Args >
pair<iterator, bool> try_emplace( const Key& k, Args&&... args );
// (2) Non const version only
template< class... Args >
pair<iterator, bool> try_emplace( Key&& k, Args&&... args );
// (3) Non const version only
template< class... Args >
iterator try_emplace( const_iterator hint, const Key& k, Args&&... args );
// (4) Non const version only
template< class... Args >
iterator try_emplace( const_iterator hint, Key&& k, Args&&... args );
Inserts a new element into the container with key k
and value constructed with args
, if there is no element with the key in the container.
- (1) If a key equivalent to
k
already exists in the container, does nothing. Otherwise, behaves likeemplace()
except that the element is constructed as
value_type(std::piecewise_construct,
std::forward_as_tuple(k),
std::forward_as_tuple(std::forward<Args>(args)...))
- (2) If a key equivalent to
k
already exists in the container, does nothing. Otherwise, behaves likeemplace()
except that the element is constructed as
value_type(std::piecewise_construct,
std::forward_as_tuple(std::move(k)),
std::forward_as_tuple(std::forward<Args>(args)...))
- (3) If a key equivalent to
k
already exists in the container, does nothing. Otherwise, behaves likeemplace_hint()
except that the element is constructed as
value_type(std::piecewise_construct,
std::forward_as_tuple(k),
std::forward_as_tuple(std::forward<Args>(args)...))
- (4) If a key equivalent to
k
already exists in the container, does nothing. Otherwise, behaves likeemplace_hint()
except that the element is constructed as
value_type(std::piecewise_construct,
std::forward_as_tuple(std::move(k)),
std::forward_as_tuple(std::forward<Args>(args)...))
No iterators or references are invalidated.
Parameters
k
- the key used both to look up and to insert if not foundhint
- iterator to the position before which the new element will be insertedargs
- 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()
.
Exceptions
If an exception is thrown by any operation, this function has no effect (strong exception guarantee).
Notes
Unlike insert()
or emplace()
,
these functions do not move from rvalue 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
).
Feature testing macro: __cpp_lib_map_try_emplace
.
Example
#include <iostream>
#include <utility>
#include <string>
#include <map>
auto print_node = [](const auto &node) {
std::cout << "[" << node.first << "] = " << node.second << '\n';
};
auto print_result = [](auto const &pair) {
std::cout << (pair.second ? "inserted: " : "ignored: ");
print_node(*pair.first);
};
int main()
{
using namespace std::literals;
std::map<std::string, std::string> m;
print_result( m.try_emplace("a", "a"s) );
print_result( m.try_emplace("b", "abcd") );
print_result( m.try_emplace("c", 10, 'c') );
print_result( m.try_emplace("c", "Won't be inserted") );
for (const auto &p : m) { print_node(p); }
}
inserted: [a] = a
inserted: [b] = abcd
inserted: [c] = cccccccccc
ignored: [c] = cccccccccc
[a] = a
[b] = abcd
[c] = cccccccccc
Hover to see the original license.