| Constrained algorithms and algorithms on ranges(C++20) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Constrained algorithms, e.g.ranges::copy,ranges::sort, ... | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Execution policies(C++17) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Numeric operations | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Operations on uninitialized memory | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Defined in header <algorithm> | ||
template<class InputIt,class OutputIt,class UnaryOp> OutputIt transform( InputIt first1, InputIt last1, | (1) | (constexpr since C++20) |
template<class ExecutionPolicy, class ForwardIt1,class ForwardIt2,class UnaryOp> | (2) | (since C++17) |
template<class InputIt1,class InputIt2, class OutputIt,class BinaryOp> | (3) | (constexpr since C++20) |
template<class ExecutionPolicy, class ForwardIt1,class ForwardIt2, | (4) | (since C++17) |
std::transform applies the given function to the elements of the given input range(s), and stores the result in an output range starting fromd_first.
[first1, last1).[first1, last1].[first1, last1) and another range ofstd::distance(first1, last1) elements starting fromfirst2.[first1, last1].std::is_execution_policy_v<std::decay_t<ExecutionPolicy>> istrue. | (until C++20) |
std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>> istrue. | (since C++20) |
Contents |
| first1, last1 | - | the pair of iterators defining the sourcerange of elements to transform |
| first2 | - | the beginning of the second range of elements to transform,(3,4) only |
| d_first | - | the beginning of the destination range, may be equal tofirst1 orfirst2 |
| policy | - | theexecution policy to use |
| unary_op | - | unary operation function object that will be applied. The signature of the function should be equivalent to the following: Ret fun(const Type&a); The signature does not need to haveconst&. |
| binary_op | - | binary operation function object that will be applied. The signature of the function should be equivalent to the following: Ret fun(const Type1&a,const Type2&b); The signature does not need to haveconst&. |
| Type requirements | ||
-InputIt, InputIt1, InputIt2 must meet the requirements ofLegacyInputIterator. | ||
-OutputIt must meet the requirements ofLegacyOutputIterator. | ||
-ForwardIt1, ForwardIt2, ForwardIt3 must meet the requirements ofLegacyForwardIterator. | ||
Output iterator to the element that follows the last element transformed.
Given\(\scriptsize N\)N asstd::distance(first1, last1):
The overloads with a template parameter namedExecutionPolicy report errors as follows:
ExecutionPolicy is one of thestandard policies,std::terminate is called. For any otherExecutionPolicy, the behavior is implementation-defined.| transform (1) |
|---|
template<class InputIt,class OutputIt,class UnaryOp>constexpr//< since C++20OutputIt transform(InputIt first1, InputIt last1, OutputIt d_first, UnaryOp unary_op){for(; first1!= last1;++d_first,++first1)*d_first= unary_op(*first1); return d_first;} |
| transform (3) |
template<class InputIt1,class InputIt2,class OutputIt,class BinaryOp>constexpr//< since C++20OutputIt transform(InputIt1 first1, InputIt1 last1, InputIt2 first2, OutputIt d_first, BinaryOp binary_op){for(; first1!= last1;++d_first,++first1,++first2)*d_first= binary_op(*first1,*first2); return d_first;} |
std::transform does not guarantee in-order application ofunary_op orbinary_op. To apply a function to a sequence in-order or to apply a function that modifies the elements of a sequence, usestd::for_each.
#include <algorithm>#include <cctype>#include <iomanip>#include <iostream>#include <string>#include <utility>#include <vector> void print_ordinals(conststd::vector<unsigned>& ordinals){std::cout<<"ordinals: ";for(unsigned ord: ordinals)std::cout<<std::setw(3)<< ord<<' ';std::cout<<'\n';} char to_uppercase(unsignedchar c){returnstd::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<unsigned> 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<unsigned> 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
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 andbinary_op could not have side effects | they cannot modify the ranges involved |
| applies a unaryfunction object to elements from arange (function template)[edit] | |
(C++20) | applies a function to a range of elements (algorithm function object)[edit] |
