boostorg/iterator
1
0
Fork 1
mirror of https://github.com/boostorg/iterator.git synced 2025-07-29 12:27:33 +02:00
Code Issues Packages Projects Releases Wiki Activity

Really re-resolved title level problem

Browse Source 
A few minor edits


[SVN r21634]
This commit is contained in:
Dave Abrahams
2004-01-12 18:02:50 +00:00
parent 129815f3dd
commit b4f1b069be
5 changed files with 65 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
doc/iterator_facade.html
View File

@ -45,19 +45,19 @@ and associated types, to be supplied by a derived iterator class.</td>
<div class="contents topic" id="table-of-contents">
<p class="topic-title"><a name="table-of-contents">Table of Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#a-facade-for-iterator-implementation" id="id21" name="id21">A Facade for Iterator Implementation</a><ul>
<li><a class="reference" href="#overview" id="id21" name="id21">Overview</a><ul>
<li><a class="reference" href="#usage" id="id22" name="id22">Usage</a></li>
<li><a class="reference" href="#iterator-core-access" id="id23" name="id23">Iterator Core Access</a></li>
<li><a class="reference" href="#operator" id="id24" name="id24"><tt class="literal"><span class="pre">operator[]</span></tt></a></li>
<li><a class="reference" href="#id2" id="id25" name="id25"><tt class="literal"><span class="pre">operator-&gt;</span></tt></a></li>
</ul>
</li>
<li><a class="reference" href="#reference" id="id26" name="id26">Reference</a><ul>
<li><a class="reference" href="#iterator-facade-requirements" id="id27" name="id27"><tt class="literal"><span class="pre">iterator_facade</span></tt> Requirements</a></li>
<li><a class="reference" href="#iterator-facade-iterator-category" id="id28" name="id28"><tt class="literal"><span class="pre">iterator_facade</span></tt> iterator category</a></li>
<li><a class="reference" href="#iterator-facade-operations" id="id29" name="id29"><tt class="literal"><span class="pre">iterator_facade</span></tt> operations</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference" href="#tutorial-example" id="id30" name="id30">Tutorial Example</a><ul>
<li><a class="reference" href="#the-problem" id="id31" name="id31">The Problem</a></li>
<li><a class="reference" href="#a-basic-iterator-using-iterator-facade" id="id32" name="id32">A Basic Iterator Using <tt class="literal"><span class="pre">iterator_facade</span></tt></a><ul>
@ -81,8 +81,8 @@ and associated types, to be supplied by a derived iterator class.</td>
</li>
</ul>
</div>
<div class="section" id="a-facade-for-iterator-implementation">
<h1><a class="toc-backref" href="#id21" name="a-facade-for-iterator-implementation">A Facade for Iterator Implementation</a></h1>
<div class="section" id="overview">
<h1><a class="toc-backref" href="#id21" name="overview">Overview</a></h1>
<!-- Version 1.1 of this ReStructuredText document corresponds to
n1530_, the paper accepted by the LWG for TR1. -->
<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
@ -102,11 +102,11 @@ identified the following core behaviors for iterators:</p>
include the associated types exposed through iterator traits:
<tt class="literal"><span class="pre">value_type</span></tt>, <tt class="literal"><span class="pre">reference</span></tt>, <tt class="literal"><span class="pre">difference_type</span></tt>, and
<tt class="literal"><span class="pre">iterator_category</span></tt>.</p>
<p>Iterator facade uses the Curiously Recurring Template Pattern (CRTP)
<a class="citation-reference" href="#cop95" id="id1" name="id1">[Cop95]</a> so that the user can specify the behavior of
<tt class="literal"><span class="pre">iterator_facade</span></tt> in a derived class. Former designs used policy
objects to specify the behavior. <tt class="literal"><span class="pre">iterator_facade</span></tt> does not use policy
objects for several reasons:</p>
<p>Iterator facade uses the Curiously Recurring Template
Pattern (CRTP) <a class="citation-reference" href="#cop95" id="id1" name="id1">[Cop95]</a> so that the user can specify the behavior
of <tt class="literal"><span class="pre">iterator_facade</span></tt> in a derived class. Former designs used
policy objects to specify the behavior, but that approach was
discarded for several reasons:</p>
<blockquote>
<ol class="arabic simple">
<li>the creation and eventual copying of the policy object may create
@ -116,9 +116,11 @@ on the created iterator types, an essential feature if
<tt class="literal"><span class="pre">iterator_facade</span></tt> should be used in other library
implementations.</li>
<li>Without the use of CRTP, the standard requirement that an
iterator's <tt class="literal"><span class="pre">operator++</span></tt> returns the iterator type itself means
that all iterators generated by <tt class="literal"><span class="pre">iterator_facade</span></tt> would be
specializations of <tt class="literal"><span class="pre">iterator_facade</span></tt>. Cumbersome type generator
iterator's <tt class="literal"><span class="pre">operator++</span></tt> returns the iterator type itself
would mean that all iterators built with the library would
have to be specializations of <tt class="literal"><span class="pre">iterator_facade&lt;...&gt;</span></tt>, rather
than something more descriptive like
<tt class="literal"><span class="pre">indirect_iterator&lt;T*&gt;</span></tt>. Cumbersome type generator
metafunctions would be needed to build new parameterized
iterators, and a separate <tt class="literal"><span class="pre">iterator_adaptor</span></tt> layer would be
impossible.</li>
@ -254,9 +256,10 @@ is a class, however, it must still be possible to access members
through <tt class="literal"><span class="pre">operator-&gt;</span></tt>. Therefore, an iterator whose <tt class="literal"><span class="pre">reference</span></tt>
type is not in fact a reference must return a proxy containing a copy
of the referenced value from its <tt class="literal"><span class="pre">operator-&gt;</span></tt>.</p>
<p>The return type for <tt class="literal"><span class="pre">operator-&gt;</span></tt> and <tt class="literal"><span class="pre">operator[]</span></tt> is not
explicitly specified. Instead it requires each <tt class="literal"><span class="pre">iterator_facade</span></tt>
specialization to meet the requirements of its <tt class="literal"><span class="pre">iterator_category</span></tt>.</p>
<p>The return types for <tt class="literal"><span class="pre">iterator_facade</span></tt>'s <tt class="literal"><span class="pre">operator-&gt;</span></tt> and
<tt class="literal"><span class="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 <tt class="literal"><span class="pre">iterator_facade</span></tt> implementation.</p>
<table class="citation" frame="void" id="cop95" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<col />
@ -266,8 +269,9 @@ Patterns, C++ Report, February 1995, pp. 24-27.</td></tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="reference">
<h2><a class="toc-backref" href="#id26" name="reference">Reference</a></h2>
<h1><a class="toc-backref" href="#id26" name="reference">Reference</a></h1>
<!-- Version 1.3 of this ReStructuredText document corresponds to
n1530_, the paper accepted by the LWG for TR1. -->
<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
@ -379,7 +383,7 @@ struct enable_if_interoperable
{};
</pre>
<div class="section" id="iterator-facade-requirements">
<h3><a class="toc-backref" href="#id27" name="iterator-facade-requirements"><tt class="literal"><span class="pre">iterator_facade</span></tt> Requirements</a></h3>
<h2><a class="toc-backref" href="#id27" name="iterator-facade-requirements"><tt class="literal"><span class="pre">iterator_facade</span></tt> Requirements</a></h2>
<p>The following table describes the typical valid expressions on
<tt class="literal"><span class="pre">iterator_facade</span></tt>'s <tt class="literal"><span class="pre">Derived</span></tt> parameter, depending on the
iterator concept(s) it will model. The operations in the first
@ -460,7 +464,7 @@ Iterator</td>
</div>
<a class="target" id="facade-iterator-category" name="facade-iterator-category"></a></div>
<div class="section" id="iterator-facade-iterator-category">
<h3><a class="toc-backref" href="#id28" name="iterator-facade-iterator-category"><tt class="literal"><span class="pre">iterator_facade</span></tt> iterator category</a></h3>
<h2><a class="toc-backref" href="#id28" name="iterator-facade-iterator-category"><tt class="literal"><span class="pre">iterator_facade</span></tt> iterator category</a></h2>
<p>The <tt class="literal"><span class="pre">iterator_category</span></tt> member of <tt class="literal"><span class="pre">iterator_facade&lt;X,V,R,C,D&gt;</span></tt>
is a type which satisfies the following conditions:</p>
<blockquote>
@ -513,7 +517,7 @@ convertible, and not to any more-derived traversal tag type.</p>
</blockquote>
</div>
<div class="section" id="iterator-facade-operations">
<h3><a class="toc-backref" href="#id29" name="iterator-facade-operations"><tt class="literal"><span class="pre">iterator_facade</span></tt> operations</a></h3>
<h2><a class="toc-backref" href="#id29" name="iterator-facade-operations"><tt class="literal"><span class="pre">iterator_facade</span></tt> operations</a></h2>
<p>The operations in this section are described in terms of operations on
the core interface of <tt class="literal"><span class="pre">Derived</span></tt> which may be inaccessible
(i.e. private). The implementation should access these operations
@ -654,7 +658,6 @@ return tmp -= n;
</table>
</div>
</div>
</div>
<div class="section" id="tutorial-example">
<h1><a class="toc-backref" href="#id30" name="tutorial-example">Tutorial Example</a></h1>
<!-- Copyright David Abrahams 2004. Use, modification and distribution is -->
@ -1129,7 +1132,7 @@ even be superior.</p>
<hr class="footer" />
<div class="footer">
<a class="reference" href="iterator_facade.rst">View document source</a>.
Generated on: 2004-01-12 15:49 UTC.
Generated on: 2004-01-12 17:28 UTC.
Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div>
</body>