# 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 Forward Iterator.
- `ForwardIterator` is mutable.
- `T` is a model of Equality Comparable.
- 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())`.

### See also

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

Copyright © 1999 Silicon Graphics, Inc. All Rights Reserved. TrademarkInformation