std::for_each_n
Defined in header <algorithm>
|
||
template< class InputIt, class Size, class UnaryFunc > InputIt for_each_n( InputIt first, Size n, UnaryFunc f ); |
(1) | (since C++17) (constexpr since C++20) |
template< class ExecutionPolicy, class ForwardIt, class Size, class UnaryFunc > |
(2) | (since C++17) |
Applies the given function object f to the result of dereferencing every iterator in the range [
first,
first + n)
. If f returns a result, the result is ignored.
UnaryFunc
is not MoveConstructible, the behavior is undefined.
std::is_execution_policy_v<std::decay_t<ExecutionPolicy>> is true. |
(until C++20) |
std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>> is true. |
(since C++20) |
UnaryFunc
is not CopyConstructible, the behavior is undefined.If n >= 0 is not true, the behavior is undefined.
If the iterator type (InputIt
/ForwardIt
) is mutable, f may modify the elements of the range through the dereferenced iterator.
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.
Contents |
[edit] 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 the result of dereferencing every iterator in the range [ first, first + n) The signature of the function should be equivalent to the following: void fun(const Type &a); The signature does not need to have const &. |
Type requirements | ||
-InputIt must meet the requirements of LegacyInputIterator.
| ||
-ForwardIt must meet the requirements of LegacyForwardIterator.
| ||
-Size must be convertible to an integral type.
|
[edit] Return value
An iterator equal to first + n, or more formally, to std::advance(first, n).
[edit] Complexity
Exactly n applications of f.
[edit] Exceptions
The overload with a template parameter named ExecutionPolicy
reports 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.
[edit] Possible implementation
See also the implementation in libstdc++, libc++ and MSVC stdlib.
template<class InputIt, class Size, class UnaryFunc> InputIt for_each_n(InputIt first, Size n, UnaryFunc f) { for (Size i = 0; i < n; ++first, (void) ++i) f(*first); return first; } |
[edit] Example
#include <algorithm> #include <iostream> #include <vector> void println(auto const& v) { for (auto count{v.size()}; const auto& 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); }
Output:
1, 2, 3, 4, 5 2, 4, 6, 4, 5
[edit] See also
applies a function to a range of elements, storing results in a destination range (function template) | |
range-for loop(C++11)
|
executes loop over range |
applies a function to a range of elements (function template) | |
(C++20) |
applies a function object to the first N elements of a sequence (algorithm function object) |