std::reverse_copy

Defined in header `<algorithm>`
	(1)
template< class BidirIt, class OutputIt > OutputIt reverse_copy( BidirIt first, BidirIt last, OutputIt d_first );			(until C++20)
template< class BidirIt, class OutputIt > constexpr OutputIt reverse_copy( BidirIt first, BidirIt last, OutputIt d_first );			(since C++20)
template< class ExecutionPolicy, class BidirIt, class ForwardIt > ForwardIt reverse_copy( ExecutionPolicy&& policy, BidirIt first, BidirIt last, ForwardIt d_first );		(2)	(since C++17)

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).

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

2) Same as (1), but executed according to policy. This overload does not participate in overload resolution unless 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.

Parameters

first, last	-	the range of elements to copy
d_first	-	the beginning of the destination range
Type requirements
- `BidirIt` must meet the requirements of LegacyBidirectionalIterator.
- `OutputIt` must meet the requirements of LegacyOutputIterator.
- `ForwardIt` must meet the requirements of LegacyForwardIterator.

Return value

Output iterator to the element past the last element copied.

Complexity

Exactly last - first assignments.

Exceptions

The overload with a template parameter named ExecutionPolicy reports 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.

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.

Possible implementation

See also the implementations in libstdc++, libc++, and MSVC STL.

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

Example

Run this code

#include <vector>
#include <iostream>
#include <algorithm>
 
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

Compiler support
Freestanding and hosted
Language
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Technical specifications
Symbols index
External libraries

reverse	reverses the order of elements in a range (function template)
ranges::reverse_copy (C++20)	creates a copy of a range that is reversed (niebloid)