+
-
-
-
-
-
In this section we'll walk through the implementation of a few
-iterators using iterator_facade, based around the simple
-example of a linked list of polymorphic objects.
-
-
-
-
Say we've written a polymorphic linked list node base class:
-
-# include <iostream>
-
-struct node_base
-{
- node_base() : m_next(0) {}
-
- // Each node manages all of its tail nodes
- virtual ~node_base() { delete m_next; }
-
- // Access the rest of the list
- node_base* next() const { return m_next; }
-
- // print to the stream
- virtual void print(std::ostream& s) const = 0;
-
- // double the value
- virtual void double_me() = 0;
-
- void append(node_base* p)
- {
- if (m_next)
- m_next->append(p);
- else
- m_next = p;
- }
-
- private:
- node_base* m_next;
-};
-
-
Lists can hold objects of different types by linking together
-specializations of the following template:
-
-template <class T>
-struct node : node_base
-{
- node(T x)
- : m_value(x)
- {}
-
- void print(std::ostream& s) const { s << this->m_value; }
- void double_me() { m_value += m_value; }
-
- private:
- T m_value;
-};
-
-
And we can print any node using the following streaming operator:
-
-inline std::ostream& operator<<(std::ostream& s, node_base const& n)
-{
- n.print(s);
- return s;
-}
-
-
Our first challenge is to build an appropriate iterator over these
-lists.
-
-
-
-
We will construct a node_iterator class using inheritance from
-iterator_facade to implement most of the iterator's operations.
-
-# include "node.hpp"
-# include <boost/iterator/iterator_facade.hpp>
-
-class node_iterator
- : public boost::iterator_facade<...>
-{
- ...
-};
-
-
-
-
iterator_facade has several template parameters, so we must decide
-what types to use for the arguments. The parameters are Derived,
-Value, CategoryOrTraversal, Reference, and Difference.
-
-
-
Because iterator_facade is meant to be used with the CRTP
-[Cop95] the first parameter is the iterator class name itself,
-node_iterator.
-
-
-
-
The Value parameter determines the node_iterator's
-value_type. In this case, we are iterating over node_base
-objects, so Value will be node_base.
-
-
-
-
Now we have to determine which iterator traversal concept our
-node_iterator is going to model. Singly-linked lists only have
-forward links, so our iterator can't can't be a bidirectional
-traversal iterator. Our iterator should be able to make multiple
-passes over the same linked list (unlike, say, an
-istream_iterator which consumes the stream it traverses), so it
-must be a forward traversal iterator. Therefore, we'll pass
-boost::forward_traversal_tag in this position .
-
-
-
-
The Reference argument becomes the type returned by
-node_iterator's dereference operation, and will also be the
-same as std::iterator_traits<node_iterator>::reference. The
-library's default for this parameter is Value&; since
-node_base& is a good choice for the iterator's reference
-type, we can omit this argument, or pass use_default.
-
-
-
-
The Difference argument determines how the distance between
-two node_iterators will be measured and will also be the
-same as std::iterator_traits<node_iterator>::difference_type.
-The library's default for Difference is std::ptrdiff_t, an
-appropriate type for measuring the distance between any two
-addresses in memory, and one that works for almost any iterator,
-so we can omit this argument, too.
-
The declaration of node_iterator will therefore look something
-like:
-
-# include "node.hpp"
-# include <boost/iterator/iterator_facade.hpp>
-
-class node_iterator
- : public boost::iterator_facade<
- node_iterator
- , node_base
- , boost::forward_traversal_tag
- >
-{
- ...
-};
-
-
-
-
-
-
Next we need to decide how to represent the iterator's position.
-This representation will take the form of data members, so we'll
-also need to write constructors to initialize them. The
-node_iterator's position is quite naturally represented using
-a pointer to a node_base. We'll need a constructor to build an
-iterator from a node_base*, and a default constructor to
-satisfy the forward traversal iterator requirements .
-Our node_iterator then becomes:
-
-# include "node.hpp"
-# include <boost/iterator/iterator_facade.hpp>
-
-class node_iterator
- : public boost::iterator_facade<
- node_iterator
- , node_base
- , boost::forward_traversal_tag
- >
-{
- public:
- node_iterator()
- : m_node(0)
- {}
-
- explicit node_iterator(node_base* p)
- : m_node(p)
- {}
-
- private:
- ...
- node_base* m_node;
-};
-
-
-
-
-
-
The last step is to implement the core operations required by
-the concepts we want our iterator to model. Referring to the
-table, we can see that the first three rows are applicable
-because node_iterator needs to satisfy the requirements for
-readable iterator, single pass iterator, and incrementable
-iterator.
-
We therefore need to supply dereference,
-equal, and increment members. We don't want these members
-to become part of node_iterator's public interface, so we can
-make them private and grant friendship to
-boost::iterator_core_access, a "back-door" that
-iterator_facade uses to get access to the core operations:
-
-# include "node.hpp"
-# include <boost/iterator/iterator_facade.hpp>
-
-class node_iterator
- : public boost::iterator_facade<
- node_iterator
- , node_base
- , boost::forward_traversal_tag
- >
-{
- public:
- node_iterator()
- : m_node(0) {}
-
- explicit node_iterator(node_base* p)
- : m_node(p) {}
-
- private:
- friend class boost::iterator_core_access;
-
- void increment() { m_node = m_node->next(); }
-
- bool equal(node_iterator const& other) const
- {
- return this->m_node == other.m_node;
- }
-
- node_base& dereference() const { return *m_node; }
-
- node_base* m_node;
-};
-
-
Voilà; a complete and conforming readable, forward-traversal
-iterator! For a working example of its use, see this program.
-
-
-
-
-
-
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;
-};
-
-
-
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;
-
-
-
-
-
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 :
-
-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;
-
-
-
-
You can see an example program which exercises our interoperable
-iterators here.
-
-
-
-
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.
-
In fact, that sort of magic is possible using
-boost::enable_if. By rewriting the converting constructor as
-follows, we can remove it from the overload set when it's not
-appropriate:
-
-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) {}
-
-
-
-
-
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.
-
-
-
+
+
+
+
In this section we'll walk through the implementation of a few
+iterators using iterator_facade, based around the simple
+example of a linked list of polymorphic objects. This example was
+inspired by a posting by Keith Macdonald on the Boost-Users
+mailing list.
+
+
+
Say we've written a polymorphic linked list node base class:
+
+# include <iostream>
+
+struct node_base
+{
+ node_base() : m_next(0) {}
+
+ // Each node manages all of its tail nodes
+ virtual ~node_base() { delete m_next; }
+
+ // Access the rest of the list
+ node_base* next() const { return m_next; }
+
+ // print to the stream
+ virtual void print(std::ostream& s) const = 0;
+
+ // double the value
+ virtual void double_me() = 0;
+
+ void append(node_base* p)
+ {
+ if (m_next)
+ m_next->append(p);
+ else
+ m_next = p;
+ }
+
+ private:
+ node_base* m_next;
+};
+
+
Lists can hold objects of different types by linking together
+specializations of the following template:
+
+template <class T>
+struct node : node_base
+{
+ node(T x)
+ : m_value(x)
+ {}
+
+ void print(std::ostream& s) const { s << this->m_value; }
+ void double_me() { m_value += m_value; }
+
+ private:
+ T m_value;
+};
+
+
And we can print any node using the following streaming operator:
+
+inline std::ostream& operator<<(std::ostream& s, node_base const& n)
+{
+ n.print(s);
+ return s;
+}
+
+
Our first challenge is to build an appropriate iterator over these
+lists.
+
+
+
+
We will construct a node_iterator class using inheritance from
+iterator_facade to implement most of the iterator's operations.
+
+# include "node.hpp"
+# include <boost/iterator/iterator_facade.hpp>
+
+class node_iterator
+ : public boost::iterator_facade<...>
+{
+ ...
+};
+
+
+
+
iterator_facade has several template parameters, so we must decide
+what types to use for the arguments. The parameters are Derived,
+Value, CategoryOrTraversal, Reference, and Difference.
+
+
+
Because iterator_facade is meant to be used with the CRTP
+[Cop95] the first parameter is the iterator class name itself,
+node_iterator.
+
+
+
+
The Value parameter determines the node_iterator's
+value_type. In this case, we are iterating over node_base
+objects, so Value will be node_base.
+
+
+
+
Now we have to determine which iterator traversal concept our
+node_iterator is going to model. Singly-linked lists only have
+forward links, so our iterator can't can't be a bidirectional
+traversal iterator. Our iterator should be able to make multiple
+passes over the same linked list (unlike, say, an
+istream_iterator which consumes the stream it traverses), so it
+must be a forward traversal iterator. Therefore, we'll pass
+boost::forward_traversal_tag in this position .
+
+
+
+
+
The Reference argument becomes the type returned by
+node_iterator's dereference operation, and will also be the
+same as std::iterator_traits<node_iterator>::reference. The
+library's default for this parameter is Value&; since
+node_base& is a good choice for the iterator's reference
+type, we can omit this argument, or pass use_default.
+
+
+
+
The Difference argument determines how the distance between
+two node_iterators will be measured and will also be the
+same as std::iterator_traits<node_iterator>::difference_type.
+The library's default for Difference is std::ptrdiff_t, an
+appropriate type for measuring the distance between any two
+addresses in memory, and one that works for almost any iterator,
+so we can omit this argument, too.
+
The declaration of node_iterator will therefore look something
+like:
+
+# include "node.hpp"
+# include <boost/iterator/iterator_facade.hpp>
+
+class node_iterator
+ : public boost::iterator_facade<
+ node_iterator
+ , node_base
+ , boost::forward_traversal_tag
+ >
+{
+ ...
+};
+
+
+
+
+
+
Next we need to decide how to represent the iterator's position.
+This representation will take the form of data members, so we'll
+also need to write constructors to initialize them. The
+node_iterator's position is quite naturally represented using
+a pointer to a node_base. We'll need a constructor to build an
+iterator from a node_base*, and a default constructor to
+satisfy the forward traversal iterator requirements .
+Our node_iterator then becomes:
+
+# include "node.hpp"
+# include <boost/iterator/iterator_facade.hpp>
+
+class node_iterator
+ : public boost::iterator_facade<
+ node_iterator
+ , node_base
+ , boost::forward_traversal_tag
+ >
+{
+ public:
+ node_iterator()
+ : m_node(0)
+ {}
+
+ explicit node_iterator(node_base* p)
+ : m_node(p)
+ {}
+
+ private:
+ ...
+ node_base* m_node;
+};
+
+
+
+
+
+
The last step is to implement the core operations required by
+the concepts we want our iterator to model. Referring to the
+table, we can see that the first three rows are applicable
+because node_iterator needs to satisfy the requirements for
+readable iterator, single pass iterator, and incrementable
+iterator.
+
We therefore need to supply dereference,
+equal, and increment members. We don't want these members
+to become part of node_iterator's public interface, so we can
+make them private and grant friendship to
+boost::iterator_core_access, a "back-door" that
+iterator_facade uses to get access to the core operations:
+
+# include "node.hpp"
+# include <boost/iterator/iterator_facade.hpp>
+
+class node_iterator
+ : public boost::iterator_facade<
+ node_iterator
+ , node_base
+ , boost::forward_traversal_tag
+ >
+{
+ public:
+ node_iterator()
+ : m_node(0) {}
+
+ explicit node_iterator(node_base* p)
+ : m_node(p) {}
+
+ private:
+ friend class boost::iterator_core_access;
+
+ void increment() { m_node = m_node->next(); }
+
+ bool equal(node_iterator const& other) const
+ {
+ return this->m_node == other.m_node;
+ }
+
+ node_base& dereference() const { return *m_node; }
+
+ node_base* m_node;
+};
+
+
Voilà; a complete and conforming readable, forward-traversal
+iterator! For a working example of its use, see this program.
+
+
+
+
+
+
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;
+};
+
+
+
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;
+
+
+
+
+
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 :
+
+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;
+
+
+
+
You can see an example program which exercises our interoperable
+iterators here.
+
+
+
+
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.
+
In fact, that sort of magic is possible using
+boost::enable_if. By rewriting the converting constructor as
+follows, we can remove it from the overload set when it's not
+appropriate:
+
+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) {}
+
+
+
+
+
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.
+
+