facade_tutorial.qbk

来自「Boost provides free peer-reviewed portab」· QBK 代码 · 共 508 行 · 第 1/2 页

Voila; a complete and conforming readable, forward-traversal
iterator!  For a working example of its use, see 
[@../example/node_iterator1.cpp `this program`].

__ ../example/node_iterator1.cpp

[h2 A constant `node_iterator`]

[blurb *Constant and Mutable iterators*\n\n
The term **mutable iterator** means an iterator through which
the object it references (its "referent") can be modified.  A
**constant iterator** is one which doesn't allow modification of
its referent.\n\n  
The words *constant* and *mutable* don't refer to the ability to
modify the iterator itself.  For example, an `int const*` is a
non-\ `const` *constant iterator*, which can be incremented
but doesn't allow modification of its referent, and `int*
const` is a `const` *mutable iterator*, which cannot be
modified but which allows modification of its referent.\n\n
Confusing?  We agree, but those are the standard terms.  It
probably doesn't help much that a container's constant iterator
is called `const_iterator`.
]

Now, our `node_iterator` gives clients access to both `node`\
's `print(std::ostream&) const` member function, but also its
mutating `double_me()` member.  If we wanted to build a
*constant* `node_iterator`, we'd only have to make three
changes:

  class const_node_iterator
    : public boost::iterator_facade<
          node_iterator
        , node_base **const**
        , boost::forward_traversal_tag
      >
  {
   public:
      const_node_iterator()
        : m_node(0) {}

      explicit const_node_iterator(node_base* p)
        : m_node(p) {}

   private:
      friend class boost::iterator_core_access;

      void increment() { m_node = m_node->next(); }

      bool equal(const_node_iterator const& other) const
      {
          return this->m_node == other.m_node;
      }

      node_base **const**\ & dereference() const { return \*m_node; }

      node_base **const**\ * m_node;
  };

[blurb `const` and an iterator's `value_type`\n\n
The C++ standard requires an iterator's `value_type` *not* be
`const`\ -qualified, so `iterator_facade` strips the
`const` from its `Value` parameter in order to produce the
iterator's `value_type`.  Making the `Value` argument
`const` provides a useful hint to `iterator_facade` that the
iterator is a *constant iterator*, and the default `Reference`
argument will be correct for all lvalue iterators.
]

As a matter of fact, `node_iterator` and `const_node_iterator`
are so similar that it makes sense to factor the common code out
into a template as follows:

  template <class Value>
  class node_iter
    : public boost::iterator_facade<
          node_iter<Value>
        , Value
        , boost::forward_traversal_tag
      >
  {
   public:
      node_iter()
        : m_node(0) {}

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

   private:
      friend class boost::iterator_core_access;

      bool equal(node_iter<Value> const& other) const
      {
          return this->m_node == other.m_node;
      }

      void increment()
      { m_node = m_node->next(); }

      Value& dereference() const
      { return *m_node; }

      Value* m_node;
  };
  typedef node_iter<node_base> node_iterator;
  typedef node_iter<node_base const> node_const_iterator;


[h2 Interoperability]

Our `const_node_iterator` works perfectly well on its own, but
taken together with `node_iterator` it doesn't quite meet
expectations.  For example, we'd like to be able to pass a
`node_iterator` where a `node_const_iterator` was expected,
just as you can with `std::list<int>`\ 's `iterator` and
`const_iterator`.  Furthermore, given a `node_iterator` and a
`node_const_iterator` into the same list, we should be able to
compare them for equality.

This expected ability to use two different iterator types together
is known as |interoperability|_.  Achieving interoperability in
our case is as simple as templatizing the `equal` function and
adding a templatized converting constructor [#broken]_ [#random]_:

  template <class Value>
  class node_iter
    : public boost::iterator_facade<
          node_iter<Value>
        , Value
        , boost::forward_traversal_tag
      >
  {
   public:
      node_iter()
        : m_node(0) {}

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

      template <class OtherValue>
      node_iter(node_iter<OtherValue> const& other)
        : m_node(other.m_node) {}

   private:
      friend class boost::iterator_core_access;
      template <class> friend class node_iter;

      template <class OtherValue>
      bool equal(node_iter<OtherValue> const& other) const
      { 
          return this->m_node == other.m_node;
      }

      void increment()
      { m_node = m_node->next(); }

      Value& dereference() const
      { return *m_node; }

      Value* m_node;
  };
  typedef impl::node_iterator<node_base> node_iterator;
  typedef impl::node_iterator<node_base const> node_const_iterator;

.. |interoperability| replace:: **interoperability**
.. _interoperability: new-iter-concepts.html#interoperable-iterators-lib-interoperable-iterators

.. [#broken] If you're using an older compiler and it can't handle
   this example, see the `example code`__ for workarounds.

.. [#random] If `node_iterator` had been a `random access
   traversal iterator`_, we'd have had to templatize its
   `distance_to` function as well.


__ ../example/node_iterator2.hpp

You can see an example program which exercises our interoperable
iterators 
[@../example/node_iterator2.cpp `here`].


[h2 Telling the Truth]

Now `node_iterator` and `node_const_iterator` behave exactly as
you'd expect... almost.  We can compare them and we can convert in
one direction: from `node_iterator` to `node_const_iterator`.
If we try to convert from `node_const_iterator` to
`node_iterator`, we'll get an error when the converting
constructor tries to initialize `node_iterator`\ 's `m_node`, a
`node*` with a `node const*`.  So what's the problem?

The problem is that
`boost::`\ |is_convertible|_\ `<node_const_iterator,node_iterator>::value`
will be `true`, but it should be `false`.  |is_convertible|_
lies because it can only see as far as the *declaration* of
`node_iter`\ 's converting constructor, but can't look inside at
the *definition* to make sure it will compile.  A perfect solution
would make `node_iter`\ 's converting constructor disappear when
the `m_node` conversion would fail.

.. |is_convertible| replace:: `is_convertible`
.. _is_convertible:  ../../type_traits/index.html#relationships

In fact, that sort of magic is possible using
|enable_if|__.  By rewriting the converting constructor as
follows, we can remove it from the overload set when it's not
appropriate:

  #include <boost/type_traits/is_convertible.hpp>
  #include <boost/utility/enable_if.hpp>

    ...

  private: 
    struct enabler {};

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

.. |enable_if| replace:: `boost::enable_if`
__ ../../utility/enable_if.html


[h2 Wrap Up]

This concludes our `iterator_facade` tutorial, but before you
stop reading we urge you to take a look at |iterator_adaptor|__.
There's another way to approach writing these iterators which might
even be superior.

.. |iterator_adaptor| replace:: `iterator_adaptor`
__ iterator_adaptor.html

.. _`iterator traversal concept`: new-iter-concepts.html#iterator-traversal-concepts-lib-iterator-traversal
.. _`readable iterator`: new-iter-concepts.html#readable-iterators-lib-readable-iterators
.. _`lvalue iterator`: new-iter-concepts.html#lvalue-iterators-lib-lvalue-iterators
.. _`single pass iterator`: new-iter-concepts.html#single-pass-iterators-lib-single-pass-iterators
.. _`incrementable iterator`: new-iter-concepts.html#incrementable-iterators-lib-incrementable-iterators
.. _`forward traversal iterator`: new-iter-concepts.html#forward-traversal-iterators-lib-forward-traversal-iterators
.. _`bidirectional traversal iterator`: new-iter-concepts.html#bidirectional-traversal-iterators-lib-bidirectional-traversal-iterators
.. _`random access traversal iterator`: new-iter-concepts.html#random-access-traversal-iterators-lib-random-access-traversal-iterators

[endsect]