std::for_each_n() algorithm
- od C++20
- od C++17
// (1)
template< class InputIt, class Size, class UnaryFunction >
constexpr InputIt for_each_n( InputIt first, Size n, UnaryFunction f );
// (2)
template< class ExecutionPolicy, class ForwardIt, class Size, class UnaryFunction2 >
ForwardIt for_each_n( ExecutionPolicy&& policy,
ForwardIt first, Size n, UnaryFunction2 f );
// (1)
template< class InputIt, class Size, class UnaryFunction >
InputIt for_each_n( InputIt first, Size n, UnaryFunction f );
// (2)
template< class ExecutionPolicy, class ForwardIt, class Size, class UnaryFunction2 >
ForwardIt for_each_n( ExecutionPolicy&& policy,
ForwardIt first, Size n, UnaryFunction2 f );
Applies the given function to all elements in in range defined by an iterator and a size.
-
(1) Applies the given function object
f
to the result of dereferencing every iterator in the range [first
,first + n
), 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_n
is not allowed to make copies of the elements in the sequence even if they are TriviallyCopyable.
If n
is less than zero, the behavior is undefined
Parameters
first | The beginning of the range to apply the function to. |
n | The number 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
An iterator equal to first + n
, or more formally, to std::advance(first, n)
.
Complexity
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_n (1)
template<class InputIt, class Size, class UnaryFunction>
InputIt for_each_n(InputIt first, Size n, UnaryFunction f)
{
for (Size i = 0; i < n; ++first, (void) ++i)
f(*first);
return first;
}
Examples
#include <algorithm>
#include <iostream>
#include <vector>
void println(auto const& v)
{
for (auto count{v.size()}; auto const& e : v)
std::cout << e << (--count ? ", " : "\n");
}
int main()
{
std::vector<int> vi {1, 2, 3, 4, 5};
println(vi);
std::for_each_n(vi.begin(), 3, [](auto& n) { n *= 2; });
println(vi);
}
1, 2, 3, 4, 5
2, 4, 6, 4, 5
Hover to see the original license.