Scattering

template <typename DerivedPolicy,   typename InputIterator1,   typename InputIterator2,   typename RandomAccessIterator> _CCCL_HOST_DEVICE void scatter(const thrust::detail::execution_policy_base< DerivedPolicy > & exec,   InputIterator1 first,   InputIterator1 last,   InputIterator2 map,   RandomAccessIterator result);
template <typename InputIterator1,   typename InputIterator2,   typename RandomAccessIterator> void scatter(InputIterator1 first,   InputIterator1 last,   InputIterator2 map,   RandomAccessIterator result);
template <typename DerivedPolicy,   typename InputIterator1,   typename InputIterator2,   typename InputIterator3,   typename RandomAccessIterator> _CCCL_HOST_DEVICE void scatter_if(const thrust::detail::execution_policy_base< DerivedPolicy > & exec,   InputIterator1 first,   InputIterator1 last,   InputIterator2 map,   InputIterator3 stencil,   RandomAccessIterator output);
template <typename InputIterator1,   typename InputIterator2,   typename InputIterator3,   typename RandomAccessIterator> void scatter_if(InputIterator1 first,   InputIterator1 last,   InputIterator2 map,   InputIterator3 stencil,   RandomAccessIterator output);
template <typename DerivedPolicy,   typename InputIterator1,   typename InputIterator2,   typename InputIterator3,   typename RandomAccessIterator,   typename Predicate> _CCCL_HOST_DEVICE void scatter_if(const thrust::detail::execution_policy_base< DerivedPolicy > & exec,   InputIterator1 first,   InputIterator1 last,   InputIterator2 map,   InputIterator3 stencil,   RandomAccessIterator output,   Predicate pred);
template <typename InputIterator1,   typename InputIterator2,   typename InputIterator3,   typename RandomAccessIterator,   typename Predicate> void scatter_if(InputIterator1 first,   InputIterator1 last,   InputIterator2 map,   InputIterator3 stencil,   RandomAccessIterator output,   Predicate pred);

Functions

Function scatter

template <typename DerivedPolicy,   typename InputIterator1,   typename InputIterator2,   typename RandomAccessIterator> _CCCL_HOST_DEVICE void 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.

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'svalue_type.
  • InputIterator2 must be a model of Input Iterator and InputIterator2'svalue_type must be convertible to RandomAccessIterator'sdifference_type.
  • RandomAccessIterator must be a model of Random Access iterator.

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

Preconditions:

  • 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)).
  • 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)).
  • The expression result[*i] shall be valid for all iterators in the range [map,map + (last - first)).

Function scatter

template <typename InputIterator1,   typename InputIterator2,   typename RandomAccessIterator> void scatter(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 following code snippet demonstrates how to use scatter to reorder a range.

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

// 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(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.

Template Parameters:

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

Function Parameters:

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

Preconditions:

  • 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)).
  • 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)).
  • The expression result[*i] shall be valid for all iterators in the range [map,map + (last - first)).

Function scatter_if

template <typename DerivedPolicy,   typename InputIterator1,   typename InputIterator2,   typename InputIterator3,   typename RandomAccessIterator> _CCCL_HOST_DEVICE void scatter_if(const thrust::detail::execution_policy_base< DerivedPolicy > & exec,   InputIterator1 first,   InputIterator1 last,   InputIterator2 map,   InputIterator3 stencil,   RandomAccessIterator output); scatter_if conditionally copies elements from a source range into an output array according to a map. For each iterator i in the range [first, last) such that *(stencil + (i - first)) is true, 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.

#include <thrust/scatter.h>
#include <thrust/execution_policy.h>
...
int V[8] = {10, 20, 30, 40, 50, 60, 70, 80};
int M[8] = {0, 5, 1, 6, 2, 7, 3, 4};
int S[8] = {1, 0, 1, 0, 1, 0, 1, 0};
int D[8] = {0, 0, 0, 0, 0, 0, 0, 0};

thrust::scatter_if(thrust::host, V, V + 8, M, S, D);

// D contains [10, 30, 50, 70, 0, 0, 0, 0];

Note: scatter_if is the inverse of thrust::gather_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'svalue_type.
  • InputIterator2 must be a model of Input Iterator and InputIterator2'svalue_type must be convertible to RandomAccessIterator'sdifference_type.
  • InputIterator3 must be a model of Input Iterator and InputIterator3'svalue_type must be convertible to bool.
  • RandomAccessIterator must be a model of Random Access iterator.

Function 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.
  • stencil Beginning of the sequence of predicate values.
  • output Beginning of the destination range.

Preconditions:

  • 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)).
  • 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)).
  • The iterator result + i shall not refer to any element referenced by any iterator j in the range [stencil,stencil + (last - first)) for all iterators i in the range [map,map + (last - first)).
  • The expression result[*i] shall be valid for all iterators i in the range [map,map + (last - first)) for which the following condition holds: *(stencil + i) != false.

Function scatter_if

template <typename InputIterator1,   typename InputIterator2,   typename InputIterator3,   typename RandomAccessIterator> void scatter_if(InputIterator1 first,   InputIterator1 last,   InputIterator2 map,   InputIterator3 stencil,   RandomAccessIterator output); scatter_if conditionally copies elements from a source range into an output array according to a map. For each iterator i in the range [first, last) such that *(stencil + (i - first)) is true, 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.

#include <thrust/scatter.h>
...
int V[8] = {10, 20, 30, 40, 50, 60, 70, 80};
int M[8] = {0, 5, 1, 6, 2, 7, 3, 4};
int S[8] = {1, 0, 1, 0, 1, 0, 1, 0};
int D[8] = {0, 0, 0, 0, 0, 0, 0, 0};

thrust::scatter_if(V, V + 8, M, S, D);

// D contains [10, 30, 50, 70, 0, 0, 0, 0];

Note: scatter_if is the inverse of thrust::gather_if.

Template Parameters:

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

Function Parameters:

  • 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.
  • stencil Beginning of the sequence of predicate values.
  • output Beginning of the destination range.

Preconditions:

  • 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)).
  • 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)).
  • The iterator result + i shall not refer to any element referenced by any iterator j in the range [stencil,stencil + (last - first)) for all iterators i in the range [map,map + (last - first)).
  • The expression result[*i] shall be valid for all iterators i in the range [map,map + (last - first)) for which the following condition holds: *(stencil + i) != false.

Function scatter_if

template <typename DerivedPolicy,   typename InputIterator1,   typename InputIterator2,   typename InputIterator3,   typename RandomAccessIterator,   typename Predicate> _CCCL_HOST_DEVICE void scatter_if(const thrust::detail::execution_policy_base< DerivedPolicy > & exec,   InputIterator1 first,   InputIterator1 last,   InputIterator2 map,   InputIterator3 stencil,   RandomAccessIterator output,   Predicate pred); scatter_if conditionally copies elements from a source range into an output array according to a map. For each iterator i in the range [first, last) such that pred(*(stencil + (i - first))) is true, 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.

#include <thrust/scatter.h>
#include <thrust/execution_policy.h>

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

...

int V[8] = {10, 20, 30, 40, 50, 60, 70, 80};
int M[8] = {0, 5, 1, 6, 2, 7, 3, 4};
int S[8] = {2, 1, 2, 1, 2, 1, 2, 1};
int D[8] = {0, 0, 0, 0, 0, 0, 0, 0};

is_even pred;
thrust::scatter_if(thrust::host, V, V + 8, M, S, D, pred);

// D contains [10, 30, 50, 70, 0, 0, 0, 0];

Note: scatter_if is the inverse of thrust::gather_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'svalue_type.
  • InputIterator2 must be a model of Input Iterator and InputIterator2'svalue_type must be convertible to RandomAccessIterator'sdifference_type.
  • InputIterator3 must be a model of Input Iterator and InputIterator3'svalue_type must be convertible to Predicate'sargument_type.
  • RandomAccessIterator must be a model of Random Access iterator.
  • Predicate must be a model of Predicate.

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

Preconditions:

  • 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)).
  • 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)).
  • The iterator result + i shall not refer to any element referenced by any iterator j in the range [stencil,stencil + (last - first)) for all iterators i in the range [map,map + (last - first)).
  • The expression result[*i] shall be valid for all iterators i in the range [map,map + (last - first)) for which the following condition holds: pred(*(stencil + i)) != false.

Function scatter_if

template <typename InputIterator1,   typename InputIterator2,   typename InputIterator3,   typename RandomAccessIterator,   typename Predicate> void scatter_if(InputIterator1 first,   InputIterator1 last,   InputIterator2 map,   InputIterator3 stencil,   RandomAccessIterator output,   Predicate pred); scatter_if conditionally copies elements from a source range into an output array according to a map. For each iterator i in the range [first, last) such that pred(*(stencil + (i - first))) is true, 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.

#include <thrust/scatter.h>

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

...

int V[8] = {10, 20, 30, 40, 50, 60, 70, 80};
int M[8] = {0, 5, 1, 6, 2, 7, 3, 4};
int S[8] = {2, 1, 2, 1, 2, 1, 2, 1};
int D[8] = {0, 0, 0, 0, 0, 0, 0, 0};

is_even pred;
thrust::scatter_if(V, V + 8, M, S, D, pred);

// D contains [10, 30, 50, 70, 0, 0, 0, 0];

Note: scatter_if is the inverse of thrust::gather_if.

Template Parameters:

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

Function Parameters:

  • 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.
  • stencil Beginning of the sequence of predicate values.
  • output Beginning of the destination range.
  • pred Predicate to apply to the stencil values.

Preconditions:

  • 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)).
  • 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)).
  • The iterator result + i shall not refer to any element referenced by any iterator j in the range [stencil,stencil + (last - first)) for all iterators i in the range [map,map + (last - first)).
  • The expression result[*i] shall be valid for all iterators i in the range [map,map + (last - first)) for which the following condition holds: pred(*(stencil + i)) != false.