std::adjacent_difference

在标头 `<numeric>` 定义
template< class InputIt, class OutputIt > OutputIt adjacent_difference( InputIt first, InputIt last, OutputIt d_first );	(1)	(C++20 起为 `constexpr`)
template< class ExecutionPolicy, class ForwardIt1, class ForwardIt2 > ForwardIt2 adjacent_difference( ExecutionPolicy&& policy, ForwardIt1 first, ForwardIt1 last, ForwardIt2 d_first );	(2)	(C++17 起)
template< class InputIt, class OutputIt, class BinaryOp > OutputIt adjacent_difference( InputIt first, InputIt last, OutputIt d_first, BinaryOp op );	(3)	(C++20 起为 `constexpr`)
template< class ExecutionPolicy, class ForwardIt1, class ForwardIt2, class BinaryOp > ForwardIt2 adjacent_difference( ExecutionPolicy&& policy, ForwardIt1 first, ForwardIt1 last, ForwardIt2 d_first, BinaryOp op );	(4)	(C++17 起)

1) 如果 [first, last) 为空，那么什么也不做。

否则按顺序进行以下操作：

创建 T 类型累加器 acc，以 *first 初始化。
将 acc 赋给 *d_first。
对于 [++first, last) 中的每个迭代器 iter，依次按顺序进行以下操作：

a) 创建 T 类型对象 val，以 *iter 初始化。

b) 计算 val - acc (C++20 前)val - std::move(acc) (C++20 起)。

c) 将计算结果赋给 *++d_first。

d) 从 val 复制 (C++20 前)移动 (C++20 起)赋值到 acc。

2) 如果 [first, last) 为空，那么什么也不做。

否则按顺序进行以下操作：

将 *first 赋给 *d_first。
对于 [1, std::distance(first, last)) 中的所有整数 i，按顺序进行以下操作：

a) 计算 curr - prev，其中 curr 是 first 的下 i 个迭代器，prev 是 first 的下 i - 1 个迭代器。

b) 将计算结果赋给 *dest，其中 dest 是 d_first 的下 i 个迭代器。

3) 同 (1)，但计算的是 op(val, acc) (C++20 前)op(val, std::move(acc)) (C++20 起)。

4) 同 (2)，但计算的是 op(curr, prev)。

给定 binary_op 为实际的二元运算：

如果满足以下任意条件，那么程序非良构：

对于重载 (1,3)：

T 不可从 *first 构造。
acc 不可写入 d_first。
binary_op(val, acc) (C++20 前)binary_op(val, std::move(acc)) (C++20 起) 的结果不可写入 d_first。

对于重载 (2,4)：

*first 不可写入 d_first。
binary_op(*first, *first) 的结果不可写入 d_first。

给定 d_last 为要返回的迭代器，如果满足以下任意条件，那么行为未定义：

对于重载 (1,3)，T 不可移动赋值 (MoveAssignable) 。

(C++20 起)

对于重载 (2,4)，[first, last) 和 [d_first, d_last) 有重叠。
binary_op 会修改 [first, last) 或 [d_first, d_last) 的元素。
binary_op 会使 [first, last] 或 [d_first, d_last] 中的迭代器或子范围失效。

参数

first, last	-	元素范围
d_first	-	目标范围的起始
policy	-	所用的执行策略。细节见执行策略。
op	-	被使用的二元函数对象。该函数的签名应当等价于： Ret fun(const Type1 &a, const Type2 &b); 签名中并不需要有 const &。类型 Type1 与 Type2 必须使得 iterator_traits<InputIt>::value_type 类型的对象能隐式转换到这两个类型。类型 Ret 必须使得 OutputIt 类型对象能被解引用并能被赋 Ret 类型值。
类型要求
- `InputIt` 必须满足老式输入迭代器 (LegacyInputIterator) 。
- `OutputIt` 必须满足老式输出迭代器 (LegacyOutputIterator) 。
- `ForwardIt1, ForwardIt2` 必须满足老式向前迭代器 (LegacyForwardIterator) 。

返回值

指向最后被写入元素后一位置的迭代器，或者在 [first, last) 为空时返回 d_first。

复杂度

给定 $\scriptsize N$ $N$ 为 std::distance(first, last)：

1,2) 应用

N-1

次 operator-。

3,4) 应用

N-1

次二元函数 op。

异常

拥有名为 ExecutionPolicy 的模板形参的重载按下列方式报告错误：

如果作为算法一部分调用的函数的执行抛出异常，且 ExecutionPolicy 是标准策略之一，那么调用 std::terminate。对于任何其他 ExecutionPolicy，行为由实现定义。
如果算法无法分配内存，那么抛出 std::bad_alloc。

可能的实现

adjacent_difference (1)

template<class InputIt, class OutputIt>
constexpr // C++20 起
OutputIt adjacent_difference(InputIt first, InputIt last, OutputIt d_first)
{
    if (first == last)
        return d_first;
 
    typedef typename std::iterator_traits<InputIt>::value_type value_t;
    value_t acc = *first;
    *d_first = acc;
 
    while (++first != last)
    {
        value_t val = *first;
        *++d_first = val - std::move(acc); // C++20 起有 std::move
        acc = std::move(val);
    }
 
    return ++d_first;
}

adjacent_difference (3)

template<class InputIt, class OutputIt, class BinaryOp>
constexpr // C++20 起
OutputIt adjacent_difference(InputIt first, InputIt last, 
                             OutputIt d_first, BinaryOp op)
{
    if (first == last)
        return d_first;
 
    typedef typename std::iterator_traits<InputIt>::value_type value_t;
    value_t acc = *first;
    *d_first = acc;
 
    while (++first != last)
    {
        value_t val = *first;
        *++d_first = op(val, std::move(acc)); // C++20 起有 std::move
        acc = std::move(val);
    }
 
    return ++d_first;
}

注解

acc 通过 LWG 问题 539 的解决方案引入。使用 acc 而不是直接将结果相减的原因是后者的语义在以下类型不匹配时难以理解：

InputIt 的值类型
OutputIt 的可写入类型
operator- 或 op 的形参类型
operator- 或 op 的返回类型

acc 用来作为缓存遍历过的值的中间对象：

它的类型是 InputIt 的值类型
写入 d_first 的值（即 operator+ 或 op 的返回值）会赋给它
它的值会传递给 operator+ 或 op

char i_array[4] = {100, 100, 100, 100};
int  o_array[4];
 
// OK：在需要时进行转换
// 1. 创建 char 类型（值类型）的 “acc”
// 2. 将 “acc” 赋给 “o_array” 的首个元素
// 3. 将 char 实参用于 long 乘法（char -> long）
// 4. 将 long 类型的积赋到输出范围中（long -> int）
// 5. 将 “i_array” 的下个值赋给 “acc”
// 6. 回到第 3 步，处理输入序列的剩余元素
std::adjacent_difference(i_array, i_array + 4, o_array, std::multiplies<long>{});

示例

运行此代码

#include <array>
#include <functional>
#include <iostream>
#include <iterator>
#include <numeric>
#include <vector>
 
void println(auto comment, const auto& sequence)
{
    std::cout << comment;
    for (const auto& n : sequence)
        std::cout << n << ' ';
    std::cout << '\n';
};
 
int main()
{
    // 默认实现——两个相邻项之间的差
    std::vector v{4, 6, 9, 13, 18, 19, 19, 15, 10};
    println("一开始，v = ", v);
    std::adjacent_difference(v.begin(), v.end(), v.begin());
    println("修改后，v = ", v);
 
    // 斐波那契
    std::array<int, 10> a {1};
    adjacent_difference(begin(a), std::prev(end(a)), std::next(begin(a)), std::plus<>{});
    println("斐波那契，a = ", a);
}

输出：

一开始，v = 4 6 9 13 18 19 19 15 10 
修改后，v = 4 2 3 4 5 1 0 -4 -5 
斐波那契，a = 1 1 2 3 5 8 13 21 34 55

缺陷报告

下列更改行为的缺陷报告追溯地应用于以前出版的 C++ 标准。

缺陷报告	应用于	出版时的行为	正确行为
LWG 242	C++98	op 不能有任何副作用	它不能修改涉及到的范围
LWG 539	C++98	缺失了需要保证对结果的求值和赋值合法的条件要求	已补充
LWG 3058	C++17	对于重载 (2,4)，每次调用 operator- 或 op 都会创建临时对象存储结果，然后将该对象赋到输出范围中	直接将结果赋到输出范围中

参阅

partial_sum	计算范围内元素的部分和 (函数模板)
accumulate	对一个范围内的元素求和或折叠 (函数模板)

编译器支持
自立实现与有宿主实现
语言
标准库
标准库标头
具名要求
功能特性测试宏 (C++20)
语言支持库
概念库 (C++20)
元编程库 (C++11)
诊断库
通用工具库
字符串库
容器库
迭代器库
范围库 (C++20)
算法库
数值库
本地化库
输入/输出库
文件系统库 (C++17)
正则表达式库 (C++11)
并发支持库 (C++11)
技术规范
符号索引
外部库

std::adjacent_difference

参数

返回值

复杂度

异常

可能的实现

注解

示例

缺陷报告

参阅

导航