thrust::iterator_facade

template<typename Derived, typename Value, typename System, typename Traversal, typename Reference, typename Difference = ::cuda::std::ptrdiff_t>
class 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.

Public Types

using value_type = ::cuda::std::remove_const_t<Value>

The type of element pointed to by iterator_facade.

using reference = Reference

The return type of iterator_facade::operator*().

using pointer = void

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.

using difference_type = Difference

The type of expressions of the form x - y where x and y are of type iterator_facade.

using iterator_category = detail::iterator_facade_category_t<System, Traversal>

The type of iterator category of iterator_facade.

Public Functions

inline reference operator*() const

operator*() dereferences this iterator_facade.

Returns:

A reference to the element pointed to by this iterator_facade.

inline reference operator[](difference_type n) const

operator[] performs indexed dereference.

Returns:

A reference to the element n distance away from this iterator_facade.

inline Derived &operator++()

operator++ pre-increments this iterator_facade to refer to the element in the next position.

Returns:

*this

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

inline Derived &operator--()

operator-- pre-decrements this iterator_facade to refer to the element in the previous position.

Returns:

*this

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

inline Derived &operator+=(difference_type n)

operator+= increments this iterator_facade to refer to an element a given distance after its current position.

Parameters:

n – The quantity to increment.

Returns:

*this

inline Derived &operator-=(difference_type n)

operator-= decrements this iterator_facade to refer to an element a given distance before its current position.

Parameters:

n – The quantity to decrement.

Returns:

*this

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

Parameters:

n – The quantity to decrement

Returns:

An iterator_facade pointing n elements before this iterator_facade.