<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
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
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 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>
<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
<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>
<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>The <ttclass="literal"><spanclass="pre">iterator_category</span></tt> member of <ttclass="literal"><spanclass="pre">iterator_facade<X,V,R,C,D></span></tt>
is a type which satisfies the following conditions:</p>
<blockquote>
<ul>
<li><pclass="first">if <ttclass="literal"><spanclass="pre">C</span></tt> is convertible to <ttclass="literal"><spanclass="pre">std::input_iterator_tag</span></tt> or
<ttclass="literal"><spanclass="pre">C</span></tt> is convertible to <ttclass="literal"><spanclass="pre">std::output_iterator_tag</span></tt>,
<ttclass="literal"><spanclass="pre">iterator_category</span></tt> is the same as <ttclass="literal"><spanclass="pre">C</span></tt>.</p>
</li>
<li><pclass="first">Otherwise, if <ttclass="literal"><spanclass="pre">C</span></tt> is not convertible to
<ttclass="literal"><spanclass="pre">incrementable_traversal_tag</span></tt>, the program is ill-formed</p>
</li>
<li><pclass="first">Otherwise:</p>
<ul>
<li><pclass="first"><ttclass="literal"><spanclass="pre">iterator_category</span></tt> is convertible to the iterator
category tag or tags given by the following algorithm, and
not to any more-derived iterator category tag or tags:</p>
<preclass="literal-block">
if (R is a reference type
&& C is convertible to forward_traversal_tag)
{
if (C is convertible to random_access_traversal_tag)
return random_access_iterator_tag
else if (C is convertible to bidirectional_traversal_tag)
return bidirectional_iterator_tag
else
return forward_traversal_tag
}
else
{
if (C is convertible to single_pass_traversal_tag
&& R is convertible to V)
{
if (V is const)
return input_iterator_tag
else
return input_iterator_tag and output_iterator_tag
}
else
return output_iterator_tag
}
</pre>
</li>
<li><pclass="first"><ttclass="literal"><spanclass="pre">iterator_traversal<X>::type</span></tt> is convertible to the most
derived traversal tag type to which <ttclass="literal"><spanclass="pre">C</span></tt> is also
convertible, and not to any more-derived traversal tag type.</p>
<p><ttclass="literal"><spanclass="pre">operator->()</span><spanclass="pre">const;</span></tt> (see <aclass="reference"href="#operator-arrow">below</a>)</p>
<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">reference</span></tt> and holding a copy
<em>p</em> of <ttclass="literal"><spanclass="pre">*static_cast<Derived</span><spanclass="pre">const*>(this)</span><spanclass="pre">+</span><spanclass="pre">n</span></tt> such that, for a constant object <ttclass="literal"><spanclass="pre">v</span></tt> of type
<ttclass="literal"><spanclass="pre">value_type</span></tt>, <ttclass="literal"><spanclass="pre">(*static_cast<Derived</span><spanclass="pre">const*>(this))[n]</span><spanclass="pre">=</span><spanclass="pre">v</span></tt> is equivalent
Generated by <aclass="reference"href="http://docutils.sourceforge.net/">Docutils</a> from <aclass="reference"href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
