std::adjacent_difference

template< class InputIt, class OutputIt >
OutputIt adjacent_difference( InputIt first, InputIt last,
                              OutputIt d_first );

template< class ExecutionPolicy,
          class ForwardIt1, class ForwardIt2 >
ForwardIt2 adjacent_difference( ExecutionPolicy&& policy,
                                ForwardIt1 first, ForwardIt1 last,
                                ForwardIt2 d_first );

template< class InputIt, class OutputIt, class BinaryOp >
OutputIt adjacent_difference( InputIt first, InputIt last, 
                              OutputIt d_first, BinaryOp op );

template< class ExecutionPolicy,
          class ForwardIt1, class ForwardIt2, class BinaryOp >
ForwardIt2 adjacent_difference( ExecutionPolicy&& policy,
                                ForwardIt1 first, ForwardIt1 last, 
                                ForwardIt2 d_first, BinaryOp op );

Пусть T — это тип значения decltype(first).

Пусть 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 — итератор, который будет возвращён. Если выполняется любое из следующих условий, поведение не определено:

• Для перегрузок (2,4) [first, last) и [d_first, d_last) пересекаются.
• binary_op изменяет любой элемент [first, last) или [d_first, d_last).
• binary_op делает недействительным любой итератор или поддиапазон в [first, last] или [d_first, d_last].

Параметры

Возвращаемое значение

Итератор на элемент после последнего записанного элемента или d_first, если [first, last) пуст.

Сложность

Пусть \(\scriptsize N\)N — это std::distance(first, last):

Исключения

Перегрузки с параметром шаблона с именем ExecutionPolicy сообщают об ошибках следующим образом:

• Если выполнение функции, вызванной в рамках алгоритма, приводит к исключению и ExecutionPolicy является одной из стандартных политик, вызывается std::terminate. Для любой другой ExecutionPolicy поведение определяется реализацией.
• Если алгоритму не удаётся выделить память, выбрасывается std::bad_alloc.

Возможная реализация

template<class InputIt, class OutputIt>
constexpr // since 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); // std::move since C++20
        acc = std::move(val);
    }
    
    return ++d_first;
}

template<class InputIt, class OutputIt, class BinaryOp>
constexpr // since 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)); // std::move since C++20
        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: performs conversions when needed
// 1. creates “acc” of type char (the value type)
// 2. “acc” is assigned to the first element of “o_array”
// 3. the char arguments are used for long multiplication (char -> long)
// 4. the long product is assigned to the output range (long -> int)
// 5. the next value of “i_array” is assigned to “acc”
// 6. go back to step 3 to process the remaining elements in the input range
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()
{
    // Default implementation - the difference between two adjacent items
    std::vector v{4, 6, 9, 13, 18, 19, 19, 15, 10};
    println("Initially, v = ", v);
    std::adjacent_difference(v.begin(), v.end(), v.begin());
    println("Modified v = ", v);
    
    // Fibonacci
    std::array<int, 10> a {1};
    std::adjacent_difference(std::begin(a), std::prev(std::end(a)),
                             std::next(std::begin(a)), std::plus<>{});
    println("Fibonacci, a = ", a);
}

Initially, v = 4 6 9 13 18 19 19 15 10 
Modified v = 4 2 3 4 5 1 0 -4 -5 
Fibonacci, a = 1 1 2 3 5 8 13 21 34 55

Сведения об исправлениях ошибок

Следующие исправления ошибок, изменяющие поведение, были применены задним числом к ранее опубликованным стандартам C++.

См. также