std::transform - cppreference.com (original) (raw)

std::transform applies the given function to the elements of the given input range(s), and stores the result in an output range starting from d_first.

1. The unary operation unary_op is applied to the elements of [first1, last1).

If unary_op invalidates an iterator or modifies an element in any of the following ranges, the behavior is undefined:

• [first1, last1].
• The range of std::distance(first1, last1) + 1 elements starting from d_first.

1. The binary operation binary_op is applied to pairs of elements from two ranges: [first1, last1) and another range of std::distance(first1, last1) elements starting from first2.

If binary_op invalidates an iterator or modifies an element in any of the following ranges, the behavior is undefined:

• [first1, last1].
• The range of std::distance(first1, last1) + 1 elements starting from first2.
• The range of std::distance(first1, last1) + 1 elements starting from d_first.

2,4) Same as (1,3), but executed according to policy.

These overloads participate in overload resolution only if all following conditions are satisfied:

Contents

• 1 Parameters
• 2 Return value
• 3 Complexity
• 4 Exceptions
• 5 Possible implementation
• 6 Notes
• 7 Example
• 8 Defect reports
• 9 See also

[edit] Parameters

[edit] Return value

Output iterator to the element that follows the last element transformed.

[edit] Complexity

Given \(\scriptsize N\)N as std::distance(first1, last1):

1,2) Exactly \(\scriptsize N\)N applications of unary_op.

3,4) Exactly \(\scriptsize N\)N applications of binary_op.

[edit] 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 other ExecutionPolicy, the behavior is implementation-defined.
• If the algorithm fails to allocate memory, std::bad_alloc is thrown.

[edit] Possible implementation

[edit] 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.

[edit] Example

#include #include #include #include #include #include #include   void print_ordinals(const std::vector& 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); }   void unary_transform_example(std::string& hello, std::string world) { // Transform string to uppercase in-place   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'; }   void binary_transform_example(std::vector ordinals) { // Transform numbers to doubled values   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 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

[edit] Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

[edit] See also