remove

 Category: algorithms Component type: function

Prototype

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

Description

`Remove` removes from the range `[first, last)` all elements that are equal to `value`. That is, `remove` returns an iterator `new_last` such that the range `[first, new_last)` contains no elements equal to `value`. [1] The iterators in the range `[new_last, last)` are all still dereferenceable, but the elements that they point to are unspecified. `Remove` is stable, meaning that the relative order of elements that are not equal to `value` is unchanged.

Definition

Defined in the standard header algorithm, and in the nonstandard backward-compatibility header algo.h.

Requirements on types

• `ForwardIterator` is a model of ForwardIterator.
• `ForwardIterator` is mutable.
• `T` is a model of EqualityComparable.
• Objects of type `T` can be compared for equality with objects of `ForwardIterator`'s value type.

Preconditions

• `[first, last)` is a valid range.

Complexity

Linear. `Remove` performs exactly `last - first` comparisons for equality.

Example

```Vector<int> V;
V.push_back(3);
V.push_back(1);
V.push_back(4);
V.push_back(1);
V.push_back(5);
V.push_back(9);

copy(V.begin(), V.end(), ostream_iterator<int>(cout, " "));
// The output is "3 1 4 1 5 9".

vector<int>::iterator new_end = remove(V.begin(), V.end(), 1);
copy(V.begin(), new_end, ostream_iterator<int>(cout, " "));
// The output is "3 4 5 9".
```

Notes

[1] The meaning of "removal" is somewhat subtle. `Remove` does not destroy any iterators, and does not change the distance between `first` and `last`. (There's no way that it could do anything of the sort.) So, for example, if `V` is a Vector, `remove(V.begin(), V.end(), 0)` does not change `V.size()`: `V` will contain just as many elements as it did before. `Remove` returns an iterator that points to the end of the resulting range after elements have been removed from it; it follows that the elements after that iterator are of no interest, and may be discarded. If you are removing elements from a Sequence, you may simply erase them. That is, a reasonable way of removing elements from a Sequence is `S.erase(remove(S.begin(), S.end(), x), S.end())`.

`remove_if`, `remove_copy`, `remove_copy_if`, `unique`, `unique_copy`.