std::unordered_map::try_emplace(3)

NAME
std::unordered_map::try_emplace - std::unordered_map::try_emplace

Synopsis
   template< class... Args > (1) (since C++17)
   pair<iterator, bool> try_emplace( const Key& k, Args&&... args );
   template< class... Args > (2) (since C++17)
   pair<iterator, bool> try_emplace( Key&& k, Args&&... args );
   template< class... Args >
   iterator try_emplace( const_iterator hint, const Key& k, Args&&... (3) (since C++17)
   args );
   template< class... Args >
   iterator try_emplace( const_iterator hint, Key&& k, Args&&... args (4) (since C++17)
   );
   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 like emplace 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 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(std::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(std::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(std::forward<Args>(args)...))
   If rehashing occurs due to the insertion, all iterators are invalidated. Otherwise
   iterators are not affected. References are not invalidated. Rehashing occurs only if
   the new number of elements is greater than max_load_factor()*bucket_count().

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 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::unordered_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-test macro: __cpp_lib_unordered_map_try_emplace

Example
// Run this code
 #include <iostream>
 #include <utility>
 #include <string>
 #include <unordered_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::unordered_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); }
 }

Possible output:
 inserted: [a] = a
 inserted: [b] = abcd
 inserted: [c] = cccccccccc
 ignored: [c] = cccccccccc
 [a] = a
 [b] = abcd
 [c] = cccccccccc

See also
   emplace constructs element in-place
   (C++11) (public member function)
   emplace_hint constructs elements in-place using a hint
   (C++11) (public member function)
                inserts elements
   insert or nodes
   (C++11) (since C++17)
                (public member function)