# std::unordered_map<Key,T,Hash,KeyEqual,Allocator>::try_emplace

> C++ Atlas: `cppatlas.com/w/cpp/container/unordered_map/try_emplace` | Source: https://en.cppreference.com/w/cpp/container/unordered_map/try_emplace | Domain: Containers | Standards: C++17, 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.

## Official Specification Summary (cppreference)

```cpp
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:

1) 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) 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) Behaves like `emplace` except that the element is constructed as
`value_type(std::piecewise_construct, std::forward_as_tuple(std::forward<K>(k)), std::forward_as_tuple(std::forward<Args>(args)...))`

4) 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)...))`

5) 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)...))`

6) Behaves like `emplace_hint` except that the element is constructed as
`value_type(std::piecewise_construct, std::forward_as_tuple(std::forward<K>(k)), std::forward_as_tuple(std::forward<Args>(args)...))`

1-6) If `value_type` is not *EmplaceConstructible* into `unordered_map` from the corresponding expression, the behavior is undefined.

  3) This overload participates in overload resolution only if all following conditions are satisfied:

     - `std::is_convertible_v<K&&, const_iterator>` and `std::is_convertible_v<K&&, iterator>` are both `false`.
     - `Hash::is_transparent` and `KeyEqual::is_transparent` are valid and each denotes a type.

  If `hash_function()(u.first) != hash_function()(k) || contains(u.first)` is `true`, the behavior is undefined, where `u` is the new element to be inserted.

  6) This overload participates in overload resolution only if `Hash::is_transparent` and `KeyEqual::is_transparent` are both valid and each denotes a type.

  If `hash_function()(u.first) != hash_function()(k) || contains(u.first)` is `true`, the behavior is undefined, where `u` is the new element to be inserted.

If after the operation the new number of elements is greater than old `max_load_factor() * bucket_count()` a rehashing takes place.
If rehashing occurs (due to the insertion), all iterators are invalidated. Otherwise (no rehashing), iterators are not 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-3) Same as for `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.

4-6) Same as for `emplace_hint`:
An iterator to the inserted element, or to the element that prevented the insertion.

### Complexity

1-3) Same as for `emplace`:
Amortized constant on average, worst case linear in the size of the container.

4-6) Same as for `emplace_hint`:
Amortized constant on average, worst case linear in the size of the container.

### 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`).

Overloads (3,6) can be called without constructing an object of type `Key`.

| Feature-test macro | Value | Std | Feature |
| --- | --- | --- | --- |
| `__cpp_lib_unordered_map_try_emplace` | `201411L` | (C++17) | `std::unordered_map::try_emplace`, `std::unordered_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

```cpp
#include <iostream>
#include <string>
#include <unordered_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::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:

```text
inserted: [a] = a
inserted: [b] = abcd
inserted: [c] = cccccccccc
ignored:  [c] = cccccccccc
[a] = a
[b] = abcd
[c] = cccccccccc
```

### See also

- [`emplace`](https://en.cppreference.com/w/cpp/container/unordered_map/emplace): constructs element in-place (public member function)
- [`emplace_hint`](https://en.cppreference.com/w/cpp/container/unordered_map/emplace_hint): constructs elements in-place using a hint (public member function)
- [`insert`](https://en.cppreference.com/w/cpp/container/unordered_map/insert): inserts elements or nodes (since C++17) (public member function)

---
Attribution: content from https://en.cppreference.com/w/cpp/container/unordered_map/try_emplace (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.