std::unorde...ap::emplace(3)

💖 NAME 💖

std::unordered_multimap::emplace — the one and only std::unordered_multimap::emplace, straight from the C++ Standard Libary manual. bestie, this is the in-place insert era 💅

---

✨ Synopsis ✨

okay so here's the signature, no cap:

template< class... Args >            (since C++11)
iterator emplace( Args&&... args );

Inserts a new element into the container constructed in-place with the given args. 🫶

The constructor of the new element (i.e. std::pair<const Key, T>) is called with exactly the same arguments as supplied to emplace, forwarded via std::forward<Args>(args).... literally forwarding the vibes ✨

Careful use of emplace allows the new element to be constructed while avoiding unnecessary copy or move operations. iconic behavior, honestly 🎀

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. so yeah, mind your iterators bestie 😭

---

🌸 Parameters 🌸

• args — arguments to forward to the constructor of the element. 💖

---

🦋 Return value 🦋

An iterator to the inserted element. slay. ✨

---

🎀 Exceptions 🎀

If an exception is thrown for any reason, this function has no effect — that's the strong exception safety guarantee, bestie. 🫶

---

🔥 Complexity 🔥

Amortized constant on average, worst case linear in the size of the container. 👑

---

🌈 Example 🌈

// Run this code

#include <iostream>
#include <string>
#include <utility>
#include <unordered_map>

int main()
{
    std::unordered_multimap<std::string, std::string> m;

    // uses pair's move constructor
    m.emplace(std::make_pair(std::string("a"), std::string("a")));

    // uses pair's converting move constructor
    m.emplace(std::make_pair("b", "abcd"));

    // uses pair's template constructor
    m.emplace("d", "ddd");

    // emplace with duplicate key
    m.emplace("d", "DDD");

    // uses pair's piecewise constructor
    m.emplace(std::piecewise_construct,
              std::forward_as_tuple("c"),
              std::forward_as_tuple(10, 'c'));

    for (const auto& p : m)
        std::cout << p.first << " => " << p.second << '\n';
}

Possible output:

a => a
b => abcd
c => cccccccccc
d => ddd
d => DDD

---

👑 See also 👑

• emplace_hint — constructs elements in-place using a hint (public member function). 💅
• try_emplace — inserts in-place if the key does not exist, does nothing if the key exists (public member function). ✨
• insert — inserts elements or nodes (since C++17) (public member function). 🌈

---

mwah 💋 — source: cppreference.com, date: 2024.06.10. go be iconic, bestie 🫶