Class thrust::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
  • the reindexing scheme that defines how the elements of V will be permuted.

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 subrange of V. The indices neither 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 <thrust/iterator/permutation_iterator.h>
#include <thrust/device_vector.h>
...
thrust::device_vector<float> values(8);
values[0] = 10.0f;
values[1] = 20.0f;
values[2] = 30.0f;
values[3] = 40.0f;
values[4] = 50.0f;
values[5] = 60.0f;
values[6] = 70.0f;
values[7] = 80.0f;

thrust::device_vector<int> indices(4);
indices[0] = 2;
indices[1] = 6;
indices[2] = 1;
indices[3] = 3;

typedef thrust::device_vector<float>::iterator ElementIterator;
typedef thrust::device_vector<int>::iterator   IndexIterator;

thrust::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}

Inherits From: thrust::detail::permutation_iterator_base::type

See: make_permutation_iterator

#include <thrust/iterator/permutation_iterator.h>
template <typename ElementIterator,   typename IndexIterator> class thrust::permutation_iterator { public:  permutation_iterator() = default;
  explicit _CCCL_HOST_DEVICE   permutation_iterator(ElementIterator x,     IndexIterator y);
  template <typename OtherElementIterator,       typename OtherIndexIterator,       detail::enable_if_convertible_t< OtherElementIterator, ElementIterator, int > = 0,       detail::enable_if_convertible_t< OtherIndexIterator, IndexIterator, int > = 0>   _CCCL_HOST_DEVICE   permutation_iterator(permutation_iterator< OtherElementIterator, OtherIndexIterator > const & rhs); };

Member Functions

Function thrust::permutation_iterator::permutation_iterator

permutation_iterator() = default; Null constructor calls the null constructor of this permutation_iterator's element iterator.

Function thrust::permutation_iterator::permutation_iterator

explicit _CCCL_HOST_DEVICE permutation_iterator(ElementIterator x,   IndexIterator y); Constructor accepts an ElementIterator into a range of values and an IndexIterator into a range of indices defining the indexing scheme on the values.

Function Parameters:

  • x An ElementIterator pointing this permutation_iterator's range of values.
  • y An IndexIterator pointing to an indexing scheme to use on x.

Function thrust::permutation_iterator::permutation_iterator

template <typename OtherElementIterator,   typename OtherIndexIterator,   detail::enable_if_convertible_t< OtherElementIterator, ElementIterator, int > = 0,   detail::enable_if_convertible_t< OtherIndexIterator, IndexIterator, int > = 0> _CCCL_HOST_DEVICE permutation_iterator(permutation_iterator< OtherElementIterator, OtherIndexIterator > const & rhs); Copy constructor accepts a related permutation_iterator.

Function Parameters: r: A compatible permutation_iterator to copy from.