zip_iterator#

template<class ..._Iterators> class zip_iterator : public __zv_iter_category_base<_Iterators...>#

zip_iterator is an iterator which represents a tuple of 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 <cuda/iterator>
#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'};

cuda::zip_iterator iter{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')

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

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

This example shows how to use zip_iterator to copy multiple ranges with a single call to thrust::copy.

#include <cuda/iterator>
#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(cuda::zip_iterator{int_in.begin(), float_in.begin()},
               cuda::zip_iterator{int_in.end(),   float_in.end()},
               cuda::zip_iterator{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;
}

Public Types

using iterator_concept = decltype(__get_zip_view_iterator_tag<_Iterators...>())#

using value_type = __tuple_or_pair<::cuda::std::iter_value_t<_Iterators>...>#

using reference = __tuple_or_pair<::cuda::std::iter_reference_t<_Iterators>...>#

using difference_type = ::cuda::std::common_type_t<::cuda::std::iter_difference_t<_Iterators>...>#

Public Functions

zip_iterator() = default#: Default-constructs a zip_iterator by defaulting all stored iterators.

inline explicit constexpr zip_iterator( __tuple_or_pair<_Iterators...> __iters, )#

Constructs a zip_iterator from a tuple of iterators.

Parameters:: __iters – A tuple or pair of iterators

template<size_t _NumIterators = sizeof...(_Iterators), ::cuda::std::enable_if_t<(_NumIterators == 2), int> = 0> inline explicit constexpr zip_iterator( ::cuda::std::tuple<_Iterators...> __iters, )#

Constructs a zip_iterator from a tuple of iterators.

Parameters:: __iters – A tuple of iterators

inline explicit constexpr zip_iterator(_Iterators... __iters)#

Constructs a zip_iterator from variadic set of iterators.

Parameters:: __iters – The input iterators

template<class ..._OtherIters, ::cuda::std::enable_if_t<(sizeof...(_OtherIters) == sizeof...(_Iterators)) && __all_convertible<_OtherIters...>, int> = 0> inline constexpr zip_iterator( zip_iterator<_OtherIters...> __iter, )#

Converts a different zip_iterator.

Parameters:: __iter – The other zip_iterator

inline constexpr auto operator*( ) const noexcept(noexcept(::cuda::std::apply(__zip_op_star, __current_)))#

Dereferences the zip_iterator.

Returns:: A tuple of references obtained by referencing every stored iterator

template<class _Constraints = __zip_iter_constraints<_Iterators...>, ::cuda::std::enable_if_t<_Constraints::__all_random_access, int> = 0> inline constexpr auto operator[]( difference_type __n, ) const#

Subscripts the zip_iterator with an offset.

Parameters:: __n – The additional offset
Returns:: A tuple of references obtained by subscripting every stored iterator

inline constexpr zip_iterator &operator++( ) noexcept(noexcept(::cuda::std::apply(__zip_op_increment, __current_)))#: Increments all stored iterators.

inline constexpr auto operator++(int)#

Increments all stored iterators.

Returns:: A copy of the original zip_iterator if possible

template<class _Constraints = __zip_iter_constraints<_Iterators...>, ::cuda::std::enable_if_t<_Constraints::__all_bidirectional, int> = 0> inline constexpr zip_iterator &operator--( ) noexcept(noexcept(::cuda::std::apply(__zip_op_decrement, __current_)))#: Decrements all stored iterators.

template<class _Constraints = __zip_iter_constraints<_Iterators...>, ::cuda::std::enable_if_t<_Constraints::__all_bidirectional, int> = 0> inline constexpr zip_iterator operator--( int, )#: Decrements all stored iterators.

template<class _Constraints = __zip_iter_constraints<_Iterators...>, ::cuda::std::enable_if_t<_Constraints::__all_random_access, int> = 0> inline constexpr zip_iterator &operator+=( difference_type __n, )#

Increments all stored iterators by a given number of elements.

Parameters:: __n – The number of elements to increment

template<class _Constraints = __zip_iter_constraints<_Iterators...>, ::cuda::std::enable_if_t<_Constraints::__all_random_access, int> = 0> inline constexpr zip_iterator &operator-=( difference_type __n, )#

Decrements all stored iterators by a given number of elements.

Parameters:: __n – The number of elements to decrement

Friends

template<class _Constraints = __zip_iter_constraints<_Iterators...>> inline friend constexpr auto operator+( const zip_iterator &__iter, difference_type __n, ) -> zip_iterator # requires (_Constraints::__all_random_access)

Returns a copy of a zip_iterator incremented by a given number of elements.

Parameters:

__iter – The zip_iterator to increment
__n – The number of elements to increment

template<class _Constraints = __zip_iter_constraints<_Iterators...>> inline friend constexpr auto operator+( difference_type __n, const zip_iterator &__iter, ) -> zip_iterator # requires (_Constraints::__all_random_access)

Returns a copy of a zip_iterator incremented by a given number of elements.

Parameters:

__n – The number of elements to increment
__iter – The zip_iterator to increment

template<class _Constraints = __zip_iter_constraints<_Iterators...>> inline friend constexpr auto operator-( const zip_iterator &__iter, difference_type __n, ) -> zip_iterator # requires (_Constraints::__all_random_access)

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

Parameters:

__n – The number of elements to decrement
__iter – The zip_iterator to decrement

template<class _Constraints = __zip_iter_constraints<_Iterators...>> inline friend constexpr auto operator-( const zip_iterator &__n, const zip_iterator &__y, ) -> difference_type # requires (_Constraints::__all_sized_sentinel)

Returns the distance between two zip_iterators.

Returns:: The minimal distance between any of the stored iterators

template<class _Constraints = __zip_iter_constraints<_Iterators...>> inline friend constexpr auto operator==( const zip_iterator &__n, const zip_iterator &__y, ) -> bool# requires (_Constraints::__all_equality_comparable): Compares two zip_iterator for equality by comparing the tuple of stored iterators.

template<class _Constraints = __zip_iter_constraints<_Iterators...>> inline friend constexpr auto operator<( const zip_iterator &__n, const zip_iterator &__y, ) -> bool# requires (_Constraints::__all_random_access): Compares two zip_iterator for less than by comparing the tuple of stored iterators.

template<class _Constraints = __zip_iter_constraints<_Iterators...>> inline friend constexpr auto operator>( const zip_iterator &__n, const zip_iterator &__y, ) -> bool# requires (_Constraints::__all_random_access): Compares two zip_iterator for greater than by comparing the tuple of stored iterators.

template<class _Constraints = __zip_iter_constraints<_Iterators...>> inline friend constexpr auto operator<=( const zip_iterator &__n, const zip_iterator &__y, ) -> bool# requires (_Constraints::__all_random_access): Compares two zip_iterator for less equal by comparing the tuple of stored iterators.

template<class _Constraints = __zip_iter_constraints<_Iterators...>> inline friend constexpr auto operator>=( const zip_iterator &__n, const zip_iterator &__y, ) -> bool# requires (_Constraints::__all_random_access): Compares two zip_iterator for greater equal by comparing the tuple of stored iterators.

template<class _Constraints = __zip_iter_constraints<_Iterators...>> inline friend constexpr auto iter_move( const zip_iterator &__iter, ) noexcept(_Constraints::__all_nothrow_iter_movable)#: Applies iter_move by applying it to all stored iterators.

template<class _Constraints = __zip_iter_constraints<_Iterators...>> inline friend constexpr auto iter_swap( const zip_iterator &__lhs, const zip_iterator &__rhs, ) noexcept(_Constraints::__all_noexcept_swappable) -> void# requires (_Constraints::__all_indirectly_swappable): Applies iter_swap to two zip_iterator by applying it to all stored iterators.