function template

std::remove

template <class ForwardIterator, class T>  ForwardIterator remove (ForwardIterator first, ForwardIterator last, const T& val);

Remove value from range

[Note: This is the reference for algorithm remove. See remove for <cstdio>'s remove.]

Transforms the range [first,last) into a range with all the elements that compare equal to val 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 that compare equal to val by the next element that 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 function uses operator== to compare the individual elements to val.

The behavior of this function template is equivalent to:

template <class ForwardIterator, class T>
  ForwardIterator remove (ForwardIterator first, ForwardIterator last, const T& val)
{
  ForwardIterator result = first;
  while (first!=last) {
    if (!(*first == val)) {
      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 T>
  ForwardIterator remove (ForwardIterator first, ForwardIterator last, const T& val)
{
  ForwardIterator result = first;
  while (first!=last) {
    if (!(*first == val)) {
      if (result!=first)
        *result = move(*first);
      ++result;
    }
    ++first;
  }
  return result;
}

Parameters

first, last: Forward iterators to the initial and final positions in a sequence of move-assignable elements supporting being compared to a value of type T. 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.
val: Value to be removed.

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 that do not compare equal to val.

Example

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

int main () {
  int myints[] = {10,20,30,30,20,10,10,20};      // 10 20 30 30 20 10 10 20

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

  pend = std::remove (pbegin, pend, 20);         // 10 30 30 10 10 ?  ?  ?
                                                 // ^              ^
  std::cout << "range contains:";
  for (int* p=pbegin; p!=pend; ++p)
    std::cout << ' ' << *p;
  std::cout << '\n';

  return 0;
}

Output:

range contains: 10 30 30 10 10

Complexity

Linear in the distance between first and last: Compares 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 the element comparisons, the element assignments or the operations on iterators throws.
Note that invalid arguments cause undefined behavior.