Apache C++ Standard Library Reference Guide

## transform()

Library: Algorithms

    Function

- Local Index
- Summary
- Synopsis
- Description
- Complexity
- Example
- Standards Conformance

### Local Index

No Entries

### Summary

Algorithm that applies an operation to a range of values in a collection and stores the result

### Synopsis

    #include <algorithm>

    namespace std {
      template <class InputIterator, class OutputIterator,
                class UnaryOperation>
      OutputIterator
      transform(InputIterator start, InputIterator finish,
                OutputIterator result, UnaryOperation op);

      template <class InputIterator1, class InputIterator2,
                class OutputIterator, class BinaryOperation>
      OutputIterator
      transform(InputIterator1 start1, InputIterator1 finish1,
                InputIterator2 start2, OutputIterator result,
                BinaryOperation binary_op);
    }

### Description

The `transform()` algorithm has two forms. The first form applies unary operation `op` to each element of the range `[start, finish)`, and assigns the result to the element pointed to by the output iterator `result`. For example, this version of `transform()` could be used to square each element in a vector. If the output iterator (`result`) is the same as the input iterator used to traverse the range, `transform()` performs its transformation in place.

The second form of `transform()` applies a binary operation, `binary_op`, to corresponding elements in the range `[start1, finish1)` and the range that begins at `start2`, and assigns the result to the element pointed to by `result`. For example, `transform()` can be used to add corresponding elements in two sequences, and store the set of sums in a third. The algorithm assumes, but does not check, that the second sequence has at least as many elements as the first sequence. Note that the output iterator `result` can be a third sequence, or either of the two input sequences.

Formally, `transform()` assigns through every iterator `i` in the range `[result, result + (finish1 - start1))` a new corresponding value equal to:

`op(*(start1 + (i - result))`

or:

`binary_op(*(start1 + (i - result), *(start2 + (i - result)))`

`transform()` returns `result + (finish1 - start1)`. `op` and `binary_op` must not have any side effects. `result` may be equal to `start` in case of unary transform, or to `start1` or `start2` in case of binary transform.

### Complexity

Exactly `finish1 - start1` applications of `op` or `binary_op` are performed.

### Example

    //
    //  trnsform.cpp
    //

    #include <algorithm>    // for transform
    #include <functional>   // for multiplies
    #include <deque>        // for deque
    #include <iostream>     // for cout, endl
    #include <iomanip>      // for setw

    int main ()
    {
        typedef std::deque<int, std::allocator<int> > Deque;

        // Initialize a deque with an array of integers.
        const Deque::value_type a [] = { 99, 264, 126, 330, 132 };
        const Deque::value_type b [] = { 280, 105, 220, 84, 210 };

        Deque d1 (a, a + sizeof a / sizeof *a);
        Deque d2 (b, b + sizeof b / sizeof *b);

        // Print the original values.
        std::cout << "The following pairs of numbers: \n     ";
        Deque::iterator i1;
        for (i1 = d1.begin(); i1 != d1.end(); ++i1)
            std::cout << std::setw (6) << *i1 << " ";

        std::cout << "\n     ";
        for (i1 = d2.begin(); i1 != d2.end(); ++i1)
            std::cout << std::setw (6) << *i1 << " ";

        // transform the numbers in one sequence to
        // their factorials and store the results in
        // another sequence
        std::transform (d1.begin (), d1.end (),
                        d2.begin (), d1.begin (),
                        std::multiplies<int>());

        // Display the results.
        std::cout << "\n\nHave the products: \n     ";
        for (i1 = d1.begin (); i1 != d1.end (); ++i1)
            std::cout << std::setw (6) << *i1 << " ";

        std::cout << std::endl;

        return 0;
    }

    Program Output:

    The following pairs of numbers:
             99    264    126    330    132
            280    105    220     84    210

    Have the products:
          27720  27720  27720  27720  27720

### Standards Conformance

ISO/IEC 14882:1998 -- International Standard for Information Systems -- Programming Language C++, Section 25.2.3