std::map<Key,T,Compare,Allocator>::try_emplace
| template< class... Args > std::pair<iterator, bool> try_emplace( const Key& k, Args&&... args ); |
(1) | (since C++17) |
| template< class... Args > std::pair<iterator, bool> try_emplace( Key&& k, Args&&... args ); |
(2) | (since C++17) |
| template< class K, class... Args > std::pair<iterator, bool> try_emplace( K&& k, Args&&... args ); |
(3) | (since C++26) |
| template< class... Args > iterator try_emplace( const_iterator hint, const Key& k, Args&&... args ); |
(4) | (since C++17) |
| template< class... Args > iterator try_emplace( const_iterator hint, Key&& k, Args&&... args ); |
(5) | (since C++17) |
template< class K, class... Args > iterator try_emplace( const_iterator hint, K&& k, Args&&... args ); |
(6) | (since C++26) |
If a key equivalent to k already exists in the container, does nothing. Otherwise, inserts a new element into the container with key k and value constructed with args. In such case:
emplace except that the element is constructed asvalue_type(std::piecewise_construct,
std::forward_as_tuple(std::forward<Args>(args)...))
emplace except that the element is constructed asvalue_type(std::piecewise_construct,
std::forward_as_tuple(std::move(k)),
emplace except that the element is constructed asvalue_type(std::piecewise_construct,
std::forward_as_tuple(std::forward<K>(k)),
emplace_hint except that the element is constructed asvalue_type(std::piecewise_construct,
std::forward_as_tuple(std::forward<Args>(args)...))
emplace_hint except that the element is constructed asvalue_type(std::piecewise_construct,
std::forward_as_tuple(std::move(k)),
emplace_hint except that the element is constructed asvalue_type(std::piecewise_construct,
std::forward_as_tuple(std::forward<K>(k)),
value_type is not EmplaceConstructible into map from the corresponding expression, the behavior is undefined.- std::is_convertible_v<K&&, const_iterator> and std::is_convertible_v<K&&, iterator> are both false.
- The qualified-id Compare::is_transparent is valid and denotes a type.
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
emplace:A pair consisting of an iterator to the inserted element (or to the element that prevented the insertion) and a bool value set to true if and only if the insertion took place.
emplace_hint:An iterator to the inserted element, or to the element that prevented the insertion.
Complexity
emplace_hint:Logarithmic in the size of the container in general, but amortized constant if the new element is inserted just before hint.
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).
Overloads (3,6) can be called without constructing an object of type Key.
| Feature-test macro | Value | Std | Feature |
|---|---|---|---|
__cpp_lib_map_try_emplace |
201411L |
(C++17) | std::map::try_emplace, std::map::insert_or_assign
|
__cpp_lib_associative_heterogeneous_insertion |
202311L |
(C++26) | Heterogeneous overloads for the remaining member functions in ordered and unordered associative containers. Overloads (3) and (6). |
Example
#include <iostream> #include <string> #include <map> #include <utility> void print_node(const auto& node) { std::cout << '[' << node.first << "] = " << node.second << '\n'; } void 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); }
Output:
inserted: [a] = a inserted: [b] = abcd inserted: [c] = cccccccccc ignored: [c] = cccccccccc [a] = a [b] = abcd [c] = cccccccccc
See also
| (C++11) |
constructs element in-place (public member function) |
| (C++11) |
constructs elements in-place using a hint (public member function) |
| inserts elements or nodes(since C++17) (public member function) |