Class thrust::zip_iterator

zip_iterator is an iterator which represents a pointer into a range of tuples whose elements are themselves taken from a tuple of input iterators. This iterator is useful for creating a virtual array of structures while achieving the same performance and bandwidth as the structure of arrays idiom. zip_iterator also facilitates kernel fusion by providing a convenient means of amortizing the execution of the same operation over multiple ranges.

The following code snippet demonstrates how to create a zip_iterator which represents the result of “zipping” multiple ranges together.

#include <thrust/iterator/zip_iterator.h>
#include <thrust/tuple.h>
#include <thrust/device_vector.h>
...
thrust::device_vector<int> int_v{0, 1, 2};
thrust::device_vector<float> float_v{0.0f, 1.0f, 2.0f};
thrust::device_vector<char> char_v{'a', 'b', 'c'};

// aliases for iterators
using IntIterator = thrust::device_vector<int>::iterator;
using FloatIterator = thrust::device_vector<float>::iterator;
using CharIterator = thrust::device_vector<char>::iterator;

// alias for a tuple of these iterators
using IteratorTuple = thrust::tuple<IntIterator, FloatIterator, CharIterator>;

// typedef the zip_iterator of this tuple
using ZipIterator = thrust::zip_iterator<IteratorTuple>;

// finally, create the zip_iterator
ZipIterator iter(thrust::make_tuple(int_v.begin(), float_v.begin(), char_v.begin()));

*iter;   // returns (0, 0.0f, 'a')
iter[0]; // returns (0, 0.0f, 'a')
iter[1]; // returns (1, 1.0f, 'b')
iter[2]; // returns (2, 2.0f, 'c')

thrust::get<0>(iter[2]); // returns 2
thrust::get<1>(iter[0]); // returns 0.0f
thrust::get<2>(iter[1]); // returns 'b'

// iter[3] is an out-of-bounds error

Defining the type of a zip_iterator can be complex. The next code example demonstrates how to use the make_zip_iterator function with the make_tuple function to avoid explicitly specifying the type of the zip_iterator. This example shows how to use zip_iterator to copy multiple ranges with a single call to thrust::copy.

#include <thrust/zip_iterator.h>
#include <thrust/tuple.h>
#include <thrust/device_vector.h>

int main()
{
  thrust::device_vector<int> int_in{0, 1, 2}, int_out(3);
  thrust::device_vector<float> float_in{0.0f, 10.0f, 20.0f}, float_out(3);

  thrust::copy(thrust::make_zip_iterator(thrust::make_tuple(int_in.begin(), float_in.begin())),
               thrust::make_zip_iterator(thrust::make_tuple(int_in.end(),   float_in.end())),
               thrust::make_zip_iterator(thrust::make_tuple(int_out.begin(),float_out.begin())));

  // int_out is now [0, 1, 2]
  // float_out is now [0.0f, 10.0f, 20.0f]

  return 0;
}

Inherits From: detail::zip_iterator_base::type

See:

• make_zip_iterator
• make_tuple
• tuple
• get

#include <thrust/iterator/zip_iterator.h>
template <typename IteratorTuple> class thrust::zip_iterator { public:  using iterator_tuple = see below;
  zip_iterator() = default;
  _CCCL_HOST_DEVICE   zip_iterator(IteratorTuple iterator_tuple);
  template <typename OtherIteratorTuple,       detail::enable_if_convertible_t< OtherIteratorTuple, IteratorTuple, int > = 0>   _CCCL_HOST_DEVICE   zip_iterator(const zip_iterator< OtherIteratorTuple > & other);
  _CCCL_HOST_DEVICE const IteratorTuple &   get_iterator_tuple() const; };

Member Types

Type Alias thrust::zip_iterator::iterator_tuple

using iterator_tuple = IteratorTuple; The underlying iterator tuple type. Alias to zip_iterator’s first template argument.

Member Functions

Function thrust::zip_iterator::zip_iterator

zip_iterator() = default; Default constructor does nothing.

Function thrust::zip_iterator::zip_iterator

_CCCL_HOST_DEVICE zip_iterator(IteratorTuple iterator_tuple); This constructor creates a new zip_iterator from a tuple of iterators.

Function Parameters: iterator_tuple: The tuple of iterators to copy from.

Function thrust::zip_iterator::zip_iterator

template <typename OtherIteratorTuple,   detail::enable_if_convertible_t< OtherIteratorTuple, IteratorTuple, int > = 0> _CCCL_HOST_DEVICE zip_iterator(const zip_iterator< OtherIteratorTuple > & other); This copy constructor creates a new zip_iterator from another zip_iterator.

Function Parameters: other: The zip_iterator to copy.

Function thrust::zip_iterator::get_iterator_tuple

_CCCL_HOST_DEVICE const IteratorTuple & get_iterator_tuple() const; This method returns a const reference to this zip_iterator'stuple of iterators.

Returns: A const reference to this zip_iterator'stuple of iterators.