NAME¶

std::rotate_copy - std::rotate_copy

Synopsis¶

Defined in header <algorithm>
template< class ForwardIt, class OutputIt >

OutputIt rotate_copy( ForwardIt first, ForwardIt
n_first, (1) (constexpr since C++20)

ForwardIt last, OutputIt d_first
);
template< class ExecutionPolicy,

class ForwardIt1, class ForwardIt2 >
ForwardIt2 rotate_copy( ExecutionPolicy&& policy,
ForwardIt1 first, ForwardIt1 (2) (since C++17)
n_first,

ForwardIt1 last, ForwardIt2
d_first );

1) Copies the elements from the range [first, last), to another range beginning at
d_first in such a way, that the element *(n_first) becomes the first element of the
new range and *(n_first - 1) becomes the last element.
2) Same as (1), but executed according to policy.
This overload participates in overload resolution only if

std::is_execution_policy_v<std::decay_t<ExecutionPolicy>> is true. (until
C++20)
std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>> is true. (since
C++20)

If any of the following conditions is satisfied, the behavior is undefined:

* [first, n_first) or [n_first, last) is not a valid range.
* The source and destination ranges overlap.

Parameters¶

first, last - the range of elements to copy
n_first - an iterator to an element in [first, last) that should appear at the
beginning of the new range
d_first - beginning of the destination range
policy - the execution policy to use. See execution policy for details.

Type requirements¶

-
ForwardIt, ForwardIt1, ForwardIt2 must meet the requirements of
LegacyForwardIterator.
-
OutputIt must meet the requirements of LegacyOutputIterator.

Return value¶

Output iterator to the element past the last element copied.

Complexity¶

Exactly std::distance(first, last) 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.

Possible implementation¶

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

template<class ForwardIt, class OutputIt>
constexpr // since C++20
OutputIt rotate_copy(ForwardIt first, ForwardIt n_first,
ForwardIt last, OutputIt d_first)
{
d_first = std::copy(n_first, last, d_first);
return std::copy(first, n_first, d_first);
}

Example¶

// Run this code

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

int main()
{
std::vector<int> src{1, 2, 3, 4, 5};
std::vector<int> dest(src.size());
auto pivot = std::find(src.begin(), src.end(), 3);

std::rotate_copy(src.begin(), pivot, src.end(), dest.begin());
for (int i : dest)
std::cout << i << ' ';
std::cout << '\n';

// copy the rotation result directly to the std::cout
pivot = std::find(dest.begin(), dest.end(), 1);
std::rotate_copy(dest.begin(), pivot, dest.end(),
std::ostream_iterator<int>(std::cout, " "));
std::cout << '\n';
}

Output:¶

3 4 5 1 2
1 2 3 4 5

See also¶

rotate rotates the order of elements in a range
(function template)
ranges::rotate_copy copies and rotate a range of elements
(C++20) (niebloid)