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's
adapts
.
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.