Iterators

Contents

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

20
21
22
23
...

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

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. This iterator is not functional on gfx94x architectures.

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.

  • This iterator is not functional on gfx94x architectures, as native texture fetch functions are not supported in gfx94x.

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.

Public Functions

template<class Qualified>
inline hipError_t bind_texture(Qualified *ptr, size_t bytes = size_t(-1), size_t texture_offset = 0)#

Creates a hipTextureObject_t and binds this iterator to it.

Template Parameters:

Texture – data pointer type

Parameters:

  • ptr – - pointer to the texture data on the device

  • bytes – - size of the texture data (in bytes)

  • texture_offset – - an offset from ptr to load texture data from (Defaults to 0)

inline hipError_t unbind_texture()#

Destroys the texture object that this iterator points at.

Contents