| Constrained algorithms and algorithms on ranges(C++20) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Constrained algorithms, e.g.ranges::copy,ranges::sort, ... | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Execution policies(C++17) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Numeric operations | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Operations on uninitialized memory | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Defined in header <algorithm> | ||
template<class InputIt,class UnaryFunc> UnaryFunc for_each( InputIt first, InputIt last, UnaryFunc f); | (1) | (constexpr since C++20) |
template<class ExecutionPolicy,class ForwardIt,class UnaryFunc> void for_each( ExecutionPolicy&& policy, | (2) | (since C++17) |
Applies the given unaryfunction objectf to the result of dereferencing everyiterator in therange[first, last). Iff returns a result, the result is ignored.
If | (since C++11) |
std::is_execution_policy_v<std::decay_t<ExecutionPolicy>> istrue. | (until C++20) |
std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>> istrue. | (since C++20) |
If the iterator type (InputIt/ForwardIt) is mutable,f may modify the elements of therange through the dereferenced iterator.
Unlike the rest of the parallel algorithms,for_each is not allowed to make copies of the elements in the sequence even if they areTriviallyCopyable.
Contents |
| first, last | - | the pair of iterators defining therange of elements to which thefunction object will be applied |
| policy | - | theexecution policy to use |
| f | - | function object, to be applied to the result of dereferencing every iterator in therange[first, last)The signature of the function should be equivalent to the following: void fun(const Type&a); The signature does not need to haveconst&. |
| Type requirements | ||
-InputIt must meet the requirements ofLegacyInputIterator. | ||
-ForwardIt must meet the requirements ofLegacyForwardIterator. | ||
Exactlystd::distance(first, last) applications off.
The overload with a template parameter namedExecutionPolicy reports errors as follows:
ExecutionPolicy is one of thestandard policies,std::terminate is called. For any otherExecutionPolicy, the behavior is implementation-defined.See also the implementations inlibstdc++,libc++ andMSVC stdlib.
template<class InputIt,class UnaryFunc>constexpr UnaryFunc for_each(InputIt first, InputIt last, UnaryFunc f){for(; first!= last;++first) f(*first); return f;// implicit move since C++11} |
For overload(1),f can be a stateful function object. The return value can be considered as the final state of the batch operation.
For overload(2), multiple copies off may be created to perform parallel invocation. No value is returned because parallelization often does not permit efficient state accumulation.
The following example uses alambda-expression to increment all of the elements of a vector and then uses an overloadedoperator() in a function object (i.k.a., "functor") to compute their sum. Note that to compute the sum, it is recommended to use the dedicated algorithmstd::accumulate.
#include <algorithm>#include <iostream>#include <vector> int main(){std::vector<int> v{3,-4,2,-8,15,267}; auto print=[](constint& n){std::cout<< n<<' ';}; std::cout<<"before:\t"; std::for_each(v.cbegin(), v.cend(), print);std::cout<<'\n'; // increment elements in-place std::for_each(v.begin(), v.end(),[](int&n){ n++;}); std::cout<<"after:\t"; std::for_each(v.cbegin(), v.cend(), print);std::cout<<'\n'; struct Sum{void operator()(int n){ sum+= n;}int sum{0};}; // invoke Sum::operator() for each element Sum s= std::for_each(v.cbegin(), v.cend(), Sum());std::cout<<"sum:\t"<< s.sum<<'\n';}
Output:
before:3 -4 2 -8 15 267 after:4 -3 3 -7 16 268 sum:281
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
| DR | Applied to | Behavior as published | Correct behavior |
|---|---|---|---|
| LWG 475 | C++98 | it was unclear whetherf can modify the elements of the sequence being iterated over ( for_each isclassified as “non-modifying sequence operations”) | made clear (allowed if the iterator type is mutable) |
| LWG 2747 | C++11 | overload(1) returnedstd::move(f) | returnsf (which implicitly moves) |
| applies a function to a range of elements, storing results in a destination range (function template)[edit] | |
(C++17) | applies a function object to the first N elements of a sequence (function template)[edit] |
(C++20) | applies a unaryfunction object to elements from arange (algorithm function object)[edit] |
(C++20) | applies a function object to the first N elements of a sequence (algorithm function object)[edit] |
range-for loop(C++11) | executes loop over range[edit] |
