24 Algorithms library [algorithms]

24.6 Mutating sequence operations [alg.modifying.operations]

24.6.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); namespace ranges { template<Permutable I, Sentinel<I> S, class T, class Proj = identity> requires IndirectRelation<ranges::equal_to<>, projected<I, Proj>, const T*> constexpr I remove(I first, S last, const T& value, Proj proj = {}); template<ForwardRange R, class T, class Proj = identity> requires Permutable<iterator_t<R>> && IndirectRelation<ranges::equal_to<>, projected<iterator_t<R>, Proj>, const T*> constexpr safe_iterator_t<R> remove(R&& r, const T& value, Proj proj = {}); template<Permutable I, Sentinel<I> S, class Proj = identity, IndirectUnaryPredicate<projected<I, Proj>> Pred> constexpr I remove_if(I first, S last, Pred pred, Proj proj = {}); template<ForwardRange R, class Proj = identity, IndirectUnaryPredicate<projected<iterator_t<R>, Proj>> Pred> requires Permutable<iterator_t<R>> constexpr safe_iterator_t<R> remove_if(R&& r, Pred pred, Proj proj = {}); }
Let E be
  • bool(*i == value) for remove,
  • bool(pred(*i)) for remove_­if,
  • bool(invoke(proj, *i) == value) for ranges::remove, or
  • bool(invoke(pred, invoke(proj, *i))) for ranges::remove_­if.
Requires: For the algorithms in namespace std, the type of *first shall meet the Cpp17MoveAssignable requirements (Table 28).
Effects: Eliminates all the elements referred to by iterator i in the range [first, last) for which E holds.
Returns: The end of the resulting range.
Remarks: Stable ([algorithm.stable]).
Complexity: Exactly last - first applications of the corresponding predicate and any projection.
[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); namespace ranges { template<InputIterator I, Sentinel<I> S, WeaklyIncrementable O, class T, class Proj = identity> requires IndirectlyCopyable<I, O> && IndirectRelation<ranges::equal_to<>, projected<I, Proj>, const T*> constexpr remove_copy_result<I, O> remove_copy(I first, S last, O result, const T& value, Proj proj = {}); template<InputRange R, WeaklyIncrementable O, class T, class Proj = identity> requires IndirectlyCopyable<iterator_t<R>, O> && IndirectRelation<ranges::equal_to<>, projected<iterator_t<R>, Proj>, const T*> constexpr remove_copy_result<safe_iterator_t<R>, O> remove_copy(R&& r, O result, const T& value, Proj proj = {}); template<InputIterator I, Sentinel<I> S, WeaklyIncrementable O, class Proj = identity, IndirectUnaryPredicate<projected<I, Proj>> Pred> requires IndirectlyCopyable<I, O> constexpr remove_copy_if_result<I, O> remove_copy_if(I first, S last, O result, Pred pred, Proj proj = {}); template<InputRange R, WeaklyIncrementable O, class Proj = identity, IndirectUnaryPredicate<projected<iterator_t<R>, Proj>> Pred> requires IndirectlyCopyable<iterator_t<R>, O> constexpr remove_copy_if_result<safe_iterator_t<R>, O> remove_copy_if(R&& r, O result, Pred pred, Proj proj = {}); }
Let E be
  • bool(*i == value) for remove_­copy,
  • bool(pred(*i)) for remove_­copy_­if,
  • bool(invoke(proj, *i) == value) for ranges::remove_­copy, or
  • bool(invoke(pred, invoke(proj, *i))) for ranges::remove_­copy_­if.
Let N be the number of elements in [first, last) for which E is false.
Requires: The ranges [first, last) and [result, result + (last - first)) shall not overlap.
The expression *result = *first shall be valid.
[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 26) requirements.
end note
]
Effects: Copies all the elements referred to by the iterator i in the range [first, last) for which E is false.
Returns:
  • result + N, for the algorithms in namespace std, or
  • {last, result + N}, for the algorithms in namespace ranges.
Complexity: Exactly last - first applications of the corresponding predicate and any projection.
Remarks: Stable ([algorithm.stable]).