std::transform
| Defined in header <algorithm>
|
||
template< class InputIt, class OutputIt, class UnaryOp >
OutputIt transform( InputIt first1, InputIt last1,
OutputIt d_first, UnaryOp unary_op );
|
(1) | (constexpr since C++20) |
template< class InputIt1, class InputIt2,
class OutputIt, class BinaryOp >
OutputIt transform( InputIt1 first1, InputIt1 last1, InputIt2 first2,
OutputIt d_first, BinaryOp binary_op );
|
(2) | (constexpr since C++20) |
template< class ExecutionPolicy,
class ForwardIt1, class ForwardIt2, class UnaryOp >
ForwardIt2 transform( ExecutionPolicy&& policy,
ForwardIt1 first1, ForwardIt1 last1,
ForwardIt2 d_first, UnaryOp unary_op );
|
(3) | (since C++17) |
template< class ExecutionPolicy,
class ForwardIt1, class ForwardIt2,
class ForwardIt3, class BinaryOp >
ForwardIt3 transform( ExecutionPolicy&& policy,
ForwardIt1 first1, ForwardIt1 last1,
ForwardIt2 first2,
ForwardIt3 d_first, BinaryOp binary_op );
|
(4) | (since C++17) |
Given count as std::distance(first1, last1). Applies the given function to the elements of the given source range(s), and stores the result in the destination range [d_first, std::next(d_first, count)).
[first1, last1), and the unary operation unary_op is applied to each of its elements.unary_op invalidates an iterator or modifies an element in any of the following ranges, the behavior is undefined:
[first1,last1][d_first,std::next(d_first, count)]
[first1, last1) and [first2, std::next(first2, count)), and the binary operation binary_op is applied to each pair of their corresponding elements.binary_op invalidates an iterator or modifies an element in any of the following ranges, the behavior is undefined:
[first1,last1][first2,std::next(first2, count)][d_first,std::next(d_first, count)]
policy.true:
|
|
(until C++20) |
|
|
(since C++20) |
Parameters
| first1, last1 | - | the pair of iterators defining the first source range |
| first2 | - | the beginning of the second source range |
| d_first | - | the beginning of the destination range |
| unary_op | - | unary operation function object that will be applied. The signature of the function should be equivalent to the following:
The signature does not need to have |
| binary_op | - | binary operation function object that will be applied. The signature of the function should be equivalent to the following:
The signature does not need to have |
| policy | - | the execution policy to use |
| Type requirements | ||
-InputIt, InputIt1, InputIt2 must meet the requirements of LegacyInputIterator.
| ||
-OutputIt must meet the requirements of LegacyOutputIterator.
| ||
-ForwardIt1, ForwardIt2, ForwardIt3 must meet the requirements of LegacyForwardIterator.
| ||
Return value
The past-the-end iterator of the destination range.
Complexity
Given N as std::distance(first1, last1):
unary_op.binary_op.Exceptions
- If the temporary memory resources required for parallelization are not available, std::bad_alloc is thrown.
- If an uncaught exception is thrown while accessing objects via an algorithm argument, the behavior is determined by the execution policy (for standard policies, std::terminate is invoked).
Possible implementation
| transform (1) |
|---|
template<class InputIt, class OutputIt, class UnaryOp>
constexpr //< since C++20
OutputIt transform(InputIt first1, InputIt last1,
OutputIt d_first, UnaryOp unary_op)
{
for (; first1 != last1; ++d_first, ++first1)
*d_first = unary_op(*first1);
return d_first;
}
|
| transform (2) |
template<class InputIt1, class InputIt2,
class OutputIt, class BinaryOp>
constexpr //< since C++20
OutputIt transform(InputIt1 first1, InputIt1 last1, InputIt2 first2,
OutputIt d_first, BinaryOp binary_op)
{
for (; first1 != last1; ++d_first, ++first1, ++first2)
*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
#include <algorithm>
#include <cctype>
#include <iomanip>
#include <iostream>
#include <string>
#include <utility>
#include <vector>
void print_ordinals(const std::vector<unsigned>& ordinals)
{
std::cout << "ordinals: ";
for (unsigned ord : ordinals)
std::cout << std::setw(3) << ord << ' ';
std::cout << '\n';
}
char to_uppercase(unsigned char c)
{
return std::toupper(c);
}
void to_uppercase_inplace(char& c)
{
c = to_uppercase(c);
}
// Transform string to uppercase in-place
void unary_transform_example(std::string& hello, std::string world)
{
std::transform(hello.cbegin(), hello.cend(), hello.begin(), to_uppercase);
std::cout << "hello = " << std::quoted(hello) << '\n';
// for_each version (see Notes above)
std::for_each(world.begin(), world.end(), to_uppercase_inplace);
std::cout << "world = " << std::quoted(world) << '\n';
}
// Transform numbers to doubled values
void binary_transform_example(std::vector<unsigned> ordinals)
{
print_ordinals(ordinals);
std::transform(ordinals.cbegin(), ordinals.cend(), ordinals.cbegin(),
ordinals.begin(), std::plus<>{});
print_ordinals(ordinals);
}
int main()
{
std::string hello("hello");
unary_transform_example(hello, "world");
std::vector<unsigned> ordinals;
std::copy(hello.cbegin(), hello.cend(), std::back_inserter(ordinals));
binary_transform_example(std::move(ordinals));
}
Output:
hello = "HELLO"
world = "WORLD"
ordinals: 72 69 76 76 79
ordinals: 144 138 152 152 158
Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
| DR | Applied to | Behavior as published | Correct behavior |
|---|---|---|---|
| LWG 242 | C++98 | unary_op and binary_op could not have side effects
|
they cannot modify the ranges involved |
See also
(C++20) |
applies a function to a range of elements (algorithm function object) |
| applies a unary function object to elements from a range (function template & algorithm function object) | |
(C++20) |