<metaname="author"content="David Abrahams, Jeremy Siek, Thomas Witt"/>
<metaname="organization"content="Boost Consulting, Indiana University Open Systems Lab, University of Hanover Institute for Transport Railway Operation and Construction"/>
<td><aclass="first reference"href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <aclass="reference"href="http://www.osl.iu.edu">Open Systems
Lab</a>, University of Hanover <aclass="last reference"href="http://www.ive.uni-hannover.de">Institute for Transport
<trclass="field"><thclass="field-name">abstract:</th><tdclass="field-body"><ttclass="literal"><spanclass="pre">iterator_facade</span></tt> is a base class template that implements the
interface of standard iterators in terms of a few core functions
and associated types, to be supplied by a derived iterator class.</td>
<li><aclass="reference"href="#a-basic-iterator-using-iterator-facade"id="id30"name="id30">A Basic Iterator Using <ttclass="literal"><spanclass="pre">iterator_facade</span></tt></a><ul>
<li><aclass="reference"href="#template-arguments-for-iterator-facade"id="id31"name="id31">Template Arguments for <ttclass="literal"><spanclass="pre">iterator_facade</span></tt></a><ul>
<p>While the iterator interface is rich, there is a core subset of the
interface that is necessary for all the functionality. We have
identified the following core behaviors for iterators:</p>
<ulclass="simple">
<li>dereferencing</li>
<li>incrementing</li>
<li>decrementing</li>
<li>equality comparison</li>
<li>random-access motion</li>
<li>distance measurement</li>
</ul>
<p>In addition to the behaviors listed above, the core interface elements
include the associated types exposed through iterator traits:
<ttclass="literal"><spanclass="pre">value_type</span></tt>, <ttclass="literal"><spanclass="pre">reference</span></tt>, <ttclass="literal"><spanclass="pre">difference_type</span></tt>, and
<td>Measure the distance to <ttclass="literal"><spanclass="pre">j</span></tt></td>
</tr>
</tbody>
</table>
</blockquote>
<!-- Should we add a comment that a zero overhead implementation of iterator_facade
is possible with proper inlining? -->
<p>In addition to implementing the core interface functions, an iterator
derived from <ttclass="literal"><spanclass="pre">iterator_facade</span></tt> typically defines several
constructors. To model any of the standard iterator concepts, the
iterator must at least have a copy constructor. Also, if the iterator
type <ttclass="literal"><spanclass="pre">X</span></tt> is meant to be automatically interoperate with another
iterator type <ttclass="literal"><spanclass="pre">Y</span></tt> (as with constant and mutable iterators) then
there must be an implicit conversion from <ttclass="literal"><spanclass="pre">X</span></tt> to <ttclass="literal"><spanclass="pre">Y</span></tt> or from <ttclass="literal"><spanclass="pre">Y</span></tt>
to <ttclass="literal"><spanclass="pre">X</span></tt> (but not both), typically implemented as a conversion
constructor. Finally, if the iterator is to model Forward Traversal
Iterator or a more-refined iterator concept, a default constructor is
member (e.g. <aclass="reference"href="counting_iterator.html"><ttclass="literal"><spanclass="pre">counting_iterator</span></tt></a>), because <ttclass="literal"><spanclass="pre">*(p+n)</span></tt> is a reference
<p>Writable iterators built with <ttclass="literal"><spanclass="pre">iterator_facade</span></tt> implement the
semantics required by the preferred resolution to <aclass="reference"href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-active.html#299">issue 299</a> and
adopted by proposal <aclass="reference"href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/papers/2003/n1550.html">n1550</a>: the result of <ttclass="literal"><spanclass="pre">p[n]</span></tt> is an object
convertible to the iterator's <ttclass="literal"><spanclass="pre">value_type</span></tt>, and <ttclass="literal"><spanclass="pre">p[n]</span><spanclass="pre">=</span><spanclass="pre">x</span></tt> is
equivalent to <ttclass="literal"><spanclass="pre">*(p</span><spanclass="pre">+</span><spanclass="pre">n)</span><spanclass="pre">=</span><spanclass="pre">x</span></tt> (Note: This result object may be
implemented as a proxy containing a copy of <ttclass="literal"><spanclass="pre">p+n</span></tt>). This approach
will work properly for any random-access iterator regardless of the
other details of its implementation. A user who knows more about
the implementation of her iterator is free to implement an
<ttclass="literal"><spanclass="pre">operator[]</span></tt> that returns an lvalue in the derived iterator
class; it will hide the one supplied by <ttclass="literal"><spanclass="pre">iterator_facade</span></tt> from
<p>The <ttclass="literal"><spanclass="pre">reference</span></tt> type of a readable iterator (and today's input
iterator) need not in fact be a reference, so long as it is
convertible to the iterator's <ttclass="literal"><spanclass="pre">value_type</span></tt>. When the <ttclass="literal"><spanclass="pre">value_type</span></tt>
is a class, however, it must still be possible to access members
through <ttclass="literal"><spanclass="pre">operator-></span></tt>. Therefore, an iterator whose <ttclass="literal"><spanclass="pre">reference</span></tt>
type is not in fact a reference must return a proxy containing a copy
of the referenced value from its <ttclass="literal"><spanclass="pre">operator-></span></tt>.</p>
<p>The return types for <ttclass="literal"><spanclass="pre">iterator_facade</span></tt>'s <ttclass="literal"><spanclass="pre">operator-></span></tt> and
<ttclass="literal"><spanclass="pre">operator[]</span></tt> are not explicitly specified. Instead, those types
are described in terms of a set of requirements, which must be
satisfied by the <ttclass="literal"><spanclass="pre">iterator_facade</span></tt> implementation.</p>
<aclass="target"id="iterator-category"name="iterator-category"></a><p>The <ttclass="literal"><spanclass="pre">iterator_category</span></tt> member of <ttclass="literal"><spanclass="pre">iterator_facade</span></tt> is
<p>The <ttclass="literal"><spanclass="pre">enable_if_interoperable</span></tt> template used above is for exposition
purposes. The member operators should be only be in an overload set
provided the derived types <ttclass="literal"><spanclass="pre">Dr1</span></tt> and <ttclass="literal"><spanclass="pre">Dr2</span></tt> are interoperable,
meaning that at least one of the types is convertible to the other. The
<ttclass="literal"><spanclass="pre">enable_if_interoperable</span></tt> approach uses SFINAE to take the operators
out of the overload set when the types are not interoperable.
The operators should behave <em>as-if</em><ttclass="literal"><spanclass="pre">enable_if_interoperable</span></tt>
<p>In the table below, <ttclass="literal"><spanclass="pre">F</span></tt> is <ttclass="literal"><spanclass="pre">iterator_facade<X,V,C,R,D></span></tt>, <ttclass="literal"><spanclass="pre">a</span></tt> is an
object of type <ttclass="literal"><spanclass="pre">X</span></tt>, <ttclass="literal"><spanclass="pre">b</span></tt> and <ttclass="literal"><spanclass="pre">c</span></tt> are objects of type <ttclass="literal"><spanclass="pre">const</span><spanclass="pre">X</span></tt>,
<ttclass="literal"><spanclass="pre">n</span></tt> is an object of <ttclass="literal"><spanclass="pre">F::difference_type</span></tt>, <ttclass="literal"><spanclass="pre">y</span></tt> is a constant
object of a single pass iterator type interoperable with <ttclass="literal"><spanclass="pre">X</span></tt>, and <ttclass="literal"><spanclass="pre">z</span></tt>
is a constant object of a random access traversal iterator type
interoperable with <ttclass="literal"><spanclass="pre">X</span></tt>.</p>
<p><ttclass="literal"><spanclass="pre">operator->()</span><spanclass="pre">const;</span></tt> (see <aclass="reference"href="#operator-arrow">below</a>)</p>
<tableclass="field-list"frame="void"rules="none">
<colclass="field-name"/>
<colclass="field-body"/>
<tbodyvalign="top">
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body"><pclass="first">If <ttclass="literal"><spanclass="pre">reference</span></tt> is a reference type, an object
of type <ttclass="literal"><spanclass="pre">pointer</span></tt> equal to:</p>
<pclass="last">Otherwise returns an object of unspecified type such that,
<ttclass="literal"><spanclass="pre">(*static_cast<Derived</span><spanclass="pre">const*>(this))->m</span></tt> is equivalent to <ttclass="literal"><spanclass="pre">(w</span><spanclass="pre">=</span><spanclass="pre">**static_cast<Derived</span><spanclass="pre">const*>(this),</span>
<spanclass="pre">w.m)</span></tt> for some temporary object <ttclass="literal"><spanclass="pre">w</span></tt> of type <ttclass="literal"><spanclass="pre">value_type</span></tt>.</p>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">an object convertible to <ttclass="literal"><spanclass="pre">value_type</span></tt>. For constant
objects <ttclass="literal"><spanclass="pre">v</span></tt> of type <ttclass="literal"><spanclass="pre">value_type</span></tt>, and <ttclass="literal"><spanclass="pre">n</span></tt> of type
<ttclass="literal"><spanclass="pre">difference_type</span></tt>, <ttclass="literal"><spanclass="pre">(*this)[n]</span><spanclass="pre">=</span><spanclass="pre">v</span></tt> is equivalent to
<ttclass="literal"><spanclass="pre">*(*this</span><spanclass="pre">+</span><spanclass="pre">n)</span><spanclass="pre">=</span><spanclass="pre">v</span></tt>, and <ttclass="literal"><spanclass="pre">static_cast<value_type</span>
<!-- 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) -->
<p>In this section we'll walk through the implementation of a few
iterators using <ttclass="literal"><spanclass="pre">iterator_facade</span></tt>, based around the simple
example of a linked list of polymorphic objects. This example was
inspired by a <aclass="reference"href="http://thread.gmane.org/gmane.comp.lib.boost.user/5100">posting</a> by Keith Macdonald on the <aclass="reference"href="../../../more/mailing_lists.htm#users">Boost-Users</a>
<h2><aclass="toc-backref"href="#id30"name="a-basic-iterator-using-iterator-facade">A Basic Iterator Using <ttclass="literal"><spanclass="pre">iterator_facade</span></tt></a></h2>
<h3><aclass="toc-backref"href="#id31"name="template-arguments-for-iterator-facade">Template Arguments for <ttclass="literal"><spanclass="pre">iterator_facade</span></tt></a></h3>
<p><ttclass="literal"><spanclass="pre">iterator_facade</span></tt> has several template parameters, so we must decide
what types to use for the arguments. The parameters are <ttclass="literal"><spanclass="pre">Derived</span></tt>,
<ttclass="literal"><spanclass="pre">Value</span></tt>, <ttclass="literal"><spanclass="pre">CategoryOrTraversal</span></tt>, <ttclass="literal"><spanclass="pre">Reference</span></tt>, and <ttclass="literal"><spanclass="pre">Difference</span></tt>.</p>
<p>The <ttclass="literal"><spanclass="pre">Value</span></tt> parameter determines the <ttclass="literal"><spanclass="pre">node_iterator</span></tt>'s
<ttclass="literal"><spanclass="pre">value_type</span></tt>. In this case, we are iterating over <ttclass="literal"><spanclass="pre">node_base</span></tt>
objects, so <ttclass="literal"><spanclass="pre">Value</span></tt> will be <ttclass="literal"><spanclass="pre">node_base</span></tt>.</p>
<p>Now we have to determine which <aclass="reference"href="new-iter-concepts.html#iterator-traversal-concepts-lib-iterator-traversal">iterator traversal concept</a> our
<ttclass="literal"><spanclass="pre">node_iterator</span></tt> is going to model. Singly-linked lists only have
forward links, so our iterator can't can't be a <aclass="reference"href="new-iter-concepts.html#bidirectional-traversal-iterators-lib-bidirectional-traversal-iterators">bidirectional
traversal iterator</a>. Our iterator should be able to make multiple
passes over the same linked list (unlike, say, an
<ttclass="literal"><spanclass="pre">istream_iterator</span></tt> which consumes the stream it traverses), so it
must be a <aclass="reference"href="new-iter-concepts.html#forward-traversal-iterators-lib-forward-traversal-iterators">forward traversal iterator</a>. Therefore, we'll pass
<ttclass="literal"><spanclass="pre">boost::forward_traversal_tag</span></tt> in this position <aclass="footnote-reference"href="#category"id="id9"name="id9"><sup>1</sup></a>.</p>
<tr><tdclass="label"><aclass="fn-backref"href="#id9"name="category">[1]</a></td><td><ttclass="literal"><spanclass="pre">iterator_facade</span></tt> also supports old-style category
tags, so we could have passed <ttclass="literal"><spanclass="pre">std::forward_iterator_tag</span></tt> here;
either way, the resulting iterator's <ttclass="literal"><spanclass="pre">iterator_category</span></tt> will
end up being <ttclass="literal"><spanclass="pre">std::forward_iterator_tag</span></tt>.</td></tr>
<p>The <ttclass="literal"><spanclass="pre">Reference</span></tt> argument becomes the type returned by
<ttclass="literal"><spanclass="pre">node_iterator</span></tt>'s dereference operation, and will also be the
same as <ttclass="literal"><spanclass="pre">std::iterator_traits<node_iterator>::reference</span></tt>. The
library's default for this parameter is <ttclass="literal"><spanclass="pre">Value&</span></tt>; since
<ttclass="literal"><spanclass="pre">node_base&</span></tt> is a good choice for the iterator's <ttclass="literal"><spanclass="pre">reference</span></tt>
type, we can omit this argument, or pass <ttclass="literal"><spanclass="pre">use_default</span></tt>.</p>
<p>The <ttclass="literal"><spanclass="pre">Difference</span></tt> argument determines how the distance between
two <ttclass="literal"><spanclass="pre">node_iterator</span></tt>s will be measured and will also be the
same as <ttclass="literal"><spanclass="pre">std::iterator_traits<node_iterator>::difference_type</span></tt>.
The library's default for <ttclass="literal"><spanclass="pre">Difference</span></tt> is <ttclass="literal"><spanclass="pre">std::ptrdiff_t</span></tt>, 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.</p>
<p>The declaration of <ttclass="literal"><spanclass="pre">node_iterator</span></tt> will therefore look something
<p>The last step is to implement the <aclass="reference"href="#core-operations">core operations</a> required by
the concepts we want our iterator to model. Referring to the
<aclass="reference"href="#core-operations">table</a>, we can see that the first three rows are applicable
because <ttclass="literal"><spanclass="pre">node_iterator</span></tt> needs to satisfy the requirements for
<aclass="reference"href="new-iter-concepts.html#readable-iterators-lib-readable-iterators">readable iterator</a>, <aclass="reference"href="new-iter-concepts.html#single-pass-iterators-lib-single-pass-iterators">single pass iterator</a>, and <aclass="reference"href="new-iter-concepts.html#incrementable-iterators-lib-incrementable-iterators">incrementable
iterator</a>.</p>
<p>We therefore need to supply <ttclass="literal"><spanclass="pre">dereference</span></tt>,
<ttclass="literal"><spanclass="pre">equal</span></tt>, and <ttclass="literal"><spanclass="pre">increment</span></tt> members. We don't want these members
to become part of <ttclass="literal"><spanclass="pre">node_iterator</span></tt>'s public interface, so we can
make them private and grant friendship to
<ttclass="literal"><spanclass="pre">boost::iterator_core_access</span></tt>, a "back-door" that
<ttclass="literal"><spanclass="pre">iterator_facade</span></tt> uses to get access to the core operations:</p>
<pclass="sidebar-title">Constant and Mutable iterators</p>
<p>The term <strong>mutable iterator</strong> means an iterator through which
the object it references (its "referent") can be modified. A
<strong>constant iterator</strong> is one which doesn't allow modification of
its referent.</p>
<p>The words <em>constant</em> and <em>mutable</em> don't refer to the ability to
modify the iterator itself. For example, an <ttclass="literal"><spanclass="pre">int</span><spanclass="pre">const*</span></tt> is a
non-<ttclass="literal"><spanclass="pre">const</span></tt><em>constant iterator</em>, which can be incremented
but doesn't allow modification of its referent, and <ttclass="literal"><spanclass="pre">int*</span>
<spanclass="pre">const</span></tt> is a <ttclass="literal"><spanclass="pre">const</span></tt><em>mutable iterator</em>, which cannot be
modified but which allows modification of its referent.</p>
<p>Confusing? We agree, but those are the standard terms. It
probably doesn't help much that a container's constant iterator
is called <ttclass="literal"><spanclass="pre">const_iterator</span></tt>.</p>
</div>
<p>Now, our <ttclass="literal"><spanclass="pre">node_iterator</span></tt> gives clients access to both <ttclass="literal"><spanclass="pre">node</span></tt>'s <ttclass="literal"><spanclass="pre">print(std::ostream&)</span><spanclass="pre">const</span></tt> member function, but also its
mutating <ttclass="literal"><spanclass="pre">double_me()</span></tt> member. If we wanted to build a
<em>constant</em><ttclass="literal"><spanclass="pre">node_iterator</span></tt>, we'd only have to make three
<pclass="sidebar-title"><ttclass="literal"><spanclass="pre">const</span></tt> and an iterator's <ttclass="literal"><spanclass="pre">value_type</span></tt></p>
<p>The C++ standard requires an iterator's <ttclass="literal"><spanclass="pre">value_type</span></tt><em>not</em> be
<ttclass="literal"><spanclass="pre">const</span></tt>-qualified, so <ttclass="literal"><spanclass="pre">iterator_facade</span></tt> strips the
<ttclass="literal"><spanclass="pre">const</span></tt> from its <ttclass="literal"><spanclass="pre">Value</span></tt> parameter in order to produce the
iterator's <ttclass="literal"><spanclass="pre">value_type</span></tt>. Making the <ttclass="literal"><spanclass="pre">Value</span></tt> argument
<ttclass="literal"><spanclass="pre">const</span></tt> provides a useful hint to <ttclass="literal"><spanclass="pre">iterator_facade</span></tt> that the
iterator is a <em>constant iterator</em>, and the default <ttclass="literal"><spanclass="pre">Reference</span></tt>
argument will be correct for all lvalue iterators.</p>
<p>As a matter of fact, <ttclass="literal"><spanclass="pre">node_iterator</span></tt> and <ttclass="literal"><spanclass="pre">const_node_iterator</span></tt>
are so similar that it makes sense to factor the common code out
<p>Our <ttclass="literal"><spanclass="pre">const_node_iterator</span></tt> works perfectly well on its own, but
taken together with <ttclass="literal"><spanclass="pre">node_iterator</span></tt> it doesn't quite meet
expectations. For example, we'd like to be able to pass a
<ttclass="literal"><spanclass="pre">node_iterator</span></tt> where a <ttclass="literal"><spanclass="pre">node_const_iterator</span></tt> was expected,
just as you can with <ttclass="literal"><spanclass="pre">std::list<int></span></tt>'s <ttclass="literal"><spanclass="pre">iterator</span></tt> and
<ttclass="literal"><spanclass="pre">const_iterator</span></tt>. Furthermore, given a <ttclass="literal"><spanclass="pre">node_iterator</span></tt> and a
<ttclass="literal"><spanclass="pre">node_const_iterator</span></tt> into the same list, we should be able to
compare them for equality.</p>
<p>This expected ability to use two different iterator types together
is known as <strong>interoperability</strong>. Achieving interoperability in
our case is as simple as templatizing the <ttclass="literal"><spanclass="pre">equal</span></tt> function and
<tr><tdclass="label"><aclass="fn-backref"href="#id15"name="random">[4]</a></td><td>If <ttclass="literal"><spanclass="pre">node_iterator</span></tt> had been a <aclass="reference"href="new-iter-concepts.html#random-access-traversal-iterators-lib-random-access-traversal-iterators">random access
<p>Now <ttclass="literal"><spanclass="pre">node_iterator</span></tt> and <ttclass="literal"><spanclass="pre">node_const_iterator</span></tt> behave exactly as
you'd expect... almost. We can compare them and we can convert in
one direction: from <ttclass="literal"><spanclass="pre">node_iterator</span></tt> to <ttclass="literal"><spanclass="pre">node_const_iterator</span></tt>.
If we try to convert from <ttclass="literal"><spanclass="pre">node_const_iterator</span></tt> to
<ttclass="literal"><spanclass="pre">node_iterator</span></tt>, we'll get an error when the converting
constructor tries to initialize <ttclass="literal"><spanclass="pre">node_iterator</span></tt>'s <ttclass="literal"><spanclass="pre">m_node</span></tt>, a
<ttclass="literal"><spanclass="pre">node*</span></tt> with a <ttclass="literal"><spanclass="pre">node</span><spanclass="pre">const*</span></tt>. So what's the problem?</p>
will be <ttclass="literal"><spanclass="pre">true</span></tt>, but it should be <ttclass="literal"><spanclass="pre">false</span></tt>. <aclass="reference"href="../../type_traits/index.html#relationships"><ttclass="literal"><spanclass="pre">is_convertible</span></tt></a>
lies because it can only see as far as the <em>declaration</em> of
<ttclass="literal"><spanclass="pre">node_iter</span></tt>'s converting constructor, but can't look inside at
the <em>definition</em> to make sure it will compile. A perfect solution
would make <ttclass="literal"><spanclass="pre">node_iter</span></tt>'s converting constructor disappear when
the <ttclass="literal"><spanclass="pre">m_node</span></tt> conversion would fail.</p>
<p>In fact, that sort of magic is possible using
<aclass="reference"href="../../utility/enable_if.html"><ttclass="literal"><spanclass="pre">boost::enable_if</span></tt></a>. By rewriting the converting constructor as
follows, we can remove it from the overload set when it's not
<p>This concludes our <ttclass="literal"><spanclass="pre">iterator_facade</span></tt> tutorial, but before you
stop reading we urge you to take a look at <aclass="reference"href="iterator_adaptor.html"><ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt></a>.
There's another way to approach writing these iterators which might
Generated by <aclass="reference"href="http://docutils.sourceforge.net/">Docutils</a> from <aclass="reference"href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
