Apache C++ Standard Library Reference Guide

## copy(), copy_backward()

Library:  Algorithms

`Function`

No Entries

### Summary

Algorithm that copies a range of elements

### Synopsis

```#include <algorithm>

namespace std {
template <class InputIterator, class OutputIterator>
OutputIterator copy(InputIterator start,
InputIterator finish,
OutputIterator result);
template <class BidirectionalIterator1,
class BidirectionalIterator2>
BidirectionalIterator2
copy_backward(BidirectionalIterator1 start,
BidirectionalIterator1 finish,
BidirectionalIterator2 result);
}
```

### Description

The copy() algorithm copies values from the range specified by [start, finish) to the range specified by [result, result + (finish - start)). copy() returns result + (finish - start). For each non-negative integer n < (finish - start), copy() assigns *(start + n) to *(result + n). The result of copy() is undefined if result is in the range [start, finish).

Unless result is an insert iterator, copy() assumes that all iterators in the range [result + (finish - start)] are dereferenceable.

The copy_backward() algorithm copies elements in the range specified by [start, finish) into the range specified by [result - (finish - start), result), starting from the end of the sequence (finish-1) and progressing to the front (start). Note that copy_backward() does not reverse the order of the elements, it simply reverses the order of transfer. copy_backward() returns result - (finish - start). You should use copy_backward() instead of copy() when finish is in the range [result - (finish - start), result). For each positive integer n <= (finish - start), copy_backward() assigns *(finish - n) to *(result - n). The result of copy_backward() is undefined if result is in the range [start, finish). copy_backward() should be used when finish is in the range [result - (finish - start), result).

Unless result is an insert iterator, copy_backward() assumes that all iterators in the range [result - (finish - start), result) are dereferenceable.

### Complexity

Both copy() and copy_backward() perform exactly finish - start assignments.

### Example

```//
// copyex.cpp
//

#include <algorithm>   // for copy
#include <iostream>    // for cout, endl, ostream_iterator
#include <vector>      // for vector

int main ()
{
// Typedef for convenience.
typedef std::vector<short, std::allocator<short> > vector;

const vector::value_type d1[] = { 1, 2, 3, 4 };
const vector::value_type d2[] = { 5, 6, 7, 8 };

// Set up three vectors.
vector v1(d1 + 0, d1 + 4),
v2(d2 + 0, d2 + 4),
v3(d2 + 0, d2 + 4);

// Set up one empty vector.
vector v4;

// Copy v1 to v2.
std::copy(v1.begin(), v1.end(), v2.begin());

// Copy backwards v1 to v3.
std::copy_backward(v1.begin(), v1.end(), v3.end());

// Use insert iterator to copy into empty vector.
std::copy(v1.begin(), v1.end(), std::back_inserter(v4));

// Copy all four vectors to cout.
std::ostream_iterator<vector::value_type, char,
std::char_traits<char> > out(std::cout, " ");

std::copy(v1.begin(), v1.end(), out);
std::cout << std::endl;

std::copy(v2.begin(), v2.end(), out);
std::cout << std::endl;

std::copy(v3.begin(), v3.end(), out);
std::cout << std::endl;

std::copy(v4.begin(), v4.end(), out);
std::cout << std::endl;

return 0;
}

Program Output:
```
```1 2 3 4
1 2 3 4
1 2 3 4
1 2 3 4
```