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
AnElementIterator
pointing thispermutation_iterator's
range of values.y
AnIndexIterator
pointing to an indexing scheme to use onx
.
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.