function template
<algorithm>

std::rotate_copy

template <class ForwardIterator, class OutputIterator>
  OutputIterator rotate_copy (ForwardIterator first, ForwardIterator middle,
                              ForwardIterator last, OutputIterator result);
Copy range rotated left
Copies the elements in the range [first,last) to the range beginning at result, but rotating the order of the elements in such a way that the element pointed by middle becomes the first element in the resulting range.

The behavior of this function template is equivalent to:
1
2
3
4
5
6
7
 
template <class ForwardIterator, class OutputIterator>
  OutputIterator rotate_copy (ForwardIterator first, ForwardIterator middle,
                              ForwardIterator last, OutputIterator result)
{
  result=std::copy (middle,last,result);
  return std::copy (first,middle,result);
}


Parameters

first, last
Forward iterators to the initial and final positions of the range to be copy-rotated. The range used is [first,last), which contains all the elements between first and last, including the element pointed by first but not the element pointed by last.
Notice that in this function, these are not consecutive parameters, but the first and third ones.
middle
Forward iterator pointing to the element within the range [first,last) that is copied as the first element in the resulting range.
result
Output iterator to the initial position of the range where the reversed range is stored.
The pointed type shall support being assigned the value of an element in the range [first,last).

The ranges shall not overlap.

Return value

An output iterator pointing to the end of the copied range.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
 
// rotate_copy algorithm example
#include <iostream>     // std::cout
#include <algorithm>    // std::rotate_copy
#include <vector>       // std::vector

int main () {
  int myints[] = {10,20,30,40,50,60,70};

  std::vector<int> myvector (7);

  std::rotate_copy(myints,myints+3,myints+7,myvector.begin());

  // print out content:
  std::cout << "myvector contains:";
  for (std::vector<int>::iterator it=myvector.begin(); it!=myvector.end(); ++it)
    std::cout << ' ' << *it;
  std::cout << '\n';

  return 0;
}


Output:
myvector contains: 40 50 60 70 10 20 30

Complexity

Linear in the distance between first and last: Performs an assignment for each element.

Data races

The objects in the range [first,last) are accessed.
The objects in the range between result and the returned value are modified.
Each object is accessed exactly once.

Exceptions

Throws if either an element assignment or an operation on an iterator throws.
Note that invalid arguments cause undefined behavior.

See also

rotate
Rotate left the elements in range (function template )
reverse_copy
Copy range reversed (function template )
random_shuffle
Randomly rearrange elements in range (function template )
copy
Copy range of elements (function template )

C++