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

Predicate#

template<class DataIterator, class PredicateDataIterator, class UnaryPredicate>
class predicate_iterator#

A random-access iterator which can discard values assigned to it upon dereference based on a predicate.

Overview

  • predicate_iterator can be used to ignore certain input or output of algorithms.

  • When writing to predicate_iterator, it will only write to the underlying iterator if the predicate holds. Otherwise it will discard the value.

  • When reading from predicate_iterator, it will only read from the underlying iterator if the predicate holds. Otherwise it will return the default constructed value.

Template Parameters:

  • DataIterator – Type of the data iterator that will be forwarded upon dereference.

  • PredicateDataIterator – Type of the test iterator used to test the predicate function.

  • UnaryPredicate – Type of the predicate function that tests the test.

Public Types

using value_type = typename std::iterator_traits<DataIterator>::value_type#

The type of the value that can be obtained by dereferencing the iterator.

using reference = typename std::iterator_traits<DataIterator>::reference#

A reference type of the type iterated over (value_type).

using pointer = typename std::iterator_traits<DataIterator>::pointer#

A pointer type of the type iterated over (value_type).

using difference_type = typename std::iterator_traits<DataIterator>::difference_type#

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 predicate_iterator(DataIterator data_iterator, PredicateDataIterator predicate_iterator, UnaryPredicate predicate)#

Creates a new predicate_iterator.

Parameters:

  • data_iterator – The data iterator that will be forwarded whenever the predicate is true.

  • predicate_iterator – The test iterator that is used to test the predicate on.

  • predicate – Unary function used to select values obtained. from range pointed by iterator.

struct proxy#

Assignable proxy for values in DataIterator.

Public Types

using capture_t = decltype(*std::declval<DataIterator>())#

The return type on the dereference operator. This may be different than reference.

Public Functions

__host__ __device__ inline proxy(capture_t val, const bool keep)#

Constructs a proxy object with the given reference and keep flag.

Parameters:

  • val – The value or reference to be captured.

  • keep – Boolean flag that indicates whether to keep the reference.

__host__ __device__ inline proxy &operator=(const value_type &value)#

Assigns a value to the held reference if the keep flag is true.

Parameters:

value – The value to assign to the captured value.

Returns:

A reference to the (possibly) modified proxy object.

__host__ __device__ inline operator value_type() const#

Converts the proxy to the underlying value type.

Returns:

The referenced value or the default-constructed value.

Note

predicate_iterator(sequence, test, predicate) generates the sequence:

predicate(test[0]) ? sequence[0] : default
predicate(test[1]) ? sequence[1] : default
predicate(test[2]) ? sequence[2] : default
...

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