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 backward-compatibility 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.