Gathering

template <typename DerivedPolicy,   typename InputIterator,   typename RandomAccessIterator,   typename OutputIterator> _CCCL_HOST_DEVICE OutputIterator gather(const thrust::detail::execution_policy_base< DerivedPolicy > & exec,   InputIterator map_first,   InputIterator map_last,   RandomAccessIterator input_first,   OutputIterator result);
template <typename InputIterator,   typename RandomAccessIterator,   typename OutputIterator> OutputIterator gather(InputIterator map_first,   InputIterator map_last,   RandomAccessIterator input_first,   OutputIterator result);
template <typename DerivedPolicy,   typename InputIterator1,   typename InputIterator2,   typename RandomAccessIterator,   typename OutputIterator> _CCCL_HOST_DEVICE OutputIterator gather_if(const thrust::detail::execution_policy_base< DerivedPolicy > & exec,   InputIterator1 map_first,   InputIterator1 map_last,   InputIterator2 stencil,   RandomAccessIterator input_first,   OutputIterator result);
template <typename InputIterator1,   typename InputIterator2,   typename RandomAccessIterator,   typename OutputIterator> OutputIterator gather_if(InputIterator1 map_first,   InputIterator1 map_last,   InputIterator2 stencil,   RandomAccessIterator input_first,   OutputIterator result);
template <typename DerivedPolicy,   typename InputIterator1,   typename InputIterator2,   typename RandomAccessIterator,   typename OutputIterator,   typename Predicate> _CCCL_HOST_DEVICE OutputIterator gather_if(const thrust::detail::execution_policy_base< DerivedPolicy > & exec,   InputIterator1 map_first,   InputIterator1 map_last,   InputIterator2 stencil,   RandomAccessIterator input_first,   OutputIterator result,   Predicate pred);
template <typename InputIterator1,   typename InputIterator2,   typename RandomAccessIterator,   typename OutputIterator,   typename Predicate> OutputIterator gather_if(InputIterator1 map_first,   InputIterator1 map_last,   InputIterator2 stencil,   RandomAccessIterator input_first,   OutputIterator result,   Predicate pred);

Functions

Function gather

template <typename DerivedPolicy,   typename InputIterator,   typename RandomAccessIterator,   typename OutputIterator> _CCCL_HOST_DEVICE OutputIterator 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:

#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}

Remark: gather is the inverse of thrust::scatter.

Template Parameters:

• DerivedPolicy The name of the derived execution policy.
• InputIterator must be a model of Input Iterator and InputIterator'svalue_type must be convertible to RandomAccessIterator'sdifference_type.
• RandomAccessIterator must be a model of Random Access Iterator and RandomAccessIterator'svalue_type must be convertible to OutputIterator'svalue_type.
• OutputIterator must be a model of Output Iterator.

Function 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.

Preconditions:

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

Function gather

template <typename InputIterator,   typename RandomAccessIterator,   typename OutputIterator> OutputIterator gather(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 following code snippet demonstrates how to use gather to reorder a range.

#include <thrust/gather.h>
#include <thrust/device_vector.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(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}

Remark: gather is the inverse of thrust::scatter.

Template Parameters:

• InputIterator must be a model of Input Iterator and InputIterator'svalue_type must be convertible to RandomAccessIterator'sdifference_type.
• RandomAccessIterator must be a model of Random Access Iterator and RandomAccessIterator'svalue_type must be convertible to OutputIterator'svalue_type.
• OutputIterator must be a model of Output Iterator.

Function Parameters:

• 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.

Preconditions:

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

Function gather_if

template <typename DerivedPolicy,   typename InputIterator1,   typename InputIterator2,   typename RandomAccessIterator,   typename OutputIterator> _CCCL_HOST_DEVICE OutputIterator gather_if(const thrust::detail::execution_policy_base< DerivedPolicy > & exec,   InputIterator1 map_first,   InputIterator1 map_last,   InputIterator2 stencil,   RandomAccessIterator input_first,   OutputIterator result); gather_if conditionally 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), such that the value of *(stencil + (i - map_first)) is true, 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_if to gather selected values from an input range using the thrust::device execution policy:

#include <thrust/gather.h>
#include <thrust/device_vector.h>
#include <thrust/execution_policy.h>
...

int values[10] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9};
thrust::device_vector<int> d_values(values, values + 10);

// select elements at even-indexed locations
int stencil[10] = {1, 0, 1, 0, 1, 0, 1, 0, 1, 0};
thrust::device_vector<int> d_stencil(stencil, stencil + 10);

// map 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, 7);
thrust::gather_if(thrust::device,
                  d_map.begin(), d_map.end(),
                  d_stencil.begin(),
                  d_values.begin(),
                  d_output.begin());
// d_output is now {0, 7, 4, 7, 8, 7, 3, 7, 7, 7}

Remark: gather_if is the inverse of scatter_if.

Template Parameters:

• DerivedPolicy The name of the derived execution policy.
• InputIterator1 must be a model of Input Iterator and InputIterator1'svalue_type must be convertible to RandomAccessIterator'sdifference_type.
• InputIterator2 must be a model of Input Iterator and InputIterator2'svalue_type must be convertible to bool.
• RandomAccessIterator must be a model of Random Access iterator and RandomAccessIterator'svalue_type must be convertible to OutputIterator'svalue_type.
• OutputIterator must be a model of Output Iterator.

Function 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.
• stencil Beginning of the range of predicate values.
• input_first Beginning of the source range.
• result Beginning of the destination range.

Preconditions:

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

Function gather_if

template <typename InputIterator1,   typename InputIterator2,   typename RandomAccessIterator,   typename OutputIterator> OutputIterator gather_if(InputIterator1 map_first,   InputIterator1 map_last,   InputIterator2 stencil,   RandomAccessIterator input_first,   OutputIterator result); gather_if conditionally 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), such that the value of *(stencil + (i - map_first)) is true, the value input_first[*i] is assigned to *(result + (i - map_first)). RandomAccessIterator must permit random access.

The following code snippet demonstrates how to use gather_if to gather selected values from an input range.

#include <thrust/gather.h>
#include <thrust/device_vector.h>
...

int values[10] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9};
thrust::device_vector<int> d_values(values, values + 10);

// select elements at even-indexed locations
int stencil[10] = {1, 0, 1, 0, 1, 0, 1, 0, 1, 0};
thrust::device_vector<int> d_stencil(stencil, stencil + 10);

// map 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, 7);
thrust::gather_if(d_map.begin(), d_map.end(),
                  d_stencil.begin(),
                  d_values.begin(),
                  d_output.begin());
// d_output is now {0, 7, 4, 7, 8, 7, 3, 7, 7, 7}

Remark: gather_if is the inverse of scatter_if.

Template Parameters:

• InputIterator1 must be a model of Input Iterator and InputIterator1'svalue_type must be convertible to RandomAccessIterator'sdifference_type.
• InputIterator2 must be a model of Input Iterator and InputIterator2'svalue_type must be convertible to bool.
• RandomAccessIterator must be a model of Random Access iterator and RandomAccessIterator'svalue_type must be convertible to OutputIterator'svalue_type.
• OutputIterator must be a model of Output Iterator.

Function Parameters:

• map_first Beginning of the range of gather locations.
• map_last End of the range of gather locations.
• stencil Beginning of the range of predicate values.
• input_first Beginning of the source range.
• result Beginning of the destination range.

Preconditions:

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

Function gather_if

template <typename DerivedPolicy,   typename InputIterator1,   typename InputIterator2,   typename RandomAccessIterator,   typename OutputIterator,   typename Predicate> _CCCL_HOST_DEVICE OutputIterator gather_if(const thrust::detail::execution_policy_base< DerivedPolicy > & exec,   InputIterator1 map_first,   InputIterator1 map_last,   InputIterator2 stencil,   RandomAccessIterator input_first,   OutputIterator result,   Predicate pred); gather_if conditionally 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) such that the value of pred(*(stencil + (i - map_first))) is true, 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_if to gather selected values from an input range based on an arbitrary selection function using the thrust::device execution policy for parallelization:

#include <thrust/gather.h>
#include <thrust/device_vector.h>
#include <thrust/execution_policy.h>

struct is_even
{
  __host__ __device__
  bool operator()(const int x)
  {
    return (x % 2) == 0;
  }
};
...

int values[10] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9};
thrust::device_vector<int> d_values(values, values + 10);

// we will select an element when our stencil is even
int stencil[10] = {0, 3, 4, 1, 4, 1, 2, 7, 8, 9};
thrust::device_vector<int> d_stencil(stencil, stencil + 10);

// map 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, 7);
thrust::gather_if(thrust::device,
                  d_map.begin(), d_map.end(),
                  d_stencil.begin(),
                  d_values.begin(),
                  d_output.begin(),
                  is_even());
// d_output is now {0, 7, 4, 7, 8, 7, 3, 7, 7, 7}

Remark: gather_if is the inverse of scatter_if.

Template Parameters:

• DerivedPolicy The name of the derived execution policy.
• InputIterator1 must be a model of Input Iterator and InputIterator1'svalue_type must be convertible to RandomAccessIterator'sdifference_type.
• InputIterator2 must be a model of Input Iterator and InputIterator2'svalue_type must be convertible to Predicate'sargument_type.
• RandomAccessIterator must be a model of Random Access iterator and RandomAccessIterator'svalue_type must be convertible to OutputIterator'svalue_type.
• OutputIterator must be a model of Output Iterator.
• Predicate must be a model of Predicate.

Function 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.
• stencil Beginning of the range of predicate values.
• input_first Beginning of the source range.
• result Beginning of the destination range.
• pred Predicate to apply to the stencil values.

Preconditions:

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

Function gather_if

template <typename InputIterator1,   typename InputIterator2,   typename RandomAccessIterator,   typename OutputIterator,   typename Predicate> OutputIterator gather_if(InputIterator1 map_first,   InputIterator1 map_last,   InputIterator2 stencil,   RandomAccessIterator input_first,   OutputIterator result,   Predicate pred); gather_if conditionally 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) such that the value of pred(*(stencil + (i - map_first))) is true, the value input_first[*i] is assigned to *(result + (i - map_first)). RandomAccessIterator must permit random access.

The following code snippet demonstrates how to use gather_if to gather selected values from an input range based on an arbitrary selection function.

#include <thrust/gather.h>
#include <thrust/device_vector.h>

struct is_even
{
  __host__ __device__
  bool operator()(const int x)
  {
    return (x % 2) == 0;
  }
};
...

int values[10] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9};
thrust::device_vector<int> d_values(values, values + 10);

// we will select an element when our stencil is even
int stencil[10] = {0, 3, 4, 1, 4, 1, 2, 7, 8, 9};
thrust::device_vector<int> d_stencil(stencil, stencil + 10);

// map 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, 7);
thrust::gather_if(d_map.begin(), d_map.end(),
                  d_stencil.begin(),
                  d_values.begin(),
                  d_output.begin(),
                  is_even());
// d_output is now {0, 7, 4, 7, 8, 7, 3, 7, 7, 7}

Remark: gather_if is the inverse of scatter_if.

Template Parameters:

• InputIterator1 must be a model of Input Iterator and InputIterator1'svalue_type must be convertible to RandomAccessIterator'sdifference_type.
• InputIterator2 must be a model of Input Iterator and InputIterator2'svalue_type must be convertible to Predicate'sargument_type.
• RandomAccessIterator must be a model of Random Access iterator and RandomAccessIterator'svalue_type must be convertible to OutputIterator'svalue_type.
• OutputIterator must be a model of Output Iterator.
• Predicate must be a model of Predicate.

Function Parameters:

• map_first Beginning of the range of gather locations.
• map_last End of the range of gather locations.
• stencil Beginning of the range of predicate values.
• input_first Beginning of the source range.
• result Beginning of the destination range.
• pred Predicate to apply to the stencil values.

Preconditions:

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