transform_iterator#

template<class _Iter, class _Fn>
class transform_iterator : public __transform_iterator_category_base<_Iter, _Fn>#

transform_iterator is an iterator which represents a pointer into a range of values after transformation by a functor.

This iterator is useful for creating a range filled with the result of applying an operation to another range without either explicitly storing it in memory, or explicitly executing the transformation. Using transform_iterator facilitates kernel fusion by deferring the execution of a transformation until the value is needed while saving both memory capacity and bandwidth.

The following code snippet demonstrates how to create a transform_iterator which represents the result of sqrtf applied to the contents of a thrust::device_vector.

#include <cuda/iterator>
#include <thrust/device_vector.h>

struct square_root
{
  __host__ __device__
  float operator()(float x) const
  {
    return sqrtf(x);
  }
};

int main()
{
  thrust::device_vector<float> v{1.0f, 4.0f, 9.0f, 16.0f};

  using FloatIterator = thrust::device_vector<float>::iterator;

  cuda::transform_iterator iter(v.begin(), square_root{});

  *iter;   // returns 1.0f
  iter[0]; // returns 1.0f;
  iter[1]; // returns 2.0f;
  iter[2]; // returns 3.0f;
  iter[3]; // returns 4.0f;

  // iter[4] is an out-of-bounds error
}

This next example demonstrates how to use a transform_iterator with the thrust::reduce functor to compute the sum of squares of a sequence. We will create temporary transform_iterators utilising class template argument deduction avoid explicitly specifying their type:

#include <cuda/iterator>
#include <thrust/device_vector.h>
#include <thrust/reduce.h>
#include <iostream>

struct square
{
  __host__ __device__
  float operator()(float x) const
  {
    return x * x;
  }
};

int main()
{
  // initialize a device array
  thrust::device_vector<float> v(4);
  v[0] = 1.0f;
  v[1] = 2.0f;
  v[2] = 3.0f;
  thrust::device_vector<float> v{1.0f, 2.0f, 3.0f, 4.0f};
  thrust::reduce(cuda::transform_iterator{v.begin(), square{}},
                 cuda::transform_iterator{v.end(),   square{}});

  std::cout << "sum of squares: " << sum_of_squares << std::endl;
  return 0;
}

Public Types

using iterator_concept = ::cuda::std::conditional_t<::cuda::std::random_access_iterator<_Iter>, ::cuda::std::random_access_iterator_tag, ::cuda::std::conditional_t<::cuda::std::bidirectional_iterator<_Iter>, ::cuda::std::bidirectional_iterator_tag, ::cuda::std::conditional_t<::cuda::std::forward_iterator<_Iter>, ::cuda::std::forward_iterator_tag, ::cuda::std::input_iterator_tag>>>#
using value_type = ::cuda::std::remove_cvref_t<::cuda::std::invoke_result_t<_Fn&, ::cuda::std::iter_reference_t<_Iter>>>#
using difference_type = ::cuda::std::iter_difference_t<_Iter>#

Public Functions

template<class _Iter2 = _Iter, class _Fn2 = _Fn>
inline constexpr transform_iterator(
) noexcept(::cuda::std::is_nothrow_default_constructible_v<_Iter2> && ::cuda::std::is_nothrow_default_constructible_v<_Fn2>)#

Default constructs a transform_iterator with a value initialized iterator and functor.

inline constexpr transform_iterator(
_Iter __iter,
_Fn __func,
) noexcept(::cuda::std::is_nothrow_move_constructible_v<_Iter> && ::cuda::std::is_nothrow_move_constructible_v<_Fn>)#

Constructs a transform_iterator with a given iterator and functor.

Parameters:

  • __iter – The iterator to transform

  • __func – The functor to apply to the iterator

inline constexpr const _Iter &base() const & noexcept#

Returns a const reference to the stored iterator.

inline constexpr _Iter base(
) && noexcept(::cuda::std::is_nothrow_move_constructible_v<_Iter>)#

Extracts the stored iterator.

template<class _Iter2 = _Iter, ::cuda::std::enable_if_t< ::cuda::std::regular_invocable< const _Fn &, int >=0 > ::cuda::std::iter_reference_t< const _Iter2 >> inline constexpr decltype(auto) operator* () const noexcept(noexcept(::cuda::std::invoke(*__func_, *__current_)))

Dereferences the stored iterator and applies the stored functor to the result.

inline constexpr decltype(auto) operator*(
) noexcept(noexcept(::cuda::std::invoke(*__func_, *__current_)))#

Dereferences the stored iterator and applies the stored functor to the result.

template<class _Iter2 = _Iter, ::cuda::std::enable_if_t< ::cuda::std::random_access_iterator< _Iter2 > &&::cuda::std::regular_invocable< const _Fn &, int >=0 > ::cuda::std::iter_reference_t< const _Iter2 >> inline constexpr decltype(auto) operator[] (difference_type __n) const noexcept(__transform_iterator_nothrow_subscript< const _Fn, _Iter2 >)

Subscripts the stored iterator by a number of elements and applies the stored functor to the result.

Parameters:

__n – The number of elements to advance by

template<class _Iter2 = _Iter, ::cuda::std::enable_if_t<::cuda::std::random_access_iterator<_Iter2>, int> = 0>
inline constexpr decltype(auto) operator[](
difference_type __n,
) noexcept(__transform_iterator_nothrow_subscript<_Fn, _Iter2>)#

Subscripts the stored iterator by a number of elements and applies the stored functor to the result.

Parameters:

__n – The number of elements to advance by

inline constexpr transform_iterator &operator++(
) noexcept(noexcept(++__current_))#

Increments the stored iterator.

inline constexpr auto operator++(
int,
) noexcept(noexcept(++__current_))#

Increments the stored iterator.

template<class _Iter2 = _Iter, ::cuda::std::enable_if_t<::cuda::std::bidirectional_iterator<_Iter2>, int> = 0>
inline constexpr transform_iterator &operator--(
) noexcept(noexcept(--__current_))#

Decrements the stored iterator.

template<class _Iter2 = _Iter, ::cuda::std::enable_if_t<::cuda::std::bidirectional_iterator<_Iter2>, int> = 0>
inline constexpr transform_iterator operator--(
int,
) noexcept(::cuda::std::is_nothrow_copy_constructible_v<_Iter> && noexcept(--__current_))#

Decrements the stored iterator.

template<class _Iter2 = _Iter, ::cuda::std::enable_if_t<::cuda::std::random_access_iterator<_Iter2>, int> = 0>
inline constexpr transform_iterator &operator+=(
difference_type __n,
) noexcept(noexcept(__current_ += __n))#

Increments the transform_iterator by a given number of elements.

Parameters:

__n – The number of elements to increment

template<class _Iter2 = _Iter, ::cuda::std::enable_if_t<::cuda::std::random_access_iterator<_Iter2>, int> = 0>
inline constexpr transform_iterator &operator-=(
difference_type __n,
) noexcept(noexcept(__current_ -= __n))#

Decrements the transform_iterator by a given number of elements.

Parameters:

__n – The number of elements to decrement

Friends

template<class _Iter2 = _Iter>
inline friend constexpr auto operator+(
const transform_iterator &__iter,
difference_type __n,
) -> transform_iterator#
requires (::cuda::std::random_access_iterator<_Iter2>)

Returns a copy of a transform_iterator advanced by a given number of elements.

Parameters:

  • __iter – The transform_iterator to advance

  • __n – The amount of elements to increment

template<class _Iter2 = _Iter>
inline friend constexpr auto operator+(
difference_type __n,
const transform_iterator &__iter,
) -> transform_iterator#
requires (::cuda::std::random_access_iterator<_Iter2>)

Returns a copy of a transform_iterator advanced by a given number of elements.

Parameters:

  • __n – The amount of elements to increment

  • __iter – The transform_iterator to advance

template<class _Iter2 = _Iter>
inline friend constexpr auto operator-(
const transform_iterator &__iter,
difference_type __n,
) -> transform_iterator#
requires (::cuda::std::random_access_iterator<_Iter2>)

Returns a copy of a transform_iterator decremented by a given number of elements.

Parameters:

  • __iter – The transform_iterator to decrement

  • __n – The amount of elements to decrement

template<class _Iter2 = _Iter>
inline friend constexpr auto operator-(
const transform_iterator &__lhs,
const transform_iterator &__rhs,
) -> difference_type#
requires (::cuda::std::sized_sentinel_for<_Iter2, _Iter2>)

Returns the distance between two transform_iterator.

template<class _Iter2 = _Iter>
inline friend constexpr auto operator==(
const transform_iterator &__lhs,
const transform_iterator &__rhs,
) noexcept(noexcept(::cuda::std::declval<const _Iter2&>() == ::cuda::std::declval<const _Iter2&>())) -> bool#
requires (::cuda::std::equality_comparable<_Iter2>)

Compares two transform_iterator for equality by comparing the stored iterators.

template<class _Iter2 = _Iter>
inline friend constexpr auto operator<(
const transform_iterator &__lhs,
const transform_iterator &__rhs,
) noexcept(noexcept(::cuda::std::declval<const _Iter2&>() < ::cuda::std::declval<const _Iter2&>())) -> bool#
requires (::cuda::std::random_access_iterator<_Iter2>)

Compares two transform_iterator for less than by comparing the stored iterators.

template<class _Iter2 = _Iter>
inline friend constexpr auto operator>(
const transform_iterator &__lhs,
const transform_iterator &__rhs,
) noexcept(noexcept(::cuda::std::declval<const _Iter2&>() < ::cuda::std::declval<const _Iter2&>())) -> bool#
requires (::cuda::std::random_access_iterator<_Iter2>)

Compares two transform_iterator for greater than by comparing the stored iterators.

template<class _Iter2 = _Iter>
inline friend constexpr auto operator<=(
const transform_iterator &__lhs,
const transform_iterator &__rhs,
) noexcept(noexcept(::cuda::std::declval<const _Iter2&>() < ::cuda::std::declval<const _Iter2&>())) -> bool#
requires (::cuda::std::random_access_iterator<_Iter2>)

Compares two transform_iterator for less equal by comparing the stored iterators.

template<class _Iter2 = _Iter>
inline friend constexpr auto operator>=(
const transform_iterator &__lhs,
const transform_iterator &__rhs,
) noexcept(noexcept(::cuda::std::declval<const _Iter2&>() < ::cuda::std::declval<const _Iter2&>())) -> bool#
requires (::cuda::std::random_access_iterator<_Iter2>)

Compares two transform_iterator for greater equal by comparing the stored iterators.

template<class _Iter, class _Fn>
inline constexpr auto make_transform_iterator(
_Iter __iter,
_Fn __fun,
)#

Creates a transform_iterator from a base iterator and a functor.

Parameters:

  • __iter – The iterator of the input range

  • __fun – The functor used to transform the input range