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
ExecutionPolicy
is one of the standard policies,std::terminate
is called. For any otherExecutionPolicy
, the behavior is implementation-defined. - If the algorithm fails to allocate memory,
std::bad_alloc
is 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