std::unorde...imap::erase(3)

okay bestie, this is the std::unordered_multimap::erase(3) page from the C++ Standard Libary manual — yes, the manual name is literally std::unordered_multimap::erase(3), and we're about to make erasing elements make sense. 🫶

🏷️ NAME

std::unordered_multimap::erase — the erase member function of std::unordered_multimap. That's the whole name, periodt. 💅

✨ SYNOPSIS ✨

the overloads, exactly as written:

iterator erase( iterator pos );                              (1)
iterator erase( const_iterator pos );                        (2)
iterator erase( const_iterator first, const_iterator last ); (3)
size_type erase( const Key& key );                           (4)
template< class K >                                          (5)
size_type erase( K&& x );

• (1), (2), (3), (4) are since C++11.
• (5) is since C++23.

It removes the specified elements from the container, and the order of the remaining elements is preserved — yes, preserved. (This makes it possible to erase individual elements while iterating through the container.) 🦋

• (1), (2) — removes the element at pos.
• (3) — removes the elements in the range [first, last), which must be a valid range in *this.
• (4) — removes all elements with the key equivalent to key.
• (5) — removes all elements with key that compares equivalent to the value x. This overload participates in overload resolution only if Hash::is_transparent and KeyEqual::is_transparent are valid and each denotes a type, and neither iterator nor const_iterator is implicitly convertible from K. This assumes that such Hash is callable with both K and Key type, and that the KeyEqual is transparent, which, together, allows calling this function without constructing an instance of Key. 🔥

References and iterators to the erased elements are invalidated. Other iterators and references are not invalidated.

The pos iterator must be valid and dereferenceable. So end() — which is valid, but is not dereferenceable — cannot be used as a value for pos. no cap, don't do it 😭

🌸 PARAMETERS 🌸

• pos — iterator to the element to remove.
• first, last — range of elements to remove.
• key — key value of the elements to remove.
• x — a value of any type that can be transparently compared with a key denoting the elements to remove.

🎀 RETURN VALUE 🎀

• (1)-(3) — iterator following the last removed element.
• (4) — number of elements removed.
• (5) — number of elements removed.

🦋 EXCEPTIONS 🦋

• (1)-(3) — throws nothing.
• (4), (5) — any exceptions thrown by the Hash and KeyEqual object.

⭐ COMPLEXITY ⭐

Given an instance c of unordered_multimap:

• (1), (2) — average case: constant, worst case: c.size().
• (3) — average case: std::distance(first, last), worst case: c.size().
• (4) — average case: c.count(key), worst case: c.size().
• (5) — average case: c.count(x), worst case: c.size().

🧚 NOTES 🧚

the feature-test macro tea ☕:

• __cpp_lib_associative_heterogeneous_erasure — value 202110L, std (C++23), feature: Heterogeneous erasure in associative and unordered associative containers; overload (5).

💜 EXAMPLE 💜

Run this code, bestie:

#include <unordered_map>
#include <iostream>

int main()
{
    std::unordered_multimap<int, std::string> c =
    {
        {1, "one"}, {2, "two"}, {3, "three"},
        {4, "four"}, {5, "five"}, {6, "six"}
    };

    // erase all odd numbers from c
    for (auto it = c.begin(); it != c.end();)
    {
        if (it->first % 2 != 0)
            it = c.erase(it);
        else
            ++it;
    }

    for (auto& p : c)
        std::cout << p.second << ' ';
    std::cout << '\n';
}

🌈 POSSIBLE OUTPUT 🌈

two four six

🍓 DEFECT REPORTS 🍓

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

• LWG 2059 — applied to: C++11. Behavior as published: there was ambiguity for overload (2). Correct behavior: added overload (1).
• LWG 2356 — applied to: C++11. Behavior as published: the order of non-equivalent elements that are not erased was not guaranteed to be preserved. Correct behavior: required to be preserved.

👀 SEE ALSO 👀

• clear — clears the contents (public member function).

---

that's the whole page, bestie — source: http://cppreference.com, version/date: 2024.06.10, and the manual name again for the vibes: std::unordered_multimap::erase(3). slay. 💅✨