Class thrust::transform_iterator

transform_iterator is an iterator which represents a pointer into a range of values after transformation by a function. 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 device_vector.

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

// note: functor inherits from unary_function
struct square_root : public thrust::unary_function<float,float>
{
  __host__ __device__
  float operator()(float x) const
  {
    return sqrtf(x);
  }
};

int main()
{
  thrust::device_vector<float> v(4);
  v[0] = 1.0f;
  v[1] = 4.0f;
  v[2] = 9.0f;
  v[3] = 16.0f;

  typedef thrust::device_vector<float>::iterator FloatIterator;

  thrust::transform_iterator<square_root, FloatIterator> 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 function to compute the sum of squares of a sequence. We will create temporary transform_iterators with the make_transform_iterator function in order to avoid explicitly specifying their type:

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

// note: functor inherits from unary_function
struct square : public thrust::unary_function<float,float>
{
  __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;
  v[3] = 4.0f;

  float sum_of_squares =
   thrust::reduce(thrust::make_transform_iterator(v.begin(), square()),
                  thrust::make_transform_iterator(v.end(),   square()));

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

Note that in the previous two examples the transform functor (namely square_root and square) inherits from thrust::unary_function. Inheriting from thrust::unary_function ensures that a functor is a valid AdaptableUnaryFunction and provides all the necessary typedef declarations. The transform_iterator can also be applied to a UnaryFunction that does not inherit from thrust::unary_function using an optional template argument. The following example illustrates how to use the third template argument to specify the result_type of the function.

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

// note: functor *does not* inherit from unary_function
struct square_root
{
  __host__ __device__
  float operator()(float x) const
  {
    return sqrtf(x);
  }
};

int main()
{
  thrust::device_vector<float> v(4);
  v[0] = 1.0f;
  v[1] = 4.0f;
  v[2] = 9.0f;
  v[3] = 16.0f;

  typedef thrust::device_vector<float>::iterator FloatIterator;

  // note: float result_type is specified explicitly
  thrust::transform_iterator<square_root, FloatIterator, float> 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
}

Inherits From: detail::transform_iterator_base::type

See: make_transform_iterator

#include <thrust/iterator/transform_iterator.h>
template <class AdaptableUnaryFunction,   class Iterator,   class Reference = use_default,   class Value = use_default> class thrust::transform_iterator { public:  transform_iterator() = default;
  transform_iterator(transform_iterator const &) = default;
  _CCCL_HOST_DEVICE   transform_iterator(Iterator const & x,     AdaptableUnaryFunction f);
  explicit _CCCL_HOST_DEVICE   transform_iterator(Iterator const & x);
  template <typename OtherAdaptableUnaryFunction,       typename OtherIterator,       typename OtherReference,       typename OtherValue>   _CCCL_HOST_DEVICE   transform_iterator(const transform_iterator< OtherAdaptableUnaryFunction, OtherIterator, OtherReference, OtherValue > & other,     typename thrust::detail::enable_if_convertible< OtherIterator, Iterator >::type * = 0,     typename thrust::detail::enable_if_convertible< OtherAdaptableUnaryFunction, AdaptableUnaryFunction >::type * = 0);
  _CCCL_HOST_DEVICE transform_iterator &   operator=(const transform_iterator & other);
  _CCCL_HOST_DEVICE AdaptableUnaryFunction   functor() const; };

Member Functions

Function thrust::transform_iterator::transform_iterator

transform_iterator() = default; Null constructor does nothing.

Function thrust::transform_iterator::transform_iterator

transform_iterator(transform_iterator const &) = default;

Function thrust::transform_iterator::transform_iterator

_CCCL_HOST_DEVICE transform_iterator(Iterator const & x,   AdaptableUnaryFunction f); This constructor takes as arguments an Iterator and an AdaptableUnaryFunction and copies them to a new transform_iterator.

Function Parameters:

• x An Iterator pointing to the input to this transform_iterator'sAdaptableUnaryFunction.
• f An AdaptableUnaryFunction used to transform the objects pointed to by x.

Function thrust::transform_iterator::transform_iterator

explicit _CCCL_HOST_DEVICE transform_iterator(Iterator const & x); This explicit constructor copies the value of a given Iterator and creates this transform_iterator'sAdaptableUnaryFunction using its null constructor.

Function Parameters: x: An Iterator to copy.

Function thrust::transform_iterator::transform_iterator

template <typename OtherAdaptableUnaryFunction,   typename OtherIterator,   typename OtherReference,   typename OtherValue> _CCCL_HOST_DEVICE transform_iterator(const transform_iterator< OtherAdaptableUnaryFunction, OtherIterator, OtherReference, OtherValue > & other,   typename thrust::detail::enable_if_convertible< OtherIterator, Iterator >::type * = 0,   typename thrust::detail::enable_if_convertible< OtherAdaptableUnaryFunction, AdaptableUnaryFunction >::type * = 0); This copy constructor creates a new transform_iterator from another transform_iterator.

Function Parameters: other: The transform_iterator to copy.

Function thrust::transform_iterator::operator=

_CCCL_HOST_DEVICE transform_iterator & operator=(const transform_iterator & other); Copy assignment operator copies from another transform_iterator. other The other transform_iterator to copy In any case, this transform_iterator's underlying iterator will be copy assigned.

Note: If the type of this transform_iterator's functor is not copy assignable (for example, if it is a lambda) it is not an error to call this function. In this case, however, the functor will not be modified.

Returns: *this

Function thrust::transform_iterator::functor

_CCCL_HOST_DEVICE AdaptableUnaryFunction functor() const; This method returns a copy of this transform_iterator'sAdaptableUnaryFunction.

Returns: A copy of this transform_iterator'sAdaptableUnaryFunction.