copy(), copy_backward()

Module:  Standard C++ Library   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

Copyright (c) 1994-2006 Rogue Wave Software, a Quovadx Division.
Licensed under the Apache License, Version 2.0.
Contact Rogue Wave about documentation or support issues. You can also seek help from other developers through the Apache stdcxx community (see below).