std::transform

Defined in header `<algorithm>`
template< class InputIt, class OutputIt, class UnaryOperation > OutputIt transform( InputIt first1, InputIt last1, OutputIt d_first, UnaryOperation unary_op );	(1)
template< class InputIt1, class InputIt2, class OutputIt, class BinaryOperation > OutputIt transform( InputIt1 first1, InputIt1 last1, InputIt2 first2, OutputIt d_first, BinaryOperation binary_op );	(2)

Defined in header <algorithm>

template< class InputIt, class OutputIt, class UnaryOperation >
OutputIt transform( InputIt first1, InputIt last1, OutputIt d_first,
                    UnaryOperation unary_op );

(1)

template< class InputIt1, class InputIt2, class OutputIt, class BinaryOperation >
OutputIt transform( InputIt1 first1, InputIt1 last1, InputIt2 first2, 
                    OutputIt d_first, BinaryOperation binary_op );

(2)

std::transform applies the given function to a range and stores the result in another range, beginning at d_first.

In the first version unary operation unary_op is applied to the range defined by [first1, last1). In the second version the binary operation binary_op is applied to pairs of elements from two ranges: one defined by [first1, last1) and the other beginning at first2.

`unary_op` and `binary_op` must not have side effects.	(until C++11)
`unary_op` and `binary_op` must not invalidate any iterators, including the end iterators, or modify any elements of the ranges involved.	(since C++11)

Parameters

first1, last1	-	the first range of elements to transform
first2	-	the beginning of the second range of elements to transform
d_first	-	the beginning of the destination range, may be equal to `first1` or `first2`
unary_op	-	unary operation function object that will be applied. The signature of the function should be equivalent to the following: `Ret fun(const Type &a);` The signature does not need to have `const &`. The type `Type` must be such that an object of type `InputIt` can be dereferenced and then implicitly converted to `Type`. The type `Ret` must be such that an object of type `OutputIt` can be dereferenced and assigned a value of type `Ret`.
binary_op	-	binary operation function object that will be applied. The signature of the function should be equivalent to the following: `Ret fun(const Type1 &a, const Type2 &b);` The signature does not need to have `const &`. The types `Type1` and `Type2` must be such that objects of types `InputIt1` and `InputIt2` can be dereferenced and then implicitly converted to `Type1` and `Type2` respectively. The type `Ret` must be such that an object of type `OutputIt` can be dereferenced and assigned a value of type `Ret`.
Type requirements
- `InputIt` must meet the requirements of `InputIterator`.
- `InputIt1` must meet the requirements of `InputIterator`.
- `InputIt2` must meet the requirements of `InputIterator`.
- `OutputIt` must meet the requirements of `OutputIterator`.

Return value

Output iterator to the element past the last element transformed.

Complexity

1) Exactly std::distance(first1, last1) applications of unary_op

2) Exactly std::distance(first1, last1) applications of binary_op

Possible implementation

First version
template<class InputIt, class OutputIt, class UnaryOperation> OutputIt transform(InputIt first1, InputIt last1, OutputIt d_first, UnaryOperation unary_op) { while (first1 != last1) { d_first++ = unary_op(first1++); } return d_first; }
Second version
template<class InputIt1, class InputIt2, class OutputIt, class BinaryOperation> OutputIt transform(InputIt1 first1, InputIt1 last1, InputIt2 first2, OutputIt d_first, BinaryOperation binary_op) { while (first1 != last1) { d_first++ = binary_op(first1++, *first2++); } return d_first; }

First version

template<class InputIt, class OutputIt, class UnaryOperation>
OutputIt transform(InputIt first1, InputIt last1, OutputIt d_first, 
                   UnaryOperation unary_op)
{
    while (first1 != last1) {
        *d_first++ = unary_op(*first1++);
    }
    return d_first;
}

Second version

template<class InputIt1, class InputIt2, 
         class OutputIt, class BinaryOperation>
OutputIt transform(InputIt1 first1, InputIt1 last1, InputIt2 first2, 
                   OutputIt d_first, BinaryOperation binary_op)
{
    while (first1 != last1) {
        *d_first++ = binary_op(*first1++, *first2++);
    }
    return d_first;
}

Notes

std::transform does not guarantee in-order application of unary_op or binary_op. To apply a function to a sequence in-order or to apply a function that modifies the elements of a sequence, use std::for_each.

Example

The following code uses transform to convert a string to uppercase using the toupper function:

#include <string>
#include <ctype.h>
#include <algorithm>
#include <functional>
#include <iostream>
 
int main()
{
    std::string s("hello");
    std::transform(s.begin(), s.end(), s.begin(), ::toupper);
    std::cout << s;
}

Output:

HELLO

for_each	applies a function to a range of elements (function template)
std::experimental::parallel::transform (parallelism TS)	parallelized version of `std::transform` (function template)