Iterators

Iterators#

Constant#

template<class ValueType, class Difference = std::ptrdiff_t> class constant_iterator#

A random-access input (read-only) iterator which generates a sequence of homogeneous values.

Overview

A constant_iterator represents a pointer into a range of same values.
Using it for simulating a range filled with a sequence of same values saves memory capacity and bandwidth.

Template Parameters:

ValueType – - type of value that can be obtained by dereferencing the iterator.
Difference – - a type used for identify distance between iterators

Public Types

using value_type = typename std::remove_const<ValueType>::type#: The type of the value that can be obtained by dereferencing the iterator.

using reference = value_type #: A reference type of the type iterated over (value_type). It’s same as value_type since constant_iterator is a read-only iterator and does not have underlying buffer.

using pointer = const value_type*#: A pointer type of the type iterated over (value_type). It’s const since constant_iterator is a read-only iterator.

using difference_type = Difference #: A type used for identify distance between iterators.

using iterator_category = std::random_access_iterator_tag#: The category of the iterator.

Public Functions

__host__ __device__ inline explicit constant_iterator(const value_type value, const size_t index = 0)#

Creates constant_iterator and sets its initial value to value.

Parameters:

value – initial value
index – optional index for constant_iterator

__host__ __device__ inline value_type operator[](difference_type) const#: Constant_iterator is not writable, so we don’t return reference, just something convertible to reference. That matches requirement of RandomAccessIterator concept

Note

For example, constant_iterator(20) generates the infinite sequence:

20
20
20
...

Counting#

template<class Incrementable, class Difference = std::ptrdiff_t> class counting_iterator#

A random-access input (read-only) iterator over a sequence of consecutive integer values.

Overview

A counting_iterator represents a pointer into a range of sequentially increasing values.
Using it for simulating a range filled with a sequence of consecutive values saves memory capacity and bandwidth.

Template Parameters:

Incrementable – - type of value that can be obtained by dereferencing the iterator.
Difference – - a type used for identify distance between iterators

Public Types

using value_type = typename std::remove_const<Incrementable>::type#: The type of the value that can be obtained by dereferencing the iterator.

using reference = value_type #: A reference type of the type iterated over (value_type). It’s same as value_type since constant_iterator is a read-only iterator and does not have underlying buffer.

using pointer = const value_type*#: A pointer type of the type iterated over (value_type). It’s const since counting_iterator is a read-only iterator.

using difference_type = Difference #: A type used for identify distance between iterators.

using iterator_category = std::random_access_iterator_tag#: The category of the iterator.

Public Functions

__host__ __device__ inline ~counting_iterator() = default#: Creates counting_iterator with its initial value initialized to its default value (usually 0).

__host__ __device__ inline explicit counting_iterator(const value_type value)#

Creates counting_iterator and sets its initial value to value_.

Parameters:: value – initial value

Note

For example, counting_iterator(20) generates the infinite sequence:

Transform#

template<class InputIterator, class UnaryFunction, class ValueType = typename ::rocprim::detail::invoke_result<UnaryFunction, typename std::iterator_traits<InputIterator>::value_type>::type> class transform_iterator#

A random-access input (read-only) iterator adaptor for transforming dereferenced values.

Overview

A transform_iterator uses functor of type UnaryFunction to transform value obtained by dereferencing underlying iterator.
Using it for simulating a range filled with results of applying functor of type UnaryFunction to another range saves memory capacity and/or bandwidth.

Template Parameters:

InputIterator – - type of the underlying random-access input iterator. Must be a random-access iterator.
UnaryFunction – - type of the transform functor.
ValueType – - type of value that can be obtained by dereferencing the iterator. By default it is the return type of UnaryFunction.

Public Types

using value_type = ValueType #: The type of the value that can be obtained by dereferencing the iterator.

using reference = const value_type&#: A reference type of the type iterated over (value_type). It’s const since transform_iterator is a read-only iterator.

using pointer = const value_type*#: A pointer type of the type iterated over (value_type). It’s const since transform_iterator is a read-only iterator.

using difference_type = typename std::iterator_traits<InputIterator>::difference_type#: A type used for identify distance between iterators.

using iterator_category = std::random_access_iterator_tag#: The category of the iterator.

using unary_function = UnaryFunction #: The type of unary function used to transform input range.

Public Functions

__host__ __device__ inline transform_iterator(InputIterator iterator, UnaryFunction transform)#

Creates a new transform_iterator.

Parameters:

iterator – input iterator to iterate over and transform.
transform – unary function used to transform values obtained from range pointed by iterator.

Note

transform_iterator(sequence, transform) should generate the sequence:

transform(sequence(0))
transform(sequence(1))
...

Pairing Values with Indices#

template<class InputIterator, class Difference = std::ptrdiff_t, class InputValueType = typename std::iterator_traits<InputIterator>::value_type> class arg_index_iterator#

A random-access input (read-only) iterator adaptor for pairing dereferenced values with their indices.

Overview

Dereferencing arg_index_iterator return a value of key_value_pair<Difference, InputValueType> type, which includes value from the underlying range and its index in that range.
std::iterator_traits<InputIterator>::value_type should be convertible to InputValueType.

Template Parameters:

InputIterator – - type of the underlying random-access input iterator. Must be a random-access iterator.
Difference – - type used for identify distance between iterators and as the index type in the output pair type (see value_type).
InputValueType – - value type used in the output pair type (see value_type).

Public Types

using value_type = ::rocprim::key_value_pair<Difference, InputValueType>#: The type of the value that can be obtained by dereferencing the iterator.

using reference = const value_type&#: A reference type of the type iterated over (value_type). It’s const since arg_index_iterator is a read-only iterator.

using pointer = const value_type*#: A pointer type of the type iterated over (value_type). It’s const since arg_index_iterator is a read-only iterator.

using difference_type = Difference #: A type used for identify distance between iterators.

using iterator_category = std::random_access_iterator_tag#: The category of the iterator.

Public Functions

__host__ __device__ inline arg_index_iterator(InputIterator iterator, difference_type offset = 0)#

Creates a new arg_index_iterator.

Parameters:

iterator – input iterator pointing to the input range.
offset – index of the iterator in the input range.

Note

arg_index_iterator(sequence) generates the sequence of tuples:

(0, sequence[0])
(1, sequence[1])
...

Zip#

template<class IteratorTuple> class zip_iterator#

TBD.

Overview

TBD

Template Parameters:: IteratorTuple – -

Public Types

using reference = typename detail::tuple_of_references<IteratorTuple>::type#

A reference type of the type iterated over.

The type of the tuple made of the reference types of the iterator types in the IteratorTuple argument.

using value_type = typename detail::tuple_of_values<IteratorTuple>::type#: The type of the value that can be obtained by dereferencing the iterator.

using pointer = value_type*#: A pointer type of the type iterated over (value_type).

using difference_type = typename std::iterator_traits<typename ::rocprim::tuple_element<0, IteratorTuple>::type>::difference_type#

A type used for identify distance between iterators.

The difference_type member of zip_iterator is the difference_type of the first of the iterator types in the IteratorTuple argument.

using iterator_category = std::random_access_iterator_tag#: The category of the iterator.

Public Functions

__host__ __device__ inline zip_iterator(IteratorTuple iterator_tuple)#

Creates a new zip_iterator.

Parameters:: iterator_tuple – tuple of iterators

Note

zip_iterator(sequence_X, sequence_Y) generates the sequence of tuples:

(sequence_X[0], sequence_Y[0])
(sequence_X[1], sequence_Y[1])
...

Discard#

class discard_iterator#

A random-access iterator which discards values assigned to it upon dereference.

Overview

discard_iterator does not have any underlying array (memory) and does not save values written to it upon dereference.
discard_iterator can be used to safely ignore certain output of algorithms, which saves memory capacity and/or bandwidth.

Public Types

using value_type = discard_value #: The type of the value that can be obtained by dereferencing the iterator.

using reference = discard_value #: A reference type of the type iterated over (value_type).

using pointer = discard_value*#: A pointer type of the type iterated over (value_type).

using difference_type = std::ptrdiff_t#: A type used for identify distance between iterators.

using iterator_category = std::random_access_iterator_tag#: The category of the iterator.

Public Functions

__host__ __device__ inline discard_iterator(size_t index = 0)#

Creates a new discard_iterator.

Parameters:: index – - optional index of discard iterator (default = 0).

struct discard_value#

Texture Cache#

template<class T, class Difference = std::ptrdiff_t> class texture_cache_iterator#

A random-access input (read-only) iterator adaptor for dereferencing array values through texture cache.

Overview

A texture_cache_iterator wraps a device pointer of type T, where values are obtained by dereferencing through texture cache.
Can be exchanged and manipulated within and between host and device functions.
Can only be constructed within host functions, and can only be dereferenced within device functions.
Accepts any data type from memory, and loads through texture cache.

Template Parameters:

T – - type of value that can be obtained by dereferencing the iterator.
Difference – - a type used for identify distance between iterators.

Public Types

using value_type = typename std::remove_const<T>::type#: The type of the value that can be obtained by dereferencing the iterator.

using reference = const value_type&#: A reference type of the type iterated over (value_type).

using pointer = const value_type*#: A pointer type of the type iterated over (value_type).

using difference_type = Difference #: A type used for identify distance between iterators.

using iterator_category = std::random_access_iterator_tag#: The category of the iterator.

Iterators

Contents

Iterators#

Constant#

Counting#

Transform#

Pairing Values with Indices#

Zip#

Discard#

Texture Cache#