std::forwar...ve,remove_if(3)

💅 std::forward_list::remove, remove_if — bestie edition 💅

okay so welcome to the std::forwar...ve,remove_if(3) page from the C++ Standard Libary manual — yes, that's the manual name exactly as the header spells it. This is the std::forward_list::remove and remove_if situation, and we're gonna make it make sense together. 🫶

🌸 NAME 🌸

std::forward_list::remove,remove_if — that's the name, bestie. The description line is the exact same string: std::forward_list::remove,remove_if. It's giving "the title is the title" energy, and honestly? iconic. ✨

✨ Synopsis ✨

The synopsis on the page is a little feral, so here it is with all the exact declarations and annotations:

void remove( const T& value );                   (since C++11)
                                                 (until C++20)
size_type remove( const T& value );              (since C++20)
template< class UnaryPredicate >         (1)                   (since C++11)
void remove_if( UnaryPredicate p );          (2)               (until C++20)
template< class UnaryPredicate >                               (since C++20)
size_type remove_if( UnaryPredicate p );

It removes all elements that satisfy the criteria. The only iterators and references that get invalidated are the ones pointing at the removed elements — not the whole container, so breathe. 💅

1. Removes every element equal to value, using operator==.
2. Removes every element for which the predicate p returns true.

💖 Parameters 💖

• value — the value of the elements to remove.
• p — a unary predicate that returns true if the element should be removed.

Okay, predicate lore time: the expression p(v) must be convertible to bool for every argument v of type (possibly const) T, regardless of value category, and it must not modify v. So a parameter type of T& is not allowed, and neither is T unless for T a move is equivalent to a copy (since C++11). 🫶

🎀 Type requirements 🎀

• UnaryPredicate must meet the requirements of Predicate.

🦋 Return value 🦋

• (none) — until C++20.
• The number of elements removed — since C++20.

🌈 Complexity 🌈

Given N as std::distance(begin(), end()):

1. Exactly N comparisons using operator==.
2. Exactly N applications of the predicate p.

⭐ Notes ⭐

The feature-test macro table is serving:

• Feature-test macro: __cpp_lib_list_remove_return_type
• Value: 201806L
• Std: (C++20)
• Feature: Change the return type

🍓 Example 🍓

The example starts with // Run this code and then does this:

// Run this code

#include <forward_list>
#include <iostream>

int main()
{
    std::forward_list<int> l = {1, 100, 2, 3, 10, 1, 11, -1, 12};

    auto count1 = l.remove(1);
    std::cout << count1 << " elements equal to 1 were removed\n";

    auto count2 = l.remove_if([](int n){ return n > 10; });
    std::cout << count2 << " elements greater than 10 were removed\n";

    std::cout << "Finally, the list contains: ";
    for (int n : l)
        std::cout << n << ' ';
    std::cout << '\n';
}

💀 Output 💀

And the output block is exactly:

2 elements equal to 1 were removed
3 elements greater than 10 were removed
Finally, the list contains: 2 3 10 -1

👑 See also 👑

• remove — removes elements satisfying specific criteria
• remove_if (function template)

xoxo, source: http://cppreference.com · version/date: 2024.06.10 · page: std::forwar...ve,remove_if(3) — catch u later, bestie 💜🦋