std::reverse_copy() algorithm

since C++20

// (1)
template< class BidirIt, class OutputIt >
constexpr OutputIt reverse_copy( BidirIt first, BidirIt last, OutputIt d_first );

// (2)
template< class ExecutionPolicy, class BidirIt, class ForwardIt >
ForwardIt reverse_copy( ExecutionPolicy&& policy,
                        BidirIt first, BidirIt last, ForwardIt d_first );

since C++17

// (1)
template< class BidirIt, class OutputIt >
OutputIt reverse_copy( BidirIt first, BidirIt last, OutputIt d_first );

// (2)
template< class ExecutionPolicy, class BidirIt, class ForwardIt >
ForwardIt reverse_copy( ExecutionPolicy&& policy,
                        BidirIt first, BidirIt last, ForwardIt d_first );

until C++17

// (1)
template< class BidirIt, class OutputIt >
OutputIt reverse_copy( BidirIt first, BidirIt last, OutputIt d_first );

• (1) Copies the elements from the range [first; last) to another range beginning at d_first in such a way that the elements in the new range are in reverse order.

  Behaves as if by executing the assignment *(d_first + (last - first) - 1 - i) = *(first + i) once for each non-negative i < (last - first).

• (2) Same as (1), but executed according to policy.

  Overload Resolution

  These overloads participate in overload resolution only if std::is_execution_policy_v<std::decay_t<ExecutionPolicy>>  (until C++20) std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>>  (since C++20) is true.

Undefined Behaviour

If the source and destination ranges (that is, [first; last) and [d_first; d_first + (last - first)), respectively) overlap, the behavior is undefined

.

Parameters

first last	The range of elements to copy.
d_first	The beginning of the destination range.
policy	The execution policy to use. See execution policy for details.

Type requirements

BidirIt	LegacyBidirectionalIterator
OutputIt	LegacyOutputIterator
ForwardIt	LegacyForwardIterator

Return value

Output iterator to the element past the last element copied.

Complexity

Exactly last - first assignments.

Exceptions

The overloads with a template parameter named ExecutionPolicy report errors as follows:

• If execution of a function invoked as part of the algorithm throws an exception and ExecutionPolicy is one of the standard policies, std::terminate is called. For any other ExecutionPolicy, the behavior is implementation-defined.
• If the algorithm fails to allocate memory, std::bad_alloc is thrown.

Possible implementation

reverse_copy(1)

template<class BidirIt, class OutputIt>
constexpr // since C++20
OutputIt reverse_copy(BidirIt first, BidirIt last, OutputIt d_first)
{
    for (; first != last; ++d_first)
        *d_first = *(--last);
    return d_first;
}

Notes

Implementations (e.g. MSVC STL) may enable vectorization when the both iterator types satisfy LegacyContiguousIterator and have the same value type, and the value type is TriviallyCopyable.

Examples

Main.cpp

#include <algorithm>
#include <iostream>
#include <vector>

int main()
{
    auto print = [](std::vector<int> const& v)
    {
        for (const auto& value : v)
            std::cout << value << ' ';
        std::cout << '\t';
    };

    std::vector<int> v {1, 2, 3};
    print(v);

    std::vector<int> destination(3);
    std::reverse_copy(std::begin(v), std::end(v), std::begin(destination));
    print(destination);

    std::reverse_copy(std::rbegin(v), std::rend(v), std::begin(destination));
    print(destination);
}

Output

1 2 3   3 2 1   1 2 3