std::rotate_copy(3)

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)