std::flat_multimap::insert(3)

💅 NAME 💅

std::flat_multimap::insert — literally std::flat_multimap::insert, bestie. This is the std::flat_multimap::insert(3) page from the C++ Standard Libary manual (yes, that's the spelling on the page, don't come for me 😭), and it's giving full insert-overload lore.

---

✨ Synopsis ✨

          iterator insert( const value_type& value );                       (1)
       (since C++23)
          iterator 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 >                                               (5)
       (since C++23)
          iterator insert( P&& x );
          template< class P >                                               (6)
       (since C++23)
          iterator insert( const_iterator pos, P&& x );
          template< class InputIt >                                         (7)
       (since C++23)
          void insert( InputIt first, InputIt last );
          template< class InputIt >
          void insert( std::sorted_equivalent_t, InputIt first, InputIt     (8)
       (since C++23)
          last );
          void insert( std::initializer_list<key_type> ilist );             (9)
       (since C++23)
          void insert( std::sorted_equivalent_t s,
       (10) (since C++23)
          std::initializer_list<key_type> ilist );

🫶 okay so what does it actually do 🫶

Inserts element(s) into the container. Groundbreaking, I know. Here's the tea, overload by overload:

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

May allocate memory during the in-place merge operation.

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.

May allocate memory during the in-place merge operation.

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

Also, the page literally has this line: 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()).

---

🦋 Type requirements 🦋

• InputIt must meet the requirements of LegacyInputIterator.

---

🎀 Return value 🎀

• 1-6) An iterator to the inserted element.
• 7-10) (none)

---

💀 Exceptions 💀

• 1-6) If an exception is thrown by any operation, the insertion has no effect.
• 7-10) No exception safety guarantee. (?)

This section is incomplete Reason: double check 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.

---

🧚 Example 🧚

This section is incomplete Reason: no example

---

👑 See also 👑

• emplace — constructs element in-place (public member function)
• emplace_hint — constructs elements in-place using a hint (public member function)
• inserter — creates a std::insert_iterator of type inferred from the argument (function template)

---

🍓 Categories 🍓

• Todo with reason
• Todo no example

---

okay bestie, that's the whole page 💖 source/version: http://cppreference.com · date: 2024.06.10 · page: std::flat_multimap::insert(3) — mwah 💋