copy(), copy_backward()

Library:  Algorithms

Function

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

Algorithm that copies a range of elements

#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);
}

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.

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

//
// 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 

Algorithms, <algorithm>

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