Apache C++ Standard Library Reference Guide

## copy(), copy_backward()

Library: Algorithms

    Function

- Local Index
- Summary
- Synopsis
- Description
- Complexity
- Example
- See Also
- Standards Conformance

### Local Index

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

### See Also

Algorithms, <algorithm>

### Standards Conformance

ISO/IEC 14882:1998 -- International Standard for Information Systems -- Programming Language C++, Section 25.2.1