Difference between revisions of "cpp/algorithm/for each n"

Latest revision as of 18:37, 18 March 2024

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 > ForwardIt for_each_n( ExecutionPolicy&& policy, ForwardIt first, Size n, UnaryFunc f );	(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.

1) f is applied in order starting from first.

If UnaryFunc is not MoveConstructible, the behavior is undefined.

2) f might not be applied in order. The algorithm is executed according to policy.

This overload participates in overload resolution only if

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)

If 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.

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 &. The type Type must be such that an object of type InputIt can be dereferenced and then implicitly converted to Type.
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 other ExecutionPolicy, 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

Run this code

#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

transform	applies a function to a range of elements, storing results in a destination range (function template) [edit]
range-`for` loop(C++11)	executes loop over range[edit]
for_each	applies a function to a range of elements (function template) [edit]
ranges::for_each_n (C++20)	applies a function object to the first N elements of a sequence (niebloid)[edit]

@@ Line 2: / Line 2: @@
 {{cpp/algorithm/navbar}}
 {{dcl begin}}
-{{dcl header | algorithm}}
+{{dcl header|algorithm}}
-{{dcl rev multi | num=1 | since1=c++17 | until1=c++20 |dcl1=
+{{dcl|num=1|since=c++17|notes={{mark constexpr since c++20}}|
+template< class InputIt, class Size, class UnaryFunc >
+InputIt for_each_n( InputIt first, Size n, UnaryFunc f );
+}}
+{{dcl|num=2|since=c++17|
+template< class ExecutionPolicy,
+          class ForwardIt, class Size, class UnaryFunc >
+ForwardIt for_each_n( ExecutionPolicy&& policy,
+                      ForwardIt first, Size n, UnaryFunc f );
+}}
+{{dcl end}}
-template< class InputIt, class Size, class UnaryFunction >
+Applies the given function object {{c|f}} to the result of dereferencing every iterator in the range {{range|first|first + n}}. If {{c|f}} returns a result, the result is ignored.
-InputIt for_each_n( InputIt first, Size n, UnaryFunction f );
-|dcl2=
+@1@ {{c|f}} is applied in order starting from {{c|first}}.
-template< class InputIt, class Size, class UnaryFunction >
+@@ If {{tt|UnaryFunc}} is not {{named req|MoveConstructible}}, the behavior is undefined.
-constexpr InputIt for_each_n( InputIt first, Size n, UnaryFunction f );
-}}
-{{dcl | since=c++17 | until= | num=2 |1=
-template< class ExecutionPolicy, class ForwardIt, class Size, class UnaryFunction2 >
+@2@ {{c|f}} might not be applied in order. The algorithm is executed according to {{c|policy}}.
-ForwardIt for_each_n( ExecutionPolicy&& policy, ForwardIt first, Size n, UnaryFunction2 f );
+@@ {{cpp/algorithm/parallel overload precondition}}
+@@ If {{tt|UnaryFunc}} is not {{named req|CopyConstructible}}, the behavior is undefined.
-}}
+If {{c|1=n >= 0}} is not {{c|true}}, the behavior is undefined.
-{{dcl end}}
-@1@ Applies the given function object {{tt|f}} to the result of dereferencing every iterator in the range {{tt|[first, first + n)}}, in order.
+If the iterator type ({{tt|InputIt}}/{{tt|ForwardIt}}) is mutable, {{c|f}} may modify the elements of the range through the dereferenced iterator.
-@2@  Applies the given function object {{tt|f}} to the result of dereferencing every iterator in the range {{tt|[first, first + n)}} (not necessarily in order). The algorithm is executed according to {{tt|policy}}. This overload does not participate in overload resolution unless {{c|std::is_execution_policy_v<std::decay_t<ExecutionPolicy>>}} is true.
-For both overloads, if the iterator type is mutable, {{tt|f}} may modify the elements of the range through the dereferenced iterator. If {{tt|f}} returns a result, the result is ignored. If {{tt|n}} is less than zero, the behavior is undefined.
+Unlike the rest of the parallel algorithms, {{tt|for_each_n}} is not allowed to make copies of the elements in the sequence even if they are {{named req|TriviallyCopyable}}.
 ===Parameters===
 {{par begin}}
-{{par | first | the beginning of the range to apply the function to}}
+{{par|first|the beginning of the range to apply the function to}}
-{{par | n | the number of elements to apply the function to}}
+{{par|n|the number of elements to apply the function to}}
 {{par exec pol}}
-{{par opf | f | to be applied to the result of dereferencing every iterator in the range {{tt|[first, first + n)}} | p1=InputIt}}
+{{par opf|f|to be applied to the result of dereferencing every iterator in the range {{range|first|first + n}}|p1=InputIt}}
 {{par hreq}}
-{{par req concept | InputIt | InputIterator}}
+{{par req named|InputIt|InputIterator}}
-{{par req concept | ForwardIt | ForwardIterator}}
+{{par req named|ForwardIt|ForwardIterator}}
-{{par req concept | UnaryFunction | MoveConstructible | notes=Does not have to be {{named req|CopyConstructible}}}}
+{{par req|{{tt|Size}} must be convertible to an integral type.}}
-{{par req concept | UnaryFunction2 | CopyConstructible }}
 {{par end}}
 ===Return value===
-{{c|first + n}}
+An iterator equal to {{c|first + n}}, or more formally, to {{c|std::advance(first, n)}}.
 ===Complexity===
-Exactly {{tt|n}} applications of {{tt|f}}
+Exactly {{c|n}} applications of {{c|f}}.
 ===Exceptions===
-{{cpp/algorithm/parallel_exceptions_reporting_behavior|singular=yes}}
+{{cpp/algorithm/parallel exceptions reporting behavior|singular=yes}}
 ===Possible implementation===
-{{eq fun | 1=
+See also the implementation in [https://github.com/gcc-mirror/gcc/blob/d9375e490072d1aae73a93949aa158fcd2a27018/libstdc%2B%2B-v3/include/pstl/algorithm_impl.h#L82 libstdc++], [https://github.com/llvm-mirror/libcxx/blob/a12cb9d211019d99b5875b6d8034617cbc24c2cc/include/algorithm#L896 libc++] and [https://github.com/microsoft/STL/blob/ff83542af4b683fb2f2dea1423fd6c50fe3e13b0/stl/inc/algorithm#L246 MSVC stdlib].
-template<class InputIt, class Size, class UnaryFunction>
+{{eq fun|1=
-InputIt for_each_n(InputIt first, Size n, UnaryFunction f)
+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) {
+     for (Size i = 0; i < n; ++first, (void) ++i)
          f(*first);
-     }
      return first;
 }
@@ Line 60: / Line 65: @@
 ===Example===
-{{example|code=
+{{example
+|code=
 #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> ns{1, 2, 3, 4, 5};
+     std::vector<int> vi{1, 2, 3, 4, 5};
-     for (auto n: ns) std::cout << n << ", ";
+     println(vi);
-     std::cout << '\n';
-     std::for_each_n(ns.begin(), 3, [](auto& n){ n *= 2; });
+     std::for_each_n(vi.begin(), 3, [](auto& n) { n *= 2; });
-     for (auto n: ns) std::cout << n << ", ";
+     println(vi);
-    std::cout << '\n';
 }
 |output=
-, 2, 3, 4, 5,
+, 2, 3, 4, 5
-, 4, 6, 4, 5,
+, 4, 6, 4, 5
 }}
 ===See also===
 {{dsc begin}}
-{{dsc inc | cpp/algorithm/dsc transform}}
+{{dsc inc|cpp/algorithm/dsc transform}}
-{{dsc inc | cpp/language/dsc range-for}}
+{{dsc inc|cpp/language/dsc range-for}}
-{{dsc inc | cpp/algorithm/dsc for_each}}
+{{dsc inc|cpp/algorithm/dsc for_each}}
+{{dsc inc|cpp/algorithm/ranges/dsc for_each_n}}
 {{dsc end}}
-[[de:cpp/algorithm/for each n]]
+{{langlinks|de|es|fr|it|ja|pt|ru|zh}}
-[[es:cpp/algorithm/for each n]]
-[[fr:cpp/algorithm/for each n]]
-[[it:cpp/algorithm/for each n]]
-[[ja:cpp/algorithm/for each n]]
-[[pt:cpp/algorithm/for each n]]
-[[ru:cpp/algorithm/for each n]]
-[[zh:cpp/algorithm/for each n]]

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Execution support library (C++26)
Technical specifications
Symbols index
External libraries

cppreference.com

Namespaces

Variants

Views

Actions

Difference between revisions of "cpp/algorithm/for each n"

Latest revision as of 18:37, 18 March 2024

Contents

[edit] Parameters