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

factored iterator adaptor stuff and a few other edits

Browse Source 
[SVN r19465]
This commit is contained in:
Jeremy Siek
2003-08-05 18:19:55 +00:00
parent 19977c757f
commit 0f42b93c3b
9 changed files with 656 additions and 308 deletions
Download Patch File Download Diff File Expand all files Collapse all files

540
doc/facade-and-adaptor.html
View File

@ -3,11 +3,11 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.2.8: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.3.0: http://docutils.sourceforge.net/" />
<title>Iterator Facade and Adaptor</title>
<meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" />
<meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, University of Hanover Institute for Transport Railway Operation and Construction" />
<meta name="date" content="2003-07-13" />
<meta name="date" content="2003-08-05" />
<meta name="copyright" content="Copyright Dave Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved" />
<link rel="stylesheet" href="default.css" type="text/css" />
</head>
@ -27,7 +27,7 @@
Lab</a>, University of Hanover <a class="last reference" href="http://www.ive.uni-hannover.de">Institute for Transport
Railway Operation and Construction</a></td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2003-07-13</td></tr>
<td>2003-08-05</td></tr>
<tr class="field"><th class="docinfo-name">Number:</th><td class="field-body"><strong>This document is a revised version of the official</strong> N1476=03-0059</td>
</tr>
<tr><th class="docinfo-name">Copyright:</th>
@ -47,74 +47,78 @@ by adapting other iterators.</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="#motivation" id="id11" name="id11">Motivation</a></li>
<li><a class="reference" href="#impact-on-the-standard" id="id12" name="id12">Impact on the Standard</a></li>
<li><a class="reference" href="#design" id="id13" name="id13">Design</a><ul>
<li><a class="reference" href="#iterator-concepts" id="id14" name="id14">Iterator Concepts</a></li>
<li><a class="reference" href="#interoperability" id="id15" name="id15">Interoperability</a></li>
<li><a class="reference" href="#iterator-facade" id="id16" name="id16">Iterator Facade</a><ul>
<li><a class="reference" href="#usage" id="id17" name="id17">Usage</a></li>
<li><a class="reference" href="#iterator-core-access" id="id18" name="id18">Iterator Core Access</a></li>
<li><a class="reference" href="#operator" id="id19" name="id19"><tt class="literal"><span class="pre">operator[]</span></tt></a></li>
<li><a class="reference" href="#id7" id="id20" name="id20"><tt class="literal"><span class="pre">operator-&gt;</span></tt></a></li>
<li><a class="reference" href="#motivation" id="id17" name="id17">Motivation</a></li>
<li><a class="reference" href="#impact-on-the-standard" id="id18" name="id18">Impact on the Standard</a></li>
<li><a class="reference" href="#design" id="id19" name="id19">Design</a><ul>
<li><a class="reference" href="#iterator-concepts" id="id20" name="id20">Iterator Concepts</a></li>
<li><a class="reference" href="#interoperability" id="id21" name="id21">Interoperability</a></li>
<li><a class="reference" href="#iterator-facade" id="id22" name="id22">Iterator Facade</a><ul>
<li><a class="reference" href="#usage" id="id23" name="id23">Usage</a></li>
<li><a class="reference" href="#iterator-core-access" id="id24" name="id24">Iterator Core Access</a></li>
<li><a class="reference" href="#operator" id="id25" name="id25"><tt class="literal"><span class="pre">operator[]</span></tt></a></li>
<li><a class="reference" href="#id7" id="id26" name="id26"><tt class="literal"><span class="pre">operator-&gt;</span></tt></a></li>
</ul>
</li>
<li><a class="reference" href="#iterator-adaptor" id="id21" name="id21">Iterator Adaptor</a></li>
<li><a class="reference" href="#specialized-adaptors" id="id22" name="id22">Specialized Adaptors</a></li>
<li><a class="reference" href="#iterator-adaptor" id="id27" name="id27">Iterator Adaptor</a></li>
<li><a class="reference" href="#specialized-adaptors" id="id28" name="id28">Specialized Adaptors</a></li>
</ul>
</li>
<li><a class="reference" href="#proposed-text" id="id23" name="id23">Proposed Text</a><ul>
<li><a class="reference" href="#header-iterator-helper-synopsis-lib-iterator-helper-synopsis" id="id24" name="id24">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="id25" name="id25">Iterator facade [lib.iterator.facade]</a><ul>
<li><a class="reference" href="#class-template-iterator-facade" id="id26" name="id26">Class template <tt class="literal"><span class="pre">iterator_facade</span></tt></a></li>
<li><a class="reference" href="#proposed-text" id="id29" name="id29">Proposed Text</a><ul>
<li><a class="reference" href="#header-iterator-helper-synopsis-lib-iterator-helper-synopsis" id="id30" name="id30">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="id31" name="id31">Iterator facade [lib.iterator.facade]</a><ul>
<li><a class="reference" href="#class-template-iterator-facade" id="id32" name="id32">Class template <tt class="literal"><span class="pre">iterator_facade</span></tt></a><ul>
<li><a class="reference" href="#id13" id="id33" name="id33"><tt class="literal"><span class="pre">iterator_facade</span></tt> requirements</a></li>
<li><a class="reference" href="#iterator-facade-operations" id="id34" name="id34"><tt class="literal"><span class="pre">iterator_facade</span></tt> operations</a></li>
</ul>
</li>
<li><a class="reference" href="#iterator-adaptor-lib-iterator-adaptor" id="id27" name="id27">Iterator adaptor [lib.iterator.adaptor]</a><ul>
<li><a class="reference" href="#class-template-iterator-adaptor" id="id28" name="id28">Class template <tt class="literal"><span class="pre">iterator_adaptor</span></tt></a></li>
<li><a class="reference" href="#iterator-adaptor-requirements" id="id29" name="id29"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> requirements</a></li>
<li><a class="reference" href="#iterator-adaptor-public-operations" id="id30" name="id30"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> public operations</a></li>
<li><a class="reference" href="#iterator-adaptor-protected-member-functions" id="id31" name="id31"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> protected member functions</a></li>
<li><a class="reference" href="#iterator-adaptor-private-member-functions" id="id32" name="id32"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> private member functions</a></li>
</ul>
</li>
<li><a class="reference" href="#specialized-adaptors-lib-iterator-special-adaptors" id="id33" name="id33">Specialized adaptors [lib.iterator.special.adaptors]</a><ul>
<li><a class="reference" href="#indirect-iterator" id="id34" name="id34">Indirect iterator</a><ul>
<li><a class="reference" href="#class-template-indirect-iterator" id="id35" name="id35">Class template <tt class="literal"><span class="pre">indirect_iterator</span></tt></a></li>
<li><a class="reference" href="#indirect-iterator-requirements" id="id36" name="id36"><tt class="literal"><span class="pre">indirect_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#indirect-iterator-operations" id="id37" name="id37"><tt class="literal"><span class="pre">indirect_iterator</span></tt> operations</a></li>
<li><a class="reference" href="#iterator-adaptor-lib-iterator-adaptor" id="id35" name="id35">Iterator adaptor [lib.iterator.adaptor]</a><ul>
<li><a class="reference" href="#class-template-iterator-adaptor" id="id36" name="id36">Class template <tt class="literal"><span class="pre">iterator_adaptor</span></tt></a></li>
<li><a class="reference" href="#iterator-adaptor-requirements" id="id37" name="id37"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> requirements</a></li>
<li><a class="reference" href="#iterator-adaptor-public-operations" id="id38" name="id38"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> public operations</a></li>
<li><a class="reference" href="#iterator-adaptor-protected-member-functions" id="id39" name="id39"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> protected member functions</a></li>
<li><a class="reference" href="#iterator-adaptor-private-member-functions" id="id40" name="id40"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> private member functions</a></li>
</ul>
</li>
<li><a class="reference" href="#reverse-iterator" id="id38" name="id38">Reverse iterator</a><ul>
<li><a class="reference" href="#class-template-reverse-iterator" id="id39" name="id39">Class template <tt class="literal"><span class="pre">reverse_iterator</span></tt></a></li>
<li><a class="reference" href="#reverse-iterator-requirements" id="id40" name="id40"><tt class="literal"><span class="pre">reverse_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#specialized-adaptors-lib-iterator-special-adaptors" id="id41" name="id41">Specialized adaptors [lib.iterator.special.adaptors]</a><ul>
<li><a class="reference" href="#indirect-iterator" id="id42" name="id42">Indirect iterator</a><ul>
<li><a class="reference" href="#class-template-indirect-iterator" id="id43" name="id43">Class template <tt class="literal"><span class="pre">indirect_iterator</span></tt></a></li>
<li><a class="reference" href="#indirect-iterator-requirements" id="id44" name="id44"><tt class="literal"><span class="pre">indirect_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#indirect-iterator-operations" id="id45" name="id45"><tt class="literal"><span class="pre">indirect_iterator</span></tt> operations</a></li>
</ul>
</li>
<li><a class="reference" href="#transform-iterator" id="id41" name="id41">Transform iterator</a><ul>
<li><a class="reference" href="#class-template-transform-iterator" id="id42" name="id42">Class template <tt class="literal"><span class="pre">transform_iterator</span></tt></a></li>
<li><a class="reference" href="#transform-iterator-requirements" id="id43" name="id43"><tt class="literal"><span class="pre">transform_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#transform-iterator-public-operations" id="id44" name="id44"><tt class="literal"><span class="pre">transform_iterator</span></tt> public operations</a></li>
<li><a class="reference" href="#transform-iterator-private-operations" id="id45" name="id45"><tt class="literal"><span class="pre">transform_iterator</span></tt> private operations</a></li>
<li><a class="reference" href="#reverse-iterator" id="id46" name="id46">Reverse iterator</a><ul>
<li><a class="reference" href="#class-template-reverse-iterator" id="id47" name="id47">Class template <tt class="literal"><span class="pre">reverse_iterator</span></tt></a></li>
<li><a class="reference" href="#reverse-iterator-requirements" id="id48" name="id48"><tt class="literal"><span class="pre">reverse_iterator</span></tt> requirements</a></li>
</ul>
</li>
<li><a class="reference" href="#filter-iterator" id="id46" name="id46">Filter iterator</a><ul>
<li><a class="reference" href="#class-template-filter-iterator" id="id47" name="id47">Class template <tt class="literal"><span class="pre">filter_iterator</span></tt></a></li>
<li><a class="reference" href="#transform-iterator" id="id49" name="id49">Transform iterator</a><ul>
<li><a class="reference" href="#class-template-transform-iterator" id="id50" name="id50">Class template <tt class="literal"><span class="pre">transform_iterator</span></tt></a></li>
<li><a class="reference" href="#transform-iterator-requirements" id="id51" name="id51"><tt class="literal"><span class="pre">transform_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#transform-iterator-public-operations" id="id52" name="id52"><tt class="literal"><span class="pre">transform_iterator</span></tt> public operations</a></li>
<li><a class="reference" href="#transform-iterator-private-operations" id="id53" name="id53"><tt class="literal"><span class="pre">transform_iterator</span></tt> private operations</a></li>
</ul>
</li>
<li><a class="reference" href="#filter-iterator-requirements" id="id48" name="id48"><tt class="literal"><span class="pre">filter_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#filter-iterator-operations" id="id49" name="id49"><tt class="literal"><span class="pre">filter_iterator</span></tt> operations</a></li>
<li><a class="reference" href="#id10" id="id50" name="id50">Counting iterator</a><ul>
<li><a class="reference" href="#class-template-counting-iterator" id="id51" name="id51">Class template <tt class="literal"><span class="pre">counting_iterator</span></tt></a></li>
<li><a class="reference" href="#filter-iterator" id="id54" name="id54">Filter iterator</a><ul>
<li><a class="reference" href="#class-template-filter-iterator" id="id55" name="id55">Class template <tt class="literal"><span class="pre">filter_iterator</span></tt></a></li>
</ul>
</li>
<li><a class="reference" href="#counting-iterator-requirements" id="id52" name="id52"><tt class="literal"><span class="pre">counting_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#counting-iterator-operations" id="id53" name="id53"><tt class="literal"><span class="pre">counting_iterator</span></tt> operations</a></li>
<li><a class="reference" href="#function-output-iterator" id="id54" name="id54">Function output iterator</a><ul>
<li><a class="reference" href="#class-template-function-output-iterator" id="id55" name="id55">Class template <tt class="literal"><span class="pre">function_output_iterator</span></tt></a></li>
<li><a class="reference" href="#filter-iterator-requirements" id="id56" name="id56"><tt class="literal"><span class="pre">filter_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#filter-iterator-operations" id="id57" name="id57"><tt class="literal"><span class="pre">filter_iterator</span></tt> operations</a></li>
<li><a class="reference" href="#id16" id="id58" name="id58">Counting iterator</a><ul>
<li><a class="reference" href="#class-template-counting-iterator" id="id59" name="id59">Class template <tt class="literal"><span class="pre">counting_iterator</span></tt></a></li>
</ul>
</li>
<li><a class="reference" href="#function-output-iterator-requirements" id="id56" name="id56"><tt class="literal"><span class="pre">function_output_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#function-output-iterator-operations" id="id57" name="id57"><tt class="literal"><span class="pre">function_output_iterator</span></tt> operations</a></li>
<li><a class="reference" href="#function-output-iterator-output-proxy-operations" id="id58" name="id58"><tt class="literal"><span class="pre">function_output_iterator::output_proxy</span></tt> operations</a></li>
<li><a class="reference" href="#counting-iterator-requirements" id="id60" name="id60"><tt class="literal"><span class="pre">counting_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#counting-iterator-operations" id="id61" name="id61"><tt class="literal"><span class="pre">counting_iterator</span></tt> operations</a></li>
<li><a class="reference" href="#function-output-iterator" id="id62" name="id62">Function output iterator</a><ul>
<li><a class="reference" href="#class-template-function-output-iterator" id="id63" name="id63">Class template <tt class="literal"><span class="pre">function_output_iterator</span></tt></a></li>
</ul>
</li>
<li><a class="reference" href="#function-output-iterator-requirements" id="id64" name="id64"><tt class="literal"><span class="pre">function_output_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#function-output-iterator-operations" id="id65" name="id65"><tt class="literal"><span class="pre">function_output_iterator</span></tt> operations</a></li>
<li><a class="reference" href="#function-output-iterator-output-proxy-operations" id="id66" name="id66"><tt class="literal"><span class="pre">function_output_iterator::output_proxy</span></tt> operations</a></li>
</ul>
</li>
</ul>
@ -122,7 +126,7 @@ by adapting other iterators.</td>
</ul>
</div>
<div class="section" id="motivation">
<h1><a class="toc-backref" href="#id11" name="motivation">Motivation</a></h1>
<h1><a class="toc-backref" href="#id17" name="motivation">Motivation</a></h1>
<p>Iterators play an important role in modern C++ programming. The
iterator is the central abstraction of the algorithms of the Standard
Library, allowing algorithms to be re-used in in a wide variety of
@ -207,15 +211,15 @@ applies some user-specified function during the dereference of the
iterator.</p>
</div>
<div class="section" id="impact-on-the-standard">
<h1><a class="toc-backref" href="#id12" name="impact-on-the-standard">Impact on the Standard</a></h1>
<h1><a class="toc-backref" href="#id18" name="impact-on-the-standard">Impact on the Standard</a></h1>
<p>This proposal is purely an addition to the C++ standard library.
However, note that this proposal relies on the proposal for New
Iterator Concepts.</p>
</div>
<div class="section" id="design">
<h1><a class="toc-backref" href="#id13" name="design">Design</a></h1>
<h1><a class="toc-backref" href="#id19" name="design">Design</a></h1>
<div class="section" id="iterator-concepts">
<h2><a class="toc-backref" href="#id14" name="iterator-concepts">Iterator Concepts</a></h2>
<h2><a class="toc-backref" href="#id20" name="iterator-concepts">Iterator Concepts</a></h2>
<p>This proposal is formulated in terms of the new <tt class="literal"><span class="pre">iterator</span> <span class="pre">concepts</span></tt>
as proposed in <a class="reference" href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/papers/2003/n1477.html">n1477</a>, since user-defined and especially adapted
iterators suffer from the well known categorization problems that are
@ -225,7 +229,7 @@ is a direct mapping between new and old categories. This proposal
could be reformulated using this mapping if <a class="reference" href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/papers/2003/n1477.html">n1477</a> was not accepted.</p>
</div>
<div class="section" id="interoperability">
<h2><a class="toc-backref" href="#id15" name="interoperability">Interoperability</a></h2>
<h2><a class="toc-backref" href="#id21" name="interoperability">Interoperability</a></h2>
<p>The question of iterator interoperability is poorly addressed in the
current standard. There are currently two defect reports that are
concerned with interoperability issues.</p>
@ -245,7 +249,7 @@ fixes the issues raised in 280. It provides the desired
interoperability without introducing unwanted overloads.</p>
</div>
<div class="section" id="iterator-facade">
<h2><a class="toc-backref" href="#id16" name="iterator-facade">Iterator Facade</a></h2>
<h2><a class="toc-backref" href="#id22" name="iterator-facade">Iterator Facade</a></h2>
<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>
@ -284,7 +288,7 @@ impossible.</li>
</ol>
</blockquote>
<div class="section" id="usage">
<h3><a class="toc-backref" href="#id17" name="usage">Usage</a></h3>
<h3><a class="toc-backref" href="#id23" name="usage">Usage</a></h3>
<p>The user of <tt class="literal"><span class="pre">iterator_facade</span></tt> derives his iterator class from an
instantiation of <tt class="literal"><span class="pre">iterator_facade</span></tt> which takes the derived iterator
class as the first template parameter. The order of the other
@ -300,7 +304,7 @@ of the derived iterator type. These member functions are described
briefly below and in more detail in the iterator facade
requirements.</p>
<blockquote>
<table class="table" frame="border" rules="all">
<table border class="table">
<colgroup>
<col width="44%" />
<col width="56%" />
@ -347,7 +351,7 @@ Iterator or a more-refined iterator concept, a default constructor is
required.</p>
</div>
<div class="section" id="iterator-core-access">
<h3><a class="toc-backref" href="#id18" name="iterator-core-access">Iterator Core Access</a></h3>
<h3><a class="toc-backref" href="#id24" name="iterator-core-access">Iterator Core Access</a></h3>
<p><tt class="literal"><span class="pre">iterator_facade</span></tt> and the operator implementations need to be able
to access the core member functions in the derived class. Making the
core member functions public would expose an implementation detail to
@ -381,7 +385,7 @@ open a safety loophole, as every core member function preserves the
invariants of the iterator.</p>
</div>
<div class="section" id="operator">
<h3><a class="toc-backref" href="#id19" name="operator"><tt class="literal"><span class="pre">operator[]</span></tt></a></h3>
<h3><a class="toc-backref" href="#id25" name="operator"><tt class="literal"><span class="pre">operator[]</span></tt></a></h3>
<p>The indexing operator for a generalized iterator presents special
challenges. A random access iterator's <tt class="literal"><span class="pre">operator[]</span></tt> is only
required to return something convertible to its <tt class="literal"><span class="pre">value_type</span></tt>.
@ -402,7 +406,7 @@ iterator class; it will hide the one supplied by <tt class="literal"><span class
from clients of her iterator.</p>
<a class="target" id="operator-arrow" name="operator-arrow"></a></div>
<div class="section" id="id7">
<h3><a class="toc-backref" href="#id20" name="id7"><tt class="literal"><span class="pre">operator-&gt;</span></tt></a></h3>
<h3><a class="toc-backref" href="#id26" name="id7"><tt class="literal"><span class="pre">operator-&gt;</span></tt></a></h3>
<p>The <tt class="literal"><span class="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 <tt class="literal"><span class="pre">value_type</span></tt>. When the <tt class="literal"><span class="pre">value_type</span></tt>
@ -424,7 +428,7 @@ Patterns, C++ Report, February 1995, pp. 24-27.</td></tr>
</div>
</div>
<div class="section" id="iterator-adaptor">
<h2><a class="toc-backref" href="#id21" name="iterator-adaptor">Iterator Adaptor</a></h2>
<h2><a class="toc-backref" href="#id27" name="iterator-adaptor">Iterator Adaptor</a></h2>
<p>The <tt class="literal"><span class="pre">iterator_adaptor</span></tt> class template adapts some <tt class="literal"><span class="pre">Base</span></tt> <a class="footnote-reference" href="#base" id="id8" name="id8"><sup>3</sup></a>
type to create a new iterator. Instantiations of <tt class="literal"><span class="pre">iterator_adaptor</span></tt>
are derived from a corresponding instantiation of <tt class="literal"><span class="pre">iterator_facade</span></tt>
@ -460,7 +464,7 @@ template parameter may not always be identical to the iterator's
assumption.</p>
</div>
<div class="section" id="specialized-adaptors">
<h2><a class="toc-backref" href="#id22" name="specialized-adaptors">Specialized Adaptors</a></h2>
<h2><a class="toc-backref" href="#id28" name="specialized-adaptors">Specialized Adaptors</a></h2>
<p>This proposal also contains several examples of specialized adaptors
which were easily implemented using <tt class="literal"><span class="pre">iterator_adaptor</span></tt>:</p>
<ul class="simple">
@ -497,9 +501,9 @@ Standard compliant iterators).</p>
</div>
</div>
<div class="section" id="proposed-text">
<h1><a class="toc-backref" href="#id23" name="proposed-text">Proposed Text</a></h1>
<h1><a class="toc-backref" href="#id29" name="proposed-text">Proposed Text</a></h1>
<div class="section" id="header-iterator-helper-synopsis-lib-iterator-helper-synopsis">
<h2><a class="toc-backref" href="#id24" name="header-iterator-helper-synopsis-lib-iterator-helper-synopsis">Header <tt class="literal"><span class="pre">&lt;iterator_helper&gt;</span></tt> synopsis [lib.iterator.helper.synopsis]</a></h2>
<h2><a class="toc-backref" href="#id30" name="header-iterator-helper-synopsis-lib-iterator-helper-synopsis">Header <tt class="literal"><span class="pre">&lt;iterator_helper&gt;</span></tt> synopsis [lib.iterator.helper.synopsis]</a></h2>
<pre class="literal-block">
struct use_default;
@ -560,15 +564,345 @@ class function_output_iterator;
</pre>
</div>
<div class="section" id="iterator-facade-lib-iterator-facade">
<h2><a class="toc-backref" href="#id25" name="iterator-facade-lib-iterator-facade">Iterator facade [lib.iterator.facade]</a></h2>
<p>..include:: iterator_facade_abstract.rst</p>
<h2><a class="toc-backref" href="#id31" name="iterator-facade-lib-iterator-facade">Iterator facade [lib.iterator.facade]</a></h2>
<p><tt class="literal"><span class="pre">iterator_facade</span></tt> is a base class template that implements the
interface of standard iterators in terms of a few core functions
and associated types, to be supplied by a derived iterator class.</p>
<div class="section" id="class-template-iterator-facade">
<h3><a class="toc-backref" href="#id26" name="class-template-iterator-facade">Class template <tt class="literal"><span class="pre">iterator_facade</span></tt></a></h3>
<p>..include:: iterator_facade_ref.rst</p>
<h3><a class="toc-backref" href="#id32" name="class-template-iterator-facade">Class template <tt class="literal"><span class="pre">iterator_facade</span></tt></a></h3>
<pre class="literal-block">
template &lt;
class Derived
, class Value
, class AccessCategory
, class TraversalCategory
, class Reference = /* see <a class="reference" href="#iterator-facade-requirements">below</a> */
, class Difference = ptrdiff_t
&gt;
class iterator_facade {
public:
typedef remove_cv&lt;Value&gt;::type value_type;
typedef Reference reference;
typedef /* see <a class="reference" href="#operator-arrow">description of operator-&gt;</a> */ pointer;
typedef Difference difference_type;
typedef iterator_tag&lt;AccessCategory, TraversalCategory&gt; iterator_category;
reference operator*() const;
/* see <a class="reference" href="#operator-arrow">below</a> */ operator-&gt;() const;
/* see <a class="reference" href="#brackets">below</a> */ operator[](difference_type n) const;
Derived&amp; operator++();
Derived operator++(int);
Derived&amp; operator--();
Derived operator--(int);
Derived&amp; operator+=(difference_type n);
Derived&amp; operator-=(difference_type n);
Derived operator-(difference_type n) const;
};
// Comparison operators
template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;
typename enable_if_interoperable&lt;Dr1, Dr2, bool&gt;::type // exposition
operator ==(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);
template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;
typename enable_if_interoperable&lt;Dr1, Dr2, bool&gt;::type
operator !=(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);
template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;
typename enable_if_interoperable&lt;Dr1, Dr2, bool&gt;::type
operator &lt;(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);
template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;
typename enable_if_interoperable&lt;Dr1, Dr2, bool&gt;::type
operator &lt;=(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);
template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;
typename enable_if_interoperable&lt;Dr1, Dr2, bool&gt;::type
operator &gt;(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);
template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;
typename enable_if_interoperable&lt;Dr1, Dr2, bool&gt;::type
operator &gt;=(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);
template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;
typename enable_if_interoperable&lt;Dr1, Dr2, bool&gt;::type
operator &gt;=(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);
// Iterator difference
template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;
typename enable_if_interoperable&lt;Dr1, Dr2, bool&gt;::type
operator -(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);
// Iterator addition
template &lt;class Derived, class V, class AC, class TC, class R, class D&gt;
Derived operator+ (iterator_facade&lt;Derived, V, AC, TC, R, D&gt; const&amp;,
typename Derived::difference_type n)
</pre>
<p>[<em>Note:</em> The <tt class="literal"><span class="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 <tt class="literal"><span class="pre">Dr1</span></tt> and <tt class="literal"><span class="pre">Dr2</span></tt> are interoperable, by
which we mean they are convertible to each other. The
<tt class="literal"><span class="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 -->
<a class="target" id="iterator-facade-requirements" name="iterator-facade-requirements"></a><div class="section" id="id13">
<h4><a class="toc-backref" href="#id33" name="id13"><tt class="literal"><span class="pre">iterator_facade</span></tt> requirements</a></h4>
<p>The <tt class="literal"><span class="pre">Derived</span></tt> template parameter must be a class derived from
<tt class="literal"><span class="pre">iterator_facade</span></tt>.</p>
<p>The default for the <tt class="literal"><span class="pre">Reference</span></tt> parameter is <tt class="literal"><span class="pre">Value&amp;</span></tt> if the
access category for <tt class="literal"><span class="pre">iterator_facade</span></tt> is implicitly convertible to
<tt class="literal"><span class="pre">writable_iterator_tag</span></tt>, and <tt class="literal"><span class="pre">const</span> <span class="pre">Value&amp;</span></tt> otherwise.</p>
<p>The following table describes the other requirements on the
<tt class="literal"><span class="pre">Derived</span></tt> parameter. Depending on the resulting iterator's
<tt class="literal"><span class="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 <tt class="literal"><span class="pre">iterator_core_access</span></tt>.</p>
<p>In the table below, <tt class="literal"><span class="pre">X</span></tt> is the derived iterator type, <tt class="literal"><span class="pre">a</span></tt> is an
object of type <tt class="literal"><span class="pre">X</span></tt>, <tt class="literal"><span class="pre">b</span></tt> and <tt class="literal"><span class="pre">c</span></tt> are objects of type <tt class="literal"><span class="pre">const</span> <span class="pre">X</span></tt>,
<tt class="literal"><span class="pre">n</span></tt> is an object of <tt class="literal"><span class="pre">X::difference_type</span></tt>, <tt class="literal"><span class="pre">y</span></tt> is a constant
object of a single pass iterator type interoperable with X, and <tt class="literal"><span class="pre">z</span></tt>
is a constant object of a random access traversal iterator type
interoperable with <tt class="literal"><span class="pre">X</span></tt>.</p>
<table border class="table">
<colgroup>
<col width="19%" />
<col width="18%" />
<col width="36%" />
<col width="26%" />
</colgroup>
<thead valign="bottom">
<tr><th>Expression</th>
<th>Return Type</th>
<th>Assertion/Note</th>
<th>Required to implement
Iterator Concept(s)</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="literal"><span class="pre">c.dereference()</span></tt></td>
<td><tt class="literal"><span class="pre">X::reference</span></tt></td>
<td>&nbsp;</td>
<td>Readable Iterator, Writable
Iterator</td>
</tr>
<tr><td><tt class="literal"><span class="pre">c.equal(b)</span></tt></td>
<td>convertible to bool</td>
<td>true iff <tt class="literal"><span class="pre">b</span></tt> and <tt class="literal"><span class="pre">c</span></tt> are
equivalent.</td>
<td>Single Pass Iterator</td>
</tr>
<tr><td><tt class="literal"><span class="pre">c.equal(y)</span></tt></td>
<td>convertible to bool</td>
<td>true iff <tt class="literal"><span class="pre">c</span></tt> and <tt class="literal"><span class="pre">y</span></tt> refer to the
same position. Implements <tt class="literal"><span class="pre">c</span> <span class="pre">==</span> <span class="pre">y</span></tt>
and <tt class="literal"><span class="pre">c</span> <span class="pre">!=</span> <span class="pre">y</span></tt>.</td>
<td>Single Pass Iterator</td>
</tr>
<tr><td><tt class="literal"><span class="pre">a.advance(n)</span></tt></td>
<td>unused</td>
<td>&nbsp;</td>
<td>Random Access Traversal
Iterator</td>
</tr>
<tr><td><tt class="literal"><span class="pre">a.increment()</span></tt></td>
<td>unused</td>
<td>&nbsp;</td>
<td>Incrementable Iterator</td>
</tr>
<tr><td><tt class="literal"><span class="pre">a.decrement()</span></tt></td>
<td>unused</td>
<td>&nbsp;</td>
<td>Bidirectional Traversal
Iterator</td>
</tr>
<tr><td><tt class="literal"><span class="pre">c.distance_to(b)</span></tt></td>
<td>convertible to
X::difference_type</td>
<td>equivalent to <tt class="literal"><span class="pre">distance(c,</span> <span class="pre">b)</span></tt></td>
<td>Random Access Traversal
Iterator</td>
</tr>
<tr><td><tt class="literal"><span class="pre">c.distance_to(z)</span></tt></td>
<td>convertible to
X::difference_type</td>
<td>equivalent to <tt class="literal"><span class="pre">distance(c,</span> <span class="pre">z)</span></tt>.
Implements <tt class="literal"><span class="pre">c</span> <span class="pre">-</span> <span class="pre">z</span></tt>, <tt class="literal"><span class="pre">c</span> <span class="pre">&lt;</span> <span class="pre">z</span></tt>, <tt class="literal"><span class="pre">c</span>
<span class="pre">&lt;=</span> <span class="pre">z</span></tt>, <tt class="literal"><span class="pre">c</span> <span class="pre">&gt;</span> <span class="pre">z</span></tt>, and <tt class="literal"><span class="pre">c</span> <span class="pre">&gt;=</span> <span class="pre">c</span></tt>.</td>
<td>Random Access Traversal
Iterator</td>
</tr>
</tbody>
</table>
<!-- We should explain more about how the
functions in the interface of iterator_facade
are there conditionally. -JGS -->
</div>
<div class="section" id="iterator-facade-operations">
<h4><a class="toc-backref" href="#id34" name="iterator-facade-operations"><tt class="literal"><span class="pre">iterator_facade</span></tt> operations</a></h4>
<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
through member functions of class <tt class="literal"><span class="pre">iterator_core_access</span></tt>.</p>
<p><tt class="literal"><span class="pre">reference</span> <span class="pre">operator*()</span> <span class="pre">const;</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">static_cast&lt;Derived</span> <span class="pre">const*&gt;(this)-&gt;dereference()</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">operator-&gt;()</span> <span class="pre">const;</span></tt> (see <a class="reference" href="#operator-arrow">below</a>)</p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">If <tt class="literal"><span class="pre">X::reference</span></tt> is a reference type, returns an object
of type <tt class="literal"><span class="pre">X::pointer</span></tt> equal to:</p>
<pre class="literal-block">
&amp;static_cast&lt;Derived const*&gt;(this)-&gt;dereference()
</pre>
<p>Otherwise returns an object of unspecified type such that, given an
object <tt class="literal"><span class="pre">a</span></tt> of type <tt class="literal"><span class="pre">X</span></tt>, <tt class="literal"><span class="pre">a-&gt;m</span></tt> is equivalent to <tt class="literal"><span class="pre">(w</span> <span class="pre">=</span> <span class="pre">*a,</span>
<span class="pre">w.m)</span></tt> for some temporary object <tt class="literal"><span class="pre">w</span></tt> of type <tt class="literal"><span class="pre">X::value_type</span></tt>.</p>
<p class="last">The type <tt class="literal"><span class="pre">X::pointer</span></tt> is <tt class="literal"><span class="pre">Value*</span></tt> if the access category for
<tt class="literal"><span class="pre">X</span></tt> is implicitly convertible to <tt class="literal"><span class="pre">writable_iterator_tag</span></tt>, and
<tt class="literal"><span class="pre">Value</span> <span class="pre">const*</span></tt> otherwise.</p>
</td>
</tr>
</tbody>
</table>
<a class="target" id="brackets" name="brackets"></a><p><em>unspecified</em> <tt class="literal"><span class="pre">operator[](difference_type</span> <span class="pre">n)</span> <span class="pre">const;</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">an object convertible to <tt class="literal"><span class="pre">X::reference</span></tt> and holding a copy
<em>p</em> of <tt class="literal"><span class="pre">a+n</span></tt> such that, for a constant object <tt class="literal"><span class="pre">v</span></tt> of type
<tt class="literal"><span class="pre">X::value_type</span></tt>, <tt class="literal"><span class="pre">X::reference(a[n]</span> <span class="pre">=</span> <span class="pre">v)</span></tt> is equivalent
to <tt class="literal"><span class="pre">p</span> <span class="pre">=</span> <span class="pre">v</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">Derived&amp;</span> <span class="pre">operator++();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><pre class="first last literal-block">
static_cast&lt;Derived*&gt;(this)-&gt;increment();
return *this;
</pre>
</td>
</tr>
</tbody>
</table>
<!-- I realize that the committee is moving away from specifying things
like this in terms of code, but I worried about the imprecision of
saying that a core interface function is invoked without describing
the downcast. An alternative to what I did would be to mention it
above where we talk about accessibility. -->
<p><tt class="literal"><span class="pre">Derived</span> <span class="pre">operator++(int);</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><pre class="first last literal-block">
Derived tmp(static_cast&lt;Derived const*&gt;(this));
++*this;
return tmp;
</pre>
</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">Derived&amp;</span> <span class="pre">operator--();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><pre class="first last literal-block">
static_cast&lt;Derived*&gt;(this)-&gt;decrement();
return *this;
</pre>
</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">Derived</span> <span class="pre">operator--(int);</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><pre class="first last literal-block">
Derived tmp(static_cast&lt;Derived const*&gt;(this));
--*this;
return tmp;
</pre>
</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">Derived&amp;</span> <span class="pre">operator+=(difference_type</span> <span class="pre">n);</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><pre class="first last literal-block">
static_cast&lt;Derived*&gt;(this)-&gt;advance(n);
return *this;
</pre>
</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">Derived&amp;</span> <span class="pre">operator-=(difference_type</span> <span class="pre">n);</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><pre class="first last literal-block">
static_cast&lt;Derived*&gt;(this)-&gt;advance(-n);
return *this;
</pre>
</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">Derived</span> <span class="pre">operator-(difference_type</span> <span class="pre">n)</span> <span class="pre">const;</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Derived tmp(static_cast&lt;Derived const*&gt;(this));
return tmp -= n;</td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">static_cast&lt;Derived</span> <span class="pre">const*&gt;(this)-&gt;advance(-n);</span></tt></td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="section" id="iterator-adaptor-lib-iterator-adaptor">
<h2><a class="toc-backref" href="#id27" name="iterator-adaptor-lib-iterator-adaptor">Iterator adaptor [lib.iterator.adaptor]</a></h2>
<h2><a class="toc-backref" href="#id35" name="iterator-adaptor-lib-iterator-adaptor">Iterator adaptor [lib.iterator.adaptor]</a></h2>
<p>The <tt class="literal"><span class="pre">iterator_adaptor</span></tt> is a base class template derived from an
instantiation of <tt class="literal"><span class="pre">iterator_facade</span></tt>. The core interface functions
expected by <tt class="literal"><span class="pre">iterator_facade</span></tt> are implemented in terms of the
@ -580,7 +914,7 @@ depends on the operations supported by the <tt class="literal"><span class="pre"
core interface functions of <tt class="literal"><span class="pre">iterator_facade</span></tt> are redefined in the
<tt class="literal"><span class="pre">Derived</span></tt> class.</p>
<div class="section" id="class-template-iterator-adaptor">
<h3><a class="toc-backref" href="#id28" name="class-template-iterator-adaptor">Class template <tt class="literal"><span class="pre">iterator_adaptor</span></tt></a></h3>
<h3><a class="toc-backref" href="#id36" name="class-template-iterator-adaptor">Class template <tt class="literal"><span class="pre">iterator_adaptor</span></tt></a></h3>
<pre class="literal-block">
template &lt;
class Derived
@ -625,7 +959,7 @@ class iterator_adaptor
</pre>
</div>
<div class="section" id="iterator-adaptor-requirements">
<h3><a class="toc-backref" href="#id29" name="iterator-adaptor-requirements"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> requirements</a></h3>
<h3><a class="toc-backref" href="#id37" name="iterator-adaptor-requirements"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> requirements</a></h3>
<p>The <tt class="literal"><span class="pre">Derived</span></tt> template parameter must be a derived class of
<tt class="literal"><span class="pre">iterator_adaptor</span></tt>. The <tt class="literal"><span class="pre">Base</span></tt> type must implement the expressions
involving <tt class="literal"><span class="pre">m_iterator</span></tt> in the specifications of those private member
@ -679,7 +1013,7 @@ else
iterator_category = Category; -->
</div>
<div class="section" id="iterator-adaptor-public-operations">
<h3><a class="toc-backref" href="#id30" name="iterator-adaptor-public-operations"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> public operations</a></h3>
<h3><a class="toc-backref" href="#id38" name="iterator-adaptor-public-operations"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> public operations</a></h3>
<p><tt class="literal"><span class="pre">iterator_adaptor();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
@ -713,7 +1047,7 @@ else
</table>
</div>
<div class="section" id="iterator-adaptor-protected-member-functions">
<h3><a class="toc-backref" href="#id31" name="iterator-adaptor-protected-member-functions"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> protected member functions</a></h3>
<h3><a class="toc-backref" href="#id39" name="iterator-adaptor-protected-member-functions"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> protected member functions</a></h3>
<p><tt class="literal"><span class="pre">Base</span> <span class="pre">const&amp;</span> <span class="pre">base_reference()</span> <span class="pre">const;</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
@ -734,7 +1068,7 @@ else
</table>
</div>
<div class="section" id="iterator-adaptor-private-member-functions">
<h3><a class="toc-backref" href="#id32" name="iterator-adaptor-private-member-functions"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> private member functions</a></h3>
<h3><a class="toc-backref" href="#id40" name="iterator-adaptor-private-member-functions"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> private member functions</a></h3>
<p><tt class="literal"><span class="pre">typename</span> <span class="pre">iterator_adaptor::reference</span> <span class="pre">dereference()</span> <span class="pre">const;</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
@ -803,7 +1137,7 @@ typename iterator_adaptor::difference_type distance_to(
</div>
</div>
<div class="section" id="specialized-adaptors-lib-iterator-special-adaptors">
<h2><a class="toc-backref" href="#id33" name="specialized-adaptors-lib-iterator-special-adaptors">Specialized adaptors [lib.iterator.special.adaptors]</a></h2>
<h2><a class="toc-backref" href="#id41" name="specialized-adaptors-lib-iterator-special-adaptors">Specialized adaptors [lib.iterator.special.adaptors]</a></h2>
<!-- The requirements for all of these need to be written *much* more
formally -DWA -->
<p>[<em>Note:</em> The <tt class="literal"><span class="pre">enable_if_convertible&lt;X,Y&gt;::type</span></tt> expression used in
@ -814,7 +1148,7 @@ type <tt class="literal"><span class="pre">Y</span></tt>. The <tt class="litera
take the constructor out of the overload set when the types are not
implicitly convertible.]</p>
<div class="section" id="indirect-iterator">
<h3><a class="toc-backref" href="#id34" name="indirect-iterator">Indirect iterator</a></h3>
<h3><a class="toc-backref" href="#id42" name="indirect-iterator">Indirect iterator</a></h3>
<p>The indirect iterator adapts an iterator by applying an <em>extra</em>
dereference inside of <tt class="literal"><span class="pre">operator*()</span></tt>. For example, this iterator
adaptor makes it possible to view a container of pointers
@ -823,7 +1157,7 @@ adaptor makes it possible to view a container of pointers
<!-- At some point we should add the capability to handle
iterators over smart pointers, which the impl handles. -JGS -->
<div class="section" id="class-template-indirect-iterator">
<h4><a class="toc-backref" href="#id35" name="class-template-indirect-iterator">Class template <tt class="literal"><span class="pre">indirect_iterator</span></tt></a></h4>
<h4><a class="toc-backref" href="#id43" name="class-template-indirect-iterator">Class template <tt class="literal"><span class="pre">indirect_iterator</span></tt></a></h4>
<pre class="literal-block">
template &lt;
class Iterator
@ -858,7 +1192,7 @@ private: // as-if specification
</pre>
</div>
<div class="section" id="indirect-iterator-requirements">
<h4><a class="toc-backref" href="#id36" name="indirect-iterator-requirements"><tt class="literal"><span class="pre">indirect_iterator</span></tt> requirements</a></h4>
<h4><a class="toc-backref" href="#id44" name="indirect-iterator-requirements"><tt class="literal"><span class="pre">indirect_iterator</span></tt> requirements</a></h4>
<p>The <tt class="literal"><span class="pre">value_type</span></tt> of the <tt class="literal"><span class="pre">Iterator</span></tt> template parameter should
itself be dereferenceable. The return type of the <tt class="literal"><span class="pre">operator*</span></tt> for
the <tt class="literal"><span class="pre">value_type</span></tt> must be the same type as the <tt class="literal"><span class="pre">Reference</span></tt> template
@ -883,7 +1217,7 @@ iterator will model the most refined standard access concept that is
modeled by the value type of <tt class="literal"><span class="pre">Iterator</span></tt>.</p>
</div>
<div class="section" id="indirect-iterator-operations">
<h4><a class="toc-backref" href="#id37" name="indirect-iterator-operations"><tt class="literal"><span class="pre">indirect_iterator</span></tt> operations</a></h4>
<h4><a class="toc-backref" href="#id45" name="indirect-iterator-operations"><tt class="literal"><span class="pre">indirect_iterator</span></tt> operations</a></h4>
<p><tt class="literal"><span class="pre">indirect_iterator();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
@ -931,13 +1265,13 @@ indirect_iterator(
</div>
</div>
<div class="section" id="reverse-iterator">
<h3><a class="toc-backref" href="#id38" name="reverse-iterator">Reverse iterator</a></h3>
<h3><a class="toc-backref" href="#id46" name="reverse-iterator">Reverse iterator</a></h3>
<!-- I think we'd better strike the old reverse_iterator text from the standard, eh? -->
<p>The reverse iterator adaptor flips the direction of a base iterator's
motion. Invoking <tt class="literal"><span class="pre">operator++()</span></tt> moves the base iterator backward and
invoking <tt class="literal"><span class="pre">operator--()</span></tt> moves the base iterator forward.</p>
<div class="section" id="class-template-reverse-iterator">
<h4><a class="toc-backref" href="#id39" name="class-template-reverse-iterator">Class template <tt class="literal"><span class="pre">reverse_iterator</span></tt></a></h4>
<h4><a class="toc-backref" href="#id47" name="class-template-reverse-iterator">Class template <tt class="literal"><span class="pre">reverse_iterator</span></tt></a></h4>
<pre class="literal-block">
template &lt;class Iterator&gt;
class reverse_iterator :
@ -976,7 +1310,7 @@ private: // as-if specification
</pre>
</div>
<div class="section" id="reverse-iterator-requirements">
<h4><a class="toc-backref" href="#id40" name="reverse-iterator-requirements"><tt class="literal"><span class="pre">reverse_iterator</span></tt> requirements</a></h4>
<h4><a class="toc-backref" href="#id48" name="reverse-iterator-requirements"><tt class="literal"><span class="pre">reverse_iterator</span></tt> requirements</a></h4>
<p>The base <tt class="literal"><span class="pre">Iterator</span></tt> must be a model of Bidirectional Traversal
Iterator. The resulting <tt class="literal"><span class="pre">reverse_iterator</span></tt> will be a model of the
most refined standard traversal and access concepts that are modeled
@ -1023,14 +1357,14 @@ reverse_iterator(
</div>
</div>
<div class="section" id="transform-iterator">
<h3><a class="toc-backref" href="#id41" name="transform-iterator">Transform iterator</a></h3>
<h3><a class="toc-backref" href="#id49" name="transform-iterator">Transform iterator</a></h3>
<p>The transform iterator adapts an iterator by applying some function
object to the result of dereferencing the iterator. In other words,
the <tt class="literal"><span class="pre">operator*</span></tt> of the transform iterator first dereferences the
base iterator, passes the result of this to the function object, and
then returns the result.</p>
<div class="section" id="class-template-transform-iterator">
<h4><a class="toc-backref" href="#id42" name="class-template-transform-iterator">Class template <tt class="literal"><span class="pre">transform_iterator</span></tt></a></h4>
<h4><a class="toc-backref" href="#id50" name="class-template-transform-iterator">Class template <tt class="literal"><span class="pre">transform_iterator</span></tt></a></h4>
<pre class="literal-block">
template &lt;class AdaptableUnaryFunction,
class Iterator,
@ -1058,7 +1392,7 @@ private:
</pre>
</div>
<div class="section" id="transform-iterator-requirements">
<h4><a class="toc-backref" href="#id43" name="transform-iterator-requirements"><tt class="literal"><span class="pre">transform_iterator</span></tt> requirements</a></h4>
<h4><a class="toc-backref" href="#id51" name="transform-iterator-requirements"><tt class="literal"><span class="pre">transform_iterator</span></tt> requirements</a></h4>
<p>The type <tt class="literal"><span class="pre">AdaptableUnaryFunction</span></tt> must be Assignable, Copy
Constructible, and the expression <tt class="literal"><span class="pre">f(x)</span></tt> must be valid where <tt class="literal"><span class="pre">f</span></tt>
is an object of type <tt class="literal"><span class="pre">AdaptableUnaryFunction</span></tt>, <tt class="literal"><span class="pre">x</span></tt> is an object of
@ -1083,7 +1417,7 @@ concept that is modeled by <tt class="literal"><span class="pre">Iterator</span>
<tt class="literal"><span class="pre">result_type</span></tt>.</p>
</div>
<div class="section" id="transform-iterator-public-operations">
<h4><a class="toc-backref" href="#id44" name="transform-iterator-public-operations"><tt class="literal"><span class="pre">transform_iterator</span></tt> public operations</a></h4>
<h4><a class="toc-backref" href="#id52" name="transform-iterator-public-operations"><tt class="literal"><span class="pre">transform_iterator</span></tt> public operations</a></h4>
<p><tt class="literal"><span class="pre">transform_iterator();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
@ -1132,7 +1466,7 @@ transform_iterator(
</table>
</div>
<div class="section" id="transform-iterator-private-operations">
<h4><a class="toc-backref" href="#id45" name="transform-iterator-private-operations"><tt class="literal"><span class="pre">transform_iterator</span></tt> private operations</a></h4>
<h4><a class="toc-backref" href="#id53" name="transform-iterator-private-operations"><tt class="literal"><span class="pre">transform_iterator</span></tt> private operations</a></h4>
<p><tt class="literal"><span class="pre">typename</span> <span class="pre">transform_iterator::value_type</span> <span class="pre">dereference()</span> <span class="pre">const;</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
@ -1145,7 +1479,7 @@ transform_iterator(
</div>
</div>
<div class="section" id="filter-iterator">
<h3><a class="toc-backref" href="#id46" name="filter-iterator">Filter iterator</a></h3>
<h3><a class="toc-backref" href="#id54" name="filter-iterator">Filter iterator</a></h3>
<p>The filter iterator adaptor creates a view of an iterator range in
which some elements of the range are skipped over. A predicate
function object controls which elements are skipped. When the
@ -1157,7 +1491,7 @@ of the underlying range. Therefore the constructor of the filter
iterator takes two iterator parameters: the position for the filtered
iterator and the end of the range.</p>
<div class="section" id="class-template-filter-iterator">
<h4><a class="toc-backref" href="#id47" name="class-template-filter-iterator">Class template <tt class="literal"><span class="pre">filter_iterator</span></tt></a></h4>
<h4><a class="toc-backref" href="#id55" name="class-template-filter-iterator">Class template <tt class="literal"><span class="pre">filter_iterator</span></tt></a></h4>
<pre class="literal-block">
template &lt;class Predicate, class Iterator&gt;
class filter_iterator
@ -1199,7 +1533,7 @@ class filter_iterator
</div>
</div>
<div class="section" id="filter-iterator-requirements">
<h3><a class="toc-backref" href="#id48" name="filter-iterator-requirements"><tt class="literal"><span class="pre">filter_iterator</span></tt> requirements</a></h3>
<h3><a class="toc-backref" href="#id56" name="filter-iterator-requirements"><tt class="literal"><span class="pre">filter_iterator</span></tt> requirements</a></h3>
<p>The base <tt class="literal"><span class="pre">Iterator</span></tt> parameter must be a model of Readable Iterator
and Single Pass Iterator. The resulting <tt class="literal"><span class="pre">filter_iterator</span></tt> will be a
model of Forward Traversal Iterator if <tt class="literal"><span class="pre">Iterator</span></tt> is, otherwise the
@ -1215,7 +1549,7 @@ expression <tt class="literal"><span class="pre">p(x)</span></tt> must be valid
<tt class="literal"><span class="pre">p(x)</span></tt> must be convertible to <tt class="literal"><span class="pre">bool</span></tt>.</p>
</div>
<div class="section" id="filter-iterator-operations">
<h3><a class="toc-backref" href="#id49" name="filter-iterator-operations"><tt class="literal"><span class="pre">filter_iterator</span></tt> operations</a></h3>
<h3><a class="toc-backref" href="#id57" name="filter-iterator-operations"><tt class="literal"><span class="pre">filter_iterator</span></tt> operations</a></h3>
<p><tt class="literal"><span class="pre">filter_iterator();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
@ -1288,14 +1622,14 @@ filter_iterator(
</tbody>
</table>
</div>
<div class="section" id="id10">
<h3><a class="toc-backref" href="#id50" name="id10">Counting iterator</a></h3>
<div class="section" id="id16">
<h3><a class="toc-backref" href="#id58" name="id16">Counting iterator</a></h3>
<p>The counting iterator adaptor implements dereference by returning a
reference to the base object. The other operations are implemented by
the base <tt class="literal"><span class="pre">m_iterator</span></tt>, as per the inheritance from
<tt class="literal"><span class="pre">iterator_adaptor</span></tt>.</p>
<div class="section" id="class-template-counting-iterator">
<h4><a class="toc-backref" href="#id51" name="class-template-counting-iterator">Class template <tt class="literal"><span class="pre">counting_iterator</span></tt></a></h4>
<h4><a class="toc-backref" href="#id59" name="class-template-counting-iterator">Class template <tt class="literal"><span class="pre">counting_iterator</span></tt></a></h4>
<pre class="literal-block">
template &lt;class Incrementable, class Category = use_default, class Difference = use_default&gt;
class counting_iterator
@ -1328,7 +1662,7 @@ the cases when the <tt class="literal"><span class="pre">Incrementable</span></t
</div>
</div>
<div class="section" id="counting-iterator-requirements">
<h3><a class="toc-backref" href="#id52" name="counting-iterator-requirements"><tt class="literal"><span class="pre">counting_iterator</span></tt> requirements</a></h3>
<h3><a class="toc-backref" href="#id60" name="counting-iterator-requirements"><tt class="literal"><span class="pre">counting_iterator</span></tt> requirements</a></h3>
<p>The <tt class="literal"><span class="pre">Incrementable</span></tt> type must be Default Constructible, Copy
Constructible, and Assignable. The default distance is
an implementation defined signed integegral type.</p>
@ -1356,7 +1690,7 @@ i &lt; j
</pre>
</div>
<div class="section" id="counting-iterator-operations">
<h3><a class="toc-backref" href="#id53" name="counting-iterator-operations"><tt class="literal"><span class="pre">counting_iterator</span></tt> operations</a></h3>
<h3><a class="toc-backref" href="#id61" name="counting-iterator-operations"><tt class="literal"><span class="pre">counting_iterator</span></tt> operations</a></h3>
<p><tt class="literal"><span class="pre">counting_iterator();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
@ -1387,7 +1721,7 @@ object copy constructed from <tt class="literal"><span class="pre">x</span></tt>
</table>
</div>
<div class="section" id="function-output-iterator">
<h3><a class="toc-backref" href="#id54" name="function-output-iterator">Function output iterator</a></h3>
<h3><a class="toc-backref" href="#id62" name="function-output-iterator">Function output iterator</a></h3>
<p>The function output iterator adaptor makes it easier to create custom
output iterators. The adaptor takes a unary function and creates a
model of Output Iterator. Each item assigned to the output iterator is
@ -1396,7 +1730,7 @@ iterator is that creating a conforming output iterator is non-trivial,
particularly because the proper implementation usually requires a
proxy object.</p>
<div class="section" id="class-template-function-output-iterator">
<h4><a class="toc-backref" href="#id55" name="class-template-function-output-iterator">Class template <tt class="literal"><span class="pre">function_output_iterator</span></tt></a></h4>
<h4><a class="toc-backref" href="#id63" name="class-template-function-output-iterator">Class template <tt class="literal"><span class="pre">function_output_iterator</span></tt></a></h4>
<pre class="literal-block">
template &lt;class UnaryFunction&gt;
class function_output_iterator {
@ -1424,7 +1758,7 @@ public:
</div>
</div>
<div class="section" id="function-output-iterator-requirements">
<h3><a class="toc-backref" href="#id56" name="function-output-iterator-requirements"><tt class="literal"><span class="pre">function_output_iterator</span></tt> requirements</a></h3>
<h3><a class="toc-backref" href="#id64" name="function-output-iterator-requirements"><tt class="literal"><span class="pre">function_output_iterator</span></tt> requirements</a></h3>
<p>The <tt class="literal"><span class="pre">UnaryFunction</span></tt> must be Assignable, Copy Constructible, and the
expression <tt class="literal"><span class="pre">f(x)</span></tt> must be valid, where <tt class="literal"><span class="pre">f</span></tt> is an object of type
<tt class="literal"><span class="pre">UnaryFunction</span></tt> and <tt class="literal"><span class="pre">x</span></tt> is an object of a type accepted by <tt class="literal"><span class="pre">f</span></tt>.
@ -1432,7 +1766,7 @@ The resulting <tt class="literal"><span class="pre">function_output_iterator</sp
and Incrementable Iterator concepts.</p>
</div>
<div class="section" id="function-output-iterator-operations">
<h3><a class="toc-backref" href="#id57" name="function-output-iterator-operations"><tt class="literal"><span class="pre">function_output_iterator</span></tt> operations</a></h3>
<h3><a class="toc-backref" href="#id65" name="function-output-iterator-operations"><tt class="literal"><span class="pre">function_output_iterator</span></tt> operations</a></h3>
<p><tt class="literal"><span class="pre">explicit</span> <span class="pre">function_output_iterator(const</span> <span class="pre">UnaryFunction&amp;</span> <span class="pre">f</span> <span class="pre">=</span> <span class="pre">UnaryFunction());</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
@ -1473,7 +1807,7 @@ a copy of the unary function <tt class="literal"><span class="pre">f</span></tt>
</table>
</div>
<div class="section" id="function-output-iterator-output-proxy-operations">
<h3><a class="toc-backref" href="#id58" name="function-output-iterator-output-proxy-operations"><tt class="literal"><span class="pre">function_output_iterator::output_proxy</span></tt> operations</a></h3>
<h3><a class="toc-backref" href="#id66" name="function-output-iterator-output-proxy-operations"><tt class="literal"><span class="pre">function_output_iterator::output_proxy</span></tt> operations</a></h3>
<p><tt class="literal"><span class="pre">output_proxy(UnaryFunction&amp;</span> <span class="pre">f);</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />

194
doc/facade-and-adaptor.rst
View File

@ -287,208 +287,22 @@ Header ``<iterator_helper>`` synopsis [lib.iterator.helper.synopsis]
Iterator facade [lib.iterator.facade]
=====================================
..include:: iterator_facade_abstract.rst
.. include:: iterator_facade_abstract.rst
Class template ``iterator_facade``
----------------------------------
..include:: iterator_facade_ref.rst
.. include:: iterator_facade_ref.rst
Iterator adaptor [lib.iterator.adaptor]
=======================================
The ``iterator_adaptor`` is a base class template derived from an
instantiation of ``iterator_facade``. The core interface functions
expected by ``iterator_facade`` are implemented in terms of the
``iterator_adaptor``\ 's ``Base`` template parameter. A class derived
from ``iterator_adaptor`` typically redefines some of the core
interface functions to adapt the behavior of the ``Base`` type.
Whether the derived class models any of the standard iterator concepts
depends on the operations supported by the ``Base`` type and which
core interface functions of ``iterator_facade`` are redefined in the
``Derived`` class.
.. include:: iterator_adaptor_abstract.rst
Class template ``iterator_adaptor``
-----------------------------------
.. parsed-literal::
template <
class Derived
, class Base
, class Value = use_default
, class Category = use_default
, class Reference = use_default
, class Difference = use_default
>
class iterator_adaptor
: public iterator_facade<Derived, /* see details__ ...\*/>
{
friend class iterator_core_access;
public:
iterator_adaptor();
explicit iterator_adaptor(Base iter);
Base base() const;
protected:
Base const& base_reference() const;
Base& base_reference();
private: // Core iterator interface for iterator_facade.
typename iterator_adaptor::reference dereference() const;
template <
class OtherDerived, class OtherIterator, class V, class C, class R, class D
>
bool equal(iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& x) const;
void advance(typename iterator_adaptor::difference_type n);
void increment();
void decrement();
template <
class OtherDerived, class OtherIterator, class V, class C, class R, class D
>
typename iterator_adaptor::difference_type distance_to(
iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& y) const;
private:
Base m_iterator;
};
__ :
``iterator_adaptor`` requirements
---------------------------------
The ``Derived`` template parameter must be a derived class of
``iterator_adaptor``. The ``Base`` type must implement the expressions
involving ``m_iterator`` in the specifications of those private member
functions of ``iterator_adaptor`` that are not redefined by the
``Derived`` class and that are needed to model the concept
corresponding to the chosen ``Category`` according to the requirements
of ``iterator_facade``. The rest of the template parameters specify
the types for the member typedefs in ``iterator_facade``. The
following pseudo-code specifies the traits types for
``iterator_adaptor``.
::
if (Value == use_default)
value_type = iterator_traits<Base>::value_type;
else
value_type = remove_cv<Value>::type;
if (Reference == use_default) {
if (Value == use_default)
reference = iterator_traits<Base>::reference;
else
reference = Value&;
} else
reference = Reference;
if (Distance == use_default)
difference_type = iterator_traits<Base>::difference_type;
else
difference_type = Distance;
if (Category == use_default)
iterator_category = iterator_tag<
access_category<
iterator< iterator_traits<Base>::iterator_category,
Value,
Distance,
Value*,
Reference > >,
traversal_category<
iterator< iterator_traits<Base>::iterator_category,
Value,
Distance,
Value*,
Reference > >
else
iterator_category = Category;
.. Replaced with new semantics --thw
if (Category == use_default)
iterator_category = iterator_traits<Base>::iterator_category;
else
iterator_category = Category;
``iterator_adaptor`` public operations
--------------------------------------
``iterator_adaptor();``
:Requires: The ``Base`` type must be Default Constructible.
:Returns: An instance of ``iterator_adaptor`` with
``m_iterator`` default constructed.
``explicit iterator_adaptor(Base iter);``
:Returns: An instance of ``iterator_adaptor`` with
``m_iterator`` copy constructed from ``iter``.
``Base base() const;``
:Returns: ``m_iterator``
``iterator_adaptor`` protected member functions
-----------------------------------------------
``Base const& base_reference() const;``
:Returns: A const reference to ``m_iterator``.
``Base& base_reference();``
:Returns: A non-const reference to ``m_iterator``.
``iterator_adaptor`` private member functions
---------------------------------------------
``typename iterator_adaptor::reference dereference() const;``
:Returns: ``*m_iterator``
::
template <
class OtherDerived, class OtherIterator, class V, class C, class R, class D
>
bool equal(iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& x) const;
:Returns: ``m_iterator == x.base()``
``void advance(typename iterator_adaptor::difference_type n);``
:Effects: ``m_iterator += n;``
``void increment();``
:Effects: ``++m_iterator;``
``void decrement();``
:Effects: ``--m_iterator;``
::
template <
class OtherDerived, class OtherIterator, class V, class C, class R, class D
>
typename iterator_adaptor::difference_type distance_to(
iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& y) const;
:Returns: ``y.base() - m_iterator``
.. include:: iterator_adaptor_ref.rst
Specialized adaptors [lib.iterator.special.adaptors]

2
doc/index.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.2.8: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.3.0: http://docutils.sourceforge.net/" />
<title>The Boost Iterator Library Boost</title>
<link rel="stylesheet" href="default.css" type="text/css" />
</head>

14
doc/iterator_adaptor.rst
View File

@ -14,5 +14,19 @@
.. _`Open Systems Lab`: http://www.osl.iu.edu
.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de
:abstract:
.. include:: iterator_adaptor_abstract.rst
.. contents:: Table of Contents
Introduction
============
.. include:: iterator_adaptor_body.rst
Reference
=========
.. include:: iterator_adaptor_ref.rst

10
doc/iterator_adaptor_abstract.rst Normal file
View File

@ -0,0 +1,10 @@
The ``iterator_adaptor`` is a base class template derived from an
instantiation of ``iterator_facade``. The core interface functions
expected by ``iterator_facade`` are implemented in terms of the
``iterator_adaptor``\ 's ``Base`` template parameter. A class derived
from ``iterator_adaptor`` typically redefines some of the core
interface functions to adapt the behavior of the ``Base`` type.
Whether the derived class models any of the standard iterator concepts
depends on the operations supported by the ``Base`` type and which
core interface functions of ``iterator_facade`` are redefined in the
``Derived`` class.

176
doc/iterator_adaptor_ref.rst Normal file
View File

@ -0,0 +1,176 @@
.. parsed-literal::
template <
class Derived
, class Base
, class Value = use_default
, class Category = use_default
, class Reference = use_default
, class Difference = use_default
>
class iterator_adaptor
: public iterator_facade<Derived, /* see details__ ...\*/>
{
friend class iterator_core_access;
public:
iterator_adaptor();
explicit iterator_adaptor(Base iter);
Base base() const;
protected:
Base const& base_reference() const;
Base& base_reference();
private: // Core iterator interface for iterator_facade.
typename iterator_adaptor::reference dereference() const;
template <
class OtherDerived, class OtherIterator, class V, class C, class R, class D
>
bool equal(iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& x) const;
void advance(typename iterator_adaptor::difference_type n);
void increment();
void decrement();
template <
class OtherDerived, class OtherIterator, class V, class C, class R, class D
>
typename iterator_adaptor::difference_type distance_to(
iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& y) const;
private:
Base m_iterator;
};
__ :
``iterator_adaptor`` requirements
---------------------------------
The ``Derived`` template parameter must be a derived class of
``iterator_adaptor``. The ``Base`` type must implement the expressions
involving ``m_iterator`` in the specifications of those private member
functions of ``iterator_adaptor`` that are not redefined by the
``Derived`` class and that are needed to model the concept
corresponding to the chosen ``Category`` according to the requirements
of ``iterator_facade``. The rest of the template parameters specify
the types for the member typedefs in ``iterator_facade``. The
following pseudo-code specifies the traits types for
``iterator_adaptor``.
::
if (Value == use_default)
value_type = iterator_traits<Base>::value_type;
else
value_type = remove_cv<Value>::type;
if (Reference == use_default) {
if (Value == use_default)
reference = iterator_traits<Base>::reference;
else
reference = Value&;
} else
reference = Reference;
if (Distance == use_default)
difference_type = iterator_traits<Base>::difference_type;
else
difference_type = Distance;
if (Category == use_default)
iterator_category = iterator_tag<
access_category<
iterator< iterator_traits<Base>::iterator_category,
Value,
Distance,
Value*,
Reference > >,
traversal_category<
iterator< iterator_traits<Base>::iterator_category,
Value,
Distance,
Value*,
Reference > >
else
iterator_category = Category;
.. Replaced with new semantics --thw
if (Category == use_default)
iterator_category = iterator_traits<Base>::iterator_category;
else
iterator_category = Category;
``iterator_adaptor`` public operations
--------------------------------------
``iterator_adaptor();``
:Requires: The ``Base`` type must be Default Constructible.
:Returns: An instance of ``iterator_adaptor`` with
``m_iterator`` default constructed.
``explicit iterator_adaptor(Base iter);``
:Returns: An instance of ``iterator_adaptor`` with
``m_iterator`` copy constructed from ``iter``.
``Base base() const;``
:Returns: ``m_iterator``
``iterator_adaptor`` protected member functions
-----------------------------------------------
``Base const& base_reference() const;``
:Returns: A const reference to ``m_iterator``.
``Base& base_reference();``
:Returns: A non-const reference to ``m_iterator``.
``iterator_adaptor`` private member functions
---------------------------------------------
``typename iterator_adaptor::reference dereference() const;``
:Returns: ``*m_iterator``
::
template <
class OtherDerived, class OtherIterator, class V, class C, class R, class D
>
bool equal(iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& x) const;
:Returns: ``m_iterator == x.base()``
``void advance(typename iterator_adaptor::difference_type n);``
:Effects: ``m_iterator += n;``
``void increment();``
:Effects: ``++m_iterator;``
``void decrement();``
:Effects: ``--m_iterator;``
::
template <
class OtherDerived, class OtherIterator, class V, class C, class R, class D
>
typename iterator_adaptor::difference_type distance_to(
iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& y) const;
:Returns: ``y.base() - m_iterator``

2
doc/iterator_facade_abstract.rst
View File

@ -1,4 +1,4 @@
``iterator_facade`` is a base class template which implements the
``iterator_facade`` is a base class template that implements the
interface of standard iterators in terms of a few core functions
and associated types, to be supplied by a derived iterator class.

4
doc/iterator_facade_ref.rst
View File

@ -106,7 +106,7 @@ out of the overload set when the types are not interoperable.]
.. _iterator facade requirements:
``iterator_facade`` requirements
================================
................................
The ``Derived`` template parameter must be a class derived from
``iterator_facade``.
@ -164,7 +164,7 @@ interoperable with ``X``.
``iterator_facade`` operations
==============================
..............................
The operations in this section are described in terms of operations on
the core interface of ``Derived`` which may be inaccessible

22
doc/new-iter-concepts.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.2.8: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.3.0: http://docutils.sourceforge.net/" />
<title>New Iterator Concepts</title>
<meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" />
<meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, University of Hanover Institute for Transport Railway Operation and Construction" />
@ -92,7 +92,7 @@ geared towards iterator traversal (hence the category names), while
requirements that address value access sneak in at various places. The
following table gives a summary of the current value access
requirements in the iterator categories.</p>
<table class="table" frame="border" rules="all">
<table border class="table">
<colgroup>
<col width="31%" />
<col width="69%" />
@ -326,7 +326,7 @@ for the value type <tt class="literal"><span class="pre">T</span></tt> if the fo
respect the stated semantics. <tt class="literal"><span class="pre">U</span></tt> is the type of any specified
member of type <tt class="literal"><span class="pre">T</span></tt>.</p>
<blockquote>
<table class="table" frame="border" rules="all">
<table border class="table">
<colgroup>
<col width="34%" />
<col width="30%" />
@ -403,7 +403,7 @@ semantics.</p>
if the following expressions are valid and respect the stated
semantics.</p>
<blockquote>
<table class="table" frame="border" rules="all">
<table border class="table">
<colgroup>
<col width="38%" />
<col width="14%" />
@ -435,7 +435,7 @@ semantics.</p>
<p>The <em>Readable Lvalue Iterator</em> concept adds the requirement that the
<tt class="literal"><span class="pre">reference</span></tt> type be a reference to the value type of the iterator.</p>
<blockquote>
<table class="table" frame="border" rules="all">
<table border class="table">
<colgroup>
<col width="35%" />
<col width="32%" />
@ -472,7 +472,7 @@ cv-qualification</td>
<tt class="literal"><span class="pre">reference</span></tt> type be a non-const reference to the value type of the
iterator.</p>
<blockquote>
<table class="table" frame="border" rules="all">
<table border class="table">
<colgroup>
<col width="45%" />
<col width="55%" />
@ -508,7 +508,7 @@ type <tt class="literal"><span class="pre">X</span></tt>, <tt class="literal"><s
concept if the following expressions are valid and respect the stated
semantics.</p>
<blockquote>
<table class="table" frame="border" rules="all">
<table border class="table">
<colgroup>
<col width="27%" />
<col width="38%" />
@ -545,7 +545,7 @@ semantics.</p>
concept if the following expressions are valid and respect the stated
semantics.</p>
<blockquote>
<table class="table" frame="border" rules="all">
<table border class="table">
<colgroup>
<col width="33%" />
<col width="27%" />
@ -590,7 +590,7 @@ its domain</td>
concept if the following expressions are valid and respect the stated
semantics.</p>
<blockquote>
<table class="table" frame="border" rules="all">
<table border class="table">
<colgroup>
<col width="39%" />
<col width="37%" />
@ -636,7 +636,7 @@ the distance between iterators</td>
Iterator</em> concept if the following expressions are valid and respect
the stated semantics.</p>
<blockquote>
<table class="table" frame="border" rules="all">
<table border class="table">
<colgroup>
<col width="28%" />
<col width="36%" />
@ -680,7 +680,7 @@ the stated semantics. In the table below, <tt class="literal"><span class="pre"
<tt class="literal"><span class="pre">iterator_traits&lt;X&gt;::difference_type</span></tt> and <tt class="literal"><span class="pre">n</span></tt> represents a
constant object of type <tt class="literal"><span class="pre">Distance</span></tt>.</p>
<blockquote>
<table class="table" frame="border" rules="all">
<table border class="table">
<colgroup>
<col width="26%" />
<col width="33%" />