thrust::permutation_iterator#

template<typename ElementIterator, typename IndexIterator> class permutation_iterator : public thrust::iterator_adaptor<permutation_iterator<ElementIterator, IndexIterator>, IndexIterator, it_value_t<ElementIterator>, minimum_system_t<System1, System2>, use_default, it_reference_t<ElementIterator>>#

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{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  ;

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}