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 asvalue_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’sconst
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 asvalue_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’sconst
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’sconst
since transform_iterator is a read-only iterator.
-
using pointer = const value_type*#
A pointer type of the type iterated over (
value_type
). It’sconst
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 toInputValueType
.
- 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’sconst
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’sconst
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.