std::copy_backward

template <class BidirectionalIterator1, class BidirectionalIterator2>  BidirectionalIterator2 copy_backward (BidirectionalIterator1 first,                                        BidirectionalIterator1 last,                                        BidirectionalIterator2 result);

Copy range of elements backward

Copies the elements in the range [first,last) starting from the end into the range terminating at result.

The function returns an iterator to the first element in the destination range.

The resulting range has the elements in the exact same order as [first,last). To reverse their order, see reverse_copy.

The function begins by copying *(last-1) into *(result-1), and then follows backward by the elements preceding these, until first is reached (and including it).

The ranges shall not overlap in such a way that result (which is the past-the-end element in the destination range) points to an element in the range (first,last]. For such cases, see copy.

The behavior of this function template is equivalent to:

template<class BidirectionalIterator1, class BidirectionalIterator2>
  BidirectionalIterator2 copy_backward ( BidirectionalIterator1 first,
                                         BidirectionalIterator1 last,
                                         BidirectionalIterator2 result )
{
  while (last!=first) *(--result) = *(--last);
  return result;
}

Parameters

first, last: Bidirectional iterators to the initial and final positions in a sequence to be copied. 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.
result: Bidirectional iterator to the past-the-end position in the destination sequence.
This shall not point to any element in the range (first,last].

Return value

An iterator to the first element of the destination sequence where elements have been copied.

Example

// copy_backward example
#include <iostream>     // std::cout
#include <algorithm>    // std::copy_backward
#include <vector>       // std::vector

int main () {
  std::vector<int> myvector;

  // set some values:
  for (int i=1; i<=5; i++)
    myvector.push_back(i*10);          // myvector: 10 20 30 40 50

  myvector.resize(myvector.size()+3);  // allocate space for 3 more elements

  std::copy_backward ( myvector.begin(), myvector.begin()+5, myvector.end() );

  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: 10 20 30 10 20 30 40 50

Complexity

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

Data races

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

Exceptions

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