transform


Category: algorithms 
Component type: function 
Prototype
Transform is an overloaded name; there are actually two transform
functions.
template <class InputIterator, class OutputIterator, class UnaryFunction>
OutputIterator transform(InputIterator first, InputIterator last,
OutputIterator result, UnaryFunction op);
template <class InputIterator1, class InputIterator2, class OutputIterator,
class BinaryFunction>
OutputIterator transform(InputIterator1 first1, InputIterator1 last1,
InputIterator2 first2, OutputIterator result,
BinaryFunction binary_op);
Description
Transform performs an operation on objects; there are two versions
of transform, one of which uses a single range of Input Iterators
and one of which uses two ranges of Input Iterators.
The first version of transform performs the operation op(*i)
for each iterator i in the range [first, last), and assigns
the result of that operation to *o, where o is the corresponding
output iterator. That is, for each n such that 0 <= n < last  first,
it performs the assignment *(result + n) = op(*(first + n)).
The return value is result + (last  first).
The second version of transform is very similar, except that it
uses a Binary Function instead of a Unary Function:
it performs the operation op(*i1, *i2) for each iterator i1 in the
range [first1, last1) and assigns the result to *o, where
i2 is the corresponding iterator in the second input range and
where o is the corresponding output iterator. That is,
for each n such that 0 <= n < last1  first1,
it performs the assignment *(result + n) = op(*(first1 + n), *(first2
+ n). The return value is result + (last1  first1).
Note that transform may be used to modify a sequence "in place":
it is permissible for the iterators first and result to be the same. [1]
Definition
Defined in the standard header algorithm, and in the nonstandard
backwardcompatibility header algo.h.
Requirements on types
For the first (unary) version:

InputIterator must be a model of Input Iterator.

OutputIterator must be a model of Output Iterator.

UnaryFunction must be a model of Unary Function.

InputIterator's value type must be
convertible to UnaryFunction's argument type.

UnaryFunction's result type must be convertible to a type in
OutputIterator's set of value types.
For the second (binary) version:

InputIterator1 and InputIterator2
must be models of Input Iterator.

OutputIterator must be a model of Output Iterator.

BinaryFunction must be a model of Binary Function.

InputIterator1's and InputIterator2's value types must
be convertible, respectively, to BinaryFunction's first and second
argument types.

UnaryFunction's result type must be convertible
to a type in OutputIterator's set of value types.
Preconditions
For the first (unary) version:

[first, last) is a valid range.

result is not an iterator within the range [first+1, last). [1]

There is enough space to hold all of the elements being copied.
More formally, the requirement is that
[result, result + (last  first)) is a valid range.
For the second (binary) version:

[first1, last1) is a valid range.

[first2, first2 + (last1  first1)) is a valid range.

result is not an iterator within the range [first1+1, last1)
or [first2 + 1, first2 + (last1  first1)).

There is enough space to hold all of the elements being copied.
More formally, the requirement is that
[result, result + (last1  first1)) is a valid range.
Complexity
Linear. The operation is applied exactly last  first times
in the case of the unary version, or last1  first1 in the case
of the binary version.
Example
Replace every number in an array with its negative.
const int N = 1000;
double A[N];
iota(A, A+N, 1);
transform(A, A+N, A, negate<double>());
Calculate the sum of two vectors, storing the result in a third vector.
const int N = 1000;
vector<int> V1(N);
vector<int> V2(N);
vector<int> V3(N);
iota(V1.begin(), V1.end(), 1);
fill(V2.begin(), V2.end(), 75);
assert(V2.size() >= V1.size() && V3.size() >= V1.size());
transform(V1.begin(), V1.end(), V2.begin(), V3.begin(),
plus<int>());
Notes
[1]
The Output Iterator result is not permitted to be the same as
any of the Input Iterators in the range [first, last), with the
exception of first itself. That is:
transform(V.begin(), V.end(), V.begin(), fabs) is valid, but
transform(V.begin(), V.end(), V.begin() + 1, fabs) is not.
See also
The function object overview, copy, generate,
fill
Copyright ©
1999 Silicon Graphics, Inc. All Rights Reserved.
TrademarkInformation
webmaster@www.sgi.com