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

### See also

The function object overview, `copy`, `generate`, `fill`

Copyright © 1999 Silicon Graphics, Inc. All Rights Reserved. TrademarkInformation