C++ Reference ยท Algorithms
The std::transform algorithm
Reference for C++ std::transform: map a range to an output with a unary or binary operation, transform in place, back_inserter output and the ranges version.
std::transform applies a function to each element of a range and writes the results to an output range. It is the C++ "map". There are two forms: a unary form that reads one input range, and a binary form that reads two ranges in step and combines their elements.
The output iterator may point at the input itself (transform in place), at another container with enough room, or at a std::back_inserter that grows a container as results arrive. Writing past the end of a too-small output is undefined behavior.
std::transform(in.begin(), in.end(), std::back_inserter(out), [](int x) { return x * x; });
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Syntax
// unary template<class InIt, class OutIt, class UnaryOp> OutIt transform(InIt first, InIt last, OutIt d_first, UnaryOp op); // binary template<class InIt1, class InIt2, class OutIt, class BinaryOp> OutIt transform(InIt1 first1, InIt1 last1, InIt2 first2, OutIt d_first, BinaryOp op);
| Name | Description |
|---|---|
first, last |
The input range [first, last). |
first2 |
Start of the second input range (binary form); it must hold at least as many elements as the first. |
d_first |
Start of the output. May equal an input iterator, but must not point into the middle of an input range. |
op |
Called as op(*it) or op(*it1, *it2); its result is assigned to *out. It must not modify the elements or invalidate iterators. |
Returns: an iterator one past the last element written.
Errors / undefined behavior: an output range shorter than the input is undefined behavior (use back_inserter or size the container first). Overlap that is not an exact in-place match is also undefined.
Usage notes
- Applies
opexactly once per element, in order for the plain overloads. Parallel overloads (with an execution policy) give no ordering guarantee. - Size the output first:
std::vector<int> out(in.size())then passout.begin(), or usestd::back_inserter(out). Passingout.begin()of an empty vector is a common bug. - In place is allowed and common:
transform(v.begin(), v.end(), v.begin(), f). - Character functions:
std::toupperfrom<cctype>takes anintthat must be representable asunsigned char; cast the character, as in the example, to avoid undefined behavior for negativecharvalues. - Side effects: use
for_eachinstead when you do not produce a result;transformwith a discarded result is misleading. - Lazy alternative (C++20):
std::views::transformcomputes elements on demand and stores nothing.std::ranges::transformis the eager, constrained algorithm and accepts a projection-style interface for ranges. - Ranges to containers (C++23):
v | std::views::transform(f) | std::ranges::to<std::vector>()builds the result vector in one expression. - Complexity: exactly
last - firstapplications ofop.