Class thrust::iterator_adaptor

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
    typedef thrust::iterator_adaptor<
      repeat_iterator<Iterator>,
      Iterator
    > super_t;

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

Inherits From: detail::iterator_adaptor_base::type

#include <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 thrust::iterator_adaptor { public:  typedef see below base_type;
  iterator_adaptor() = default;
  explicit _CCCL_EXEC_CHECK_DISABLE _CCCL_HOST_DEVICE   iterator_adaptor(Base const & iter);
  _CCCL_HOST_DEVICE Base const &   base() const;
protected:  _CCCL_HOST_DEVICE Base const &   base_reference() const;
  _CCCL_HOST_DEVICE Base &   base_reference(); };

Member Types

Typedef thrust::iterator_adaptor::base_type

typedef Basebase_type; The type of iterator this iterator_adaptor'sadapts.

Member Functions

Function thrust::iterator_adaptor::iterator_adaptor

iterator_adaptor() = default; iterator_adaptor's default constructor does nothing.

Function thrust::iterator_adaptor::iterator_adaptor

explicit _CCCL_EXEC_CHECK_DISABLE _CCCL_HOST_DEVICE iterator_adaptor(Base const & iter); This constructor copies from a given instance of the Base iterator.

Function thrust::iterator_adaptor::base

_CCCL_HOST_DEVICE Base const & base() const; Returns: A const reference to the Base iterator this iterator_adaptor adapts.

Protected Member Functions

Function thrust::iterator_adaptor::base_reference

_CCCL_HOST_DEVICE Base const & base_reference() const; Returns: A const reference to the Base iterator this iterator_adaptor adapts.

Function thrust::iterator_adaptor::base_reference

_CCCL_HOST_DEVICE Base & base_reference(); Returns: A mutable reference to the Base iterator this iterator_adaptor adapts.