std::transform in C++: apply a function to every element

std::transform applies a function to every element of a range and writes the results to another range: std::transform(v.begin(), v.end(), out.begin(), f), from the header <algorithm>. The output may be the input itself, which changes the elements in place. The output must already have room for every result, or grow through std::back_inserter.

Squaring the numbers of a std::vector into a second vector of the same size, as a whole program:

#include <algorithm>
#include <iostream>
#include <vector>

int main() {
    std::vector<int> v{1, 2, 3, 4, 5};
    std::vector<int> squares(v.size());

    std::transform(v.begin(), v.end(), squares.begin(),
                   [](int x) { return x * x; });

    std::cout << "squares:";
    for (int s : squares)
        std::cout << ' ' << s;
    std::cout << '\n';    // squares: 1 4 9 16 25
}

It printed:

squares: 1 4 9 16 25

The fourth argument is a lambda, a function written in place: std::transform calls it once for each element and writes what it returns to the same place in squares. The answer is written for C++17 (Since When’s C++17 table). The samples were built with MSVC 19.44, Clang 19.1 (MSVC STL), GCC 16.2 and Clang 23.1 (libc++), as C++20 or C++23 where a line says so, and all four printed the same.

Why does std::transform crash on an empty vector?

Because it never grows the output: it writes through its third argument, an iterator (a position in a container), as if there were room for one result per input element. Passing the begin() of an empty vector as the output, or of any vector shorter than the input, is undefined behavior: the standard promises nothing, and with the libraries’ debug checks turned on the program crashed on all four.

Three ways that work, with prices in cents (print writes a label and the values):

std::vector<int> prices{250, 1199, 75};
auto twice = [](int cents) { return cents * 2; };

std::vector<int> doubled(prices.size());    // three zeros
auto end = std::transform(prices.begin(), prices.end(),
                          doubled.begin(), twice);
print("sized", doubled);           // sized: 500 2398 150
std::cout << std::boolalpha
          << (end == doubled.end()) << '\n';    // true

std::vector<int> appended;                  // empty
std::transform(prices.begin(), prices.end(),
               std::back_inserter(appended), twice);
print("appended", appended);       // appended: 500 2398 150

std::transform(prices.begin(), prices.end(), prices.begin(), twice);
print("in place", prices);         // in place: 500 2398 150

All four printed 500 2398 150 three times, and true:

• Sized first: doubled(prices.size()) holds three zeros for std::transform to overwrite. The call returns an iterator to the element past the last one written, here doubled.end().
• Appended: std::back_inserter(appended), from <iterator>, appends each result, so the empty vector grows by one per element.
• In place: the input’s own begin() as the output replaces each price with its double. The standard allows the output to be the input.

How do you convert a string to uppercase with std::transform?

Transform the std::string in place, with a lambda that takes each character as unsigned char, passes it to std::toupper from <cctype> and casts the result back to char:

std::string t = "hello, world";
std::transform(t.begin(), t.end(), t.begin(), [](unsigned char c) {
    return static_cast<char>(std::toupper(c));
});
std::cout << t << '\n';    // HELLO, WORLD

It printed HELLO, WORLD on all four. The parameter is unsigned char because std::toupper has undefined behavior for a negative value other than EOF, and a char can hold one wherever it is signed, which the standard leaves to each implementation. The cast turns the int that std::toupper returns back into a char, so MSVC does not warn about it at /W4 (C4244). In the default “C” locale std::toupper changes only a to z, and it sees one byte at a time, so a UTF-8 letter such as é stays as it is.

Passing std::toupper by name, as in std::transform(s.begin(), s.end(), s.begin(), std::toupper), compiles with Microsoft’s standard library but not with GCC or with Clang on libc++, which could not work out which toupper was meant. Since C++20 the standard does not promise it compiles anywhere: taking the address of a library function such as std::toupper is unspecified. Wrap it in a lambda, as above.

How do you add two vectors with std::transform?

Use the second form: two input ranges, one output, and a function of two arguments that receives one element from each input. Here prices plus shipping make totals, once with the standard function object std::plus<>() and once with a lambda:

std::vector<int> prices{250, 1199, 75};
std::vector<int> shipping{499, 0, 150};
std::vector<int> totals(prices.size());

std::transform(prices.begin(), prices.end(), shipping.begin(),
               totals.begin(), std::plus<>());
print("plus", totals);      // plus: 749 1199 225

std::transform(prices.begin(), prices.end(), shipping.begin(),
               totals.begin(),
               [](int price, int ship) { return price + ship; });
print("lambda", totals);    // lambda: 749 1199 225

Both printed 749 1199 225. The second input gives only its start, so it must be at least as long as the first.

What is the difference between std::transform and std::for_each?

std::transform makes a new value from each element and writes it to an output; std::for_each calls a function on each element, from first to last, and has no output range. For an action that needs the order or changes the elements, use std::for_each, or a plain loop:

std::vector<int> prices{250, 1199, 75};
std::for_each(prices.begin(), prices.end(),
              [](int& cents) { cents *= 2; });
print("for_each", prices);     // for_each: 500 2398 150

std::vector<int> again{250, 1199, 75};
for (int& cents : again)
    cents *= 2;
print("range-for", again);     // range-for: 500 2398 150

Both printed 500 2398 150: the lambda takes int&, a reference to the element, and changes it there. The range-based for loop does the same with no algorithm, and is often the plainer choice.

What are std::ranges::transform and std::views::transform?

They are the C++20 versions. std::ranges::transform is the same algorithm taking the container itself, and std::views::transform writes nothing: it makes a lazy view, one that calls the function each time you read an element. With the same prices and twice:

std::vector<int> doubled(prices.size());
std::ranges::transform(prices, doubled.begin(), twice);  // C++20
print("algorithm", doubled);    // algorithm: 500 2398 150

std::cout << "view:";
for (int cents : prices | std::views::transform(twice))  // C++20
    std::cout << ' ' << cents;
std::cout << '\n';              // view: 500 2398 150

Both printed 500 2398 150. The view computes nothing until you iterate, as a lambda that counts its calls shows:

int calls = 0;
auto counted = [&calls](int cents) {
    ++calls;
    return cents * 2;
};
auto view = prices | std::views::transform(counted);  // C++20
std::cout << "calls before the loop: " << calls << '\n';  // 0
for (int cents : view)
    std::cout << cents << '\n';
std::cout << "calls after the loop: " << calls << '\n';   // 3

A second loop over the same view took the count to 6: the view keeps no results and calls the function on every read.

Two more differences. With two inputs, std::ranges::transform stops at the shorter one: three prices and two shipping costs gave two totals. It also returns a small struct, not a bare iterator: its out member points past the last element written. To collect a view into a vector, C++23 adds std::ranges::to: prices | std::views::transform(twice) | std::ranges::to<std::vector>().

Ranges shipped in GCC 10.1, Clang 16 with libc++ and Visual Studio 2019 16.10 (Since When’s C++20 table).

Which transform should you use?

Pick by what you want back (the other algorithms and containers are under Standard library):