std::ranges::for_each, std::ranges::for_each_result

定义于头文件 `<algorithm>`
调用签名
template< std::input_iterator I, std::sentinel_for<I> S, class Proj = std::identity, std::indirectly_unary_invocable<std::projected<I, Proj>> Fun > constexpr for_each_result<I, Fun> for_each( I first, S last, Fun f, Proj proj = {} );	(1)	(C++20 起)
template< ranges::input_range R, class Proj = std::identity, std::indirectly_unary_invocable <std::projected<ranges::iterator_t<R>, Proj>> Fun > constexpr for_each_result<ranges::borrowed_iterator_t<R>, Fun> for_each( R&& r, Fun f, Proj proj = {} );	(2)	(C++20 起)
template< /execution-policy/ Ep, std::random_access_iterator I, std::sized_sentinel_for<I> S, class Proj = std::identity, std::indirectly_unary_invocable<std::projected<I, Proj>> Fun > I for_each( Ep&& policy, I first, S last, Fun f, Proj proj = {} );	(3)	(C++26 起)
template< /execution-policy/ Ep, /sized-random-access-range/ R, class Proj = std::identity, std::indirectly_unary_invocable <std::projected<ranges::iterator_t<R>, Proj>> Fun > ranges::borrowed_iterator_t<R> for_each( Ep&& policy, R&& r, Fun f, Proj proj = {} );	(4)	(C++26 起)
辅助类型
template< class I, class F > using for_each_result = ranges::in_fun_result<I, F>;	(5)	(C++20 起)

关于 /*execution-policy*/ 的定义，参见此页面；关于 /*sized-random-access-range*/ 的定义，参见此页面。

将给定的可调用对象 f 应用于目标范围 proj 或 [first, last) 的每个元素（由 r 投影）。如果 f 返回结果，则忽略该结果。

1,2) f 按照从目标范围开始的顺序应用。

3,4) f 可能不按顺序应用。该算法根据 policy 执行。

与其他并行算法不同，for_each 不允许对目标范围中的元素进行任意复制。

本页面描述的函数式实体是 算法函数对象（非正式称为 niebloids），即：

调用它们中的任何一个时都无法指定显式模板参数列表。
它们中的任何一个都对参数依赖查找不可见。
当它们中的任何一个通过普通无限定查找作为函数调用运算符左侧的名称被发现时，参数依赖查找被阻止。

参数

first, last	-	定义目标范围
的迭代器对	-	目标范围
f	-	应用于（投影后的）元素的可调用对象
proj	-	应用于元素的投影
policy	-	使用的执行策略

返回值

1) {last, std::move(f)}

2) {ranges::next(ranges::begin(r), ranges::end(r)), std::move(f)} 如果 R 符合 forward_range 概念，否则返回 (自 C++26 起){ranges::end(r), std::move(f)}

3) last

4) ranges::next(ranges::begin(r), ranges::end(r)) 如果 R 符合 forward_range 概念，否则返回 (自 C++26 起)ranges::end(r)

复杂度

1,3) 恰好 ranges::distance(first, last) 次对 f 和 proj 的调用。

2,4) 恰好 ranges::distance(r) 次对 f 和 proj 的调用。

异常

3,4) 在执行过程中：

如果并行化所需的临时内存资源不可用，std::bad_alloc 将被抛出。
如果通过算法参数访问对象时抛出了未捕获的异常，其行为由执行策略决定（对于标准策略，会调用std::terminate）。

注意

若投影返回可变引用，f可能修改目标范围内的元素。

对于重载(1,2)，f可以是带状态的可调用对象。返回值中的可调用对象可视为批处理操作的最终状态。

对于重载(3,4)，可能创建f的多个副本以执行并行调用。返回值不包含可调用对象，因为并行化通常不允许高效的状态累积。

可能的实现

struct for_each_fn
{
    template<std::input_iterator I, std::sentinel_for<I> S, class Proj = std::identity,
             std::indirectly_unary_invocable<std::projected<I, Proj>> Fun>
    constexpr ranges::for_each_result<I, Fun>
        operator()(I first, S last, Fun f, Proj proj = {}) const
    {
        for (; first != last; ++first)
            std::invoke(f, std::invoke(proj, *first));
        return {std::move(first), std::move(f)};
    }
    
    template<ranges::input_range R, class Proj = std::identity,
             std::indirectly_unary_invocable
                 <std::projected<ranges::iterator_t<R>, Proj>> Fun>
    constexpr ranges::for_each_result<ranges::borrowed_iterator_t<R>, Fun>
        operator()(R&& r, Fun f, Proj proj = {}) const
    {
        return (*this)(ranges::begin(r), ranges::end(r), std::move(f), std::ref(proj));
    }
    
    template<ranges::forward_range R, class Proj = std::identity,
             std::indirectly_unary_invocable
                 <std::projected<ranges::iterator_t<R>, Proj>> Fun>
    constexpr ranges::for_each_result<ranges::borrowed_iterator_t<R>, Fun>
        operator()(R&& r, Fun f, Proj proj = {}) const
    {
        return (*this)(ranges::begin(r),
                       ranges::next(ranges::begin(r), ranges::end(r)),
                       std::move(f), std::ref(proj));
    }
};

inline constexpr for_each_fn for_each;

示例

以下示例使用lambda表达式递增向量中的所有元素，然后使用一个重载的operator()在可调用对象中计算它们的总和。注意，要计算总和，建议使用专用算法std::accumulate。

运行此代码

#include <algorithm>
#include <cassert>
#include <iostream>
#include <string>
#include <utility>
#include <vector>

struct Sum
{
    void operator()(int n) { sum += n; }
    int sum {0};
};

int main()
{
    namespace ranges = std::ranges;
    
    std::vector<int> nums {3, 4, 2, 8, 15, 267};
    
    auto print = [](const auto& n) { std::cout << ' ' << n; };
    
    std::cout << "before:";
    ranges::for_each(std::as_const(nums), print);
    print('\n');
    
    ranges::for_each(nums, [](int& n) { ++n; });
    
    // calls Sum::operator() for each number
    auto [i, s] = ranges::for_each(nums.begin(), nums.end(), Sum());
    assert(i == nums.end());
    
    std::cout << "after: ";
    ranges::for_each(nums.cbegin(), nums.cend(), print);
    
    std::cout << "\n" "sum: " << s.sum << '\n';
    
    using pair = std::pair<int, std::string>; 
    std::vector<pair> pairs {{1,"one"}, {2,"two"}, {3,"tree"}};
    
    std::cout << "project the pair::first: ";
    ranges::for_each(pairs, print, [](const pair& p) { return p.first; });
    
    std::cout << "\n" "project the pair::second:";
    ranges::for_each(pairs, print, &pair::second);
    print('\n');
}

输出：

before: 3 4 2 8 15 267 
after:  4 5 3 9 16 268
sum: 305
project the pair::first:  1 2 3
project the pair::second: one two tree

参阅

for_each	对函数对象从范围的元素应用一元操作
(函数模板) ranges::for_each_n	(C++20) 对序列的前N个元素应用函数对象
(算法函数对象) ranges::transform	(C++20) 对范围内元素应用函数
(算法函数对象)`for` 范围- for	循环(C++11)

编译器支持
独立与托管实现
语言
标准库
标准库头文件
具名要求
功能特性测试宏 (C++20)
语言支持库
概念库 (C++20)
诊断库
内存管理库
元编程库 (C++11)
通用工具库
容器库
迭代器库
范围库 (C++20)
算法库
字符串库
文本处理库
数值库
日期和时间库
输入/输出库
文件系统库 (C++17)
并发支持库 (C++11)
执行控制库 (C++26)
技术规范
符号索引
外部库

zh.cppreference.net

Namespaces

Variants

std::ranges::for_each, std::ranges::for_each_result

目录

参数

返回值

复杂度

异常

注意

可能的实现

示例

参阅