Namespaces
Variants
Views
Actions

std::ranges::for_each_n, std::ranges::for_each_n_result

From cppreference.com
< cpp‎ | algorithm‎ | ranges
 
 
Algorithm library
Constrained algorithms and algorithms on ranges (C++20)
Constrained algorithms: std::ranges::copy, std::ranges::sort, ...
Execution policies (C++17)
Non-modifying sequence operations
(C++11)(C++11)(C++11)
(C++17)
Modifying sequence operations
Operations on uninitialized storage
Partitioning operations
Sorting operations
(C++11)
Binary search operations
Set operations (on sorted ranges)
Heap operations
(C++11)
Minimum/maximum operations
(C++11)
(C++17)

Permutations
Numeric operations
C library
 
Constrained algorithms
Non-modifying sequence operations
Modifying sequence operations
Operations on uninitialized storage
Partitioning operations
Sorting operations
Binary search operations
Set operations (on sorted ranges)
Heap operations
Minimum/maximum operations
Permutations
 
Defined in header <algorithm>
Call signature
template< std::input_iterator I, class Proj = identity,

  std::indirectly_unary_invocable<std::projected<I, Proj>> Fun >
constexpr ranges::for_each_n_result<I, Fun>

  ranges::for_each_n( I first, std::iter_difference_t<I> n, Fun f, Proj proj = {});
(1) (since C++20)
Helper types
template< class I, class F >
using for_each_n_result = ranges::in_fun_result<I, F>;
(2) (since C++20)
1) Applies the given function object f to the result of the value projected by each iterator in the range [first, first + n), in order.

If the iterator type is mutable, f may modify the elements of the range through the dereferenced iterator. If f returns a result, the result is ignored. If n is less than zero, the behavior is undefined. The function-like entities described on this page are niebloids, that is:

In practice, they may be implemented as function objects, or with special compiler extensions.

Contents

[edit] Parameters

first - iterator denoting the begin of the range to apply the function to
n - the number of elements to apply the function to
f - the function to apply to the projected range [first, first + n)
proj - projection to apply to the elements

[edit] Return value

{std::ranges::next(std::move(first), n), std::move(f)}

[edit] Complexity

Exactly n applications of f and proj.

[edit] Notes

The overload in namespace ranges requires Fun to model copy_constructible.

[edit] Possible implementation

struct for_each_n_fn {
  template<std::input_iterator I, class Proj = std::identity,
           std::indirectly_unary_invocable<std::projected<I, Proj>> Fun>
    constexpr for_each_n_result<I, Fun>
      operator()(I first, std::iter_difference_t<I> n, Fun fun, Proj proj = Proj{}) const
      {
        for (; n-- > 0; ++first) {
          std::invoke(fun, std::invoke(proj, *first));
        }
        return {std::move(first), std::move(fun)};
      }
};
 
inline constexpr for_each_n_fn for_each_n{};

[edit] Example

#include <algorithm>
#include <array>
#include <iostream>
#include <ranges>
#include <string_view>
#include <utility>
 
using P = const std::pair<int, char>;
 
std::ostream& operator<< (std::ostream& os, const P& p) {
    return os << '{' << p.first << ",'" << p.second << "'}";
}
 
auto print = [](std::string_view name, std::ranges::forward_range auto const& v) {
    std::cout << name << ": ";
    for (const auto& e: v) { std::cout << e << ", "; }
    std::cout << '\n';
};
 
int main()
{
    std::array a{1, 2, 3, 4, 5};
    print("a", a);
    // Negate first three numbers:
    std::ranges::for_each_n(a.begin(), 3, [](auto& n) { n *= -1; });
    print("a", a);
 
    std::array s{ P{1,'a'}, P{2, 'b'}, P{3, 'c'}, P{4, 'd'} };
    print("s", s);
    // Negate data members 'pair::first' using projection:
    std::ranges::for_each_n(s.begin(), 2, [](auto& x) { x *= -1; }, &P::first);
    print("s", s);
    // Capitalize data members 'pair::second' using projection:
    std::ranges::for_each_n(s.begin(), 3, [](auto& c) { c -= 'a'-'A'; }, &P::second);
    print("s", s);
}

Output:

a: 1, 2, 3, 4, 5,
a: -1, -2, -3, 4, 5,
s: {1,'a'}, {2,'b'}, {3,'c'}, {4,'d'},
s: {-1,'a'}, {-2,'b'}, {3,'c'}, {4,'d'},
s: {-1,'A'}, {-2,'B'}, {3,'C'}, {4,'d'},

[edit] See also

range-for loop(C++11) executes loop over range[edit]
applies a function to a range of elements
(niebloid) [edit]
applies a function object to the first n elements of a sequence
(function template) [edit]
applies a function to a range of elements
(function template) [edit]