Really re-resolved title level problem

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

View File

@ -75,14 +75,12 @@ by adapting other iterators.</td>
<li><a class="reference" href="#proposed-text" id="id25" name="id25">Proposed Text</a><ul>
<li><a class="reference" href="#header-iterator-helper-synopsis-lib-iterator-helper-synopsis" id="id26" name="id26">Header <tt class="literal"><span class="pre">&lt;iterator_helper&gt;</span></tt> synopsis [lib.iterator.helper.synopsis]</a></li>
<li><a class="reference" href="#iterator-facade-lib-iterator-facade" id="id27" name="id27">Iterator facade [lib.iterator.facade]</a><ul>
<li><a class="reference" href="#class-template-iterator-facade" id="id28" name="id28">Class template <tt class="literal"><span class="pre">iterator_facade</span></tt></a><ul>
<li><a class="reference" href="#class-template-iterator-facade" id="id28" name="id28">Class template <tt class="literal"><span class="pre">iterator_facade</span></tt></a></li>
<li><a class="reference" href="#iterator-facade-requirements" id="id29" name="id29"><tt class="literal"><span class="pre">iterator_facade</span></tt> Requirements</a></li>
<li><a class="reference" href="#iterator-facade-iterator-category" id="id30" name="id30"><tt class="literal"><span class="pre">iterator_facade</span></tt> iterator category</a></li>
<li><a class="reference" href="#iterator-facade-operations" id="id31" name="id31"><tt class="literal"><span class="pre">iterator_facade</span></tt> operations</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference" href="#iterator-adaptor-lib-iterator-adaptor" id="id32" name="id32">Iterator adaptor [lib.iterator.adaptor]</a><ul>
<li><a class="reference" href="#class-template-iterator-adaptor" id="id33" name="id33">Class template <tt class="literal"><span class="pre">iterator_adaptor</span></tt></a></li>
<li><a class="reference" href="#iterator-adaptor-base-class-parameters" id="id34" name="id34"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> base class parameters</a></li>
@ -285,11 +283,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="id4" name="id4">[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="id4" name="id4">[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
@ -299,9 +297,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>
@ -437,9 +437,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 />
@ -707,8 +708,9 @@ struct enable_if_interoperable
&gt;
{};
</pre>
</div>
<div class="section" id="iterator-facade-requirements">
<h4><a class="toc-backref" href="#id29" name="iterator-facade-requirements"><tt class="literal"><span class="pre">iterator_facade</span></tt> Requirements</a></h4>
<h3><a class="toc-backref" href="#id29" name="iterator-facade-requirements"><tt class="literal"><span class="pre">iterator_facade</span></tt> Requirements</a></h3>
<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
@ -789,7 +791,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">
<h4><a class="toc-backref" href="#id30" name="iterator-facade-iterator-category"><tt class="literal"><span class="pre">iterator_facade</span></tt> iterator category</a></h4>
<h3><a class="toc-backref" href="#id30" name="iterator-facade-iterator-category"><tt class="literal"><span class="pre">iterator_facade</span></tt> iterator category</a></h3>
<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>
@ -842,7 +844,7 @@ convertible, and not to any more-derived traversal tag type.</p>
</blockquote>
</div>
<div class="section" id="iterator-facade-operations">
<h4><a class="toc-backref" href="#id31" name="iterator-facade-operations"><tt class="literal"><span class="pre">iterator_facade</span></tt> operations</a></h4>
<h3><a class="toc-backref" href="#id31" name="iterator-facade-operations"><tt class="literal"><span class="pre">iterator_facade</span></tt> operations</a></h3>
<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
@ -983,7 +985,6 @@ return tmp -= n;
</table>
</div>
</div>
</div>
<div class="section" id="iterator-adaptor-lib-iterator-adaptor">
<h2><a class="toc-backref" href="#id32" name="iterator-adaptor-lib-iterator-adaptor">Iterator adaptor [lib.iterator.adaptor]</a></h2>
<!-- Version 1.1 of this ReStructuredText document corresponds to
@ -2237,7 +2238,7 @@ LocalWords: OtherIncrementable Coplien -->
<hr class="footer" />
<div class="footer">
<a class="reference" href="facade-and-adaptor.rst">View document source</a>.
Generated on: 2004-01-12 16:01 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>

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>

View File

@ -20,14 +20,14 @@
.. contents:: Table of Contents
A Facade for Iterator Implementation
====================================
Overview
========
.. include:: iterator_facade_body.rst
Reference
---------
=========
.. include:: iterator_facade_ref.rst

View File

@ -21,11 +21,11 @@ include the associated types exposed through iterator traits:
``value_type``, ``reference``, ``difference_type``, and
``iterator_category``.
Iterator facade uses the Curiously Recurring Template Pattern (CRTP)
[Cop95]_ so that the user can specify the behavior of
``iterator_facade`` in a derived class. Former designs used policy
objects to specify the behavior. ``iterator_facade`` does not use policy
objects for several reasons:
Iterator facade uses the Curiously Recurring Template
Pattern (CRTP) [Cop95]_ so that the user can specify the behavior
of ``iterator_facade`` in a derived class. Former designs used
policy objects to specify the behavior, but that approach was
discarded for several reasons:
1. the creation and eventual copying of the policy object may create
overhead that can be avoided with the current approach.
@ -36,9 +36,11 @@ objects for several reasons:
implementations.
3. Without the use of CRTP, the standard requirement that an
iterator's ``operator++`` returns the iterator type itself means
that all iterators generated by ``iterator_facade`` would be
specializations of ``iterator_facade``. Cumbersome type generator
iterator's ``operator++`` returns the iterator type itself
would mean that all iterators built with the library would
have to be specializations of ``iterator_facade<...>``, rather
than something more descriptive like
``indirect_iterator<T*>``. Cumbersome type generator
metafunctions would be needed to build new parameterized
iterators, and a separate ``iterator_adaptor`` layer would be
impossible.
@ -180,10 +182,10 @@ through ``operator->``. Therefore, an iterator whose ``reference``
type is not in fact a reference must return a proxy containing a copy
of the referenced value from its ``operator->``.
The return type for ``operator->`` and ``operator[]`` is not
explicitly specified. Instead it requires each ``iterator_facade``
specialization to meet the requirements of its ``iterator_category``.
The return types for ``iterator_facade``\ 's ``operator->`` and
``operator[]`` are not explicitly specified. Instead, those types
are described in terms of a set of requirements, which must be
satisfied by the ``iterator_facade`` implementation.
.. [Cop95] [Coplien, 1995] Coplien, J., Curiously Recurring Template
Patterns, C++ Report, February 1995, pp. 24-27.

View File

@ -121,7 +121,7 @@ were defined to be::
``iterator_facade`` Requirements
................................
--------------------------------
The following table describes the typical valid expressions on
``iterator_facade``\ 's ``Derived`` parameter, depending on the
@ -170,7 +170,7 @@ interoperable with ``X``.
.. _facade iterator category:
``iterator_facade`` iterator category
.....................................
-------------------------------------
The ``iterator_category`` member of ``iterator_facade<X,V,R,C,D>``
is a type which satisfies the following conditions:
@ -218,7 +218,7 @@ is a type which satisfies the following conditions:
``iterator_facade`` operations
..............................
------------------------------
The operations in this section are described in terms of operations on
the core interface of ``Derived`` which may be inaccessible