# std::flat_map<Key,T,Compare,KeyContainer,MappedContainer>::insert

> C++ Atlas: `cppatlas.com/w/cpp/container/flat_map/insert` | Source: https://en.cppreference.com/w/cpp/container/flat_map/insert | Domain: Containers | Standards: C++23

Inserts element(s) into the container, if the container does not already contain an element with an equivalent key.

## Official Specification Summary (cppreference)

```cpp
std::pair<iterator, bool> insert( const value_type& value ); // (1) (since C++23)

std::pair<iterator, bool> insert( value_type&& value ); // (2) (since C++23)

iterator insert( const_iterator pos, const value_type& value ); // (3) (since C++23)

iterator insert( const_iterator pos, value_type&& value ); // (4) (since C++23)

template< class P >
std::pair<iterator, bool> insert( P&& x ); // (5) (since C++23)

template< class P >
iterator insert( const_iterator pos, P&& x ); // (6) (since C++23)

template< class InputIt >
void insert( InputIt first, InputIt last ); // (7) (since C++23)

template< class InputIt >
void insert( std::sorted_unique_t, InputIt first, InputIt last ); // (8) (since C++23)

void insert( std::initializer_list<key_type> ilist ); // (9) (since C++23)

void insert( std::sorted_unique_t s, std::initializer_list<key_type> ilist ); // (10) (since C++23)
```

Inserts element(s) into the container, if the container does not already contain an element with an equivalent key.

1) Inserts `value`. Equivalent to `return emplace(value);`.

2) Inserts `value`. Equivalent to `return emplace(std::move(value));`.

3) Inserts `value` in the position as close as possible to the position just prior to `pos`. Equivalent to `return emplace_hint(pos, value);`.

4) Inserts `value` in the position as close as possible to the position just prior to `pos`. Equivalent to `return emplace_hint(pos, std::move(value));`.

5) If `*this` already contains an element which transparently compares *equivalent* to `x`, does nothing. Otherwise, inserts `x` into `*this` as if by `emplace(std::forward<P>(x));`. This overload participates in overload resolution only if `std::is_constructible_v<pair<key_type, mapped_type>, P>` is `true`.

6) If `*this` already contains an element which transparently compares *equivalent* to `x`, does nothing. Otherwise, inserts `x` into `*this` in the position as close as possible to the position just prior to `pos`. Equivalent to `return emplace_hint(position, std::forward<P>(x));`. This overload participates in overload resolution only if `std::is_constructible_v<pair<key_type, mapped_type>, P>` is `true`.

7) Inserts elements from range `[first,` `last)` as if performing the following operations sequentially:

   1. Adds elements to `c` as if by
      `for (; first != last; ++first){ value_type value = *first; c.keys.insert(c.keys.end(), std::move(value.first)); c.values.insert(c.values.end(), std::move(value.second));}`
   2. Sorts the range of newly inserted elements with respect to `value_comp`.
   3. Merges the resulting sorted range and the sorted range of pre-existing elements into a single sorted range.
   4. Erases the duplicate elements as if by:
      `auto zv = std::views::zip(c.keys, c.values);auto it = ranges::unique(zv, key_equiv(compare)).begin();auto dist = std::distance(zv.begin(), it);c.keys.erase(c.keys.begin() + dist, c.keys.end());c.values.erase(c.values.begin() + dist, c.values.end());`

May allocate memory during the in-place merge operation.

If multiple elements in the range have keys that compare equivalent, it is unspecified which element is inserted (pending LWG2844).

8) Inserts elements from range `[first,` `last)` as if performing the following operations sequentially:

   1. Adds elements to `c` as if by
      `for (; first != last; ++first){ value_type value = *first; c.keys.insert(c.keys.end(), std::move(value.first)); c.values.insert(c.values.end(), std::move(value.second));}`
   2. Merges the sorted range of newly added elements and the sorted range of pre-existing elements into a single sorted range.
   3. Erases the duplicate elements as if by:
      `auto zv = std::views::zip(c.keys, c.values);auto it = ranges::unique(zv, key_equiv(compare)).begin();auto dist = std::distance(zv.begin(), it);c.keys.erase(c.keys.begin() + dist, c.keys.end());c.values.erase(c.values.begin() + dist, c.values.end());`

May allocate memory during the in-place merge operation.

If multiple elements in the range have keys that compare equivalent, it is unspecified which element is inserted (pending LWG2844).

9) Inserts elements from initializer list `ilist`. Equivalent to `insert(ilist.begin(), ilist.end());`.

If multiple elements in the range have keys that compare equivalent, it is unspecified which element is inserted (pending LWG2844).

10) Inserts elements from initializer list `ilist`. Equivalent to `insert(s, ilist.begin(), ilist.end());`.

If multiple elements in the range have keys that compare equivalent, it is unspecified which element is inserted (pending LWG2844).

> Note: Information on iterator invalidation is copied from here

### Parameters

- `pos` - an iterator to the position before which the new element will be inserted
- `value` - an element value to insert
- `first, last` - a range of elements to insert
- `ilist` - an initializer list to insert the values from
- `x` - a value of any type that can be transparently compared with a key
- `s` - a disambiguation tag indicating that the input sequence is sorted (with respect to `value_comp()`) and contains only unique elements

**Type requirements**

- `InputIt` must meet the requirements of *LegacyInputIterator*.

### Return value

1,2) 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.

3,4) An iterator to the inserted element, or to the element that prevented the insertion.

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

6) An iterator to the inserted element, or to the element that prevented the insertion.

7-10) (none)

### Exceptions

1-6) If an exception is thrown by any operation, the insertion has no effect.

> Note: This section is incomplete Reason: cases 7-10

### Complexity

1-6) Linear in `size()`.

7) `N + M·log(M)`, where `N` is the `size()` before the operation and `M` is `std::distance(first, last)`.

8) Linear in `size()`.

9) `N + M·log(M)`, where `N` is the `size()` before the operation and `M` is `ilist.size()`.

10) Linear in `N`, where `N` is `size()` after the operation.

### Notes

The hinted insert (3,4,6) does not return a boolean in order to be signature-compatible with positional insert on sequential containers, such as `std::vector::insert`. This makes it possible to create generic inserters such as `std::inserter`. One way to check success of a hinted insert is to compare `size()` before and after.

### Example

> Note: This section is incomplete Reason: no example

### See also

- [`emplace`](https://en.cppreference.com/w/cpp/container/flat_map/emplace): constructs element in-place (public member function)
- [`emplace_hint`](https://en.cppreference.com/w/cpp/container/flat_map/emplace_hint): constructs elements in-place using a hint (public member function)
- [`insert_or_assign`](https://en.cppreference.com/w/cpp/container/flat_map/insert_or_assign): inserts an element or assigns to the current element if the key already exists (public member function)
- [`inserter`](https://en.cppreference.com/w/cpp/iterator/inserter): creates a `std::insert_iterator` of type inferred from the argument (function template)

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