transform_iterator synopsis

template <class UnaryFunction,
          class Iterator, 
          class Reference = use_default, 
          class Value = use_default>
class transform_iterator
{
public:
  transform_iterator();
  transform_iterator(Iterator const& x, UnaryFunction f);

  template<class F2, class I2, class R2, class V2>
  transform_iterator(
        transform_iterator<F2, I2, R2, V2> const& t
      , typename enable_if_convertible<I2, Iterator>::type* = 0      // exposition
      , typename enable_if_convertible<F2, UnaryFunction>::type* = 0 // exposition
  );
  Iterator base() const;
  UnaryFunction functor() const;
  reference operator*() const;
  transform_iterator& operator++();
  transform_iterator& operator--();
private:
  Iterator m_iterator; // exposition
  UnaryFunction m_f;   // exposition
};

transform_iterator requirements

The type UnaryFunction must be Assignable, Copy Constructible, and the expression f(*i) must be valid where f is an object of type UnaryFunction, i is an object of type Iterator, and where the type of f(*i) must be result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type.

The type Iterator must at least model Readable Iterator.

transform_iterator models

The resulting transform_iterator models the most refined of the following options that is also modeled by Iterator.

• Writable Lvalue Iterator if result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type is a non-const reference.
• Readable Lvalue Iterator if result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type is a const reference.
• Readable Iterator otherwise.

The transform_iterator models the most refined standard traversal concept that is modeled by Iterator.

The reference type of transform_iterator is result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type. The value_type is remove_cv<remove_reference<reference> >::type.

transform_iterator operations

In addition to the operations required by the concepts modeled by transform_iterator, transform_iterator provides the following operations.

transform_iterator();

transform_iterator(Iterator const& x, UnaryFunction f);

template<class OtherIterator, class R2, class V2>
transform_iterator(
      transform_iterator<UnaryFunction, OtherIterator, R2, V2> const& t
    , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
);

Iterator base() const;

UnaryFunction functor() const;

reference operator*() const;

transform_iterator& operator++();

transform_iterator& operator--();

template <class UnaryFunction, class Iterator>
transform_iterator<UnaryFunction, Iterator>
make_transform_iterator(Iterator it, UnaryFunction fun);

template <class UnaryFunction, class Iterator>
transform_iterator<UnaryFunction, Iterator>
make_transform_iterator(Iterator it);

Example

This is a simple example of using the transform_iterators class to generate iterators that multiply (or add to) the value returned by dereferencing the iterator. It would be cooler to use lambda library in this example.

int x[] = { 1, 2, 3, 4, 5, 6, 7, 8 };
const int N = sizeof(x)/sizeof(int);

typedef boost::binder1st< std::multiplies<int> > Function;
typedef boost::transform_iterator<Function, int*> doubling_iterator;

doubling_iterator i(x, boost::bind1st(std::multiplies<int>(), 2)),
  i_end(x + N, boost::bind1st(std::multiplies<int>(), 2));

std::cout << "multiplying the array by 2:" << std::endl;
while (i != i_end)
  std::cout << *i++ << " ";
std::cout << std::endl;

std::cout << "adding 4 to each element in the array:" << std::endl;
std::copy(boost::make_transform_iterator(x, boost::bind1st(std::plus<int>(), 4)),
          boost::make_transform_iterator(x + N, boost::bind1st(std::plus<int>(), 4)),
          std::ostream_iterator<int>(std::cout, " "));
std::cout << std::endl;

The output is:

multiplying the array by 2:
2 4 6 8 10 12 14 16 
adding 4 to each element in the array:
5 6 7 8 9 10 11 12