std::ranges::fold_left_first

 

C++

编译器支持

独立式和宿主式

语言

标准库

标准库头文件

具名要求

特性测试宏 （C++20）

语言支持库

概念库 （C++20）

诊断库

内存管理库

元编程库 （C++11）

通用工具库

容器库

迭代器库

范围库 （C++20）

算法库

字符串库

文本处理库

数值库

日期和时间库

输入/输出库

文件系统库 （C++17）

并发支持库 （C++11）

执行控制库 （C++26）

技术规范

符号索引

外部库

 

算法库

约束算法和范围上的算法 （C++20）
约束算法，例如 ranges::copy, ranges::sort, ...
执行策略 （C++17）
is_execution_policy （C++17）   execution::seqexecution::parexecution::par_unseqexecution::unseq （C++17）    （C++17）（C++17）（C++20）	execution::sequenced_policyexecution::parallel_policyexecution::parallel_unsequenced_policyexecution::parallel_unsequenced （C++17）（C++17）（C++17）（C++20）
非修改序列操作 批量操作 for_each for_each_n （C++17） 搜索操作 all_ofany_ofnone_of （C++11）                （C++11）（C++11） countcount_if mismatch equal findfind_iffind_if_not （C++11） find_end find_first_of adjacent_find search search_n 修改序列操作 复制操作 copycopy_if （C++11） copy_backward copy_n （C++11） move （C++11） move_backward （C++11） 交换操作 swap iter_swap swap_ranges 变换操作 replacereplace_if transform replace_copyreplace_copy_if 生成操作 fill fill_n generate generate_n 移除操作 removeremove_if unique remove_copyremove_copy_if unique_copy 顺序更改操作 reverse reverse_copy rotate rotate_copy random_shuffleshuffle （直到 C++17）（C++11） shift_leftshift_right （C++20）（C++20） 采样操作 sample （C++17）	排序和相关操作 划分操作 partition partition_copy （C++11）   stable_partition is_partitioned （C++11） partition_point （C++11） 排序操作 sort stable_sort partial_sort partial_sort_copy is_sorted （C++11） is_sorted_until （C++11） nth_element 二分搜索操作 （在已划分的范围上） lower_bound upper_bound equal_range binary_search 集合操作（在已排序的范围上） includes set_union set_intersection set_difference set_symmetric_difference 归并操作（在已排序的范围上） merge inplace_merge 堆操作 push_heap pop_heap make_heap sort_heap is_heap （C++11） is_heap_until （C++11） 最小/最大操作 max min minmax （C++11） clamp （C++17） max_element min_element minmax_element （C++11） 字典序比较操作 lexicographical_compare lexicographical_compare_three_way （C++20） 排列操作 next_permutation prev_permutation is_permutation （C++11） C 库 qsort bsearch
数值操作
iota （C++11） inner_product adjacent_difference    accumulate reduce （C++17） transform_reduce （C++17）	partial_sum inclusive_scan （C++17）    exclusive_scan （C++17） transform_inclusive_scan （C++17） transform_exclusive_scan （C++17）
未初始化内存上的操作
uninitialized_copy uninitialized_move （C++17）    uninitialized_fill uninitialized_copy_n （C++11） uninitialized_move_n （C++17） uninitialized_fill_n	destroy （C++17） destroy_n （C++17） destroy_at （C++17） construct_at （C++20）       uninitialized_default_construct （C++17） uninitialized_value_construct （C++17） uninitialized_default_construct_n （C++17） uninitialized_value_construct_n （C++17）

 

约束算法

此菜单中的所有名称都属于命名空间 std::ranges

非修改序列操作

all_ofany_ofnone_of for_each for_each_n    countcount_if adjacent_find mismatch equal lexicographical_compare    containscontains_subrange （C++23）（C++23） findfind_iffind_if_not find_lastfind_last_iffind_last_if_not （C++23）（C++23）（C++23）   find_end find_first_of search search_n starts_with （C++23） ends_with （C++23）

修改序列操作

copycopy_if copy_n copy_backward    move move_backward shift_leftshift_right （C++23）（C++23）   fill fill_n generate generate_n    transform swap_ranges    shuffle sample removeremove_if replacereplace_if reverse rotate remove_copyremove_copy_if    unique replace_copyreplace_copy_if reverse_copy rotate_copy unique_copy

划分操作

is_partitioned    partition_point    partition    partition_copy    stable_partition

排序操作

is_sorted is_sorted_until     sort stable_sort         partial_sort       nth_element partial_sort_copy

二分搜索操作（在已排序的范围上）

lower_bound         upper_bound         binary_search      equal_range

集合操作（在已排序的范围上）

merge inplace_merge       set_difference set_intersection    set_union          includes set_symmetric_difference

堆操作

is_heap is_heap_until       make_heap           sort_heap push_heap pop_heap

最小/最大操作

max max_element         min min_element         minmax minmax_element     clamp

排列操作

is_permutation      next_permutation    prev_permutation

折叠操作

fold_left （C++23） fold_left_first （C++23）   fold_right （C++23） fold_right_last （C++23）   fold_left_with_iter （C++23） fold_left_first_with_iter （C++23）

数值操作 iota （C++23）             随机数生成 generate_random （C++26）

未初始化存储上的操作

construct_at    destroy destroy_n destroy_at uninitialized_copy    uninitialized_move uninitialized_fill uninitialized_copy_n    uninitialized_move_n uninitialized_fill_n uninitialized_default_construct uninitialized_default_construct_n uninitialized_value_construct uninitialized_value_construct_n

返回类型

in_fun_result in_in_result in_found_result    in_out_result in_in_out_result    in_out_out_result    min_max_result out_value_result （C++23） in_value_result （C++23）

 

定义于头文件 <algorithm>
调用签名
template< std::input_iterator I, std::sentinel_for<I> S,           /*indirectly-binary-left-foldable*/<std::iter_value_t<I>, I> F > requires std::constructible_from<std::iter_value_t<I>, std::iter_reference_t<I>> constexpr auto     fold_left_first( I first, S last, F f );	(1)	（自 C++23 起）
template< ranges::input_range R,           /*indirectly-binary-left-foldable*/<                 ranges::range_value_t<R>, ranges::iterator_t<R>> F > requires std::constructible_from<              ranges::range_value_t<R>, ranges::range_reference_t<R>> constexpr auto     fold_left_first( R&& r, F f );	(2)	（自 C++23 起）
辅助概念
template< class F, class T, class I > concept /*indirectly-binary-left-foldable*/ = /* see description */;	(3)	（仅为阐述*）

左折叠给定范围的元素，即返回链式表达式的求值结果
f(f(f(f(x1, x2), x3), ...), xn)，其中 x1, x2, ..., xn 是范围的元素。

非正式地，ranges::fold_left_first 的行为类似于 std::accumulate 的接受二元谓词的重载，不同之处在于 *first 在内部用作初始元素。

如果 [first, last) 不是有效范围，则行为未定义。

1) 范围是 [first, last)。 等价于 return ranges::fold_left_first_with_iter(std::move(first), last, f).value。

2) 与 (1) 相同，除了使用 r 作为范围，如同使用 ranges::begin(r) 作为 first 和 ranges::end(r) 作为 last。

3) 等价于

辅助概念
template< class F, class T, class I, class U > concept /*indirectly-binary-left-foldable-impl*/ =     std::movable<T> &&     std::movable<U> &&     std::convertible_to<T, U> &&     std::invocable<F&, U, std::iter_reference_t<I>> &&     std::assignable_from<U&,         std::invoke_result_t<F&, U, std::iter_reference_t<I>>>;	(3A)	（仅为阐述*）
template< class F, class T, class I > concept /*indirectly-binary-left-foldable*/ =     std::copy_constructible<F> &&     std::indirectly_readable<I> &&     std::invocable<F&, T, std::iter_reference_t<I>> &&     std::convertible_to<std::invoke_result_t<F&, T, std::iter_reference_t<I>>,         std::decay_t<std::invoke_result_t<F&, T, std::iter_reference_t<I>>>> &&     /*indirectly-binary-left-foldable-impl*/<F, T, I,         std::decay_t<std::invoke_result_t<F&, T, std::iter_reference_t<I>>>>;	(3B)	（仅为阐述*）

此页面上描述的类似函数的实体是 算法函数对象（非正式地称为 niebloids），即

• 调用它们中的任何一个时，都不能显式指定模板参数列表。
• 它们都对 实参依赖查找 不可见。
• 当通过 普通非限定查找 找到它们中的任何一个作为函数调用运算符左侧的名称时，实参依赖查找 会被抑制。

参数

first, last	-	定义要折叠元素范围的迭代器-哨位对
r	-	要折叠的元素范围
f	-	二元函数对象

返回值

类型为 std::optional<U> 的对象，包含给定范围在 f 上的左折叠结果，其中 U 等价于 decltype(ranges::fold_left(std::move(first), last, std::iter_value_t<I>(*first), f))。

如果范围为空，则返回 std::optional<U>()。

可能的实现

struct fold_left_first_fn { template<std::input_iterator I, std::sentinel_for<I> S, /*indirectly-binary-left-foldable*/<std::iter_value_t<I>, I> F> requires std::constructible_from<std::iter_value_t<I>, std::iter_reference_t<I>> constexpr auto operator()(I first, S last, F f) const { using U = decltype( ranges::fold_left(std::move(first), last, std::iter_value_t<I>(*first), f) ); if (first == last) return std::optional<U>(); std::optional<U> init(std::in_place, *first); for (++first; first != last; ++first) *init = std::invoke(f, std::move(*init), *first); return std::move(init); }   template<ranges::input_range R, /*indirectly-binary-left-foldable*/< ranges::range_value_t<R>, ranges::iterator_t<R>> F> requires std::constructible_from<ranges::range_value_t<R>, ranges::range_reference_t<R>> constexpr auto operator()(R&& r, F f) const { return (*this)(ranges::begin(r), ranges::end(r), std::ref(f)); } };   inline constexpr fold_left_first_fn fold_left_first;

复杂度

恰好 ranges::distance(first, last) - 1 次（假设范围非空）函数对象 f 的应用。

注解

下表比较了所有约束折叠算法

折叠函数模板	起始于	初始值	返回类型
ranges::fold_left	左	init	U
ranges::fold_left_first	左	首元素	std::optional<U>
ranges::fold_right	右	init	U
ranges::fold_right_last	右	尾元素	std::optional<U>
ranges::fold_left_with_iter	左	init	（1） ranges::in_value_result<I, U> （2） ranges::in_value_result<BR, U>， 其中 BR 是 ranges::borrowed_iterator_t<R>
ranges::fold_left_first_with_iter	左	首元素	（1） ranges::in_value_result<I, std::optional<U>> （2） ranges::in_value_result<BR, std::optional<U>> 其中 BR 是 ranges::borrowed_iterator_t<R>

特性测试 宏	值	Std	特性
__cpp_lib_ranges_fold	202207L	（C++23）	std::ranges 折叠算法

示例

运行此代码

#include <algorithm>
#include <array>
#include <functional>
#include <ranges>
#include <utility>
 
int main()
{
    constexpr std::array v{1, 2, 3, 4, 5, 6, 7, 8};
    static_assert
    (
        *std::ranges::fold_left_first(v.begin(), v.end(), std::plus{}) == 36
        && *std::ranges::fold_left_first(v, std::multiplies{}) == 40320
    );
 
    constexpr std::array w
    {
        1, 2, 3, 4, 13,
        1, 2, 3, 4, 13,
        1, 2, 3, 4, 13,
        1, 2, 3, 4,
    };
    static_assert
    (
        "Find the only value that (by precondition) occurs odd number of times:"
        && *std::ranges::fold_left_first(w, [](int p, int q){ return p ^ q; }) == 13
    );
 
    constexpr auto pairs = std::to_array<std::pair<char, float>>
    ({
        {'A', 3.0f},
        {'B', 3.5f},
        {'C', 4.0f}
    });
    static_assert
    (
        "Get the product of all pair::second in pairs:"
        && *std::ranges::fold_left_first
        (
            pairs | std::ranges::views::values, std::multiplies{}
        ) == 42
    );
}

参考

• C++23 标准 (ISO/IEC 14882:2024)

• 27.6.18 折叠 [alg.fold]

参见

ranges::fold_left （C++23）	左折叠一个元素范围 （算法函数对象）
ranges::fold_right （C++23）	右折叠一个元素范围 （算法函数对象）
ranges::fold_right_last （C++23）	右折叠一个元素范围，使用尾元素作为初始值 （算法函数对象）
ranges::fold_left_with_iter （C++23）	左折叠一个元素范围，并返回一个 pair (迭代器, 值) （算法函数对象）
ranges::fold_left_first_with_iter （C++23）	左折叠一个元素范围，使用首元素作为初始值，并返回一个 pair (迭代器, optional) （算法函数对象）
accumulate	对一个元素范围求和或折叠 （函数模板）
reduce （C++17）	类似于 std::accumulate，但顺序不定 （函数模板）