thrust::iterator_adaptor

Defined in thrust/iterator/iterator_adaptor.h

template<typename Derived, typename Base, typename Value = use_default, typename System = use_default, typename Traversal = use_default, typename Reference = use_default, typename Difference = use_default>
class iterator_adaptor : public detail::iterator_adaptor_base::type<Derived, Base, use_default, use_default, use_default, use_default, use_default>

iterator_adaptor is an iterator which adapts an existing type of iterator to create a new type of iterator. Most of Thrust’s fancy iterators are defined via inheritance from iterator_adaptor. While composition of these existing Thrust iterators is often sufficient for expressing the desired functionality, it is occasionally more straightforward to derive from iterator_adaptor directly.

To see how to use iterator_adaptor to create a novel iterator type, let’s examine how to use it to define repeat_iterator, a fancy iterator which repeats elements from another range a given number of time:

#include <thrust/iterator/iterator_adaptor.h>

// derive repeat_iterator from iterator_adaptor
template<typename Iterator>
  class repeat_iterator
    : public thrust::iterator_adaptor<
        repeat_iterator<Iterator>, // the first template parameter is the name of the iterator we're creating
        Iterator                   // the second template parameter is the name of the iterator we're adapting
                                   // we can use the default for the additional template parameters
      >
{
  public:
    // shorthand for the name of the iterator_adaptor we're deriving from
    using super_t = thrust::iterator_adaptor<
      repeat_iterator<Iterator>,
      Iterator
    >;

    __host__ __device__
    repeat_iterator(const Iterator &x, int n) : super_t(x), begin(x), n(n) {}

    // befriend thrust::iterator_core_access to allow it access to the private interface below
    friend class thrust::iterator_core_access;

  private:
    // repeat each element of the adapted range n times
    unsigned int n;

    // used to keep track of where we began
    const Iterator begin;

    // it is private because only thrust::iterator_core_access needs access to it
    __host__ __device__
    typename super_t::reference dereference() const
    {
      return *(begin + (this->base() - begin) / n);
    }
};

Except for the first two, iterator_adaptor's template parameters are optional. When omitted, or when the user specifies thrust::use_default in its place, iterator_adaptor will use a default type inferred from Base.

iterator_adaptor's functionality is derived from and generally equivalent to boost::iterator_adaptor. The exception is Thrust’s addition of the template parameter System, which is necessary to allow Thrust to dispatch an algorithm to one of several parallel backend systems.

iterator_adaptor is a powerful tool for creating custom iterators directly. However, the large set of iterator semantics which must be satisfied for algorithm compatibility can make iterator_adaptor difficult to use correctly. Unless you require the full expressivity of iterator_adaptor, consider building a custom iterator through composition of existing higher-level fancy iterators instead.

Interested users may refer to boost::iterator_adaptor’s documentation for further usage examples.

Public Types

using base_type = Base

The type of iterator this iterator_adaptor's adapts.

Public Functions

iterator_adaptor() = default

iterator_adaptor's default constructor does nothing.

inline explicit iterator_adaptor(Base const &iter)

This constructor copies from a given instance of the Base iterator.

inline Base const &base() const

Returns

A const reference to the Base iterator this iterator_adaptor adapts.

Protected Functions

inline Base const &base_reference() const

Returns

A const reference to the Base iterator this iterator_adaptor adapts.

inline Base &base_reference()

Returns

A mutable reference to the Base iterator this iterator_adaptor adapts.