25 Algorithms library [algorithms]

25.7 Mutating sequence operations [alg.modifying.operations]

25.7.8 Remove [alg.remove]

🔗
template<class ForwardIterator, class T> constexpr ForwardIterator remove(ForwardIterator first, ForwardIterator last, const T& value); template<class ExecutionPolicy, class ForwardIterator, class T> ForwardIterator remove(ExecutionPolicy&& exec, ForwardIterator first, ForwardIterator last, const T& value); template<class ForwardIterator, class Predicate> constexpr ForwardIterator remove_if(ForwardIterator first, ForwardIterator last, Predicate pred); template<class ExecutionPolicy, class ForwardIterator, class Predicate> ForwardIterator remove_if(ExecutionPolicy&& exec, ForwardIterator first, ForwardIterator last, Predicate pred); template<permutable I, sentinel_­for<I> S, class T, class Proj = identity> requires indirect_­binary_­predicate<ranges::equal_to, projected<I, Proj>, const T*> constexpr subrange<I> ranges::remove(I first, S last, const T& value, Proj proj = {}); template<forward_­range R, class T, class Proj = identity> requires permutable<iterator_t<R>> && indirect_­binary_­predicate<ranges::equal_to, projected<iterator_t<R>, Proj>, const T*> constexpr borrowed_subrange_t<R> ranges::remove(R&& r, const T& value, Proj proj = {}); template<permutable I, sentinel_­for<I> S, class Proj = identity, indirect_­unary_­predicate<projected<I, Proj>> Pred> constexpr subrange<I> ranges::remove_if(I first, S last, Pred pred, Proj proj = {}); template<forward_­range R, class Proj = identity, indirect_­unary_­predicate<projected<iterator_t<R>, Proj>> Pred> requires permutable<iterator_t<R>> constexpr borrowed_subrange_t<R> ranges::remove_if(R&& r, Pred pred, Proj proj = {});
1
#
Let E be
  • (1.1)
    bool(*i == value) for remove;
  • (1.2)
    bool(pred(*i)) for remove_­if;
  • (1.3)
    bool(invoke(proj, *i) == value) for ranges​::​remove;
  • (1.4)
    bool(invoke(pred, invoke(proj, *i))) for ranges​::​remove_­if.
2
#
Preconditions: For the algorithms in namespace std, the type of *first meets the Cpp17MoveAssignable requirements (Table 30).
3
#
Effects: Eliminates all the elements referred to by iterator i in the range [first, last) for which E holds.
4
#
Returns: Let j be the end of the resulting range.
Returns:
  • (4.1)
    j for the overloads in namespace std.
  • (4.2)
    {j, last} for the overloads in namespace ranges.
5
#
Remarks: Stable ([algorithm.stable]).
6
#
Complexity: Exactly last - first applications of the corresponding predicate and any projection.
7
#
[ Note
:
Each element in the range [ret, last), where ret is the returned value, has a valid but unspecified state, because the algorithms can eliminate elements by moving from elements that were originally in that range.
— end note
 ]
🔗
template<class InputIterator, class OutputIterator, class T> constexpr OutputIterator remove_copy(InputIterator first, InputIterator last, OutputIterator result, const T& value); template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class T> ForwardIterator2 remove_copy(ExecutionPolicy&& exec, ForwardIterator1 first, ForwardIterator1 last, ForwardIterator2 result, const T& value); template<class InputIterator, class OutputIterator, class Predicate> constexpr OutputIterator remove_copy_if(InputIterator first, InputIterator last, OutputIterator result, Predicate pred); template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class Predicate> ForwardIterator2 remove_copy_if(ExecutionPolicy&& exec, ForwardIterator1 first, ForwardIterator1 last, ForwardIterator2 result, Predicate pred); template<input_­iterator I, sentinel_­for<I> S, weakly_­incrementable O, class T, class Proj = identity> requires indirectly_­copyable<I, O> && indirect_­binary_­predicate<ranges::equal_to, projected<I, Proj>, const T*> constexpr ranges::remove_copy_result<I, O> ranges::remove_copy(I first, S last, O result, const T& value, Proj proj = {}); template<input_­range R, weakly_­incrementable O, class T, class Proj = identity> requires indirectly_­copyable<iterator_t<R>, O> && indirect_­binary_­predicate<ranges::equal_to, projected<iterator_t<R>, Proj>, const T*> constexpr ranges::remove_copy_result<borrowed_iterator_t<R>, O> ranges::remove_copy(R&& r, O result, const T& value, Proj proj = {}); template<input_­iterator I, sentinel_­for<I> S, weakly_­incrementable O, class Proj = identity, indirect_­unary_­predicate<projected<I, Proj>> Pred> requires indirectly_­copyable<I, O> constexpr ranges::remove_copy_if_result<I, O> ranges::remove_copy_if(I first, S last, O result, Pred pred, Proj proj = {}); template<input_­range R, weakly_­incrementable O, class Proj = identity, indirect_­unary_­predicate<projected<iterator_t<R>, Proj>> Pred> requires indirectly_­copyable<iterator_t<R>, O> constexpr ranges::remove_copy_if_result<borrowed_iterator_t<R>, O> ranges::remove_copy_if(R&& r, O result, Pred pred, Proj proj = {});
8
#
Let E be
  • (8.1)
    bool(*i == value) for remove_­copy;
  • (8.2)
    bool(pred(*i)) for remove_­copy_­if;
  • (8.3)
    bool(invoke(proj, *i) == value) for ranges​::​remove_­copy;
  • (8.4)
    bool(invoke(pred, invoke(proj, *i))) for ranges​::​remove_­copy_­if.
9
#
Let N be the number of elements in [first, last) for which E is false.
10
#
Mandates: *first is writable ([iterator.requirements.general]) to result.
11
#
Preconditions: The ranges [first, last) and [result, result + (last - first)) do not overlap.
[ Note
:
For the overloads with an ExecutionPolicy, there may be a performance cost if iterator_­traits<ForwardIterator1>​::​value_­type does not meet the Cpp17MoveConstructible (Table 28) requirements.
— end note
 ]
12
#
Effects: Copies all the elements referred to by the iterator i in the range [first, last) for which E is false.
13
#
Returns:
  • (13.1)
    result + N, for the algorithms in namespace std.
  • (13.2)
    {last, result + N}, for the algorithms in namespace ranges.
14
#
Complexity: Exactly last - first applications of the corresponding predicate and any projection.
15
#
Remarks: Stable ([algorithm.stable]).