std::for_each_n

Defined in header `<algorithm>`
	(1)
template< class InputIt, class Size, class UnaryFunction > InputIt for_each_n( InputIt first, Size n, UnaryFunction f );		(с C++17) (до C++20)
template< class InputIt, class Size, class UnaryFunction > constexpr InputIt for_each_n( InputIt first, Size n, UnaryFunction f );		(с C++20)
template< class ExecutionPolicy, class ForwardIt, class Size, class UnaryFunction2 > ForwardIt for_each_n( ExecutionPolicy&& policy, ForwardIt first, Size n, UnaryFunction2 f );	(2)	(с C++17)

1) Применяет заданный объект функции f к результату обращения по ссылке каждого итератора в диапазоне [first, first + n), в порядке следования.

2) Применяет заданный объект функции f к результату обращения по ссылке каждого итератора в диапазоне [first, first + n) (не обязательно в порядке следования). Алгоритм выполняется в соответствии с policy. Эта перегрузка не участвует в разрешении перегрузки, если

`std::is_execution_policy_v<std::decay_t<ExecutionPolicy>>` является `true`.	(до C++20)
`std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>>` является `true`.	(с C++20)

Для обеих перегрузок, если тип итератора является изменяемым, f может изменить элементы диапазона через обращение по ссылке к итератору. Если f возвращает результат, результат игнорируется. Если n меньше нуля, поведение не определено.

В отличие от остальных параллельных алгоритмов, for_each_n не разрешается создавать копии элементов в последовательности, даже если они тривиально копируемы.

Параметры

first	-	начало диапазона, к которому будет применена функция
n	-	количество элементов, к которым будет применена функция
policy	-	используемая стратегия выполнения. Подробности см. в стратегии выполнения.
f	-	объект функции, который будет применяться к результату обращения по ссылке к каждому итератору в диапазоне `[first,` `first + n)` Подпись функции должна быть эквивалентна следующей: `void fun(const Type &a);` Подпись не должна содержать `const &`. Тип Type должен быть таким, чтобы объект типа InputIt можно было обработать и затем неявно преобразовать в Type.
Требования к типу
-`InputIt` должен удовлетворять требованиям LegacyInputIterator.
-`ForwardIt` должен удовлетворять требованиям LegacyForwardIterator.
-`UnaryFunction` должен удовлетворять требованиям MoveConstructible. Не обязательно должен быть CopyConstructible.
-`UnaryFunction2` должен удовлетворять требованиям CopyConstructible.

Возвращаемое значение

Итератор, равный first + n, или, более формально, std::advance(first, n).

Сложность

Ровно n приложений f.

Исключения

Перегрузка с параметром шаблона по имени ExecutionPolicy сообщает об ошибках следующим образом:

Если выполнение функции, вызванной в рамках алгоритма, вызывает исключение, и ExecutionPolicy — одна из стандартных стратегий, вызывается std::terminate. Для любой другой ExecutionPolicy, поведение зависит от реализации.
Если алгоритм не может выделить память, выбрасывается std::bad_alloc.

Возможная реализация

См. также реализацию в libstdc++, libc++ и MSVC stdlib.

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

Пример

#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

См. также

transform	применяет функцию к диапазону элементов, сохраняя результаты в целевом диапазоне (функция-шаблон)
цикл range-`for`(C++11)	выполняет цикл по диапазону
for_each	применяет функцию к диапазону элементов (функция-шаблон)
ranges::for_each_n (C++20)	применяет объект функции к первым N элементам последовательности (niebloid)

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/cpp/algorithm/for_each_n