transform_output_iterator#

template<class _Iter, class _Fn>
class transform_output_iterator#

transform_output_iterator is a special kind of output iterator which transforms a value written upon dereference.

This iterator is useful for transforming an output from algorithms without explicitly storing the intermediate result in the memory and applying subsequent transformation, thereby avoiding wasting memory capacity and bandwidth. Using transform_iterator facilitates kernel fusion by deferring execution of transformation until the value is written while saving both memory capacity and bandwidth.

The following code snippet demonstrated how to create a transform_output_iterator which applies sqrtf to the assigning value.

#include <cuda/iterator>
#include <thrust/device_vector.h>

struct square_root
{
  __host__ __device__
  float operator()(float x) const
  {
    return cuda::std::sqrtf(x);
  }
};

int main()
{
  thrust::device_vector<float> v(4);
  cuda::transform_output_iterator iter(v.begin(), square_root());

  iter[0] =  1.0f;    // stores sqrtf( 1.0f)
  iter[1] =  4.0f;    // stores sqrtf( 4.0f)
  iter[2] =  9.0f;    // stores sqrtf( 9.0f)
  iter[3] = 16.0f;    // stores sqrtf(16.0f)
  // iter[4] is an out-of-bounds error

  v[0]; // returns 1.0f;
  v[1]; // returns 2.0f;
  v[2]; // returns 3.0f;
  v[3]; // returns 4.0f;

}

Public Types

using iterator_concept = ::cuda::std::output_iterator_tag#
using iterator_category = ::cuda::std::output_iterator_tag#
using difference_type = ::cuda::std::iter_difference_t<_Iter>#
using value_type = void#
using pointer = void#
using reference = void#

Public Functions

template<class _Iter2 = _Iter, class _Fn2 = _Fn>
inline constexpr transform_output_iterator(
) noexcept(::cuda::std::is_nothrow_default_constructible_v<_Iter2> && ::cuda::std::is_nothrow_default_constructible_v<_Fn2>)#

Default constructs a transform_output_iterator with a value initialized iterator and functor.

inline constexpr transform_output_iterator(
_Iter __iter,
_Fn __func,
) noexcept(::cuda::std::is_nothrow_move_constructible_v<_Iter> && ::cuda::std::is_nothrow_move_constructible_v<_Fn>)#

Constructs a transform_output_iterator with a given iterator and output functor.

Parameters:

  • __iter – The iterator to transform

  • __func – The output function to apply to the iterator on assignment

inline constexpr const _Iter &base() const & noexcept#

Returns a const reference to the stored iterator.

inline constexpr _Iter base(
) && noexcept(::cuda::std::is_nothrow_move_constructible_v<_Iter>)#

Extracts the stored iterator.

inline constexpr auto operator*(
) const noexcept(::cuda::std::is_nothrow_copy_constructible_v<_Iter>)#

Returns a proxy that transforms the input upon assignment.

inline constexpr auto operator*(
) noexcept(::cuda::std::is_nothrow_copy_constructible_v<_Iter>)#

Returns a proxy that transforms the input upon assignment.

template<class _Iter2 = _Iter, ::cuda::std::enable_if_t<::cuda::std::__iter_can_subscript<_Iter2>, int> = 0>
inline constexpr auto operator[](
difference_type __n,
) const noexcept(::cuda::std::is_nothrow_copy_constructible_v<_Iter2> && noexcept(__current_ + __n))#

Subscripts the transform_output_iterator.

Parameters:

__n – The number of elements to advance by

Returns:

A proxy that transforms the input upon assignment storing the current iterator advanced by a given

template<class _Iter2 = _Iter, ::cuda::std::enable_if_t<::cuda::std::__iter_can_subscript<_Iter2>, int> = 0>
inline constexpr auto operator[](
difference_type __n,
) noexcept(::cuda::std::is_nothrow_copy_constructible_v<_Iter2> && noexcept(__current_ + __n))#

Subscripts the transform_output_iterator.

Parameters:

__n – The number of elements to advance by

Returns:

A proxy that transforms the input upon assignment storing the current iterator advanced by a given

inline constexpr transform_output_iterator &operator++(
) noexcept(noexcept(++__current_))#

Increments the stored iterator.

inline constexpr auto operator++(
int,
) noexcept(noexcept(++__current_))#

Increments the stored iterator.

template<class _Iter2 = _Iter, ::cuda::std::enable_if_t<::cuda::std::__iter_can_decrement<_Iter2>, int> = 0>
inline constexpr transform_output_iterator &operator--(
) noexcept(noexcept(--__current_))#

Decrements the stored iterator.

template<class _Iter2 = _Iter, ::cuda::std::enable_if_t<::cuda::std::__iter_can_decrement<_Iter2>, int> = 0>
inline constexpr transform_output_iterator operator--(
int,
) noexcept(::cuda::std::is_nothrow_copy_constructible_v<_Iter> && noexcept(--__current_))#

Decrements the stored iterator.

template<class _Iter2 = _Iter, ::cuda::std::enable_if_t<::cuda::std::__iter_can_plus_equal<_Iter2>, int> = 0>
inline constexpr transform_output_iterator &operator+=(
difference_type __n,
) noexcept(noexcept(__current_ += __n))#

Increments the transform_output_iterator by a given number of elements.

Parameters:

__n – The number of elements to increment

template<class _Iter2 = _Iter, ::cuda::std::enable_if_t<::cuda::std::__iter_can_minus_equal<_Iter2>, int> = 0>
inline constexpr transform_output_iterator &operator-=(
difference_type __n,
) noexcept(noexcept(__current_ -= __n))#

Decrements the transform_output_iterator by a given number of elements.

Parameters:

__n – The number of elements to decrement

Friends

template<class _Iter2 = _Iter>
inline friend constexpr auto operator+(
const transform_output_iterator &__iter,
difference_type __n,
) noexcept(::cuda::std::is_nothrow_copy_constructible_v<_Iter2> && noexcept(::cuda::std::declval<const _Iter2&>() + difference_type{})) -> transform_output_iterator#
requires (::cuda::std::__iter_can_plus<_Iter2>)

Returns a copy of a transform_output_iterator incremented by a given number of elements.

Parameters:
template<class _Iter2 = _Iter>
inline friend constexpr auto operator+(
difference_type __n,
const transform_output_iterator &__iter,
) noexcept(::cuda::std::is_nothrow_copy_constructible_v<_Iter2> && noexcept(::cuda::std::declval<const _Iter2&>() + difference_type{})) -> transform_output_iterator#
requires (::cuda::std::__iter_can_plus<_Iter2>)

Returns a copy of a transform_output_iterator incremented by a given number of elements.

Parameters:
template<class _Iter2 = _Iter>
inline friend constexpr auto operator-(
const transform_output_iterator &__iter,
difference_type __n,
) noexcept(::cuda::std::is_nothrow_copy_constructible_v<_Iter2> && noexcept(::cuda::std::declval<const _Iter2&>() - difference_type{})) -> transform_output_iterator#
requires (::cuda::std::__iter_can_minus<_Iter2>)

Returns a copy of a transform_output_iterator decremented by a given number of elements.

Parameters:
template<class _Iter2 = _Iter>
inline friend constexpr auto operator-(
const transform_output_iterator &__lhs,
const transform_output_iterator &__rhs,
) noexcept(noexcept(::cuda::std::declval<const _Iter2&>() - ::cuda::std::declval<const _Iter2&>())) -> difference_type#
requires (::cuda::std::sized_sentinel_for<_Iter2, _Iter2>)

Returns the distance between two transform_output_iterator.

template<class _Iter2 = _Iter>
inline friend constexpr auto operator==(
const transform_output_iterator &__lhs,
const transform_output_iterator &__rhs,
) noexcept(noexcept(::cuda::std::declval<const _Iter2&>() == ::cuda::std::declval<const _Iter2&>())) -> bool#
requires (::cuda::std::equality_comparable<_Iter2>)

Compares two transform_output_iterator for equality by comparing the stored iterators.

template<class _Iter2 = _Iter>
inline friend constexpr auto operator<(
const transform_output_iterator &__lhs,
const transform_output_iterator &__rhs,
) noexcept(noexcept(::cuda::std::declval<const _Iter2&>() < ::cuda::std::declval<const _Iter2&>())) -> bool#
requires (::cuda::std::random_access_iterator<_Iter2>)

Compares two transform_output_iterator for less than by comparing the stored iterators.

template<class _Iter2 = _Iter>
inline friend constexpr auto operator>(
const transform_output_iterator &__lhs,
const transform_output_iterator &__rhs,
) noexcept(noexcept(::cuda::std::declval<const _Iter2&>() < ::cuda::std::declval<const _Iter2&>())) -> bool#
requires (::cuda::std::random_access_iterator<_Iter2>)

Compares two transform_output_iterator for greater than by comparing the stored iterators.

template<class _Iter2 = _Iter>
inline friend constexpr auto operator<=(
const transform_output_iterator &__lhs,
const transform_output_iterator &__rhs,
) noexcept(noexcept(::cuda::std::declval<const _Iter2&>() < ::cuda::std::declval<const _Iter2&>())) -> bool#
requires (::cuda::std::random_access_iterator<_Iter2>)

Compares two transform_output_iterator for less equal by comparing the stored iterators.

template<class _Iter2 = _Iter>
inline friend constexpr auto operator>=(
const transform_output_iterator &__lhs,
const transform_output_iterator &__rhs,
) noexcept(noexcept(::cuda::std::declval<const _Iter2&>() < ::cuda::std::declval<const _Iter2&>())) -> bool#
requires (::cuda::std::random_access_iterator<_Iter2>)

Compares two transform_output_iterator for greater equal by comparing the stored iterators.

template<class _Iter, class _InputFn, class _OutputFn>
inline constexpr auto make_transform_input_output_iterator(
_Iter __iter,
_InputFn __input_fun,
_OutputFn __output_fun,
)#

make_transform_output_iterator creates a transform_output_iterator from an iterator, an input functor and an output functor

Parameters:

  • __iter – The iterator pointing to the input range of the newly created transform_output_iterator.

  • __input_fun – The input functor used to transform the range when read

  • __output_fun – The output functor used to transform the range when written

template<class _Iter, class _Fn>
inline constexpr auto make_transform_output_iterator(
_Iter __iter,
_Fn __fun,
)#

Creates a transform_output_iterator from an iterator and an output function.

Parameters:

  • __iter – The iterator of the input range

  • __fun – The output function