iterator/doc/iterator_adaptor_tutorial.rst

.. Copyright David Abrahams 2004. Use, modification and distribution is
.. subject to the Boost Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

In this section we'll further refine the ``node_iter`` class
template we developed in the |fac_tut|_.  If you haven't already
read that material, you should go back now and check it out because
we're going to pick up right where it left off.

.. |fac_tut| replace:: ``iterator_facade`` tutorial
.. _fac_tut: iterator_facade.html#tutorial-example

.. sidebar:: ``node_base*`` really *is* an iterator

   It's not really a very interesting iterator, since ``node_base``
   is an abstract class: a pointer to a ``node_base`` just points
   at some base subobject of an instance of some other class, and
   incrementing a ``node_base*`` moves it past this base subobject
   to who-knows-where?  The most we can do with that incremented
   position is to compare another ``node_base*`` to it.  In other
   words, the original iterator traverses a one-element array.

You probably didn't think of it this way, but the ``node_base*``
object that underlies ``node_iterator`` is itself an iterator,
just like all other pointers.  If we examine that pointer closely
from an iterator perspective, we can see that it has much in common
with the ``node_iterator`` we're building.  First, they share most
of the same associated types (``value_type``, ``reference``,
``pointer``, and ``difference_type``).  Second, even some of the
core functionality is the same: ``operator*`` and ``operator==`` on
the ``node_iterator`` return the result of invoking the same
operations on the underlying pointer, via the ``node_iterator``\ 's
|dereference_and_equal|_).  The only real behavioral difference
between ``node_base*`` and ``node_iterator`` can be observed when
they are incremented: ``node_iterator`` follows the
``m_next`` pointer, while ``node_base*`` just applies an address offset.   

.. |dereference_and_equal| replace:: ``dereference`` and ``equal`` member functions
.. _dereference_and_equal: iterator_facade.html#implementing-the-core-operations

It turns out that the pattern of building an iterator on another
iterator-like type (the ``Base`` [#base]_ type) while modifying
just a few aspects of the underlying type's behavior is an
extremely common one, and it's the pattern addressed by
``iterator_adaptor``.  Using ``iterator_adaptor`` is very much like
using ``iterator_facade``, but because iterator_adaptor tries to
mimic as much of the ``Base`` type's behavior as possible, we
neither have to supply a ``Value`` argument, nor implement any core
behaviors other than ``increment``.  The implementation of
``node_iter`` is thus reduced to::

  template <class Value>
  class node_iter
    : public boost::iterator_adaptor<
          node_iter<Value>                // Derived
        , Value*                          // Base
        , boost::use_default              // Value
        , boost::forward_traversal_tag    // CategoryOrTraversal
      >
  {
   private:
      struct enabler {};  // a private type avoids misuse

   public:
      node_iter()
        : node_iter::iterator_adaptor_(0) {}

      explicit node_iter(Value* p)
        : node_iter::iterator_adaptor_(p) {}

      template <class OtherValue>
      node_iter(
          node_iter<OtherValue> const& other
        , typename boost::enable_if<
              boost::is_convertible<OtherValue*,Value*>
            , enabler
          >::type = enabler()
      )
        : node_iter::iterator_adaptor_(other.base()) {}

   private:
      friend class boost::iterator_core_access;
      void increment() { this->base_reference() = this->base()->next(); }
  };

Note the use of ``node_iter::iterator_adaptor_`` here: because
``iterator_adaptor`` defines a nested ``iterator_adaptor_`` type
that refers to itself, that gives us a convenient way to refer to
the complicated base class type of ``node_iter<Value>``. [Note:
this technique is known not to work with Borland C++ 5.6.4 and
Metrowerks CodeWarrior versions prior to 9.0]

You can see an example program that exercises this version of the
node iterators `here`__.

__ ../example/node_iterator3.cpp

In the case of ``node_iter``, it's not very compelling to pass
``boost::use_default`` as ``iterator_adaptor``\ 's ``Value``
argument; we could have just passed ``node_iter``\ 's ``Value``
along to ``iterator_adaptor``, and that'd even be shorter!  Most
iterator class templates built with ``iterator_adaptor`` are
parameterized on another iterator type, rather than on its
``value_type``.  For example, ``boost::reverse_iterator`` takes an
iterator type argument and reverses its direction of traversal,
since the original iterator and the reversed one have all the same
associated types, ``iterator_adaptor``\ 's delegation of default
types to its ``Base`` saves the implementor of
``boost::reverse_iterator`` from writing:

.. parsed-literal::

   std::iterator_traits<Iterator>::*some-associated-type*

at least four times.  

We urge you to review the documentation and implementations of
|reverse_iterator|_ and the other Boost `specialized iterator
adaptors`__ to get an idea of the sorts of things you can do with
``iterator_adaptor``.  In particular, have a look at
|transform_iterator|_, which is perhaps the most straightforward
adaptor, and also |counting_iterator|_, which demonstrates that
``iterator_adaptor``\ 's ``Base`` type needn't be an iterator.

.. |reverse_iterator| replace:: ``reverse_iterator``
.. _reverse_iterator: reverse_iterator.html

.. |counting_iterator| replace:: ``counting_iterator``
.. _counting_iterator: counting_iterator.html

.. |transform_iterator| replace:: ``transform_iterator``
.. _transform_iterator: transform_iterator.html

__ index.html#specialized-adaptors