thrust::scatter

Defined in thrust/scatter.h

template<typename DerivedPolicy, typename InputIterator1, typename InputIterator2, typename RandomAccessIterator>
void thrust::scatter(const thrust::detail::execution_policy_base<DerivedPolicy> &exec, InputIterator1 first, InputIterator1 last, InputIterator2 map, RandomAccessIterator result)

scatter copies elements from a source range into an output array according to a map. For each iterator i in the range [first, last), the value *i is assigned to output[*(map + (i - first))]. The output iterator must permit random access. If the same index appears more than once in the range [map, map + (last - first)), the result is undefined.

The algorithm’s execution is parallelized as determined by exec.

The following code snippet demonstrates how to use scatter to reorder a range using the thrust::device execution policy for parallelization:

#include <thrust/scatter.h>
#include <thrust/device_vector.h>
#include <thrust/execution_policy.h>
...
// mark even indices with a 1; odd indices with a 0
int values[10] = {1, 0, 1, 0, 1, 0, 1, 0, 1, 0};
thrust::device_vector<int> d_values(values, values + 10);

// scatter all even indices into the first half of the
// range, and odd indices vice versa
int map[10]   = {0, 5, 1, 6, 2, 7, 3, 8, 4, 9};
thrust::device_vector<int> d_map(map, map + 10);

thrust::device_vector<int> d_output(10);
thrust::scatter(thrust::device,
                d_values.begin(), d_values.end(),
                d_map.begin(), d_output.begin());
// d_output is now {1, 1, 1, 1, 1, 0, 0, 0, 0, 0}

Note

scatter is the inverse of thrust::gather.

Parameters

  • exec – The execution policy to use for parallelization.

  • first – Beginning of the sequence of values to scatter.

  • last – End of the sequence of values to scatter.

  • map – Beginning of the sequence of output indices.

  • result – Destination of the source elements.

Template Parameters

  • DerivedPolicy – The name of the derived execution policy.

  • InputIterator1 – must be a model of Input Iterator and InputIterator1's value_type must be convertible to RandomAccessIterator's value_type.

  • InputIterator2 – must be a model of Input Iterator and InputIterator2's value_type must be convertible to RandomAccessIterator's difference_type.

  • RandomAccessIterator – must be a model of Random Access iterator.

Pre

The iterator result + i shall not refer to any element referenced by any iterator j in the range [first,last) for all iterators i in the range [map,map + (last - first)).

Pre

The iterator result + i shall not refer to any element referenced by any iterator j in the range [map, map + (last - first)) for all iterators i in the range [map, map + (last - first)).

Pre

The expression result[*i] shall be valid for all iterators in the range [map, map + (last - first)).