Removes all elements satisfying specific criteria from the range[first, last) and returns a subrange[ret, last), whereret is a past-the-end iterator for the new end of the range.

Removing is done by shifting (by means of move assignment) the elements in the range in such a way that the elements that are not to be removed appear in the beginning of the range. Relative order of the elements that remain is preserved and thephysical size of the container is unchanged. Iterators pointing to an element between the newlogical end and thephysical end of the range are still dereferenceable, but the elements themselves have unspecified values (as perMoveAssignable post-condition).

The function-like entities described on this page arealgorithm function objects (informally known asniebloids), that is:

• Explicit template argument lists cannot be specified when calling any of them.
• None of them are visible toargument-dependent lookup.
• When any of them are found bynormal unqualified lookup as the name to the left of the function-call operator,argument-dependent lookup is inhibited.

[edit]Parameters

[edit]Return value

{ret, last}, where[first, ret) is the resulting subrange after removal, and the elements in subrange[ret, last) are all in valid but unspecified state, i.e.[ret, last) is the subrange to be erased.

[edit]Complexity

ExactlyN applications of the corresponding predicate and any projection, whereN=ranges::distance(first, last), andN-1 move operations at worst.

[edit]Notes

A call toranges::remove is typically followed by a call to a container'serase member function, which erases the unspecified values and reduces thephysical size of the container to match its newlogical size. These two invocations together constitute the so-callederase-remove idiom, which can be achieved by the free functionstd::erase that hasoverloads for all standardsequence containers, orstd::erase_if that hasoverloads forall standard containers.

The similarly-named containermember functionslist::remove,list::remove_if,forward_list::remove, andforward_list::remove_if erase the removed elements.

These algorithms usually cannot be used with associative containers such asstd::set andstd::map because their iterator types do not dereference toMoveAssignable types (the keys in these containers are not modifiable).

Becauseranges::remove takesvalue by reference, it can have unexpected behavior if it is a reference to an element of the range[first, last).

[edit]Possible implementation

struct remove_fn{template<std::permutable I,std::sentinel_for<I> S,class Proj=std::identity,class T= std::projected_value_t<I, Proj>>    requiresstd::indirect_binary_predicate<ranges::equal_to, std::projected<I, Proj>,const T*>constexprranges::subrange<I>        operator()(I first, S last,const T& value, Proj proj={})const{        first=ranges::find(std::move(first), last, value, proj);if(first!= last){for(I i{std::next(first)}; i!= last;++i)if(value!=std::invoke(proj,*i)){*first=ranges::iter_move(i);++first;}}return{first, last};} template<ranges::forward_range R,class Proj=std::identity,class T= std::projected_value_t<ranges::iterator_t<R>, Proj>>    requiresstd::permutable<ranges::iterator_t<R>>&&std::indirect_binary_predicate<ranges::equal_to,                  std::projected<ranges::iterator_t<R>, Proj>,const T*>constexprranges::borrowed_subrange_t<R>        operator()(R&& r,const T& value, Proj proj={})const{return(*this)(ranges::begin(r),ranges::end(r), value, std::move(proj));}}; inlineconstexpr remove_fn remove{};

struct remove_if_fn{template<std::permutable I,std::sentinel_for<I> S,class Proj=std::identity,std::indirect_unary_predicate<std::projected<I, Proj>> Pred>constexprranges::subrange<I>        operator()(I first, S last, Pred pred, Proj proj={})const{        first=ranges::find_if(std::move(first), last, pred, proj);if(first!= last){for(I i{std::next(first)}; i!= last;++i)if(!std::invoke(pred,std::invoke(proj,*i))){*first=ranges::iter_move(i);++first;}}return{first, last};} template<ranges::forward_range R,class Proj=std::identity,std::indirect_unary_predicate<std::projected<ranges::iterator_t<R>, Proj>> Pred>    requiresstd::permutable<ranges::iterator_t<R>>constexprranges::borrowed_subrange_t<R>        operator()(R&& r, Pred pred, Proj proj={})const{return(*this)(ranges::begin(r),ranges::end(r), pred, std::move(proj));}}; inlineconstexpr remove_if_fn remove_if{};

[edit]Notes

[edit]Example

#include <algorithm>#include <cassert>#include <complex>#include <cctype>#include <iomanip>#include <iostream>#include <string>#include <string_view>#include <vector> int main(){std::string v1{"No - Diagnostic - Required"};std::cout<<std::quoted(v1)<<" (v1, size: "<< v1.size()<<")\n";constauto ret= std::ranges::remove(v1,' ');std::cout<<std::quoted(v1)<<" (v1 after `remove`, size: "<< v1.size()<<")\n";std::cout<<' '<<std::string(std::distance(v1.begin(), ret.begin()),'^')<<'\n';    v1.erase(ret.begin(), ret.end());std::cout<<std::quoted(v1)<<" (v1 after `erase`, size: "<< v1.size()<<")\n\n"; // remove_if with custom unary predicate:auto rm=[](char c){return!std::isupper(c);};std::string v2{"Substitution Failure Is Not An Error"};std::cout<<std::quoted(v2)<<" (v2, size: "<< v2.size()<<")\n";constauto[first, last]= std::ranges::remove_if(v2, rm);std::cout<<std::quoted(v2)<<" (v2 after `remove_if`, size: "<< v2.size()<<")\n";std::cout<<' '<<std::string(std::distance(v2.begin(), first),'^')<<'\n';    v2.erase(first, last);std::cout<<std::quoted(v2)<<" (v2 after `erase`, size: "<< v2.size()<<")\n\n"; // creating a view into a container that is modified by `remove_if`:for(std::string s:{"Small Object Optimization","Non-Type Template Parameter"})std::cout<<std::quoted(s)<<" => "<<std::string_view{begin(s), std::ranges::remove_if(s, rm).begin()}<<'\n'; std::vector<std::complex<double>> nums{{2,2},{1,3},{4,8}};#ifdef __cpp_lib_algorithm_default_value_typeauto e= std::ranges::remove(nums,{1,3});// T gets deduced#elseauto e= std::ranges::remove(nums,std::complex<double>{1,3});#endif    nums.erase(e.begin(), e.end());assert((nums==std::vector<std::complex<double>>{{2,2},{4,8}}));}

"No _ Diagnostic _ Required" (v1, size: 26)"No_Diagnostic_Requiredired" (v1 after `remove`, size: 26) ^^^^^^^^^^^^^^^^^^^^^^"No_Diagnostic_Required" (v1 after `erase`, size: 22) "Substitution Failure Is Not An Error" (v2, size: 36)"SFINAEtution Failure Is Not An Error" (v2 after `remove_if`, size: 36) ^^^^^^"SFINAE" (v2 after `erase`, size: 6) "Small Object Optimization" => SOO"Non-Type Template Parameter" => NTTP

[edit]See also

• In other languages

• Deutsch
• Español
• Français
• Italiano
• 日本語
• Português
• Русский
• 中文