[section:transform Transform Iterator] The transform iterator adapts an iterator by modifying the `operator*` to apply a function object to the result of dereferencing the iterator and returning the result. [h2 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 > Function; typedef boost::transform_iterator doubling_iterator; doubling_iterator i(x, boost::bind1st(std::multiplies(), 2)), i_end(x + N, boost::bind1st(std::multiplies(), 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(), 4)), boost::make_transform_iterator(x + N, boost::bind1st(std::plus(), 4)), std::ostream_iterator(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 The source code for this example can be found [@../example/transform_iterator_example.cpp here]. [h2 Reference] [h3 Synopsis] template class transform_iterator { public: typedef /* see below */ value_type; typedef /* see below */ reference; typedef /* see below */ pointer; typedef iterator_traits::difference_type difference_type; typedef /* see below */ iterator_category; transform_iterator(); transform_iterator(Iterator const& x, UnaryFunction f); template transform_iterator( transform_iterator const& t , typename enable_if_convertible::type* = 0 // exposition only , typename enable_if_convertible::type* = 0 // exposition only ); UnaryFunction functor() const; Iterator const& base() const; reference operator*() const; transform_iterator& operator++(); transform_iterator& operator--(); private: Iterator m_iterator; // exposition only UnaryFunction m_f; // exposition only }; If `Reference` is `use_default` then the `reference` member of `transform_iterator` is[br] `result_of::reference)>::type`. Otherwise, `reference` is `Reference`. If `Value` is `use_default` then the `value_type` member is `remove_cv >::type`. Otherwise, `value_type` is `Value`. If `Iterator` models Readable Lvalue Iterator and if `Iterator` models Random Access Traversal Iterator, then `iterator_category` is convertible to `random_access_iterator_tag`. Otherwise, if `Iterator` models Bidirectional Traversal Iterator, then `iterator_category` is convertible to `bidirectional_iterator_tag`. Otherwise `iterator_category` is convertible to `forward_iterator_tag`. If `Iterator` does not model Readable Lvalue Iterator then `iterator_category` is convertible to `input_iterator_tag`. [h3 Requirements] The type `UnaryFunction` must be Assignable, Copy Constructible, and the expression `f(*i)` must be valid where `f` is a const object of type `UnaryFunction`, `i` is an object of type `Iterator`, and where the type of `f(*i)` must be `result_of::reference)>::type`. The argument `Iterator` shall model Readable Iterator. [h3 Concepts] The resulting `transform_iterator` models the most refined of the following that is also modeled by `Iterator`. * Writable Lvalue Iterator if `transform_iterator::reference` is a non-const reference. * Readable Lvalue Iterator if `transform_iterator::reference` is a const reference. * Readable Iterator otherwise. The `transform_iterator` models the most refined standard traversal concept that is modeled by the `Iterator` argument. If `transform_iterator` is a model of Readable Lvalue Iterator then it models the following original iterator concepts depending on what the `Iterator` argument models. [table Category [[If `Iterator` models][then `transform_iterator` models]] [[Single Pass Iterator][Input Iterator]] [[Forward Traversal Iterator][Forward Iterator]] [[Bidirectional Traversal Iterator][Bidirectional Iterator]] [[Random Access Traversal Iterator][Random Access Iterator]] ] If `transform_iterator` models Writable Lvalue Iterator then it is a mutable iterator (as defined in the old iterator requirements). `transform_iterator` is interoperable with `transform_iterator` if and only if `X` is interoperable with `Y`. [h3 Operations] In addition to the operations required by the [link iterator.specialized.transform.concepts concepts] modeled by `transform_iterator`, `transform_iterator` provides the following operations: transform_iterator(); [*Returns: ] An instance of `transform_iterator` with `m_f` and `m_iterator` default constructed. transform_iterator(Iterator const& x, UnaryFunction f); [*Returns: ] An instance of `transform_iterator` with `m_f` initialized to `f` and `m_iterator` initialized to `x`. template transform_iterator( transform_iterator const& t , typename enable_if_convertible::type* = 0 // exposition only , typename enable_if_convertible::type* = 0 // exposition only ); [*Returns: ] An instance of `transform_iterator` with `m_f` initialized to `t.functor()` and `m_iterator` initialized to `t.base()`.[br] [*Requires: ] `OtherIterator` is implicitly convertible to `Iterator`. UnaryFunction functor() const; [*Returns: ] `m_f` Iterator const& base() const; [*Returns: ] `m_iterator` reference operator*() const; [*Returns: ] `m_f(*m_iterator)` transform_iterator& operator++(); [*Effects: ] `++m_iterator`[br] [*Returns: ] `*this` transform_iterator& operator--(); [*Effects: ] `--m_iterator`[br] [*Returns: ] `*this` [endsect]