std::unordered_set::erase(3)

✨ std::unordered_set::erase — the manual page bestie 💅

Okay so like, this is the <std::unordered_set::erase(3)> page from the C++ Standard Library manual, and honestly? It's giving "I can delete things from a hash set and look cute doing it" energy. Let me walk you through it, no cap. 🎀

---

🌸 NAME 🌸

std::unordered_set::erase — literally the function that removes stuff, and its name is the same as the function, iconic.

---

🦋 SYNOPSIS 🦋

Here's the tea, bestie — the overloads are a whole vibe and you need to know every single one:

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

---

💖 DESCRIPTION 💖

This function removes specified elements from the container. The order of the remaining elements is preserved — and honestly that's highkey important because it means you can erase individual elements while you're iterating through the container. Main character energy, fr fr. 🔥

Let's break down each overload, because every single one matters:

1. Overloads 1 and 2 — Removes the element at pos. Only one overload is provided if iterator and const_iterator are the same type. (They're two versions of the same vibe.)
2. Overload 3 — Removes the elements in the range [first, last), which must be a valid range in *this. Periodt.
3. Overload 4 — Removes the element (if one exists) with the key equivalent to key. If it's not there, no biggie, nothing happens.
4. Overload 5 — Removes all elements with key that compares equivalent to the value x. But listen — this overload only participates in overload resolution 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. It's giving "optimized and smart," honestly. 🧚

Big important caveat, don't skip this: References and iterators to the erased elements are invalidated. Other iterators and references are not invalidated.

Also, and I cannot stress this enough: 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. It's literally invalid, bestie. 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 💜

• Overloads 1–3 — Iterator following the last removed element.
• Overload 4 — Number of elements removed (0 or 1).
• Overload 5 — Number of elements removed.

---

🫶 EXCEPTIONS 🫶

• Overloads 1–3 — Throws nothing. Literally nothing. Chill.
• Overloads 4, 5 — Any exceptions thrown by the Hash and KeyEqual object.

---

🍓 COMPLEXITY 🍓

Given an instance c of unordered_set:

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

So like, usually fast, but worst case it's the whole set. Manage your expectations. 😭

---

🌟 NOTES 🌟

There's a feature-test macro for the heterogeneous erasure thing, and it's giving very specific:

Anyway, that table is the whole vibe. Moving on. ✨

---

🧚 EXAMPLE 🧚

// Run this code

#include <unordered_set>
#include <iostream>

int main()
{
    std::unordered_set<int> c = {1, 2, 3, 4, 1, 2, 3, 4};

    auto print = [&c]
    {
        std::cout << "c = { ";
        for (int n : c)
            std::cout << n << ' ';
        std::cout << "}\n";
    };
    print();

    std::cout << "Erase all odd numbers:\n";
    for (auto it = c.begin(); it != c.end();)
    {
        if (*it % 2 != 0)
            it = c.erase(it);
        else
            ++it;
    }
    print();

    std::cout << "Erase 1, erased count: " << c.erase(1) << '\n';
    std::cout << "Erase 2, erased count: " << c.erase(2) << '\n';
    std::cout << "Erase 2, erased count: " << c.erase(2) << '\n';
    print();
}

This example is so cute — it prints the set, erases all the odd numbers while iterating (the safe way, bestie), then erases specific keys and shows you the counts. Obsessed. 👑

---

💀 DEFECT REPORTS 💀

The following behavior-changing defect reports were applied retroactively to previously published C++ standards. Not me reading the lore of C++ fixes, but okay:

So yeah, they fixed the ambiguity and made the preserved order a guarantee. Slay. 💅

---

👀 SEE ALSO 👀

• clear — clears the contents (public member function). Lowkey does what it says on the tin.

---

That's the whole manual page, bestie — every overload, every caveat, every complexity note, all preserved. No details lost, just vibes added. 💖

This page is from cppreference.com, dated 2024.06.10, and it's titled std::unordered_set::erase(3). ✨