std::ranges::transform() algorithm
- od C++20
- Simplified
- Detailed
// (1)
constexpr unary_transform_result<I, O>
transform( I first1, S last1, O result, F op, Proj proj = {} );
// (2)
constexpr unary_transform_result<ranges::borrowed_iterator_t<R>, O>
transform( R&& r, O result, F op, Proj proj = {} );
// (3)
constexpr binary_transform_result<I1, I2, O>
transform(
I1 first1, S1 last1,
I2 first2, S2 last2,
O result,
F binary_op,
Proj1 proj1 = {}, Proj2 proj2 = {}
);
// (4)
constexpr binary_transform_result<ranges::borrowed_iterator_t<R1>,
ranges::borrowed_iterator_t<R2>, O>
transform(
R1&& r1, R2&& r2,
O result,
F binary_op,
Proj1 proj1 = {}, Proj2 proj2 = {}
);
The type of arguments are generic and have the following constraints:
I
,I1
,I2
-std::input_iterator
S
,S1
,S2
-std::sentinel_for<I>
,std::sentinel_for<I1>
,std::sentinel_for<I2>
R
,R1
,R2
-std::ranges::input_range
O
-std::weakly_incrementable
F
-std::copy_constructible
The Proj
template argument has a default type of std::identity
for all overloads.
Additionally, each overload has the following constraints:
- (1) -
indirectly_writable<O, indirect_result_t<F&, projected<I, Proj>> >
- (2) -
indirectly_writable<O, indirect_result_t<F&, projected<ranges::iterator_t<R>, Proj>>
- (3) -
indirect_result_t<F&, projected<I1, Proj1>, projected<I2, Proj2>>>
- (4) -
indirectly_writable<O, indirect_result_t<F&, projected<ranges::iterator_t<R1>, Proj1>, projected<ranges::iterator_t<R2>, Proj2>>>
(The std::
namespace was ommitted here for readability)
// (1)
template<
std::input_iterator I,
std::sentinel_for<I> S,
std::weakly_incrementable O,
std::copy_constructible F,
class Proj = std::identity
>
requires std::indirectly_writable<O, std::indirect_result_t<F&, std::projected<I, Proj>>>
constexpr unary_transform_result<I, O>
transform( I first1, S last1, O result, F op, Proj proj = {} );
// (2)
template<
ranges::input_range R,
std::weakly_incrementable O,
std::copy_constructible F,
class Proj = std::identity
>
requires std::indirectly_writable<O, std::indirect_result_t< F&, std::projected<ranges::iterator_t<R>, Proj>>
constexpr unary_transform_result<ranges::borrowed_iterator_t<R>, O>
transform( R&& r, O result, F op, Proj proj = {} );
// (3)
template<
std::input_iterator I1, std::sentinel_for<I1> S1,
std::input_iterator I2, std::sentinel_for<I2> S2,
std::weakly_incrementable O,
std::copy_constructible F,
class Proj1 = std::identity, class Proj2 = std::identity
>
requires std::indirectly_writable<O,
std::indirect_result_t<F&, std::projected<I1, Proj1>, std::projected<I2, Proj2>>>
constexpr binary_transform_result<I1, I2, O>
transform(
I1 first1, S1 last1,
I2 first2, S2 last2,
O result,
F binary_op,
Proj1 proj1 = {}, Proj2 proj2 = {}
);
// (4)
template<
ranges::input_range R1, ranges::input_range R2,
std::weakly_incrementable O,
std::copy_constructible F,
class Proj1 = std::identity, class Proj2 = std::identity >
requires std::indirectly_writable<O,
std::indirect_result_t<F&, std::projected<ranges::iterator_t<R1>, Proj1>, std::projected<ranges::iterator_t<R2>, Proj2>>>
constexpr binary_transform_result<ranges::borrowed_iterator_t<R1>,
ranges::borrowed_iterator_t<R2>, O>
transform(
R1&& r1, R2&& r2,
O result,
F binary_op,
Proj1 proj1 = {}, Proj2 proj2 = {}
);
With the helper types defined as follows:
template< class I, class O >
using unary_transform_result = ranges::in_out_result<I, O>;
template< class I1, class I2, class O >
using binary_transform_result = ranges::in_in_out_result<I1, I2, O>;
Applies the given function to a range and stores the result in another range, beginning at result
.
-
(1) The unary operation
op
is applied to the range defined by [ first1; last1 ) (after projecting with the projectionproj
). -
(2) Same as (1), but uses
r
as the source range, as if usingranges::begin(r)
asfirst
andranges::end(r)
aslast
. -
(3) The binary operation
binary_op
is applied to pairs of elements from two ranges:- One defined by [ first1; last1 ).
- The other defined by [ first2; last2 ) (after respectively projecting with the projections
proj1
andproj2
).
-
(4) Same as (3), but uses
r1
as the first source range, as if usingranges::begin(r1)
asfirst1
andranges::end(r1)
aslast1
, and similarly forr2
.
The function-like entities described on this page are niebloids.
Parameters
first1 last1 | The first range of elements to transform (iterator, sentinel pair). |
r r1 | The first range of elements to transform (ranges). |
first2 last2 | The second range of elements to transform (iterator, sentinel pair). |
r2 | The second range of elements to transform (range). |
result | The beginning of the destination range, may be equal to |
op binary_op | Operation to apply to the projected element(s). |
proj1 | Projection to apply to the elements in the first range. |
proj2 | Projection to apply to the elements in the second range. |
Return value
- (1 - 2) Returns a
unary_transform_result
which contains an input iterator equal tolast
and an output iterator to the element past the last element transformed. - (3 - 4) Returns a
binary_transform_result
contains input iterators to last transformed elements from ranges [ first1; last1 ) and [ first2; last2 ) asin1
andin2
respectively, and the output iterator to the element past the last element transformed as out.
Complexity
- (1 - 2) Exactly
ranges::distance(first1, last1)
applications ofop
andproj
. - (3 - 4) Exactly
ranges::min(ranges::distance(first1, last1), ranges::distance(first2, last2))
applications ofbinary_op
and projections.
Exceptions
(none)
Possible implementation
transform(1) and transform(2)
struct transform_fn
{
// First version
template<std::input_iterator I, std::sentinel_for<I> S, std::weakly_incrementable O,
std::copy_constructible F, class Proj = std::identity>
requires std::indirectly_writable<O, std::indirect_result_t<F&, std::projected<I, Proj>>>
constexpr ranges::unary_transform_result<I, O>
operator()(I first1, S last1, O result, F op, Proj proj = {}) const
{
for (; first1 != last1; ++first1, (void)++result)
*result = std::invoke(op, std::invoke(proj, *first1));
return {first1, result};
}
// Second version
template<ranges::input_range R, std::weakly_incrementable O,
std::copy_constructible F, class Proj = std::identity>
requires std::indirectly_writable<O,
std::indirect_result_t<F&, std::projected<ranges::iterator_t<R>, Proj>>>
constexpr ranges::unary_transform_result<ranges::borrowed_iterator_t<R>, O>
operator()(R&& r, O result, F op, Proj proj = {}) const
{
return (*this)(ranges::begin(r), ranges::end(r), result, std::ref(op), std::ref(proj));
}
// Third version
template<std::input_iterator I1, std::sentinel_for<I1> S1,
std::input_iterator I2, std::sentinel_for<I2> S2,
std::weakly_incrementable O,
std::copy_constructible F,
class Proj1 = std::identity, class Proj2 = std::identity>
requires std::indirectly_writable<O,
std::indirect_result_t<F&,
std::projected<I1, Proj1>,
std::projected<I2, Proj2>>>
constexpr ranges::binary_transform_result<I1, I2, O>
operator()(I1 first1, S1 last1, I2 first2, S2 last2, O result,
F binary_op, Proj1 proj1 = {}, Proj2 proj2 = {}) const
{
for (; first1 != last1 && first2 != last2; ++first1, (void)++first2, (void)++result)
*result = std::invoke(binary_op,
std::invoke(proj1, *first1),
std::invoke(proj2, *first2));
return {first1, first2, result};
}
// Fourth version
template<ranges::input_range R1, ranges::input_range R2,
std::weakly_incrementable O, std::copy_constructible F,
class Proj1 = std::identity, class Proj2 = std::identity>
requires std::indirectly_writable<O,
std::indirect_result_t<F&,
std::projected<ranges::iterator_t<R1>, Proj1>,
std::projected<ranges::iterator_t<R2>, Proj2>>>
constexpr ranges::binary_transform_result<ranges::borrowed_iterator_t<R1>,
ranges::borrowed_iterator_t<R2>, O>
operator()(R1&& r1, R2&& r2, O result,
F binary_op, Proj1 proj1 = {}, Proj2 proj2 = {}) const
{
return (*this)(ranges::begin(r1), ranges::end(r1),
ranges::begin(r2), ranges::end(r2),
result, std::ref(binary_op),
std::ref(proj1), std::ref(proj2));
}
};
inline constexpr transform_fn transform;
Notes
ranges::transform
does not guarantee in-order application of 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 ranges::for_each
.
Examples
The following code uses ranges::transform
to convert a string in place to uppercase using the std::toupper
function and then transforms each char to its ordinal value.
Then ranges::transform
with a projection is used to transform elements of std::vector<Foo>
into chars to fill a std::string
.
#include <algorithm>
#include <cctype>
#include <functional>
#include <iostream>
#include <string>
#include <vector>
int main()
{
std::string s {"hello"};
namespace ranges = std::ranges;
ranges::transform(s.begin(), s.end(), s.begin(),
[](unsigned char c) -> unsigned char { return std::toupper(c); });
std::vector<std::size_t> ordinals;
ranges::transform(s, std::back_inserter(ordinals),
[](unsigned char c) -> std::size_t { return c; });
std::cout << s << ':';
for (auto ord : ordinals)
std::cout << ' ' << ord;
ranges::transform(ordinals, ordinals, ordinals.begin(), std::plus {});
std::cout << '\n';
for (auto ord : ordinals)
std::cout << ord << ' ';
std::cout << '\n';
struct Foo
{
char bar;
};
const std::vector<Foo> f = { {'h'},{'e'},{'l'},{'l'},{'o'} };
std::string bar;
ranges::transform(f, std::back_inserter(bar), &Foo::bar);
std::cout << bar << '\n';
}
HELLO: 72 69 76 76 79
144 138 152 152 158
hello
Hover to see the original license.