Iterators

Groups

template <typename InputIterator,   typename Distance> _CCCL_HOST_DEVICE void advance(InputIterator & i,   Distance n);
template <typename InputIterator> _CCCL_HOST_DEVICE thrust::iterator_traits< InputIterator >::difference_type distance(InputIterator first,   InputIterator last);

Functions

Function advance

template <typename InputIterator,   typename Distance> _CCCL_HOST_DEVICE void advance(InputIterator & i,   Distance n); advance(i, n) increments the iterator i by the distance n. If n > 0 it is equivalent to executing ++in times, and if n < 0 it is equivalent to executing –in times. If n == 0, the call has no effect.

The following code snippet demonstrates how to use advance to increment an iterator a given number of times.

#include <thrust/advance.h>
#include <thrust/device_vector.h>
...
thrust::device_vector<int> vec(13);
thrust::device_vector<int>::iterator iter = vec.begin();

thrust::advance(iter, 7);

// iter - vec.begin() == 7

Template Parameters:

  • InputIterator is a model of Input Iterator.
  • Distance is an integral type that is convertible to InputIterator's distance type.

Function Parameters:

  • i The iterator to be advanced.
  • n The distance by which to advance the iterator.

Preconditions: n shall be negative only for bidirectional and random access iterators.

See: https://en.cppreference.com/w/cpp/iterator/advance

Function distance

template <typename InputIterator> _CCCL_HOST_DEVICE thrust::iterator_traits< InputIterator >::difference_type distance(InputIterator first,   InputIterator last); distance finds the distance between first and last, i.e. the number of times that first must be incremented until it is equal to last.

The following code snippet demonstrates how to use distance to compute the distance to one iterator from another.

#include <thrust/distance.h>
#include <thrust/device_vector.h>
...
thrust::device_vector<int> vec(13);
thrust::device_vector<int>::iterator iter1 = vec.begin();
thrust::device_vector<int>::iterator iter2 = iter1 + 7;

int d = thrust::distance(iter1, iter2);

// d is 7

Template Parameters: InputIterator: is a model of Input Iterator.

Function Parameters:

  • first The beginning of an input range of interest.
  • last The end of an input range of interest.

Preconditions: If InputIterator meets the requirements of random access iterator, last shall be reachable from first or first shall be reachable from last; otherwise, last shall be reachable from first.

Returns: The distance between the beginning and end of the input range.

See: https://en.cppreference.com/w/cpp/iterator/distance