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

.SH NAME

\f2replace_copy_if\fP

\ - Substitutes elements in a collection with new values, and moves the revised sequence into \f2result\fP.



.SH  SYNOPSIS


.RE
.RS 0
#include <algorithm>
.br
template <class InputIterator,
.RE
.RS 9
class OutputIterator,
.br
class Predicate,
.br
class T>
.RE
.RS 0
OutputIterator replace_copy_if (InputIterator first,
.RE
.RS 31
InputIterator last,
.br
OutputIterator result,
.br
Predicate pred,
.br
const T& new_value);



.SH  DESCRIPTION


The replace_copy_if algorithm leaves the original sequence intact and places a revised sequence into \f2result\fP. For the range \f2[first,last)\fP, the algorithm compares each element \f2*i\fP with the conditions specified by \f2pred\fP.   If \f2pred(*i)==false\fP, replace_copy_if copies \f2*i\fP to \f2result+(first-i)\fP. If \f2pred(*i)==true\fP, then replace_copy copies \f2new_value\fP to \f2result+(first-i)\fP. replace_copy_if_returns \f2result+(last-first)\fP.



.SH  COMPLEXITY


Exactly \f2last - first\fP applications of the predicate are performed.



.SH  EXAMPLE



.RE
.RS 0
//
.br
// replace.cpp
.br
//
.RE
.RS 1
#include <algorithm>
.br
#include <vector>
.br
#include <iterator>
.br
#include <iostream>
.RE
.RS 0
using namespace std;
.br

.br
template<class Arg>
.br
struct all_true : public unary_function<Arg, bool>
.RE
.RS 1
{
.RE
.RS 2
bool operator() (const Arg&) { return 1; }
.RE
.RS 1
};
.RE
.RS 0

.br
int main ()
.RE
.RS 1
{
.RE
.RS 3
//
.br
// Initialize a vector with an array of integers.
.br
//
.RE
.RS 2
int arr[10] = { 1,2,3,4,5,6,7,8,9,10 };
.br
vector<int> v(arr+0, arr+10);
.RE
.RS 3
//
.br
// Print out original vector.
.br
//
.RE
.RS 2
cout << "The original list: " << endl << "     ";
.br
copy(v.begin(), v.end(),
.RE
.RS 7
ostream_iterator<int,char>(cout," "));
.RE
.RS 2
cout << endl << endl;
.RE
.RS 3
//
.br
// Replace the number 7 with 11.
.br
//
.RE
.RS 2
replace(v.begin(), v.end(), 7, 11);
.RE
.RS 3
//
.br
// Print out vector with 7 replaced. 
.br
//
.RE
.RS 2
cout << "List after replace:" << endl << "     ";
.br
copy(v.begin(), v.end(),
.RE
.RS 7
ostream_iterator<int,char>(cout," "));
.RE
.RS 2
cout << endl << endl;
.RE
.RS 3
//
.br
// Replace 1 2 3 with 13 13 13.
.br
//
.RE
.RS 2
replace_if(v.begin(), v.begin()+3, all_true<int>(), 13);
.RE
.RS 3
//
.br
// Print out the remaining vector.
.br
//
.RE
.RS 2
cout << "List after replace_if:" << endl << "     ";
.br
copy(v.begin(), v.end(),
.RE
.RS 7
ostream_iterator<int,char>(cout," "));
.RE
.RS 2
cout << endl << endl;
.RE
.RS 3
//
.br
// Replace those 13s with 17s on output.
.br
//
.RE
.RS 2
cout << "List using replace_copy to cout:" << endl 
.RE
.RS 8
<< "     ";
.RE
.RS 2
replace_copy(v.begin(), v.end(),
.RE
.RS 15
ostream_iterator<int,char>(cout, " "),
.br
13, 17);
.RE
.RS 2
cout << endl << endl;
.RE
.RS 3
//
.br
// A simple example of replace_copy_if.
.br
//
.RE
.RS 2
cout << "List w/ all elements output as 19s:" << endl 
.RE
.RS 7
<< "   ";
.RE
.RS 3
replace_copy_if(v.begin(), v.end(), <br>                   ostream_iterator<int,char>(cout, " "),
.RE
.RS 18
all_true<int>(), 19);
.RE
.RS 2
cout << endl;
.RE
.RS 0

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

.br
.RE
.RS 0
Program Output



.RE
.RS 0

.br
The original list:
.RE
.RS 4
1 2 3 4 5 6 7 8 9 10
.RE
.RS 0
List after replace:
.RE
.RS 4
1 2 3 4 5 6 11 8 9 10
.RE
.RS 0
List after replace_if:
.RE
.RS 4
13 13 13 4 5 6 11 8 9 10
.RE
.RS 0
List using replace_copy to cout:
.RE
.RS 4
17 17 17 4 5 6 11 8 9 10
.RE
.RS 0
List with all elements output as 19s:
.RE
.RS 4
19 19 19 19 19 19 19 19 19 19



.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 need 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.



.SH  SEE ALSO


replace, replace_if, replace_copy