123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135 |
- .. 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
|