<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
expected by <ttclass="literal"><spanclass="pre">iterator_facade</span></tt> are implemented in terms of the
<ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt>'s <ttclass="literal"><spanclass="pre">Base</span></tt> template parameter. A class derived
from <ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt> typically redefines some of the core
interface functions to adapt the behavior of the <ttclass="literal"><spanclass="pre">Base</span></tt> type.
Whether the derived class models any of the standard iterator concepts
depends on the operations supported by the <ttclass="literal"><spanclass="pre">Base</span></tt> type and which
core interface functions of <ttclass="literal"><spanclass="pre">iterator_facade</span></tt> are redefined in the
<li><aclass="reference"href="#iterator-adaptor-base-class-parameters"id="id9"name="id9"><ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt> base class parameters</a></li>
<li><aclass="reference"href="#iterator-adaptor-public-operations"id="id11"name="id11"><ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt> public operations</a></li>
<li><aclass="reference"href="#iterator-adaptor-protected-member-functions"id="id12"name="id12"><ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt> protected member functions</a></li>
<li><aclass="reference"href="#iterator-adaptor-private-member-functions"id="id13"name="id13"><ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt> private member functions</a></li>
<p>The <ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt> class template adapts some <ttclass="literal"><spanclass="pre">Base</span></tt><aclass="footnote-reference"href="#base"id="id1"name="id1"><sup>1</sup></a>
type to create a new iterator. Instantiations of <ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt>
are derived from a corresponding instantiation of <ttclass="literal"><spanclass="pre">iterator_facade</span></tt>
and implement the core behaviors in terms of the <ttclass="literal"><spanclass="pre">Base</span></tt> type. In
essence, <ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt> merely forwards all operations to an
instance of the <ttclass="literal"><spanclass="pre">Base</span></tt> type, which it stores as a member.</p>
<tr><tdclass="label"><aname="base">[1]</a></td><td><em>(<aclass="fn-backref"href="#id1">1</a>, <aclass="fn-backref"href="#id3">2</a>)</em> The term "Base" here does not refer to a base class and is
<h2><aclass="toc-backref"href="#id9"name="iterator-adaptor-base-class-parameters"><ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt> base class parameters</a></h2>
<p>In order for <ttclass="literal"><spanclass="pre">Derived</span></tt> to model the iterator concepts corresponding
to <ttclass="literal"><spanclass="pre">iterator_traits<Derived>::iterator_category</span></tt>, the expressions
involving <ttclass="literal"><spanclass="pre">m_iterator</span></tt> in the specifications of those private member
functions of <ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt> that may be called by
<ttclass="literal"><spanclass="pre">iterator_facade<Derived,</span><spanclass="pre">V,</span><spanclass="pre">C,</span><spanclass="pre">R,</span><spanclass="pre">D></span></tt> in evaluating any valid
expression involving <ttclass="literal"><spanclass="pre">Derived</span></tt> in those concepts' requirements.</p>
<!-- The above is confusing and needs a rewrite. -JGS -->
<h2><aclass="toc-backref"href="#id11"name="iterator-adaptor-public-operations"><ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt> public operations</a></h2>
<trclass="field"><thclass="field-name">Requires:</th><tdclass="field-body">The <ttclass="literal"><spanclass="pre">Base</span></tt> type must be Default Constructible.</td>
</tr>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">An instance of <ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt> with
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">An instance of <ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt> with
<ttclass="literal"><spanclass="pre">m_iterator</span></tt> copy constructed from <ttclass="literal"><spanclass="pre">iter</span></tt>.</td>
<p>[Note: specifying <ttclass="literal"><spanclass="pre">Base</span><spanclass="pre">const</span></tt> gives implementations license to
return <ttclass="literal"><spanclass="pre">Base</span><spanclass="pre">const&</span></tt> for efficiency's sake. If <ttclass="literal"><spanclass="pre">base()</span></tt>
returned just <ttclass="literal"><spanclass="pre">Base</span></tt>, it would be possible to call non-<ttclass="literal"><spanclass="pre">const</span></tt>
member functions on the result object directly]</p>
<h2><aclass="toc-backref"href="#id12"name="iterator-adaptor-protected-member-functions"><ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt> protected member functions</a></h2>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">A const reference to <ttclass="literal"><spanclass="pre">m_iterator</span></tt>.</td>
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">A non-const reference to <ttclass="literal"><spanclass="pre">m_iterator</span></tt>.</td>
<h2><aclass="toc-backref"href="#id13"name="iterator-adaptor-private-member-functions"><ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt> private member functions</a></h2>
<!-- 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 further refine the <ttclass="literal"><spanclass="pre">node_iter</span></tt> class
template we developed in the <aclass="reference"href="iterator_facade.html#tutorial-example"><ttclass="literal"><spanclass="pre">iterator_facade</span></tt> tutorial</a>. 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.</p>
<divclass="sidebar">
<pclass="sidebar-title"><ttclass="literal"><spanclass="pre">node_base*</span></tt> really <em>is</em> an iterator</p>
<p>It's not really a very interesting iterator, since <ttclass="literal"><spanclass="pre">node_base</span></tt>
is an abstract class: a pointer to a <ttclass="literal"><spanclass="pre">node_base</span></tt> just points
at some base subobject of an instance of some other class, and
incrementing a <ttclass="literal"><spanclass="pre">node_base*</span></tt> moves it past this base subobject
to who-knows-where? The most we can do with that incremented
position is to compare another <ttclass="literal"><spanclass="pre">node_base*</span></tt> to it. In other
words, the original iterator traverses a one-element array.</p>
<ttclass="literal"><spanclass="pre">pointer</span></tt>, and <ttclass="literal"><spanclass="pre">difference_type</span></tt>). Second, even some of the
core functionality is the same: <ttclass="literal"><spanclass="pre">operator*</span></tt> and <ttclass="literal"><spanclass="pre">operator==</span></tt> on
<aclass="reference"href="iterator_facade.html#implementing-the-core-operations"><ttclass="literal"><spanclass="pre">dereference</span></tt> and <ttclass="literal"><spanclass="pre">equal</span></tt> member functions</a>). However, the <ttclass="literal"><spanclass="pre">operator++</span></tt> for
<ttclass="literal"><spanclass="pre">node_iterator</span></tt> behaves differently than for <ttclass="literal"><spanclass="pre">node_base*</span></tt>
since it follows the <ttclass="literal"><spanclass="pre">m_next</span></tt> pointer.</p>
<p>It turns out that the pattern of building an iterator on another
iterator-like type (the <ttclass="literal"><spanclass="pre">Base</span></tt><aclass="footnote-reference"href="#base"id="id3"name="id3"><sup>1</sup></a> 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
<ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt>. Using <ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt> is very much like
using <ttclass="literal"><spanclass="pre">iterator_facade</span></tt>, but because iterator_adaptor tries to
mimic as much of the <ttclass="literal"><spanclass="pre">Base</span></tt> type's behavior as possible, we
neither have to supply a <ttclass="literal"><spanclass="pre">Value</span></tt> argument, nor implement any core
behaviors other than <ttclass="literal"><spanclass="pre">increment</span></tt>. The implementation of
<ttclass="literal"><spanclass="pre">node_iter</span></tt> is thus reduced to:</p>
<p>In the case of <ttclass="literal"><spanclass="pre">node_iter</span></tt>, it's not very compelling to pass
<ttclass="literal"><spanclass="pre">boost::use_default</span></tt> as <ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt>'s <ttclass="literal"><spanclass="pre">Value</span></tt>
argument; we could have just passed <ttclass="literal"><spanclass="pre">node_iter</span></tt>'s <ttclass="literal"><spanclass="pre">Value</span></tt>
along to <ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt>, and that'd even be shorter! Most
iterator class templates built with <ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt> are
parameterized on another iterator type, rather than on its
<ttclass="literal"><spanclass="pre">value_type</span></tt>. For example, <ttclass="literal"><spanclass="pre">boost::reverse_iterator</span></tt> 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, <ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt>'s delegation of default
types to its <ttclass="literal"><spanclass="pre">Base</span></tt> saves the implementor of
<ttclass="literal"><spanclass="pre">boost::reverse_iterator</span></tt> from writing</p>
<p>We urge you to review the documentation and implementations of
<aclass="reference"href="reverse_iterator.html"><ttclass="literal"><spanclass="pre">reverse_iterator</span></tt></a> and the other Boost <aclass="reference"href="index.html#specialized-adaptors">specialized iterator
adaptors</a> to get an idea of the sorts of things you can do with
<ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt>. In particular, have a look at
<aclass="reference"href="transform_iterator.html"><ttclass="literal"><spanclass="pre">transform_iterator</span></tt></a>, which is perhaps the most straightforward
adaptor, and also <aclass="reference"href="counting_iterator.html"><ttclass="literal"><spanclass="pre">counting_iterator</span></tt></a>, which demonstrates that
<ttclass="literal"><spanclass="pre">iterator_adaptor</span></tt>'s <ttclass="literal"><spanclass="pre">Base</span></tt> type needn't be an iterator.</p>
Generated by <aclass="reference"href="http://docutils.sourceforge.net/">Docutils</a> from <aclass="reference"href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
