On this page
std::transform
Defined in header <algorithm> |
||
|---|---|---|
| (1) | ||
|
(until C++20) | |
|
(since C++20) | |
|
(2) | (since C++17) |
| (3) | ||
|
(until C++20) | |
|
(since C++20) | |
|
(4) | (since C++17) |
std::transform applies the given function to a range and stores the result in another range, keeping the original elements order and beginning at d_first.
unary_op is applied to the range defined by [first1, last1).
binary_op is applied to pairs of elements from two ranges: one defined by [first1, last1) and the other beginning at first2.
policy. These overloads do not participate in overload resolution unless
|
(until C++20) |
|
(since C++20) |
unary_op and binary_op must not invalidate any iterators, including the end iterators, or modify any elements of the ranges involved.
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 |
| policy | - | the execution policy to use. See execution policy for details. |
| 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 |
| 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
Output iterator to the element that follows the last element transformed.
Complexity
Exceptions
The overloads with a template parameter named ExecutionPolicy report errors as follows:
- If execution of a function invoked as part of the algorithm throws an exception and
ExecutionPolicyis one of the standard policies,std::terminateis called. For any otherExecutionPolicy, the behavior is implementation-defined. - If the algorithm fails to allocate memory,
std::bad_allocis thrown.
Possible implementation
| transform (1) |
|---|
|
| transform (3) |
|
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 in place to uppercase using the std::toupper function and then transforms each char to its ordinal value:
#include <algorithm>
#include <cctype>
#include <iomanip>
#include <iostream>
#include <string>
#include <vector>
void print_ordinals(std::vector<std::size_t> const& ordinals)
{
std::cout << "ordinals: ";
for (std::size_t ord : ordinals)
std::cout << std::setw(3) << ord << ' ';
std::cout << '\n';
}
int main()
{
std::string s{"hello"};
std::transform(s.cbegin(), s.cend(),
s.begin(), // write to the same location
[](unsigned char c) { return std::toupper(c); });
std::cout << "s = " << std::quoted(s) << '\n';
// achieving the same with std::for_each (see Notes above)
std::string g{"hello"};
std::for_each(g.begin(), g.end(), [](char& c) // modify in-place
{
c = std::toupper(static_cast<unsigned char>(c));
});
std::cout << "g = " << std::quoted(g) << '\n';
std::vector<std::size_t> ordinals;
std::transform(s.cbegin(), s.cend(), std::back_inserter(ordinals),
[](unsigned char c) { return c; });
print_ordinals(ordinals);
std::transform(ordinals.cbegin(), ordinals.cend(), ordinals.cbegin(),
ordinals.begin(), std::plus<>{});
print_ordinals(ordinals);
}
Output:
s = "HELLO"
g = "HELLO"
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 cannot have side effects |
they cannot modify the ranges involved |
See also
| applies a function to a range of elements (function template) |
|
|
(C++20)
|
applies a function to a range of elements (niebloid) |
© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/cpp/algorithm/transform