std::multimap::erase(3)

💅 std::multimap::erase(3) 💅

okay bestie, gather round 🫶 this is std::multimap::erase(3) from the C++ Standard Libary manual, and it is literally the “remove these elements from the multimap” page. No cap, it’s giving cleanup era. ✨

🌸 NAME 🌸

std::multimap::erase - std::multimap::erase. iconic, self-titled, no notes. 💖

---

✨ Synopsis ✨

Here’s the overload lineup, bestie — every signature stays exactly as written:

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

This whole thing removes specified elements from the container. The order of the remaining equivalent elements is preserved — yes ma’am, the leftovers keep their order. 🎀

1. Overloads (1), (2) — removes the element at pos.
2. Overload (3) — removes the elements in the range [first, last), which must be a valid range in *this.
3. Overload (4) — removes all elements with the key equivalent to key.
4. Overload (5) — removes all elements with key that compares equivalent to the value x. This overload participates in overload resolution only if the qualified-id Compare::is_transparent is valid and denotes a type, and neither iterator nor const_iterator is implicitly convertible from K. It allows calling this function without constructing an instance of Key.

Important vibe check: references and iterators to the erased elements are invalidated. Other references and iterators are not affected. 💀

Also, the iterator pos must be valid and dereferenceable. So the end() iterator — which is valid, but is not dereferenceable — cannot be used as a value for pos. Do not try it, bestie, that’s not the move. 🙈

🌈 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 Compare object.

🔥 Complexity 🔥

Given an instance c of multimap:

• 1,2) Amortized constant
• 3) log(c.size()) + std::distance(first, last)
• 4) log(c.size()) + c.count(key)
• 5) log(c.size()) + c.count(x)

🧚 Notes 🧚

Feature-test macro tea time ☕ — here’s the table content, preserved and perched:

• Feature-test macro: __cpp_lib_associative_heterogeneous_erasure
• Value: 202110L
• Std: (C++23)
• Feature: Heterogeneous erasure in associative containers and unordered associative containers; overload (5)

🍓 Example 🍓

The page says // Run this code, so run it, bestie — it’s the whole demo:

#include <map>
#include <iostream>

int main()
{
    std::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';
}

Output:

two four six

👑 Defect reports 👑

The following behavior-changing defect reports were applied retroactively to previously published C++ standards. History really said “we fixed that later,” and honestly? Slay. 💅

• LWG 130 — applied to C++98; behavior as published: the return type of overloads (1) and (3) was void (it is not consistent with the erase() requirement on sequence containers); correct behavior: corrected to iterator.
• LWG 371 — applied to C++98; behavior as published: the order of equivalent elements that are not erased was not guaranteed to be preserved; correct behavior: required to be preserved.
• LWG 2059 — applied to C++11; behavior as published: replacing overload (1) with overload (2) introduced new ambiguity; correct behavior: added overload (1) back.

⭐ See also ⭐

• clear — clears the contents (public member function)

---

lowkey that’s the whole page, bestie. No cap, every overload, every caveat, every little detail is here and accounted for. 🫶

<cute sign-off> from http://cppreference.com, version 2024.06.10, page std::multimap::erase(3) — mwah 💋✨