Transform Iterator

Summary

Iterator that applies a given function to an element of a sequence, and returns the result of the function.

Header

#include "tbb/iterators.h"

Syntax

template <typename UnaryFunc, typename Iter>
class transform_iterator {
public:
    typedef typename std::iterator_traits<Iter>::value_type value_type;
    typedef typename std::iterator_traits<Iter>::difference_type difference_type;
#if __cplusplus >= 201703L
    typedef typename std::invoke_result<UnaryFunc, typename std::iterator_traits<Iter>::reference>::type reference;
#else
    typedef typename std::result_of<UnaryFunc(typename std::iterator_traits<Iter>::reference)>::type reference;
#endif
    typedef typename std::iterator_traits<Iter>::pointer pointer;
    typedef typename std::random_access_iterator_tag iterator_category;

    transform_iterator(Iter it, UnaryFunc unary_func);
    transform_iterator(const transform_iterator& input);
    transform_iterator& operator=(const transform_iterator& input);
    reference operator*() const;
    reference operator[](difference_type i) const;
    transform_iterator& operator++();
    transform_iterator& operator--();
    transform_iterator operator++(int);
    transform_iterator operator--(int);
    transform_iterator operator+(difference_type forward) const;
    transform_iterator operator-(difference_type backward) const;
    transform_iterator& operator+=(difference_type forward);
    transform_iterator& operator-=(difference_type backward);
    friend transform_iterator operator+(difference_type forward, const transform_iterator& it);
    difference_type operator-(const transform_iterator& it) const;
    bool operator==(const transform_iterator& it) const;
    bool operator!=(const transform_iterator& it) const;
    bool operator<(const transform_iterator& it) const;
    bool operator>(const transform_iterator& it) const;
    bool operator<=(const transform_iterator& it) const;
    bool operator>=(const transform_iterator& it) const;
    Iter base() const;
};

template<typename UnaryFunc, typename Iter>
transform_iterator<UnaryFunc, Iter> make_transform_iterator(Iter it, UnaryFunc unary_func);

Description

A transform_iterator is a random-access iterator that applies a transformation to a sequence. The transformation, a given function, is applied upon dereferencing of the iterator itself to the dereferenced value of an underlying iterator. Expressing a pattern this way can be efficient since the transformed sequence can be consumed for example by an algorithm without storing temporary values in memory. Function make_transform_iterator returns a transform_iterator object with underlying iterator and custom functor set.

Example

The following example illustrates calculations performed by getting data from an array a, and performing a reduction by summing up the squares.

#include <vector>
#include <numeric>
#include <tbb/iterators.h>

int main() {
    const int N = 10;
    std::vector<float> a(N);
    std::iota(a.begin(), a.end(), 0);
    auto fun = [](const auto &x){ return x * x; };
    int sum = std::reduce(tbb::make_transform_iterator(a.begin(), fun),
                          tbb::make_transform_iterator(a.end(), fun));
    return 0;
}
For more complete information about compiler optimizations, see our Optimization Notice.