.\" ident @(#)copy.3
.\" Standard Template Library
.\" $$RW_INSERT_HEADER "slyrs.man"
.TH copy 3C++ "02 Apr 1998" "Rogue Wave Software" "-"
.ce2
Standard C++ Library   
Copyright 1998, Rogue Wave Software, Inc.   

.SH NAME

\f2copy\fP, \f2copy_backward\fP

\ - Copies a range of elements.



.SH  SYNOPSIS


.br
#include <algorithm>
.br
template <class InputIterator, class OutputIterator>
.br
OutputIterator copy(InputIterator first, 
.RE
.RS 20
InputIterator last,
.br
OutputIterator result);
.RE
.RS 0
template <class BidirectionalIterator1, 
.RE
.RS 9
class BidirectionalIterator2>
.RE
.RS 0
BidirectionalIterator2
.RE
.RS 1
copy_backward(BidirectionalIterator1 first,
.RE
.RS 15
BidirectionalIterator1 last,
.br
BidirectionalIterator2 result);



.SH  DESCRIPTION


The copy algorithm copies values from the range specified by \f2[first\fP, \f2last)\fP to the range specified by \f2[result, result + (last - first))\fP. copy can be used to copy values from one container to another, or to copy values from one location in a container to another location in the same container, as long as \f2result\fP is not within the range \f2[first-last)\fP. copy returns \f2result + (last - first)\fP. For each non-negative integer \f2n < (last - first)\fP, copy assigns \f2*(first + n)\fP to \f2*(result + n)\fP. The result of copy is undefined if \f2result\fP is in the range \f2[first, last)\fP.

Unless \f2result\fP is an insert iterator, copy assumes that at least as many elements follow \f2result\fP as are in the range \f2[first, last)\fP.

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

Unless \f2result\fP is an insert iterator, copy_backward assumes that there are at least as many elements ahead of \f2result\fP as are in the range \f2[first, last)\fP.



.SH  COMPLEXITY


Both copy_and copy_backward perform exactly \f2last - first\fP assignments.



.SH  EXAMPLE



.RE
.RS 3
//
.br
// stdlib/examples/manual/copyex.cpp
.br
//
.RE
.RS 1
#include <algorithm>
.br
#include <vector>
.br
#include <iostream>
.RE
.RS 0
using namespace std;
.br

.br
int main()
.RE
.RS 1
{
.RE
.RS 2
int d1[4] = {1,2,3,4};
.br
int d2[4] = {5,6,7,8};
.RE
.RS 0

.RE
.RS 3
// Set up three vectors
.br
//
.RE
.RS 2
vector<int> v1(d1,d1 + 4), v2(d2,d2 + 4), v3(d2,d2 + 4);
.RE
.RS 3
//
.br
// Set up one empty vector
.br
//
.RE
.RS 2
vector<int> v4;
.RE
.RS 3
//
.br
// Copy v1 to v2
.br
//
.RE
.RS 2
copy(v1.begin(),v1.end(),v2.begin());
.RE
.RS 3
//
.br
// Copy backwards v1 to v3
.br
//
.RE
.RS 2
copy_backward(v1.begin(),v1.end(),v3.end());
.RE
.RS 3
//
.br
// Use insert iterator to copy into empty vector
.br
//
.RE
.RS 2
copy(v1.begin(),v1.end(),back_inserter(v4));
.RE
.RS 3
//
.br
// Copy all four to cout
.br
//
.RE
.RS 2
ostream_iterator<int,char> out(cout," ");
.br
copy(v1.begin(),v1.end(),out);
.br
cout << endl;
.br
copy(v2.begin(),v2.end(),out);
.br
cout << endl;
.br
copy(v3.begin(),v3.end(),out);
.br
cout << endl;
.br
copy(v4.begin(),v4.end(),out);
.br
cout << endl;
.RE
.RS 3

.RE
.RS 2
return 0;
.RE
.RS 1
}

.br
.RE
.RS 0
Program Output



.RE
.RS 0

.br
1 2 3 4
.br
1 2 3 4
.br
1 2 3 4
.br
1 2 3 4



.SH  WARNINGS


If your compiler does not support default template parameters, then you always need to supply the \f2Allocator\fP template argument. For instance, you have to write:

\f2vector <int, allocator<int> >\fP

instead of:

\f2vector <int>\fP

If your compiler does not support namespaces, then you do not need the using declaration for \f2std\fP.