std::set::erase(3)

🎀 NAME 🎀

std::set::erase — literally std::set::erase, bestie. Welcome to std::set::erase(3) from the C++ Standard Libary manual. Yes, that manual name is spelled exactly like that, and we are obsessed. 💅

✨ SYNOPSIS ✨

okay so here’s the overload lineup, no cap:

iterator erase( iterator pos );                          (until C++23)

iterator erase( iterator pos )
    requires(!std::same_as<iterator, const_iterator>);   (since C++23)

iterator erase( const_iterator pos );                   (2) (since C++11)

iterator erase( iterator first, iterator last );        (1) (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 >
size_type erase( K&& x );                               (5) (since C++23)

Removes specified elements from the container. Periodt. 💖

• 1,2) Removes the element at pos. Only one overload is provided if iterator and const_iterator are the same type. (since C++11)
• 3) Removes the elements in the range [first, last), which must be a valid range in *this.
• 4) Removes the element (if one exists) 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 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.

🫶 heads up, bestie: 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. Thus the end() iterator (which is valid, but is not dereferenceable) cannot be used as a value for pos.

💖 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 (0 or 1).
• 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 set:

• 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, served fresh ☕:

• 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 🦋

This little demo is giving main character energy, fr fr:

// Run this code

#include <set>
#include <iostream>

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

💀 DEFECT REPORTS 💀

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

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

---

source/version: http://cppreference.com · date: 2024.06.10 · page: std::set::erase(3) — mwah, bestie 💋✨