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))
...
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.
-
using capture_t = decltype(*std::declval<DataIterator>())#
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 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.