function template
<algorithm>

std::transform

unary operation(1)
template <class InputIterator, class OutputIterator, class UnaryOperation>
  OutputIterator transform (InputIterator first1, InputIterator last1,
                            OutputIterator result, UnaryOperation op);
binary operation(2)
template <class InputIterator1, class InputIterator2,
          class OutputIterator, class BinaryOperation>
  OutputIterator transform (InputIterator1 first1, InputIterator1 last1,
                            InputIterator2 first2, OutputIterator result,
                            BinaryOperation binary_op);
Transform range
Applies an operation sequentially to the elements of one (1) or two (2) ranges and stores the result in the range that begins at result.

(1) unary operation
Applies op to each of the elements in the range [first1,last1) and stores the value returned by each operation in the range that begins at result.
(2) binary operation
Calls binary_op using each of the elements in the range [first1,last1) as first argument, and the respective argument in the range that begins at first2 as second argument. The value returned by each call is stored in the range that begins at result.

The behavior of this function template is equivalent to:
1
2
3
4
5
6
7
8
9
10
 
template <class InputIterator, class OutputIterator, class UnaryOperator>
  OutputIterator transform (InputIterator first1, InputIterator last1,
                            OutputIterator result, UnaryOperator op)
{
  while (first1 != last1) {
    *result = op(*first1);  // or: *result=binary_op(*first1,*first2++);
    ++result; ++first1;
  }
  return result;
}


The function allows for the destination range to be the same as one of the input ranges to make transformations in place.

Parameters

first1, last1
Input iterators to the initial and final positions of the first sequence. The range used is [first1,last1), which contains all the elements between first1 and last1, including the element pointed by first1 but not the element pointed by last1.
first2
Input iterator to the initial position of the second range. The range includes as many elements as [first1,last1).
result
Output iterator to the initial position of the range where the operation results are stored. The range includes as many elements as [first1,last1).
op
Unary function that accepts one element of the type pointed by InputIterator as argument, and returns some result value convertible to the type pointed by OutputIterator.
This can either be a function pointer or a function object.
binary_op
Binary function that accepts two elements as argument (one of each of the two sequences), and returns some result value convertible to the type pointed by OutputIterator.
This can either be a function pointer or a function object.

Neither op nor binary_op should directly modify the elements passed as its arguments: These are indirectly modified by the algorithm (using the return value) if the same range is specified for result.

Return value

An iterator pointing to the element that follows the last element written in the result sequence.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
 
// transform algorithm example
#include <iostream>     // std::cout
#include <algorithm>    // std::transform
#include <vector>       // std::vector
#include <functional>   // std::plus

int op_increase (int i) { return ++i; }

int main () {
  std::vector<int> foo;
  std::vector<int> bar;

  // set some values:
  for (int i=1; i<6; i++)
    foo.push_back (i*10);                         // foo: 10 20 30 40 50

  bar.resize(foo.size());                         // allocate space

  std::transform (foo.begin(), foo.end(), bar.begin(), op_increase);
                                                  // bar: 11 21 31 41 51

  // std::plus adds together its two arguments:
  std::transform (foo.begin(), foo.end(), bar.begin(), foo.begin(), std::plus<int>());
                                                  // foo: 21 41 61 81 101

  std::cout << "foo contains:";
  for (std::vector<int>::iterator it=foo.begin(); it!=foo.end(); ++it)
    std::cout << ' ' << *it;
  std::cout << '\n';

  return 0;
}


Output:
foo contains: 21 41 61 81 101

Complexity

Linear in the distance between first1 and last1: Performs one assignment and one application of op (or binary_op) per element.

Data races

The objects in the range [first1,last1) (and eventually those in the range beginning at first2) are accessed (each object is accessed exactly once).
The objects in the range beginning at result are modified.

Exceptions

Throws if any of the function calls, the assignments or the operations on iterators throws.
Note that invalid arguments cause undefined behavior.

See also

for_each
Apply function to range (function template )
copy
Copy range of elements (function template )

C++