Class thrust::iterator_facade
iterator_facade
is a template which allows the programmer to define a novel iterator with a standards-conforming interface which Thrust can use to reason about algorithm acceleration opportunities.
Because most of a standard iterator’s interface is defined in terms of a small set of core primitives, iterator_facade
defines the non-primitive portion mechanically. In principle a novel iterator could explicitly provide the entire interface in an ad hoc fashion but doing so might be tedious and prone to subtle errors.
Often iterator_facade
is too primitive a tool to use for defining novel iterators. In these cases, iterator_adaptor
or a specific fancy iterator should be used instead.
iterator_facade's
functionality is derived from and generally equivalent to boost::iterator_facade
. 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. An additional exception is Thrust’s omission of the operator->
member function.
Interested users may refer to boost::iterator_facade
’s documentation for usage examples.
Note: iterator_facade's
arithmetic operator free functions exist with the usual meanings but are omitted here for brevity.
#include <thrust/iterator/iterator_facade.h>
template <typename Derived, typename Value, typename System, typename Traversal, typename Reference, typename Difference = std::ptrdiff_t> class thrust::iterator_facade { public: typedef see below value_type;
typedef see below reference;
typedef see below pointer;
typedef see below difference_type;
typedef see below iterator_category;
_CCCL_HOST_DEVICE reference operator*() const;
_CCCL_HOST_DEVICE reference operator[](difference_type n) const;
_CCCL_HOST_DEVICE Derived & operator++();
_CCCL_HOST_DEVICE Derived operator++(int);
_CCCL_HOST_DEVICE Derived & operator--();
_CCCL_HOST_DEVICE Derived operator--(int);
_CCCL_HOST_DEVICE Derived & operator+=(difference_type n);
_CCCL_HOST_DEVICE Derived & operator-=(difference_type n);
_CCCL_HOST_DEVICE Derived operator-(difference_type n) const; };
Member Types
Typedef thrust::iterator_facade::value_type
typedef thrust::detail::remove_const< Value >::typevalue_type;
The type of element pointed to by iterator_facade
.
Typedef thrust::iterator_facade::reference
typedef Referencereference;
The return type of iterator_facade::operator*()
.
Typedef thrust::iterator_facade::pointer
typedef voidpointer;
The return type of iterator_facade's
non-existent operator->()
member function. Unlike boost::iterator_facade
, iterator_facade
disallows access to the value_type's
members through expressions of the form iter->member
. pointer
is defined to void
to indicate that these expressions are not allowed. This limitation may be relaxed in a future version of Thrust.
Typedef thrust::iterator_facade::difference_type
typedef Differencedifference_type;
The type of expressions of the form x - y
where x
and y
are of type iterator_facade
.
Typedef thrust::iterator_facade::iterator_category
typedef thrust::detail::iterator_facade_category< System, Traversal, Value, Reference >::typeiterator_category;
The type of iterator category of iterator_facade
.
Member Functions
Function thrust::iterator_facade::operator*
_CCCL_HOST_DEVICE reference operator*() const;
operator*()
dereferences this iterator_facade
.
Returns: A reference to the element pointed to by this iterator_facade
.
Function thrust::iterator_facade::operator[]
_CCCL_HOST_DEVICE reference operator[](difference_type n) const;
operator
[] performs indexed dereference.
Returns: A reference to the element n
distance away from this iterator_facade
.
Function thrust::iterator_facade::operator++
_CCCL_HOST_DEVICE Derived & operator++();
operator++
pre-increments this iterator_facade
to refer to the element in the next position.
Returns: *this
Function thrust::iterator_facade::operator++
_CCCL_HOST_DEVICE Derived operator++(int);
operator++
post-increments this iterator_facade
and returns a new iterator_facade
referring to the element in the next position.
Returns: A copy of *this
before increment.
Function thrust::iterator_facade::operator--
_CCCL_HOST_DEVICE Derived & operator--();
operator--
pre-decrements this iterator_facade
to refer to the element in the previous position.
Returns: *this
Function thrust::iterator_facade::operator--
_CCCL_HOST_DEVICE Derived operator--(int);
operator--
post-decrements this iterator_facade
and returns a new iterator_facade
referring to the element in the previous position.
Returns: A copy of *this
before decrement.
Function thrust::iterator_facade::operator+=
_CCCL_HOST_DEVICE Derived & operator+=(difference_type n);
operator+=
increments this iterator_facade
to refer to an element a given distance after its current position.
Function Parameters: n
: The quantity to increment.
Returns: *this
Function thrust::iterator_facade::operator-=
_CCCL_HOST_DEVICE Derived & operator-=(difference_type n);
operator-=
decrements this iterator_facade
to refer to an element a given distance before its current postition.
Function Parameters: n
: The quantity to decrement.
Returns: *this
Function thrust::iterator_facade::operator-
_CCCL_HOST_DEVICE Derived operator-(difference_type n) const;
operator-
subtracts a given quantity from this iterator_facade
and returns a new iterator_facade
referring to the element at the given position before this iterator_facade
.
Function Parameters: n
: The quantity to decrement
Returns: An iterator_facade
pointing n
elements before this iterator_facade
.