std::for_each() algorithm
- od C++20
- od C++17
- do C++17
// (1)
template< class InputIt, class UnaryFunction >
constexpr UnaryFunction for_each( InputIt first, InputIt last, UnaryFunction f );
// (2)
template< class ExecutionPolicy, class ForwardIt, class UnaryFunction2 >
void for_each( ExecutionPolicy&& policy,
ForwardIt first, ForwardIt last, UnaryFunction2 f );
// (1)
template< class InputIt, class UnaryFunction >
UnaryFunction for_each( InputIt first, InputIt last, UnaryFunction f );
// (2)
template< class ExecutionPolicy, class ForwardIt, class UnaryFunction2 >
void for_each( ExecutionPolicy&& policy,
ForwardIt first, ForwardIt last, UnaryFunction2 f );
// (1)
template< class InputIt, class UnaryFunction >
UnaryFunction for_each( InputIt first, InputIt last, UnaryFunction f );
Applies the given function to all elements in range.
-
(1) Applies the given function object
f
to the result of dereferencing every iterator in the range [first
,last
), in order. -
(2) Same as (1), but executed according to policy.
warningThere is no guarantee the function will be applied to elements in order.
Overload ResolutionThese overloads participate in overload resolution only if
std::is_execution_policy_v<std::decay_t<ExecutionPolicy>>
(do C++20)std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>>
(od C++20) istrue
.
For both overloads, if the iterator type (InputIt/ForwardIt) is mutable, f
may modify the elements of the range.
If f
returns a result, the result is ignored.
Unlike the rest of the parallel algorithms, for_each
is not allowed to make copies of the elements in the sequence even if they are TriviallyCopyable.
Parameters
first last | The range of elements to apply the function to. |
policy | The execution policy to use. See execution policy for details. |
f | Function object, to be applied to every element of the range. The signature of the function should be equivalent to the following:
|
Type requirements
InputIt | LegacyInputIterator |
ForwardIt | LegacyForwardIterator |
UnaryFunction | MoveConstructible |
UnaryFunction2 | CopyConstructible |
Return value
- (1) -
f
(do C++11)std::move(f)
(od C++11). - (2) - (none)
Complexity
Given N
as std::distance(first, last)
:
Exactly N applications of f
.
Exceptions
The overloads with a template parameter named ExecutionPolicy
report errors as follows:
- If execution of a function invoked as part of the algorithm throws an exception and
ExecutionPolicy
is one of the standard policies,std::terminate
is called. For any otherExecutionPolicy
, the behavior is implementation-defined. - If the algorithm fails to allocate memory,
std::bad_alloc
is thrown.
Possible implementation
for_each (1)
template<class InputIt, class UnaryFunction>
constexpr UnaryFunction for_each(InputIt first, InputIt last, UnaryFunction f)
{
for (; first != last; ++first)
f(*first);
return f; // implicit move since C++11
}
Examples
#include <algorithm>
#include <iostream>
#include <vector>
int main()
{
std::vector<int> v {3, -4, 2, -8, 15, 267};
auto print = [](const int& 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';
}
before: 3 -4 2 -8 15 267
after: 4 -3 3 -7 16 268
sum: 281
Hover to see the original license.