std::remove_if

template <class ForwardIterator, class UnaryPredicate>  ForwardIterator remove_if (ForwardIterator first, ForwardIterator last,                             UnaryPredicate pred);

Remove elements from range

Transforms the range [first,last) into a range with all the elements for which pred returns true removed, and returns an iterator to the new end of that range.

The function cannot alter the properties of the object containing the range of elements (i.e., it cannot alter the size of an array or a container): The removal is done by replacing the elements for which pred returns true by the next element for which it does not, and signaling the new size of the shortened range by returning an iterator to the element that should be considered its new past-the-end element.

The relative order of the elements not removed is preserved, while the elements between the returned iterator and last are left in a valid but unspecified state.

The behavior of this function template is equivalent to:

template <class ForwardIterator, class UnaryPredicate>
  ForwardIterator remove_if (ForwardIterator first, ForwardIterator last,
                             UnaryPredicate pred)
{
  ForwardIterator result = first;
  while (first!=last) {
    if (!pred(*first)) {
      if (result!=first)
        *result = *first;
      ++result;
    }
    ++first;
  }
  return result;
}

The elements are replaced by move-assigning them their new values.

The behavior of this function template is equivalent to:

template <class ForwardIterator, class UnaryPredicate>
  ForwardIterator remove_if (ForwardIterator first, ForwardIterator last,
                             UnaryPredicate pred)
{
  ForwardIterator result = first;
  while (first!=last) {
    if (!pred(*first)) {
      if (result!=first)
        *result = std::move(*first);
      ++result;
    }
    ++first;
  }
  return result;
}

Parameters

first, last: Forward iterators to the initial and final positions in a sequence of move-assignable elements. The range used is [first,last), which contains all the elements between first and last, including the element pointed by first but not the element pointed by last.
pred: Unary function that accepts an element in the range as argument, and returns a value convertible to bool. The value returned indicates whether the element is to be removed (if true, it is removed).
The function shall not modify its argument.
This can either be a function pointer or a function object.

Return value

An iterator to the element that follows the last element not removed.
The range between first and this iterator includes all the elements in the sequence for which pred does not return true.

Example

// remove_if example
#include <iostream>     // std::cout
#include <algorithm>    // std::remove_if

bool IsOdd (int i) { return ((i%2)==1); }

int main () {
  int myints[] = {1,2,3,4,5,6,7,8,9};            // 1 2 3 4 5 6 7 8 9

  // bounds of range:
  int* pbegin = myints;                          // ^
  int* pend = myints+sizeof(myints)/sizeof(int); // ^                 ^

  pend = std::remove_if (pbegin, pend, IsOdd);   // 2 4 6 8 ? ? ? ? ?
                                                 // ^       ^
  std::cout << "the range contains:";
  for (int* p=pbegin; p!=pend; ++p)
    std::cout << ' ' << *p;
  std::cout << '\n';

  return 0;
}

Output:

the range contains: 2 4 6 8

Complexity

Linear in the distance between first and last: Applies pred to each element, and possibly performs assignments on some of them.

Data races

The objects in the range [first,last) are accessed and potentially modified.

Exceptions

throws if any of pred, the element assignments or the operations on iterators throws.
Note that invalid arguments cause undefined behavior.