iterator/doc/quickbook/transform_iterator.qbk

[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<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


The source code for this example can be found 
[@../example/transform_iterator_example.cpp here].

[h2 Reference]


[h3 Synopsis]

  template <class UnaryFunction,
            class Iterator, 
            class Reference = use_default, 
            class Value = use_default>
  class transform_iterator
  {
  public:
    typedef /* see below */ value_type;
    typedef /* see below */ reference;
    typedef /* see below */ pointer;
    typedef iterator_traits<Iterator>::difference_type difference_type;
    typedef /* see below */ iterator_category;

    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 only
        , typename enable_if_convertible<F2, UnaryFunction>::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<const UnaryFunction(iterator_traits<Iterator>::reference)>::type`.
Otherwise, `reference` is `Reference`.


If `Value` is `use_default` then the `value_type` member is
`remove_cv<remove_reference<reference> >::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<const UnaryFunction(iterator_traits<Iterator>::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<F1, X, R1, V1>` is interoperable with
`transform_iterator<F2, Y, R2, V2>` 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<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 only
      , typename enable_if_convertible<F2, UnaryFunction>::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]