thrust::gather

Defined in thrust/gather.h

template<typename DerivedPolicy, typename InputIterator, typename RandomAccessIterator, typename OutputIterator>
OutputIterator thrust::gather(const thrust::detail::execution_policy_base<DerivedPolicy> &exec, InputIterator map_first, InputIterator map_last, RandomAccessIterator input_first, OutputIterator result)

gather copies elements from a source array into a destination range according to a map. For each input iterator i in the range [map_first, map_last), the value input_first[*i] is assigned to *(result + (i - map_first)). RandomAccessIterator must permit random access.

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

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

Remark

gather is the inverse of thrust::scatter.

#include <thrust/gather.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);

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

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

Parameters

  • exec – The execution policy to use for parallelization.

  • map_first – Beginning of the range of gather locations.

  • map_last – End of the range of gather locations.

  • input_first – Beginning of the source range.

  • result – Beginning of the destination range.

Template Parameters

  • DerivedPolicy – The name of the derived execution policy.

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

  • RandomAccessIterator – must be a model of Random Access Iterator and RandomAccessIterator's value_type must be convertible to OutputIterator's value_type.

  • OutputIterator – must be a model of Output Iterator.

Pre

The range [map_first, map_last) shall not overlap the range [result, result + (map_last - map_first)).

Pre

The input data shall not overlap the range [result, result + (map_last - map_first)).