<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
<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
<p>The user of <ttclass="literal"><spanclass="pre">iterator_facade</span></tt> derives his iterator class from an
instantiation of <ttclass="literal"><spanclass="pre">iterator_facade</span></tt> which takes the derived iterator
class as the first template parameter. The order of the other
template parameters to <ttclass="literal"><spanclass="pre">iterator_facade</span></tt> have been carefully chosen
to take advantage of useful defaults. For example, when defining a
constant lvalue iterator, the user can pass a const-qualified version
of the iterator's <ttclass="literal"><spanclass="pre">value_type</span></tt> as <ttclass="literal"><spanclass="pre">iterator_facade</span></tt>'s <ttclass="literal"><spanclass="pre">Value</span></tt>
parameter and omit the <ttclass="literal"><spanclass="pre">Reference</span></tt> parameter which follows.</p>
<p>The derived iterator class must define member functions implementing
the iterator's core behaviors. The following table describes
expressions which are required to be valid depending on the category
of the derived iterator type. These member functions are described
briefly below and in more detail in the iterator facade
<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
<p>The indexing operator for a generalized iterator presents special
challenges. A random access iterator's <ttclass="literal"><spanclass="pre">operator[]</span></tt> is only
required to return something convertible to its <ttclass="literal"><spanclass="pre">value_type</span></tt>.
Requiring that it return an lvalue would rule out currently-legal
random-access iterators which hold the referenced value in a data
member (e.g. <aclass="reference"href="counting_iterator.html">counting_iterator</a>), because <ttclass="literal"><spanclass="pre">*(p+n)</span></tt> is a reference
into the temporary iterator <ttclass="literal"><spanclass="pre">p+n</span></tt>, which is destroyed when
<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/n1477.html">n1477</a>: the result of <ttclass="literal"><spanclass="pre">p[n]</span></tt> is a proxy object
containing a copy of <ttclass="literal"><spanclass="pre">p+n</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>. 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> which returns an lvalue in the derived
iterator class; it will hide the one supplied by <ttclass="literal"><spanclass="pre">iterator_facade</span></tt>
<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 type for <ttclass="literal"><spanclass="pre">operator-></span></tt> and <ttclass="literal"><spanclass="pre">operator[]</span></tt> is not
explicitly specified. Instead it requires each <ttclass="literal"><spanclass="pre">iterator_facade</span></tt>
instantiation to meet the requirements of its <ttclass="literal"><spanclass="pre">iterator_category</span></tt>.</p>
<p>[<em>Note:</em> 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, by
which we mean they are convertible to each 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.]</p>
<!-- we need a new label here because the presence of markup in the
title prevents an automatic link from being generated -->
<p>The default for the <ttclass="literal"><spanclass="pre">Reference</span></tt> parameter is <ttclass="literal"><spanclass="pre">Value&</span></tt> if the
access category for <ttclass="literal"><spanclass="pre">iterator_facade</span></tt> is implicitly convertible to
<ttclass="literal"><spanclass="pre">writable_iterator_tag</span></tt>, and <ttclass="literal"><spanclass="pre">const</span><spanclass="pre">Value&</span></tt> otherwise.</p>
<p>The following table describes the other requirements on the
<ttclass="literal"><spanclass="pre">Derived</span></tt> parameter. Depending on the resulting iterator's
<ttclass="literal"><spanclass="pre">iterator_category</span></tt>, a subset of the expressions listed in the table
are required to be valid. The operations in the first column must be
accessible to member functions of class <ttclass="literal"><spanclass="pre">iterator_core_access</span></tt>.</p>
<p>In the table below, <ttclass="literal"><spanclass="pre">X</span></tt> is the derived iterator type, <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">X::difference_type</span></tt>, <ttclass="literal"><spanclass="pre">y</span></tt> is a constant
object of a single pass iterator type interoperable with X, 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>
<spanclass="pre"><=</span><spanclass="pre">z</span></tt>, <ttclass="literal"><spanclass="pre">c</span><spanclass="pre">></span><spanclass="pre">z</span></tt>, and <ttclass="literal"><spanclass="pre">c</span><spanclass="pre">>=</span><spanclass="pre">c</span></tt>.</td>
<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">X::reference</span></tt> is a reference type, returns an object
of type <ttclass="literal"><spanclass="pre">X::pointer</span></tt> equal to:</p>
<p>Otherwise returns an object of unspecified type such that, given an
object <ttclass="literal"><spanclass="pre">a</span></tt> of type <ttclass="literal"><spanclass="pre">X</span></tt>, <ttclass="literal"><spanclass="pre">a->m</span></tt> is equivalent to <ttclass="literal"><spanclass="pre">(w</span><spanclass="pre">=</span><spanclass="pre">*a,</span>
<spanclass="pre">w.m)</span></tt> for some temporary object <ttclass="literal"><spanclass="pre">w</span></tt> of type <ttclass="literal"><spanclass="pre">X::value_type</span></tt>.</p>
<pclass="last">The type <ttclass="literal"><spanclass="pre">X::pointer</span></tt> is <ttclass="literal"><spanclass="pre">Value*</span></tt> if the access category for
<ttclass="literal"><spanclass="pre">X</span></tt> is implicitly convertible to <ttclass="literal"><spanclass="pre">writable_iterator_tag</span></tt>, and
<trclass="field"><thclass="field-name">Returns:</th><tdclass="field-body">an object convertible to <ttclass="literal"><spanclass="pre">X::reference</span></tt> and holding a copy
<em>p</em> of <ttclass="literal"><spanclass="pre">a+n</span></tt> such that, for a constant object <ttclass="literal"><spanclass="pre">v</span></tt> of type
<ttclass="literal"><spanclass="pre">X::value_type</span></tt>, <ttclass="literal"><spanclass="pre">X::reference(a[n]</span><spanclass="pre">=</span><spanclass="pre">v)</span></tt> is equivalent
to <ttclass="literal"><spanclass="pre">p</span><spanclass="pre">=</span><spanclass="pre">v</span></tt>.</td>
Generated by <aclass="reference"href="http://docutils.sourceforge.net/">Docutils</a> from <aclass="reference"href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
