std::for_each_n() algorithm

since C++20

// (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 );

since C++17

// (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.

  warning

  There is no guarantee the function will be applied to elements in order.

  Overload Resolution

  These overloads participate in overload resolution only if std::is_execution_policy_v<std::decay_t<ExecutionPolicy>>  (until C++20) std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>>  (since C++20) is true.

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.

warning

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.

Undefined Behaviour

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: void fun(const Type& a); The signature does not need to have const&. The type Type must be such that an object of type InputIt can be dereferenced and then implicitly converted to Type.

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 other ExecutionPolicy, 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

Main.cpp

#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);
}

Output

1, 2, 3, 4, 5
2, 4, 6, 4, 5