Namespaces
Variants

std:: erase, std:: erase_if (std::list)

From cppreference.net

C++
Containers library
std::list
Member functions
Non-member functions
(C++20)
erase (std::list) erase_if (std::list)
(C++20) (C++20)
(until C++20) (until C++20) (until C++20) (until C++20) (until C++20)
Deduction guides (C++17)
Defined in header <list>
(1)
template < class T, class Alloc, class U >

typename std:: list < T, Alloc > :: size_type

erase ( std:: list < T, Alloc > & c, const U & value ) ;
(since C++20)
(until C++26)
template < class T, class Alloc, class U = T >

constexpr typename std:: list < T, Alloc > :: size_type

erase ( std:: list < T, Alloc > & c, const U & value ) ;
(since C++26)
template < class T, class Alloc, class Pred >

typename std:: list < T, Alloc > :: size_type

erase_if ( std:: list < T, Alloc > & c, Pred pred ) ;
(2) (since C++20)
(constexpr since C++26)
1) Erases all elements that compare equal to value from the container c . Equivalent to return c. remove_if ( [ & ] ( const auto & elem ) - > bool { return elem == value ; } ) ; .
2) Erases all elements that satisfy the predicate pred from the container c . Equivalent to return c. remove_if ( pred ) ; .

Contents

Parameters

c - container from which to erase
value - value to be removed
pred - unary predicate which returns ​ true if the element should be erased.

The expression pred ( v ) must be convertible to bool for every argument v of type (possibly const) T , regardless of value category , and must not modify v . Thus, a parameter type of T & is not allowed , nor is T unless for T a move is equivalent to a copy (since C++11) . ​

Return value

The number of erased elements.

Complexity

Linear.

Notes

Unlike std::list::remove , erase accepts heterogeneous types and does not force a conversion to the container's value type before invoking the == operator.

Feature-test macro Value Std Feature
__cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for std::erase

Example

Run this code 
#include <complex>
#include <iostream>
#include <numeric>
#include <string_view>
#include <list>
void println(std::string_view comment, const auto& c)
{
    std::cout << comment << '[';
    bool first{true};
    for (const auto& x : c)
        std::cout << (first ? first = false, "" : ", ") << x;
    std::cout << "]\n";
}
int main()
{
    std::list<char> cnt(10);
    std::iota(cnt.begin(), cnt.end(), '0');
    println("Initially, cnt = ", cnt);
    std::erase(cnt, '3');
    println("After erase '3', cnt = ", cnt);
    auto erased = std::erase_if(cnt, [](char x) { return (x - '0') % 2 == 0; });
    println("After erase all even numbers, cnt = ", cnt);
    std::cout << "Erased even numbers: " << erased << '\n';
    std::list<std::complex<double>> nums{{2, 2}, {4, 2}, {4, 8}, {4, 2}};
    #ifdef __cpp_lib_algorithm_default_value_type
        std::erase(nums, {4, 2});
    #else
        std::erase(nums, std::complex<double>{4, 2});
    #endif
    println("After erase {4, 2}, nums = ", nums);
}

Output: 

Initially, cnt = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
After erase '3', cnt = [0, 1, 2, 4, 5, 6, 7, 8, 9]
After erase all even numbers, cnt = [1, 5, 7, 9]
Erased even numbers: 5
After erase {4, 2}, nums = [(2,2), (4,8)]

Defect reports

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

DR Applied to Behavior as published Correct behavior
LWG 4135 C++20 the return type of the lambda predicate used
was deduced from predicate arguments 		the return type is
explicitly specified as bool

See also

removes elements satisfying specific criteria
(function template)
(C++20) (C++20)
removes elements satisfying specific criteria
(algorithm function object)
removes elements satisfying specific criteria
(public member function)