permutation_iterator#

template<class _Iter, class _Index = _Iter> class permutation_iterator#

permutation_iterator is an iterator which represents a pointer into a reordered view of a given range.

permutation_iterator is an imprecise name; the reordered view need not be a strict permutation. This iterator is useful for fusing a scatter or gather operation with other algorithms.

This iterator takes two arguments:

an iterator to the range V on which the “permutation” will be applied, referred to as iter below
an iterator to a range of indices defining the reindexing scheme that determines how the elements of V will be permuted, referred to as index below

Note that permutation_iterator is not limited to strict permutations of the given range V. The distance between begin and end of the reindexing iterators is allowed to be smaller compared to the size of the range V, in which case the permutation_iterator only provides a “permutation” of a subset of V. The indices do not need to be unique. In this same context, it must be noted that the past-the-end permutation_iterator is completely defined by means of the past-the-end iterator to the indices.

The following code snippet demonstrates how to create a permutation_iterator which represents a reordering of the contents of a device_vector.

#include <cuda/iterator>
#include <thrust/device_vector.h>
...
thrust::device_vector<float> values{10.0f, 20.0f, 30.0f, 40.0f, 50.0f, 60.0f, 70.0f, 80.0f};
thrust::device_vector<int> indices{2, 6, 1, 3};

using ElementIterator = thrust::device_vector<float>::iterator;
using IndexIterator = thrust::device_vector<int>::iterator;

cuda::permutation_iterator<ElementIterator,IndexIterator> iter(values.begin(), indices.begin());

*iter;   // returns 30.0f;
iter[0]; // returns 30.0f;
iter[1]; // returns 70.0f;
iter[2]; // returns 20.0f;
iter[3]; // returns 40.0f;

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

*iter   = -1.0f; // sets values[2] to -1.0f;
iter[0] = -1.0f; // sets values[2] to -1.0f;
iter[1] = -1.0f; // sets values[6] to -1.0f;
iter[2] = -1.0f; // sets values[1] to -1.0f;
iter[3] = -1.0f; // sets values[3] to -1.0f;

// values is now {10, -1, -1, -1, 50, 60, -1, 80}

Public Types

using iterator_type = _Iter #

using iterator_concept = ::cuda::std::random_access_iterator_tag#

using iterator_category = ::cuda::std::random_access_iterator_tag#

using value_type = ::cuda::std::iter_value_t<_Iter>#

using difference_type = ::cuda::std::iter_difference_t<_Index>#

Public Functions

constexpr permutation_iterator() = default#

Ensure that the user passes an iterator to something interger_like.

Ensure that the index value_type is convertible to difference_type To actually use operator+ we need the index iterator to be random access To actually use operator+ we need the base iterator to be random access

Default constructs an permutation_iterator with a value initialized iterator and index

inline constexpr permutation_iterator( _Iter __iter, _Index __index, ) noexcept(::cuda::std::is_nothrow_copy_constructible_v<_Iter> && ::cuda::std::is_nothrow_copy_constructible_v<_Index>)#

Constructs an permutation_iterator from an iterator and an optional index.

Parameters:

__iter – The iterator to to index from
__index – The iterator with the permutations

inline constexpr const _Iter &base() const & noexcept#: Returns a const reference to the stored base iterator iter.

inline constexpr _Iter base( ) && noexcept(::cuda::std::is_nothrow_move_constructible_v<_Iter>)#: Extracts the stored base iterator iter.

inline constexpr difference_type index() const noexcept#

Returns the current index.

Returns:: Equivalent to *index

inline constexpr decltype(auto) operator*( ) noexcept(noexcept(__iter_[static_cast<__iter_difference_t>(*__index_)]))#

Dereferences the permutation_iterator.

Returns:: Equivalent to iter[*index]

template<class _Iter2 = _Iter, ::cuda::std::enable_if_t<::cuda::std::__dereferenceable<const _Iter2>, int> = 0> inline constexpr decltype(auto) operator*( ) const noexcept(noexcept(__iter_[static_cast<__iter_difference_t>(*__index_)]))#

Dereferences the permutation_iterator.

Returns:: Equivalent to iter[*index]

inline constexpr decltype(auto) operator[]( difference_type __n, ) noexcept(noexcept(__iter_[static_cast<__iter_difference_t>(__index_[__n])]))#

Subscripts the permutation_iterator by an offset.

Parameters:: __n – The additional offset
Returns:: Equivalent to iter[index[__n]]

template<class _Iter2 = _Iter, ::cuda::std::enable_if_t<::cuda::std::__dereferenceable<const _Iter2>, int> = 0> inline constexpr decltype(auto) operator[]( difference_type __n, ) const noexcept(noexcept(__iter_[static_cast<__iter_difference_t>(__index_[__n])]))#

Subscripts the permutation_iterator by an offset.

Parameters:: __n – The additional offset
Returns:: Equivalent to iter[index[__n]]

inline constexpr permutation_iterator &operator++( ) noexcept(noexcept(++__index_))#

Increments the permutation_iterator.

Returns:: Equivalent to ++index

inline constexpr permutation_iterator operator++( int, ) noexcept(noexcept(++__index_) && ::cuda::std::is_nothrow_copy_constructible_v<_Iter> && ::cuda::std::is_nothrow_copy_constructible_v<_Index>)#

Increments the permutation_iterator.

Returns:: Equivalent to index++

inline constexpr permutation_iterator &operator--( ) noexcept(noexcept(--__index_))#

Increments the permutation_iterator.

Returns:: Equivalent to --index

inline constexpr permutation_iterator operator--( int, ) noexcept(noexcept(--__index_) && ::cuda::std::is_nothrow_copy_constructible_v<_Iter> && ::cuda::std::is_nothrow_copy_constructible_v<_Index>)#

Increments the permutation_iterator.

Returns:: Equivalent to index++

inline constexpr permutation_iterator &operator+=( difference_type __n, ) noexcept(noexcept(__index_ += __n))#

Advances the permutation_iterator by a given number of elements.

Parameters:: __n – The number of elements to advance
Returns:: Equivalent to index + __n

inline constexpr permutation_iterator &operator-=( difference_type __n, ) noexcept(noexcept(__index_ -= __n))#

Decrements the permutation_iterator by a given number of elements.

Parameters:: __n – The number of elements to decrement
Returns:: Equivalent to index - __n

Friends

inline friend constexpr permutation_iterator operator+ (const permutation_iterator &__iter, difference_type __n) noexcept(//noexcept(__iter.__index_+__n) &&::cuda::std::is_nothrow_copy_constructible_v< _Iter > &&::cuda::std::is_nothrow_copy_constructible_v< _Index >)

Advances a permutation_iterator by a given number of elements.

Parameters:

__iter – The original permutation_iterator
__n – The number of elements to advance

Returns:

Equivalent to permutation_iterator{iter, index + __n}

inline friend constexpr permutation_iterator operator+( difference_type __n, const permutation_iterator &__iter, ) noexcept(noexcept(__iter.__index_ + __n) && ::cuda::std::is_nothrow_copy_constructible_v<_Iter> && ::cuda::std::is_nothrow_copy_constructible_v<_Index>)#

Advances a permutation_iterator by a given number of elements.

Parameters:

__n – The number of elements to advance
__iter – The original permutation_iterator

Returns:

Equivalent to permutation_iterator{iter, index + __n}

inline friend constexpr permutation_iterator operator- (const permutation_iterator &__iter, difference_type __n) noexcept(//noexcept(__iter.__index_ - __n) &&::cuda::std::is_nothrow_copy_constructible_v< _Iter > &&::cuda::std::is_nothrow_copy_constructible_v< _Index >)

Decrements a permutation_iterator by a given number of elements.

Parameters:

__iter – The original permutation_iterator
__n – The number of elements to decrement

Returns:

Equivalent to permutation_iterator{iter, index - __n}

inline friend constexpr difference_type operator-( const permutation_iterator &__lhs, const permutation_iterator &__rhs, ) noexcept(__nothrow_difference<_Index>)#

Returns the distance between two permutation_iterators.

Returns:: Equivalent to __lhs.index - __rhs.index

template<class _OtherIter, class _OtherOffset> inline friend constexpr bool operator==( const permutation_iterator &__lhs, const permutation_iterator<_OtherIter, _OtherOffset> &__rhs, ) noexcept(__nothrow_equality<_Index, _OtherOffset>)#

Compares two permutation_iterator for equality by comparing index.

Returns:: Equivalent to __lhs.index == __rhs.index

template<class _OtherIter, class _OtherOffset> inline friend constexpr bool operator<( const permutation_iterator &__lhs, const permutation_iterator<_OtherIter, _OtherOffset> &__rhs, ) noexcept(__nothrow_less_than<_Index, _OtherOffset>)#

Compares two permutation_iterator for less than by comparing index.

Returns:: Equivalent to __lhs.index < __rhs.index

template<class _OtherIter, class _OtherOffset> inline friend constexpr bool operator<=( const permutation_iterator &__lhs, const permutation_iterator<_OtherIter, _OtherOffset> &__rhs, ) noexcept(__nothrow_less_equal<_Index, _OtherOffset>)#

Compares two permutation_iterator for less equal by comparing index.

Returns:: Equivalent to __lhs.index <= __rhs.index

template<class _OtherIter, class _OtherOffset> inline friend constexpr bool operator>( const permutation_iterator &__lhs, const permutation_iterator<_OtherIter, _OtherOffset> &__rhs, ) noexcept(__nothrow_greater_than<_Index, _OtherOffset>)#

Compares two permutation_iterator for greater than by comparing index.

Returns:: Equivalent to __lhs.index > __rhs.index

template<class _OtherIter, class _OtherOffset> inline friend constexpr bool operator>=( const permutation_iterator &__lhs, const permutation_iterator<_OtherIter, _OtherOffset> &__rhs, ) noexcept(__nothrow_greater_equal<_Index, _OtherOffset>)#

Compares two permutation_iterator for greater equal by comparing index.

Returns:: Equivalent to __lhs.index >= __rhs.index

template<class _Iter, class _Index> inline constexpr permutation_iterator<_Iter, _Index> make_permutation_iterator( _Iter __iter, _Index __index, ) noexcept(::cuda::std::is_nothrow_copy_constructible_v<_Iter> && ::cuda::std::is_nothrow_copy_constructible_v<_Index>)#

Creates an permutation_iterator from a base iterator and an iterator to an integral index.

Parameters:

__iter – The iterator
__index – The iterator to an integral index