Namespaces
Variants
Views
Actions

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

From cppreference.com
< cpp‎ | algorithm
(Undo revision 92807 by 131.107.159.189 (talk))
(Wording update.)
 
(17 intermediate revisions by 10 users not shown)
Line 2: Line 2:
 
{{cpp/algorithm/navbar}}
 
{{cpp/algorithm/navbar}}
 
{{dcl begin}}
 
{{dcl begin}}
−
{{dcl header | algorithm}}
+
{{dcl header|algorithm}}
−
{{dcl | num = 1 | since = c++17 |
+
{{dcl|num=1|since=c++17|notes={{mark constexpr since c++20}}|
−
template< class InputIt, class Size, class UnaryFunction >
+
template< class InputIt, class Size, class UnaryFunc >
−
InputIt for_each_n( InputIt first, Size n, UnaryFunction f );
+
InputIt for_each_n( InputIt first, Size n, UnaryFunc f );
 
}}
 
}}
−
{{dcl | num = 2 | since = c++17 |
+
{{dcl|num=2|since=c++17|
−
template< class ExecutionPolicy, class ForwardIt, class Size, class UnaryFunction2 >
+
template< class ExecutionPolicy,
−
ForwardIt for_each_n( ExecutionPolicy&& policy, ForwardIt first, Size n, UnaryFunction2 f );
+
          class ForwardIt, class Size, class UnaryFunc >
 +
ForwardIt for_each_n( ExecutionPolicy&& policy,
 +
                      ForwardIt first, Size n, UnaryFunc f );
 
}}
 
}}
 
{{dcl end}}
 
{{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.  
+
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.
−
@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.
+
@1@ {{c|f}} is applied in order starting from {{c|first}}.
 +
@@ If {{tt|UnaryFunc}} is not {{named req|MoveConstructible}}, the behavior is undefined.
 +
 
 +
@2@ {{c|f}} might not be applied in order. The algorithm is executed according to {{c|policy}}.
 +
@@ {{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.
 +
 
 +
If the iterator type ({{tt|InputIt}}/{{tt|ForwardIt}}) is mutable, {{c|f}} may modify the elements of the range through the dereferenced iterator.
 +
 
 +
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===
 
===Parameters===
 
{{par begin}}
 
{{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 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 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 {{concept|CopyConstructible}}}}
+
{{par req|{{tt|Size}} must be convertible to an integral type.}}
−
{{par req concept | UnaryFunction2 | CopyConstructible }}
+
 
{{par end}}
 
{{par end}}
  
 
===Return value===
 
===Return value===
−
{{c|first + n}}
+
An iterator equal to {{c|first + n}}, or more formally, to {{c|std::advance(first, n)}}.
  
 
===Complexity===
 
===Complexity===
−
Exactly {{tt|n}} applications of {{tt|f}}
+
Exactly {{c|n}} applications of {{c|f}}.
  
 
===Exceptions===
 
===Exceptions===
−
{{cpp/algorithm/parallel_exceptions_reporting_behavior|singular=yes}}
+
{{cpp/algorithm/parallel exceptions reporting behavior|singular=yes}}
  
 
===Possible implementation===
 
===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);
 
         f(*first);
−
     }
+
      
 
     return first;
 
     return first;
 
}
 
}
Line 54: Line 66:
 
===Example===
 
===Example===
 
{{example
 
{{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> 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
 
}}
 
}}
  
 
===See also===
 
===See also===
 
{{dsc begin}}
 
{{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}}
 
{{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]]
+

Latest revision as of 18:37, 18 March 2024

 
C++
 
Algorithm library
Constrained algorithms and algorithms on ranges (C++20)
Constrained algorithms, e.g. ranges::copy, ranges::sort, ...
Execution policies (C++17)
Non-modifying sequence operations
Batch operations
for_each_n
(C++17)
Search operations
(C++11)                (C++11)(C++11)

Modifying sequence operations
Copy operations
(C++11)
(C++11)
(C++11)
Swap operations
Transformation operations
Generation operations
Removing operations
Order-changing operations
(until C++17)(C++11)
(C++20)(C++20)
Sampling operations
(C++17)

Sorting and related operations
Partitioning operations
Sorting operations
Binary search operations
(on partitioned ranges)
Set operations (on sorted ranges)
Merge operations (on sorted ranges)
Heap operations
Minimum/maximum operations
(C++11)
(C++17)
Lexicographical comparison operations
(C++20)
Permutation operations
C library
Numeric operations
Operations on uninitialized memory
 
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.

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

 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]
applies a function to a range of elements
(function template) [edit]
(C++20)
 applies a function object to the first N elements of a sequence
(niebloid)[edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/algorithm/for_each_n&oldid=170216"