boost_mirror/iterator
1
0
Fork 0
mirror of https://github.com/boostorg/iterator.git synced 2025-05-09 23:23:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

updated docs

Browse Source 
[SVN r29099]
This commit is contained in:
Dave Abrahams 2005-05-20 15:32:55 +00:00
parent ab372a0a74
commit 3fe9b7517e
31 changed files with 2483 additions and 2460 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

142
doc/counting_iterator.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.3.6: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.3.8: http://docutils.sourceforge.net/" />
<title>Counting Iterator</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" />
@ -12,6 +12,7 @@
<link rel="stylesheet" href="default.css" type="text/css" />
</head>
<body>
<div class="document" id="counting-iterator">
<h1 class="title">Counting Iterator</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
@ -31,20 +32,19 @@ Railway Operation and Construction</a></td></tr>
<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003.</td></tr>
</tbody>
</table>
<div class="document" id="counting-iterator">
<table class="field-list" frame="void" rules="none">
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">abstract:</th><td class="field-body"><p class="first">How would you fill up a vector with the numbers zero
through one hundred using <tt class="literal"><span class="pre">std::copy()</span></tt>? The only iterator
through one hundred using <tt class="docutils literal"><span class="pre">std::copy()</span></tt>? The only iterator
operation missing from builtin integer types is an
<tt class="literal"><span class="pre">operator*()</span></tt> that returns the current value of the integer.
<tt class="docutils literal"><span class="pre">operator*()</span></tt> that returns the current value of the integer.
The counting iterator adaptor adds this crucial piece of
functionality to whatever type it wraps. One can use the
counting iterator adaptor not only with integer types, but with
any incrementable type.</p>
<p class="last"><tt class="literal"><span class="pre">counting_iterator</span></tt> adapts an object by adding an <tt class="literal"><span class="pre">operator*</span></tt> that
<p class="last"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> adapts an object by adding an <tt class="docutils literal"><span class="pre">operator*</span></tt> that
returns the current value of the object. All other iterator operations
are forwarded to the adapted object.</p>
</td>
@ -54,15 +54,15 @@ are forwarded to the adapted object.</p>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first"><a name="table-of-contents">Table of Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#counting-iterator-synopsis" id="id2" name="id2"><tt class="literal"><span class="pre">counting_iterator</span></tt> synopsis</a></li>
<li><a class="reference" href="#counting-iterator-requirements" id="id3" name="id3"><tt class="literal"><span class="pre">counting_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#counting-iterator-models" id="id4" name="id4"><tt class="literal"><span class="pre">counting_iterator</span></tt> models</a></li>
<li><a class="reference" href="#counting-iterator-operations" id="id5" name="id5"><tt class="literal"><span class="pre">counting_iterator</span></tt> operations</a></li>
<li><a class="reference" href="#counting-iterator-synopsis" id="id2" name="id2"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> synopsis</a></li>
<li><a class="reference" href="#counting-iterator-requirements" id="id3" name="id3"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#counting-iterator-models" id="id4" name="id4"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models</a></li>
<li><a class="reference" href="#counting-iterator-operations" id="id5" name="id5"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> operations</a></li>
<li><a class="reference" href="#example" id="id6" name="id6">Example</a></li>
</ul>
</div>
<div class="section" id="counting-iterator-synopsis">
<h1><a class="toc-backref" href="#id2" name="counting-iterator-synopsis"><tt class="literal"><span class="pre">counting_iterator</span></tt> synopsis</a></h1>
<h1><a class="toc-backref" href="#id2" name="counting-iterator-synopsis"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> synopsis</a></h1>
<pre class="literal-block">
template &lt;
class Incrementable
@ -89,10 +89,10 @@ private:
Incrementable m_inc; // exposition
};
</pre>
<p>If the <tt class="literal"><span class="pre">Difference</span></tt> argument is <tt class="literal"><span class="pre">use_default</span></tt> then
<tt class="literal"><span class="pre">difference_type</span></tt> is an unspecified signed integral
type. Otherwise <tt class="literal"><span class="pre">difference_type</span></tt> is <tt class="literal"><span class="pre">Difference</span></tt>.</p>
<p><tt class="literal"><span class="pre">iterator_category</span></tt> is determined according to the following
<p>If the <tt class="docutils literal"><span class="pre">Difference</span></tt> argument is <tt class="docutils literal"><span class="pre">use_default</span></tt> then
<tt class="docutils literal"><span class="pre">difference_type</span></tt> is an unspecified signed integral
type. Otherwise <tt class="docutils literal"><span class="pre">difference_type</span></tt> is <tt class="docutils literal"><span class="pre">Difference</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">iterator_category</span></tt> is determined according to the following
algorithm:</p>
<pre class="literal-block">
if (CategoryOrTraversal is not use_default)
@ -105,31 +105,31 @@ else
iterator_traversal&lt;Incrementable&gt;::type,
Incrementable, const Incrementable&amp;)
</pre>
<dl>
<dl class="docutils">
<dt>[<em>Note:</em> implementers are encouraged to provide an implementation of</dt>
<dd><tt class="literal"><span class="pre">operator-</span></tt> and a <tt class="literal"><span class="pre">difference_type</span></tt> that avoids overflows in
the cases where <tt class="literal"><span class="pre">std::numeric_limits&lt;Incrementable&gt;::is_specialized</span></tt>
<dd><tt class="docutils literal"><span class="pre">operator-</span></tt> and a <tt class="docutils literal"><span class="pre">difference_type</span></tt> that avoids overflows in
the cases where <tt class="docutils literal"><span class="pre">std::numeric_limits&lt;Incrementable&gt;::is_specialized</span></tt>
is true.]</dd>
</dl>
</div>
<div class="section" id="counting-iterator-requirements">
<h1><a class="toc-backref" href="#id3" name="counting-iterator-requirements"><tt class="literal"><span class="pre">counting_iterator</span></tt> requirements</a></h1>
<p>The <tt class="literal"><span class="pre">Incrementable</span></tt> argument shall be Copy Constructible and Assignable.</p>
<p>If <tt class="literal"><span class="pre">iterator_category</span></tt> is convertible to <tt class="literal"><span class="pre">forward_iterator_tag</span></tt>
or <tt class="literal"><span class="pre">forward_traversal_tag</span></tt>, the following must be well-formed:</p>
<h1><a class="toc-backref" href="#id3" name="counting-iterator-requirements"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> requirements</a></h1>
<p>The <tt class="docutils literal"><span class="pre">Incrementable</span></tt> argument shall be Copy Constructible and Assignable.</p>
<p>If <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible to <tt class="docutils literal"><span class="pre">forward_iterator_tag</span></tt>
or <tt class="docutils literal"><span class="pre">forward_traversal_tag</span></tt>, the following must be well-formed:</p>
<pre class="literal-block">
Incrementable i, j;
++i; // pre-increment
i == j; // operator equal
</pre>
<p>If <tt class="literal"><span class="pre">iterator_category</span></tt> is convertible to
<tt class="literal"><span class="pre">bidirectional_iterator_tag</span></tt> or <tt class="literal"><span class="pre">bidirectional_traversal_tag</span></tt>,
<p>If <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible to
<tt class="docutils literal"><span class="pre">bidirectional_iterator_tag</span></tt> or <tt class="docutils literal"><span class="pre">bidirectional_traversal_tag</span></tt>,
the following expression must also be well-formed:</p>
<pre class="literal-block">
--i
</pre>
<p>If <tt class="literal"><span class="pre">iterator_category</span></tt> is convertible to
<tt class="literal"><span class="pre">random_access_iterator_tag</span></tt> or <tt class="literal"><span class="pre">random_access_traversal_tag</span></tt>,
<p>If <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible to
<tt class="docutils literal"><span class="pre">random_access_iterator_tag</span></tt> or <tt class="docutils literal"><span class="pre">random_access_traversal_tag</span></tt>,
the following must must also be valid:</p>
<pre class="literal-block">
counting_iterator::difference_type n;
@ -139,92 +139,92 @@ i &lt; j;
</pre>
</div>
<div class="section" id="counting-iterator-models">
<h1><a class="toc-backref" href="#id4" name="counting-iterator-models"><tt class="literal"><span class="pre">counting_iterator</span></tt> models</a></h1>
<p>Specializations of <tt class="literal"><span class="pre">counting_iterator</span></tt> model Readable Lvalue
<h1><a class="toc-backref" href="#id4" name="counting-iterator-models"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models</a></h1>
<p>Specializations of <tt class="docutils literal"><span class="pre">counting_iterator</span></tt> model Readable Lvalue
Iterator. In addition, they model the concepts corresponding to the
iterator tags to which their <tt class="literal"><span class="pre">iterator_category</span></tt> is convertible.
Also, if <tt class="literal"><span class="pre">CategoryOrTraversal</span></tt> is not <tt class="literal"><span class="pre">use_default</span></tt> then
<tt class="literal"><span class="pre">counting_iterator</span></tt> models the concept corresponding to the iterator
tag <tt class="literal"><span class="pre">CategoryOrTraversal</span></tt>. Otherwise, if
<tt class="literal"><span class="pre">numeric_limits&lt;Incrementable&gt;::is_specialized</span></tt>, then
<tt class="literal"><span class="pre">counting_iterator</span></tt> models Random Access Traversal Iterator.
Otherwise, <tt class="literal"><span class="pre">counting_iterator</span></tt> models the same iterator traversal
concepts modeled by <tt class="literal"><span class="pre">Incrementable</span></tt>.</p>
<p><tt class="literal"><span class="pre">counting_iterator&lt;X,C1,D1&gt;</span></tt> is interoperable with
<tt class="literal"><span class="pre">counting_iterator&lt;Y,C2,D2&gt;</span></tt> if and only if <tt class="literal"><span class="pre">X</span></tt> is
interoperable with <tt class="literal"><span class="pre">Y</span></tt>.</p>
iterator tags to which their <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible.
Also, if <tt class="docutils literal"><span class="pre">CategoryOrTraversal</span></tt> is not <tt class="docutils literal"><span class="pre">use_default</span></tt> then
<tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models the concept corresponding to the iterator
tag <tt class="docutils literal"><span class="pre">CategoryOrTraversal</span></tt>. Otherwise, if
<tt class="docutils literal"><span class="pre">numeric_limits&lt;Incrementable&gt;::is_specialized</span></tt>, then
<tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models Random Access Traversal Iterator.
Otherwise, <tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models the same iterator traversal
concepts modeled by <tt class="docutils literal"><span class="pre">Incrementable</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">counting_iterator&lt;X,C1,D1&gt;</span></tt> is interoperable with
<tt class="docutils literal"><span class="pre">counting_iterator&lt;Y,C2,D2&gt;</span></tt> if and only if <tt class="docutils literal"><span class="pre">X</span></tt> is
interoperable with <tt class="docutils literal"><span class="pre">Y</span></tt>.</p>
</div>
<div class="section" id="counting-iterator-operations">
<h1><a class="toc-backref" href="#id5" name="counting-iterator-operations"><tt class="literal"><span class="pre">counting_iterator</span></tt> operations</a></h1>
<h1><a class="toc-backref" href="#id5" name="counting-iterator-operations"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> operations</a></h1>
<p>In addition to the operations required by the concepts modeled by
<tt class="literal"><span class="pre">counting_iterator</span></tt>, <tt class="literal"><span class="pre">counting_iterator</span></tt> provides the following
<tt class="docutils literal"><span class="pre">counting_iterator</span></tt>, <tt class="docutils literal"><span class="pre">counting_iterator</span></tt> provides the following
operations.</p>
<p><tt class="literal"><span class="pre">counting_iterator();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">counting_iterator();</span></tt></p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="literal"><span class="pre">Incrementable</span></tt> is Default Constructible.</td>
<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="docutils literal"><span class="pre">Incrementable</span></tt> is Default Constructible.</td>
</tr>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Default construct the member <tt class="literal"><span class="pre">m_inc</span></tt>.</td>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Default construct the member <tt class="docutils literal"><span class="pre">m_inc</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">counting_iterator(counting_iterator</span> <span class="pre">const&amp;</span> <span class="pre">rhs);</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">counting_iterator(counting_iterator</span> <span class="pre">const&amp;</span> <span class="pre">rhs);</span></tt></p>
<table class="docutils 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">Construct member <tt class="literal"><span class="pre">m_inc</span></tt> from <tt class="literal"><span class="pre">rhs.m_inc</span></tt>.</td>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Construct member <tt class="docutils literal"><span class="pre">m_inc</span></tt> from <tt class="docutils literal"><span class="pre">rhs.m_inc</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">explicit</span> <span class="pre">counting_iterator(Incrementable</span> <span class="pre">x);</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">explicit</span> <span class="pre">counting_iterator(Incrementable</span> <span class="pre">x);</span></tt></p>
<table class="docutils 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">Construct member <tt class="literal"><span class="pre">m_inc</span></tt> from <tt class="literal"><span class="pre">x</span></tt>.</td>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Construct member <tt class="docutils literal"><span class="pre">m_inc</span></tt> from <tt class="docutils literal"><span class="pre">x</span></tt>.</td>
</tr>
</tbody>
</table>
<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">
<p><tt class="docutils literal"><span class="pre">reference</span> <span class="pre">operator*()</span> <span class="pre">const;</span></tt></p>
<table class="docutils 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">m_inc</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_inc</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">counting_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">counting_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
<table class="docutils 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"><tt class="literal"><span class="pre">++m_inc</span></tt></td>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="docutils literal"><span class="pre">++m_inc</span></tt></td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">*this</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">counting_iterator&amp;</span> <span class="pre">operator--();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">counting_iterator&amp;</span> <span class="pre">operator--();</span></tt></p>
<table class="docutils 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"><tt class="literal"><span class="pre">--m_inc</span></tt></td>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="docutils literal"><span class="pre">--m_inc</span></tt></td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">*this</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">Incrementable</span> <span class="pre">const&amp;</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">Incrementable</span> <span class="pre">const&amp;</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
<table class="docutils 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">m_inc</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_inc</span></tt></td>
</tr>
</tbody>
</table>
@ -232,12 +232,12 @@ operations.</p>
template &lt;class Incrementable&gt;
counting_iterator&lt;Incrementable&gt; make_counting_iterator(Incrementable x);
</pre>
<table class="field-list" frame="void" rules="none">
<table class="docutils 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 instance of <tt class="literal"><span class="pre">counting_iterator&lt;Incrementable&gt;</span></tt>
with <tt class="literal"><span class="pre">current</span></tt> constructed from <tt class="literal"><span class="pre">x</span></tt>.</td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="docutils literal"><span class="pre">counting_iterator&lt;Incrementable&gt;</span></tt>
with <tt class="docutils literal"><span class="pre">current</span></tt> constructed from <tt class="docutils literal"><span class="pre">x</span></tt>.</td>
</tr>
</tbody>
</table>
@ -245,8 +245,8 @@ with <tt class="literal"><span class="pre">current</span></tt> constructed from
<div class="section" id="example">
<h1><a class="toc-backref" href="#id6" name="example">Example</a></h1>
<p>This example fills an array with numbers and a second array with
pointers into the first array, using <tt class="literal"><span class="pre">counting_iterator</span></tt> for both
tasks. Finally <tt class="literal"><span class="pre">indirect_iterator</span></tt> is used to print out the numbers
pointers into the first array, using <tt class="docutils literal"><span class="pre">counting_iterator</span></tt> for both
tasks. Finally <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> is used to print out the numbers
into the first array via indirection through the second array.</p>
<pre class="literal-block">
int N = 7;
@ -276,7 +276,7 @@ indirectly printing out the numbers from 0 to 7
<p>The source code for this example can be found <a class="reference" href="../example/counting_iterator_example.cpp">here</a>.</p>
</div>
</div>
<hr class="footer" />
<hr class="docutils footer" />
<div class="footer">
<a class="reference" href="counting_iterator.rst">View document source</a>.
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.

BIN
doc/counting_iterator.pdf
View File

Binary file not shown.

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

File diff suppressed because it is too large Load Diff

BIN
doc/facade-and-adaptor.pdf
View File

Binary file not shown.

52
doc/function_output_iterator.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.3.6: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.3.8: http://docutils.sourceforge.net/" />
<title>Function Output Iterator</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" />
@ -12,6 +12,7 @@
<link rel="stylesheet" href="default.css" type="text/css" />
</head>
<body>
<div class="document" id="function-output-iterator">
<h1 class="title">Function Output Iterator</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
@ -31,8 +32,7 @@ Railway Operation and Construction</a></td></tr>
<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003.</td></tr>
</tbody>
</table>
<div class="document" id="function-output-iterator">
<table class="field-list" frame="void" rules="none">
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
@ -49,9 +49,9 @@ proxy object.</td>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first"><a name="table-of-contents">Table of Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#function-output-iterator-requirements" id="id1" name="id1"><tt class="literal"><span class="pre">function_output_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#function-output-iterator-models" id="id2" name="id2"><tt class="literal"><span class="pre">function_output_iterator</span></tt> models</a></li>
<li><a class="reference" href="#function-output-iterator-operations" id="id3" name="id3"><tt class="literal"><span class="pre">function_output_iterator</span></tt> operations</a></li>
<li><a class="reference" href="#function-output-iterator-requirements" id="id1" name="id1"><tt class="docutils literal"><span class="pre">function_output_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#function-output-iterator-models" id="id2" name="id2"><tt class="docutils literal"><span class="pre">function_output_iterator</span></tt> models</a></li>
<li><a class="reference" href="#function-output-iterator-operations" id="id3" name="id3"><tt class="docutils literal"><span class="pre">function_output_iterator</span></tt> operations</a></li>
<li><a class="reference" href="#example" id="id4" name="id4">Example</a></li>
</ul>
</div>
@ -77,51 +77,51 @@ private:
};
</pre>
<div class="section" id="function-output-iterator-requirements">
<h1><a class="toc-backref" href="#id1" name="function-output-iterator-requirements"><tt class="literal"><span class="pre">function_output_iterator</span></tt> requirements</a></h1>
<p><tt class="literal"><span class="pre">UnaryFunction</span></tt> must be Assignable and Copy Constructible.</p>
<h1><a class="toc-backref" href="#id1" name="function-output-iterator-requirements"><tt class="docutils literal"><span class="pre">function_output_iterator</span></tt> requirements</a></h1>
<p><tt class="docutils literal"><span class="pre">UnaryFunction</span></tt> must be Assignable and Copy Constructible.</p>
</div>
<div class="section" id="function-output-iterator-models">
<h1><a class="toc-backref" href="#id2" name="function-output-iterator-models"><tt class="literal"><span class="pre">function_output_iterator</span></tt> models</a></h1>
<p><tt class="literal"><span class="pre">function_output_iterator</span></tt> is a model of the Writable and
<h1><a class="toc-backref" href="#id2" name="function-output-iterator-models"><tt class="docutils literal"><span class="pre">function_output_iterator</span></tt> models</a></h1>
<p><tt class="docutils literal"><span class="pre">function_output_iterator</span></tt> is a model of the Writable and
Incrementable Iterator concepts.</p>
</div>
<div class="section" id="function-output-iterator-operations">
<h1><a class="toc-backref" href="#id3" name="function-output-iterator-operations"><tt class="literal"><span class="pre">function_output_iterator</span></tt> operations</a></h1>
<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">
<h1><a class="toc-backref" href="#id3" name="function-output-iterator-operations"><tt class="docutils literal"><span class="pre">function_output_iterator</span></tt> operations</a></h1>
<p><tt class="docutils 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="docutils 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">Constructs an instance of <tt class="literal"><span class="pre">function_output_iterator</span></tt>
with <tt class="literal"><span class="pre">m_f</span></tt> constructed from <tt class="literal"><span class="pre">f</span></tt>.</td>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Constructs an instance of <tt class="docutils literal"><span class="pre">function_output_iterator</span></tt>
with <tt class="docutils literal"><span class="pre">m_f</span></tt> constructed from <tt class="docutils literal"><span class="pre">f</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">operator*();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">operator*();</span></tt></p>
<table class="docutils 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 <tt class="literal"><span class="pre">r</span></tt> of unspecified type such that <tt class="literal"><span class="pre">r</span> <span class="pre">=</span> <span class="pre">t</span></tt>
is equivalent to <tt class="literal"><span class="pre">m_f(t)</span></tt> for all <tt class="literal"><span class="pre">t</span></tt>.</td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An object <tt class="docutils literal"><span class="pre">r</span></tt> of unspecified type such that <tt class="docutils literal"><span class="pre">r</span> <span class="pre">=</span> <span class="pre">t</span></tt>
is equivalent to <tt class="docutils literal"><span class="pre">m_f(t)</span></tt> for all <tt class="docutils literal"><span class="pre">t</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">function_output_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">function_output_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
<table class="docutils 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">*this</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">function_output_iterator&amp;</span> <span class="pre">operator++(int);</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">function_output_iterator&amp;</span> <span class="pre">operator++(int);</span></tt></p>
<table class="docutils 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">*this</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
</tr>
</tbody>
</table>
@ -162,7 +162,7 @@ int main(int, char*[])
</pre>
</div>
</div>
<hr class="footer" />
<hr class="docutils footer" />
<div class="footer">
<a class="reference" href="function_output_iterator.rst">View document source</a>.
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.

BIN
doc/function_output_iterator.pdf
View File

Binary file not shown.

90
doc/index.html
View File

@ -3,15 +3,15 @@
<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.3.6: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.3.8: http://docutils.sourceforge.net/" />
<title>The Boost.Iterator Library Boost</title>
<link rel="stylesheet" href="default.css" type="text/css" />
</head>
<body>
<h1 class="title">The Boost.Iterator Library <a class="reference" href="../../../index.htm"><img alt="Boost" src="../../../boost.png" /></a></h1>
<div class="document" id="the-boost-iterator-library-logo">
<hr />
<table class="field-list" frame="void" rules="none">
<h1 class="title">The Boost.Iterator Library <a class="reference" href="../../../index.htm"><img alt="Boost" src="../../../boost.png" /></a></h1>
<hr class="docutils" />
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
@ -28,7 +28,7 @@ Lab</a>, <a class="reference" href="http://www.styleadvisor.com">Zephyr Associat
</tr>
</tbody>
</table>
<table class="field-list" frame="void" rules="none">
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
@ -65,7 +65,7 @@ older Boost Iterator Adaptor Library.</td>
<li><a class="reference" href="#history" id="id29" name="id29">History</a></li>
</ul>
</div>
<hr />
<hr class="docutils" />
<div class="section" id="new-style-iterators">
<h1><a class="toc-backref" href="#id22" name="new-style-iterators">New-Style Iterators</a></h1>
<p>The iterator categories defined in C++98 are extremely limiting
@ -73,12 +73,12 @@ because they bind together two orthogonal concepts: traversal and
element access. For example, because a random access iterator is
required to return a reference (and not a proxy) when dereferenced,
it is impossible to capture the capabilities of
<tt class="literal"><span class="pre">vector&lt;bool&gt;::iterator</span></tt> using the C++98 categories. This is the
infamous &quot;<tt class="literal"><span class="pre">vector&lt;bool&gt;</span></tt> is not a container, and its iterators
<tt class="docutils literal"><span class="pre">vector&lt;bool&gt;::iterator</span></tt> using the C++98 categories. This is the
infamous &quot;<tt class="docutils literal"><span class="pre">vector&lt;bool&gt;</span></tt> is not a container, and its iterators
aren't random access iterators&quot;, debacle about which Herb Sutter
wrote two papers for the standards comittee (<a class="reference" href="http://www.gotw.ca/publications/N1185.pdf">n1185</a> and <a class="reference" href="http://www.gotw.ca/publications/N1211.pdf">n1211</a>),
and a <a class="reference" href="http://www.gotw.ca/gotw/050.htm">Guru of the Week</a>. New-style iterators go well beyond
patching up <tt class="literal"><span class="pre">vector&lt;bool&gt;</span></tt>, though: there are lots of other
patching up <tt class="docutils literal"><span class="pre">vector&lt;bool&gt;</span></tt>, though: there are lots of other
iterators already in use which can't be adequately represented by
the existing concepts. For details about the new iterator
concepts, see our</p>
@ -89,23 +89,23 @@ concepts, see our</p>
<h1><a class="toc-backref" href="#id23" name="iterator-facade-and-adaptor">Iterator Facade and Adaptor</a></h1>
<p>Writing standard-conforming iterators is tricky, but the need comes
up often. In order to ease the implementation of new iterators,
the Boost.Iterator library provides the <tt class="literal"><span class="pre">iterator_facade</span></tt> class template,
the Boost.Iterator library provides the <tt class="docutils literal"><span class="pre">iterator_facade</span></tt> class template,
which implements many useful defaults and compile-time checks
designed to help the iterator author ensure that his iterator is
correct.</p>
<p>It is also common to define a new iterator that is similar to some
underlying iterator or iterator-like type, but that modifies some
aspect of the underlying type's behavior. For that purpose, the
library supplies the <tt class="literal"><span class="pre">iterator_adaptor</span></tt> class template, which is specially
library supplies the <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> class template, which is specially
designed to take advantage of as much of the underlying type's
behavior as possible.</p>
<p>The documentation for these two classes can be found at the following
web pages:</p>
<ul class="simple">
<li><a class="reference" href="iterator_facade.html"><tt class="literal"><span class="pre">iterator_facade</span></tt></a> (<a class="reference" href="iterator_facade.pdf">PDF</a>)</li>
<li><a class="reference" href="iterator_adaptor.html"><tt class="literal"><span class="pre">iterator_adaptor</span></tt></a> (<a class="reference" href="iterator_adaptor.pdf">PDF</a>)</li>
<li><a class="reference" href="iterator_facade.html"><tt class="docutils literal"><span class="pre">iterator_facade</span></tt></a> (<a class="reference" href="iterator_facade.pdf">PDF</a>)</li>
<li><a class="reference" href="iterator_adaptor.html"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt></a> (<a class="reference" href="iterator_adaptor.pdf">PDF</a>)</li>
</ul>
<p>Both <tt class="literal"><span class="pre">iterator_facade</span></tt> and <tt class="literal"><span class="pre">iterator_adaptor</span></tt> as well as many of the <a class="reference" href="#specialized-adaptors">specialized
<p>Both <tt class="docutils literal"><span class="pre">iterator_facade</span></tt> and <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> as well as many of the <a class="reference" href="#specialized-adaptors">specialized
adaptors</a> mentioned below have been proposed for standardization,
and accepted into the first C++ technical report; see our</p>
<blockquote>
@ -117,27 +117,27 @@ and accepted into the first C++ technical report; see our</p>
<p>The iterator library supplies a useful suite of standard-conforming
iterator templates based on the Boost <a class="reference" href="#iterator-facade-and-adaptor">iterator facade and adaptor</a>.</p>
<ul class="simple">
<li><a class="reference" href="counting_iterator.html"><tt class="literal"><span class="pre">counting_iterator</span></tt></a> (<a class="reference" href="counting_iterator.pdf">PDF</a>): an iterator over a sequence of consecutive values.
<li><a class="reference" href="counting_iterator.html"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt></a> (<a class="reference" href="counting_iterator.pdf">PDF</a>): an iterator over a sequence of consecutive values.
Implements a &quot;lazy sequence&quot;</li>
<li><a class="reference" href="filter_iterator.html"><tt class="literal"><span class="pre">filter_iterator</span></tt></a> (<a class="reference" href="filter_iterator.pdf">PDF</a>): an iterator over the subset of elements of some
<li><a class="reference" href="filter_iterator.html"><tt class="docutils literal"><span class="pre">filter_iterator</span></tt></a> (<a class="reference" href="filter_iterator.pdf">PDF</a>): an iterator over the subset of elements of some
sequence which satisfy a given predicate</li>
<li><a class="reference" href="function_output_iterator.html"><tt class="literal"><span class="pre">function_output_iterator</span></tt></a> (<a class="reference" href="function_output_iterator.pdf">PDF</a>): an output iterator wrapping a unary function
<li><a class="reference" href="function_output_iterator.html"><tt class="docutils literal"><span class="pre">function_output_iterator</span></tt></a> (<a class="reference" href="function_output_iterator.pdf">PDF</a>): an output iterator wrapping a unary function
object; each time an element is written into the dereferenced
iterator, it is passed as a parameter to the function object.</li>
<li><a class="reference" href="indirect_iterator.html"><tt class="literal"><span class="pre">indirect_iterator</span></tt></a> (<a class="reference" href="indirect_iterator.pdf">PDF</a>): an iterator over the objects <em>pointed-to</em> by the
<li><a class="reference" href="indirect_iterator.html"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt></a> (<a class="reference" href="indirect_iterator.pdf">PDF</a>): an iterator over the objects <em>pointed-to</em> by the
elements of some sequence.</li>
<li><a class="reference" href="permutation_iterator.html"><tt class="literal"><span class="pre">permutation_iterator</span></tt></a> (<a class="reference" href="permutation_iterator.pdf">PDF</a>): an iterator over the elements of some random-access
<li><a class="reference" href="permutation_iterator.html"><tt class="docutils literal"><span class="pre">permutation_iterator</span></tt></a> (<a class="reference" href="permutation_iterator.pdf">PDF</a>): an iterator over the elements of some random-access
sequence, rearranged according to some sequence of integer indices.</li>
<li><a class="reference" href="reverse_iterator.html"><tt class="literal"><span class="pre">reverse_iterator</span></tt></a> (<a class="reference" href="reverse_iterator.pdf">PDF</a>): an iterator which traverses the elements of some
<li><a class="reference" href="reverse_iterator.html"><tt class="docutils literal"><span class="pre">reverse_iterator</span></tt></a> (<a class="reference" href="reverse_iterator.pdf">PDF</a>): an iterator which traverses the elements of some
bidirectional sequence in reverse. Corrects many of the
shortcomings of C++98's <tt class="literal"><span class="pre">std::reverse_iterator</span></tt>.</li>
<li><a class="reference" href="../../utility/shared_container_iterator.html"><tt class="literal"><span class="pre">shared_container_iterator</span></tt></a>: an iterator over elements of a container whose
lifetime is maintained by a <a class="reference" href="../../smart_ptr/shared_ptr.htm"><tt class="literal"><span class="pre">shared_ptr</span></tt></a> stored in the iterator.</li>
<li><a class="reference" href="transform_iterator.html"><tt class="literal"><span class="pre">transform_iterator</span></tt></a> (<a class="reference" href="transform_iterator.pdf">PDF</a>): an iterator over elements which are the result of
shortcomings of C++98's <tt class="docutils literal"><span class="pre">std::reverse_iterator</span></tt>.</li>
<li><a class="reference" href="../../utility/shared_container_iterator.html"><tt class="docutils literal"><span class="pre">shared_container_iterator</span></tt></a>: an iterator over elements of a container whose
lifetime is maintained by a <a class="reference" href="../../smart_ptr/shared_ptr.htm"><tt class="docutils literal"><span class="pre">shared_ptr</span></tt></a> stored in the iterator.</li>
<li><a class="reference" href="transform_iterator.html"><tt class="docutils literal"><span class="pre">transform_iterator</span></tt></a> (<a class="reference" href="transform_iterator.pdf">PDF</a>): an iterator over elements which are the result of
applying some functional transformation to the elements of an
underlying sequence. This component also replaces the old
<tt class="literal"><span class="pre">projection_iterator_adaptor</span></tt>.</li>
<li><a class="reference" href="zip_iterator.html"><tt class="literal"><span class="pre">zip_iterator</span></tt></a> (<a class="reference" href="zip_iterator.pdf">PDF</a>): an iterator over tuples of the elements at corresponding
<tt class="docutils literal"><span class="pre">projection_iterator_adaptor</span></tt>.</li>
<li><a class="reference" href="zip_iterator.html"><tt class="docutils literal"><span class="pre">zip_iterator</span></tt></a> (<a class="reference" href="zip_iterator.pdf">PDF</a>): an iterator over tuples of the elements at corresponding
positions of heterogeneous underlying iterators.</li>
</ul>
</div>
@ -146,12 +146,12 @@ positions of heterogeneous underlying iterators.</li>
<div class="section" id="traits">
<h2><a class="toc-backref" href="#id26" name="traits">Traits</a></h2>
<ul class="simple">
<li><a class="reference" href="pointee.html"><tt class="literal"><span class="pre">pointee.hpp</span></tt></a> (<a class="reference" href="pointee.pdf">PDF</a>): Provides the capability to deduce the referent types
<li><a class="reference" href="pointee.html"><tt class="docutils literal"><span class="pre">pointee.hpp</span></tt></a> (<a class="reference" href="pointee.pdf">PDF</a>): Provides the capability to deduce the referent types
of pointers, smart pointers and iterators in generic code. Used
in <tt class="literal"><span class="pre">indirect_iterator</span></tt>.</li>
<li><a class="reference" href="iterator_traits.html"><tt class="literal"><span class="pre">iterator_traits.hpp</span></tt></a> (<a class="reference" href="iterator_traits.pdf">PDF</a>): Provides <a class="reference" href="../../mpl/doc/index.html">MPL</a>-compatible metafunctions which
in <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt>.</li>
<li><a class="reference" href="iterator_traits.html"><tt class="docutils literal"><span class="pre">iterator_traits.hpp</span></tt></a> (<a class="reference" href="iterator_traits.pdf">PDF</a>): Provides <a class="reference" href="../../mpl/doc/index.html">MPL</a>-compatible metafunctions which
retrieve an iterator's traits. Also corrects for the deficiencies
of broken implementations of <tt class="literal"><span class="pre">std::iterator_traits</span></tt>.</li>
of broken implementations of <tt class="docutils literal"><span class="pre">std::iterator_traits</span></tt>.</li>
</ul>
<!-- * |interoperable|_ (PDF__): Provides an MPL_\ -compatible metafunction for
testing iterator interoperability -->
@ -160,35 +160,35 @@ testing iterator interoperability -->
<div class="section" id="testing-and-concept-checking">
<h2><a class="toc-backref" href="#id27" name="testing-and-concept-checking">Testing and Concept Checking</a></h2>
<ul class="simple">
<li><a class="reference" href="iterator_concepts.html"><tt class="literal"><span class="pre">iterator_concepts.hpp</span></tt></a> (<a class="reference" href="iterator_concepts.pdf">PDF</a>): Concept checking classes for the new iterator concepts.</li>
<li><a class="reference" href="iterator_archetypes.html"><tt class="literal"><span class="pre">iterator_archetypes.hpp</span></tt></a> (<a class="reference" href="iterator_archetypes.pdf">PDF</a>): Concept archetype classes for the new iterators concepts.</li>
<li><a class="reference" href="iterator_concepts.html"><tt class="docutils literal"><span class="pre">iterator_concepts.hpp</span></tt></a> (<a class="reference" href="iterator_concepts.pdf">PDF</a>): Concept checking classes for the new iterator concepts.</li>
<li><a class="reference" href="iterator_archetypes.html"><tt class="docutils literal"><span class="pre">iterator_archetypes.hpp</span></tt></a> (<a class="reference" href="iterator_archetypes.pdf">PDF</a>): Concept archetype classes for the new iterators concepts.</li>
</ul>
</div>
</div>
<div class="section" id="upgrading-from-the-old-boost-iterator-adaptor-library">
<h1><a class="toc-backref" href="#id28" name="upgrading-from-the-old-boost-iterator-adaptor-library">Upgrading from the old Boost Iterator Adaptor Library</a></h1>
<a class="target" id="upgrading" name="upgrading"></a><p>If you have been using the old Boost Iterator Adaptor library to
implement iterators, you probably wrote a <tt class="literal"><span class="pre">Policies</span></tt> class which
implement iterators, you probably wrote a <tt class="docutils literal"><span class="pre">Policies</span></tt> class which
captures the core operations of your iterator. In the new library
design, you'll move those same core operations into the body of the
iterator class itself. If you were writing a family of iterators,
you probably wrote a <a class="reference" href="../../../more/generic_programming.html#type_generator">type generator</a> to build the
<tt class="literal"><span class="pre">iterator_adaptor</span></tt> specialization you needed; in the new library
<tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> specialization you needed; in the new library
design you don't need a type generator (though may want to keep it
around as a compatibility aid for older code) because, due to the
use of the Curiously Recurring Template Pattern (CRTP) <a class="citation-reference" href="#cop95" id="id21" name="id21">[Cop95]</a>,
you can now define the iterator class yourself and acquire
functionality through inheritance from <tt class="literal"><span class="pre">iterator_facade</span></tt> or
<tt class="literal"><span class="pre">iterator_adaptor</span></tt>. As a result, you also get much finer control
functionality through inheritance from <tt class="docutils literal"><span class="pre">iterator_facade</span></tt> or
<tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>. As a result, you also get much finer control
over how your iterator works: you can add additional constructors,
or even override the iterator functionality provided by the
library.</p>
<p>If you're looking for the old <tt class="literal"><span class="pre">projection_iterator</span></tt> component,
its functionality has been merged into <tt class="literal"><span class="pre">transform_iterator</span></tt>: as
long as the function object's <tt class="literal"><span class="pre">result_type</span></tt> (or the <tt class="literal"><span class="pre">Reference</span></tt>
<p>If you're looking for the old <tt class="docutils literal"><span class="pre">projection_iterator</span></tt> component,
its functionality has been merged into <tt class="docutils literal"><span class="pre">transform_iterator</span></tt>: as
long as the function object's <tt class="docutils literal"><span class="pre">result_type</span></tt> (or the <tt class="docutils literal"><span class="pre">Reference</span></tt>
template argument, if explicitly specified) is a true reference
type, <tt class="literal"><span class="pre">transform_iterator</span></tt> will behave like
<tt class="literal"><span class="pre">projection_iterator</span></tt> used to.</p>
type, <tt class="docutils literal"><span class="pre">transform_iterator</span></tt> will behave like
<tt class="docutils literal"><span class="pre">projection_iterator</span></tt> used to.</p>
</div>
<div class="section" id="history">
<h1><a class="toc-backref" href="#id29" name="history">History</a></h1>
@ -212,11 +212,11 @@ policies into the iterator class itself. Thomas Witt expressed
interest and became the voice of strict compile-time checking for
the project, adding uses of the SFINAE technique to eliminate false
converting constructors and operators from the overload set. He
also recognized the need for a separate <tt class="literal"><span class="pre">iterator_facade</span></tt>, and
factored it out of <tt class="literal"><span class="pre">iterator_adaptor</span></tt>. Finally, after a
also recognized the need for a separate <tt class="docutils literal"><span class="pre">iterator_facade</span></tt>, and
factored it out of <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>. Finally, after a
near-complete rewrite of the prototype, they came up with the
library you see today.</p>
<table class="citation" frame="void" id="cop95" rules="none">
<table class="docutils citation" frame="void" id="cop95" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id21" name="cop95">[Cop95]</a></td><td>[Coplien, 1995] Coplien, J., Curiously Recurring Template
@ -232,7 +232,7 @@ LocalWords: incrementable xxx min prev inplace png oldeqnew AccessTag struct
LocalWords: TraversalTag typename lvalues DWA Hmm JGS -->
</div>
</div>
<hr class="footer" />
<hr class="docutils footer" />
<div class="footer">
<a class="reference" href="index.rst">View document source</a>.
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.

154
doc/indirect_iterator.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.3.6: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.3.8: http://docutils.sourceforge.net/" />
<title>Indirect Iterator</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" />
@ -12,6 +12,7 @@
<link rel="stylesheet" href="default.css" type="text/css" />
</head>
<body>
<div class="document" id="indirect-iterator">
<h1 class="title">Indirect Iterator</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
@ -31,18 +32,17 @@ Railway Operation and Construction</a></td></tr>
<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003.</td></tr>
</tbody>
</table>
<div class="document" id="indirect-iterator">
<table class="field-list" frame="void" rules="none">
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">abstract:</th><td class="field-body"><tt class="literal"><span class="pre">indirect_iterator</span></tt> adapts an iterator by applying an
<em>extra</em> dereference inside of <tt class="literal"><span class="pre">operator*()</span></tt>. For example, this
<tr class="field"><th class="field-name">abstract:</th><td class="field-body"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> adapts an iterator by applying an
<em>extra</em> dereference inside of <tt class="docutils literal"><span class="pre">operator*()</span></tt>. For example, this
iterator adaptor makes it possible to view a container of pointers
(e.g. <tt class="literal"><span class="pre">list&lt;foo*&gt;</span></tt>) as if it were a container of the pointed-to type
(e.g. <tt class="literal"><span class="pre">list&lt;foo&gt;</span></tt>). <tt class="literal"><span class="pre">indirect_iterator</span></tt> depends on two
auxiliary traits, <tt class="literal"><span class="pre">pointee</span></tt> and <tt class="literal"><span class="pre">indirect_reference</span></tt>, to
provide support for underlying iterators whose <tt class="literal"><span class="pre">value_type</span></tt> is
(e.g. <tt class="docutils literal"><span class="pre">list&lt;foo*&gt;</span></tt>) as if it were a container of the pointed-to type
(e.g. <tt class="docutils literal"><span class="pre">list&lt;foo&gt;</span></tt>). <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> depends on two
auxiliary traits, <tt class="docutils literal"><span class="pre">pointee</span></tt> and <tt class="docutils literal"><span class="pre">indirect_reference</span></tt>, to
provide support for underlying iterators whose <tt class="docutils literal"><span class="pre">value_type</span></tt> is
not an iterator.</td>
</tr>
</tbody>
@ -50,15 +50,15 @@ not an iterator.</td>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first"><a name="table-of-contents">Table of Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#indirect-iterator-synopsis" id="id2" name="id2"><tt class="literal"><span class="pre">indirect_iterator</span></tt> synopsis</a></li>
<li><a class="reference" href="#indirect-iterator-requirements" id="id3" name="id3"><tt class="literal"><span class="pre">indirect_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#indirect-iterator-models" id="id4" name="id4"><tt class="literal"><span class="pre">indirect_iterator</span></tt> models</a></li>
<li><a class="reference" href="#indirect-iterator-operations" id="id5" name="id5"><tt class="literal"><span class="pre">indirect_iterator</span></tt> operations</a></li>
<li><a class="reference" href="#indirect-iterator-synopsis" id="id2" name="id2"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> synopsis</a></li>
<li><a class="reference" href="#indirect-iterator-requirements" id="id3" name="id3"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#indirect-iterator-models" id="id4" name="id4"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> models</a></li>
<li><a class="reference" href="#indirect-iterator-operations" id="id5" name="id5"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> operations</a></li>
<li><a class="reference" href="#example" id="id6" name="id6">Example</a></li>
</ul>
</div>
<div class="section" id="indirect-iterator-synopsis">
<h1><a class="toc-backref" href="#id2" name="indirect-iterator-synopsis"><tt class="literal"><span class="pre">indirect_iterator</span></tt> synopsis</a></h1>
<h1><a class="toc-backref" href="#id2" name="indirect-iterator-synopsis"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> synopsis</a></h1>
<pre class="literal-block">
template &lt;
class Iterator
@ -98,9 +98,9 @@ private:
Iterator m_iterator; // exposition
};
</pre>
<p>The member types of <tt class="literal"><span class="pre">indirect_iterator</span></tt> are defined according to
the following pseudo-code, where <tt class="literal"><span class="pre">V</span></tt> is
<tt class="literal"><span class="pre">iterator_traits&lt;Iterator&gt;::value_type</span></tt></p>
<p>The member types of <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> are defined according to
the following pseudo-code, where <tt class="docutils literal"><span class="pre">V</span></tt> is
<tt class="docutils literal"><span class="pre">iterator_traits&lt;Iterator&gt;::value_type</span></tt></p>
<pre class="literal-block">
if (Value is use_default) then
typedef remove_const&lt;pointee&lt;V&gt;::type&gt;::type value_type;
@ -136,64 +136,64 @@ else
</pre>
</div>
<div class="section" id="indirect-iterator-requirements">
<h1><a class="toc-backref" href="#id3" name="indirect-iterator-requirements"><tt class="literal"><span class="pre">indirect_iterator</span></tt> requirements</a></h1>
<p>The expression <tt class="literal"><span class="pre">*v</span></tt>, where <tt class="literal"><span class="pre">v</span></tt> is an object of
<tt class="literal"><span class="pre">iterator_traits&lt;Iterator&gt;::value_type</span></tt>, shall be valid
expression and convertible to <tt class="literal"><span class="pre">reference</span></tt>. <tt class="literal"><span class="pre">Iterator</span></tt> shall
model the traversal concept indicated by <tt class="literal"><span class="pre">iterator_category</span></tt>.
<tt class="literal"><span class="pre">Value</span></tt>, <tt class="literal"><span class="pre">Reference</span></tt>, and <tt class="literal"><span class="pre">Difference</span></tt> shall be chosen so
that <tt class="literal"><span class="pre">value_type</span></tt>, <tt class="literal"><span class="pre">reference</span></tt>, and <tt class="literal"><span class="pre">difference_type</span></tt> meet
the requirements indicated by <tt class="literal"><span class="pre">iterator_category</span></tt>.</p>
<h1><a class="toc-backref" href="#id3" name="indirect-iterator-requirements"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> requirements</a></h1>
<p>The expression <tt class="docutils literal"><span class="pre">*v</span></tt>, where <tt class="docutils literal"><span class="pre">v</span></tt> is an object of
<tt class="docutils literal"><span class="pre">iterator_traits&lt;Iterator&gt;::value_type</span></tt>, shall be valid
expression and convertible to <tt class="docutils literal"><span class="pre">reference</span></tt>. <tt class="docutils literal"><span class="pre">Iterator</span></tt> shall
model the traversal concept indicated by <tt class="docutils literal"><span class="pre">iterator_category</span></tt>.
<tt class="docutils literal"><span class="pre">Value</span></tt>, <tt class="docutils literal"><span class="pre">Reference</span></tt>, and <tt class="docutils literal"><span class="pre">Difference</span></tt> shall be chosen so
that <tt class="docutils literal"><span class="pre">value_type</span></tt>, <tt class="docutils literal"><span class="pre">reference</span></tt>, and <tt class="docutils literal"><span class="pre">difference_type</span></tt> meet
the requirements indicated by <tt class="docutils literal"><span class="pre">iterator_category</span></tt>.</p>
<p>[Note: there are further requirements on the
<tt class="literal"><span class="pre">iterator_traits&lt;Iterator&gt;::value_type</span></tt> if the <tt class="literal"><span class="pre">Value</span></tt>
parameter is not <tt class="literal"><span class="pre">use_default</span></tt>, as implied by the algorithm for
deducing the default for the <tt class="literal"><span class="pre">value_type</span></tt> member.]</p>
<tt class="docutils literal"><span class="pre">iterator_traits&lt;Iterator&gt;::value_type</span></tt> if the <tt class="docutils literal"><span class="pre">Value</span></tt>
parameter is not <tt class="docutils literal"><span class="pre">use_default</span></tt>, as implied by the algorithm for
deducing the default for the <tt class="docutils literal"><span class="pre">value_type</span></tt> member.]</p>
</div>
<div class="section" id="indirect-iterator-models">
<h1><a class="toc-backref" href="#id4" name="indirect-iterator-models"><tt class="literal"><span class="pre">indirect_iterator</span></tt> models</a></h1>
<p>In addition to the concepts indicated by <tt class="literal"><span class="pre">iterator_category</span></tt>
and by <tt class="literal"><span class="pre">iterator_traversal&lt;indirect_iterator&gt;::type</span></tt>, a
specialization of <tt class="literal"><span class="pre">indirect_iterator</span></tt> models the following
concepts, Where <tt class="literal"><span class="pre">v</span></tt> is an object of
<tt class="literal"><span class="pre">iterator_traits&lt;Iterator&gt;::value_type</span></tt>:</p>
<h1><a class="toc-backref" href="#id4" name="indirect-iterator-models"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> models</a></h1>
<p>In addition to the concepts indicated by <tt class="docutils literal"><span class="pre">iterator_category</span></tt>
and by <tt class="docutils literal"><span class="pre">iterator_traversal&lt;indirect_iterator&gt;::type</span></tt>, a
specialization of <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> models the following
concepts, Where <tt class="docutils literal"><span class="pre">v</span></tt> is an object of
<tt class="docutils literal"><span class="pre">iterator_traits&lt;Iterator&gt;::value_type</span></tt>:</p>
<blockquote>
<ul class="simple">
<li>Readable Iterator if <tt class="literal"><span class="pre">reference(*v)</span></tt> is convertible to
<tt class="literal"><span class="pre">value_type</span></tt>.</li>
<li>Writable Iterator if <tt class="literal"><span class="pre">reference(*v)</span> <span class="pre">=</span> <span class="pre">t</span></tt> is a valid
expression (where <tt class="literal"><span class="pre">t</span></tt> is an object of type
<tt class="literal"><span class="pre">indirect_iterator::value_type</span></tt>)</li>
<li>Lvalue Iterator if <tt class="literal"><span class="pre">reference</span></tt> is a reference type.</li>
<li>Readable Iterator if <tt class="docutils literal"><span class="pre">reference(*v)</span></tt> is convertible to
<tt class="docutils literal"><span class="pre">value_type</span></tt>.</li>
<li>Writable Iterator if <tt class="docutils literal"><span class="pre">reference(*v)</span> <span class="pre">=</span> <span class="pre">t</span></tt> is a valid
expression (where <tt class="docutils literal"><span class="pre">t</span></tt> is an object of type
<tt class="docutils literal"><span class="pre">indirect_iterator::value_type</span></tt>)</li>
<li>Lvalue Iterator if <tt class="docutils literal"><span class="pre">reference</span></tt> is a reference type.</li>
</ul>
</blockquote>
<p><tt class="literal"><span class="pre">indirect_iterator&lt;X,V1,C1,R1,D1&gt;</span></tt> is interoperable with
<tt class="literal"><span class="pre">indirect_iterator&lt;Y,V2,C2,R2,D2&gt;</span></tt> if and only if <tt class="literal"><span class="pre">X</span></tt> is
interoperable with <tt class="literal"><span class="pre">Y</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">indirect_iterator&lt;X,V1,C1,R1,D1&gt;</span></tt> is interoperable with
<tt class="docutils literal"><span class="pre">indirect_iterator&lt;Y,V2,C2,R2,D2&gt;</span></tt> if and only if <tt class="docutils literal"><span class="pre">X</span></tt> is
interoperable with <tt class="docutils literal"><span class="pre">Y</span></tt>.</p>
</div>
<div class="section" id="indirect-iterator-operations">
<h1><a class="toc-backref" href="#id5" name="indirect-iterator-operations"><tt class="literal"><span class="pre">indirect_iterator</span></tt> operations</a></h1>
<h1><a class="toc-backref" href="#id5" name="indirect-iterator-operations"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> operations</a></h1>
<p>In addition to the operations required by the concepts described
above, specializations of <tt class="literal"><span class="pre">indirect_iterator</span></tt> provide the
above, specializations of <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> provide the
following operations.</p>
<p><tt class="literal"><span class="pre">indirect_iterator();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">indirect_iterator();</span></tt></p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="literal"><span class="pre">Iterator</span></tt> must be Default Constructible.</td>
<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="docutils literal"><span class="pre">Iterator</span></tt> must be Default Constructible.</td>
</tr>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Constructs an instance of <tt class="literal"><span class="pre">indirect_iterator</span></tt> with
a default-constructed <tt class="literal"><span class="pre">m_iterator</span></tt>.</td>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Constructs an instance of <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> with
a default-constructed <tt class="docutils literal"><span class="pre">m_iterator</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">indirect_iterator(Iterator</span> <span class="pre">x);</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">indirect_iterator(Iterator</span> <span class="pre">x);</span></tt></p>
<table class="docutils 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">Constructs an instance of <tt class="literal"><span class="pre">indirect_iterator</span></tt> with
<tt class="literal"><span class="pre">m_iterator</span></tt> copy constructed from <tt class="literal"><span class="pre">x</span></tt>.</td>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Constructs an instance of <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> with
<tt class="docutils literal"><span class="pre">m_iterator</span></tt> copy constructed from <tt class="docutils literal"><span class="pre">x</span></tt>.</td>
</tr>
</tbody>
</table>
@ -209,54 +209,54 @@ indirect_iterator(
, typename enable_if_convertible&lt;Iterator2, Iterator&gt;::type* = 0 // exposition
);
</pre>
<table class="field-list" frame="void" rules="none">
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="literal"><span class="pre">Iterator2</span></tt> is implicitly convertible to <tt class="literal"><span class="pre">Iterator</span></tt>.</td>
<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="docutils literal"><span class="pre">Iterator2</span></tt> is implicitly convertible to <tt class="docutils literal"><span class="pre">Iterator</span></tt>.</td>
</tr>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Constructs an instance of <tt class="literal"><span class="pre">indirect_iterator</span></tt> whose
<tt class="literal"><span class="pre">m_iterator</span></tt> subobject is constructed from <tt class="literal"><span class="pre">y.base()</span></tt>.</td>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Constructs an instance of <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> whose
<tt class="docutils literal"><span class="pre">m_iterator</span></tt> subobject is constructed from <tt class="docutils literal"><span class="pre">y.base()</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">Iterator</span> <span class="pre">const&amp;</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">Iterator</span> <span class="pre">const&amp;</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
<table class="docutils 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">m_iterator</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_iterator</span></tt></td>
</tr>
</tbody>
</table>
<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">
<p><tt class="docutils literal"><span class="pre">reference</span> <span class="pre">operator*()</span> <span class="pre">const;</span></tt></p>
<table class="docutils 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">**m_iterator</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">**m_iterator</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">indirect_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">indirect_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
<table class="docutils 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"><tt class="literal"><span class="pre">++m_iterator</span></tt></td>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="docutils literal"><span class="pre">++m_iterator</span></tt></td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">*this</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">indirect_iterator&amp;</span> <span class="pre">operator--();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">indirect_iterator&amp;</span> <span class="pre">operator--();</span></tt></p>
<table class="docutils 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"><tt class="literal"><span class="pre">--m_iterator</span></tt></td>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="docutils literal"><span class="pre">--m_iterator</span></tt></td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">*this</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
</tr>
</tbody>
</table>
@ -264,13 +264,13 @@ indirect_iterator(
<div class="section" id="example">
<h1><a class="toc-backref" href="#id6" name="example">Example</a></h1>
<p>This example prints an array of characters, using
<tt class="literal"><span class="pre">indirect_iterator</span></tt> to access the array of characters through an
array of pointers. Next <tt class="literal"><span class="pre">indirect_iterator</span></tt> is used with the
<tt class="literal"><span class="pre">transform</span></tt> algorithm to copy the characters (incremented by one) to
<tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> to access the array of characters through an
array of pointers. Next <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> is used with the
<tt class="docutils literal"><span class="pre">transform</span></tt> algorithm to copy the characters (incremented by one) to
another array. A constant indirect iterator is used for the source and
a mutable indirect iterator is used for the destination. The last part
of the example prints the original array of characters, but this time
using the <tt class="literal"><span class="pre">make_indirect_iterator</span></tt> helper function.</p>
using the <tt class="docutils literal"><span class="pre">make_indirect_iterator</span></tt> helper function.</p>
<pre class="literal-block">
char characters[] = &quot;abcdefg&quot;;
const int N = sizeof(characters)/sizeof(char) - 1; // -1 since characters has a null char
@ -323,7 +323,7 @@ a,b,c,d,e,f,g,
<p>The source code for this example can be found <a class="reference" href="../example/indirect_iterator_example.cpp">here</a>.</p>
</div>
</div>
<hr class="footer" />
<hr class="docutils footer" />
<div class="footer">
<a class="reference" href="indirect_iterator.rst">View document source</a>.
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.

BIN
doc/indirect_iterator.pdf
View File

Binary file not shown.

247
doc/iterator_adaptor.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.3.6: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.3.8: http://docutils.sourceforge.net/" />
<title>Iterator 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" />
@ -12,6 +12,7 @@
<link rel="stylesheet" href="default.css" type="text/css" />
</head>
<body>
<div class="document" id="iterator-adaptor">
<h1 class="title">Iterator Adaptor</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
@ -31,8 +32,7 @@ Railway Operation and Construction</a></td></tr>
<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003.</td></tr>
</tbody>
</table>
<div class="document" id="iterator-adaptor">
<table class="field-list" frame="void" rules="none">
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
@ -43,26 +43,26 @@ Railway Operation and Construction</a></td></tr>
<!-- Version 1.1 of this ReStructuredText document corresponds to
n1530_, the paper accepted by the LWG. -->
<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. -->
<p>Each specialization of the <tt class="literal"><span class="pre">iterator_adaptor</span></tt> class template is derived from
a specialization 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
<tt class="literal"><span class="pre">iterator_adaptor</span></tt>'s <tt class="literal"><span class="pre">Base</span></tt> template parameter. A class derived
from <tt class="literal"><span class="pre">iterator_adaptor</span></tt> typically redefines some of the core
interface functions to adapt the behavior of the <tt class="literal"><span class="pre">Base</span></tt> type.
<p>Each specialization of the <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> class template is derived from
a specialization of <tt class="docutils literal"><span class="pre">iterator_facade</span></tt>. The core interface functions
expected by <tt class="docutils literal"><span class="pre">iterator_facade</span></tt> are implemented in terms of the
<tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>'s <tt class="docutils literal"><span class="pre">Base</span></tt> template parameter. A class derived
from <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> typically redefines some of the core
interface functions to adapt the behavior of the <tt class="docutils literal"><span class="pre">Base</span></tt> type.
Whether the derived class models any of the standard iterator concepts
depends on the operations supported by the <tt class="literal"><span class="pre">Base</span></tt> type and which
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>
depends on the operations supported by the <tt class="docutils literal"><span class="pre">Base</span></tt> type and which
core interface functions of <tt class="docutils literal"><span class="pre">iterator_facade</span></tt> are redefined in the
<tt class="docutils literal"><span class="pre">Derived</span></tt> class.</p>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first"><a name="table-of-contents">Table of Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#overview" id="id6" name="id6">Overview</a></li>
<li><a class="reference" href="#reference" id="id7" name="id7">Reference</a><ul>
<li><a class="reference" href="#iterator-adaptor-requirements" id="id8" name="id8"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> requirements</a></li>
<li><a class="reference" href="#iterator-adaptor-base-class-parameters" id="id9" name="id9"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> base class parameters</a></li>
<li><a class="reference" href="#iterator-adaptor-public-operations" id="id10" name="id10"><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="id11" name="id11"><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="id12" name="id12"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> private member functions</a></li>
<li><a class="reference" href="#iterator-adaptor-requirements" id="id8" name="id8"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> requirements</a></li>
<li><a class="reference" href="#iterator-adaptor-base-class-parameters" id="id9" name="id9"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> base class parameters</a></li>
<li><a class="reference" href="#iterator-adaptor-public-operations" id="id10" name="id10"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> public operations</a></li>
<li><a class="reference" href="#iterator-adaptor-protected-member-functions" id="id11" name="id11"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> protected member functions</a></li>
<li><a class="reference" href="#iterator-adaptor-private-member-functions" id="id12" name="id12"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> private member functions</a></li>
</ul>
</li>
<li><a class="reference" href="#tutorial-example" id="id13" name="id13">Tutorial Example</a></li>
@ -73,40 +73,40 @@ core interface functions of <tt class="literal"><span class="pre">iterator_facad
<!-- Version 1.2 of this ReStructuredText document corresponds to
n1530_, the paper accepted by the LWG for TR1. -->
<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. -->
<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="id1" name="id1"><sup>1</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>
and implement the core behaviors in terms of the <tt class="literal"><span class="pre">Base</span></tt> type. In
essence, <tt class="literal"><span class="pre">iterator_adaptor</span></tt> merely forwards all operations to an
instance of the <tt class="literal"><span class="pre">Base</span></tt> type, which it stores as a member.</p>
<table class="footnote" frame="void" id="base" rules="none">
<p>The <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> class template adapts some <tt class="docutils literal"><span class="pre">Base</span></tt> <a class="footnote-reference" href="#base" id="id1" name="id1">[1]</a>
type to create a new iterator. Instantiations of <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>
are derived from a corresponding instantiation of <tt class="docutils literal"><span class="pre">iterator_facade</span></tt>
and implement the core behaviors in terms of the <tt class="docutils literal"><span class="pre">Base</span></tt> type. In
essence, <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> merely forwards all operations to an
instance of the <tt class="docutils literal"><span class="pre">Base</span></tt> type, which it stores as a member.</p>
<table class="docutils footnote" frame="void" id="base" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="base">[1]</a></td><td><em>(<a class="fn-backref" href="#id1">1</a>, <a class="fn-backref" href="#id3">2</a>)</em> The term &quot;Base&quot; here does not refer to a base class and is
not meant to imply the use of derivation. We have followed the lead
of the standard library, which provides a base() function to access
the underlying iterator object of a <tt class="literal"><span class="pre">reverse_iterator</span></tt> adaptor.</td></tr>
the underlying iterator object of a <tt class="docutils literal"><span class="pre">reverse_iterator</span></tt> adaptor.</td></tr>
</tbody>
</table>
<p>The user of <tt class="literal"><span class="pre">iterator_adaptor</span></tt> creates a class derived from an
instantiation of <tt class="literal"><span class="pre">iterator_adaptor</span></tt> and then selectively
<p>The user of <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> creates a class derived from an
instantiation of <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> and then selectively
redefines some of the core member functions described in the
<tt class="literal"><span class="pre">iterator_facade</span></tt> core requirements table. The <tt class="literal"><span class="pre">Base</span></tt> type need
<tt class="docutils literal"><span class="pre">iterator_facade</span></tt> core requirements table. The <tt class="docutils literal"><span class="pre">Base</span></tt> type need
not meet the full requirements for an iterator; it need only
support the operations used by the core interface functions of
<tt class="literal"><span class="pre">iterator_adaptor</span></tt> that have not been redefined in the user's
<tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> that have not been redefined in the user's
derived class.</p>
<p>Several of the template parameters of <tt class="literal"><span class="pre">iterator_adaptor</span></tt> default
to <tt class="literal"><span class="pre">use_default</span></tt>. This allows the
<p>Several of the template parameters of <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> default
to <tt class="docutils literal"><span class="pre">use_default</span></tt>. This allows the
user to make use of a default parameter even when she wants to
specify a parameter later in the parameter list. Also, the
defaults for the corresponding associated types are somewhat
complicated, so metaprogramming is required to compute them, and
<tt class="literal"><span class="pre">use_default</span></tt> can help to simplify the implementation. Finally,
the identity of the <tt class="literal"><span class="pre">use_default</span></tt> type is not left unspecified
because specification helps to highlight that the <tt class="literal"><span class="pre">Reference</span></tt>
<tt class="docutils literal"><span class="pre">use_default</span></tt> can help to simplify the implementation. Finally,
the identity of the <tt class="docutils literal"><span class="pre">use_default</span></tt> type is not left unspecified
because specification helps to highlight that the <tt class="docutils literal"><span class="pre">Reference</span></tt>
template parameter may not always be identical to the iterator's
<tt class="literal"><span class="pre">reference</span></tt> type, and will keep users from making mistakes based on
<tt class="docutils literal"><span class="pre">reference</span></tt> type, and will keep users from making mistakes based on
that assumption.</p>
</div>
<div class="section" id="reference">
@ -129,7 +129,8 @@ class iterator_adaptor
friend class iterator_core_access;
public:
iterator_adaptor();
explicit iterator_adaptor(Base iter);
explicit iterator_adaptor(Base const&amp; iter);
typedef Base base_type;
Base const&amp; base() const;
protected:
typedef iterator_adaptor iterator_adaptor_;
@ -158,14 +159,14 @@ class iterator_adaptor
};
</pre>
<a class="target" id="requirements" name="requirements"></a><div class="section" id="iterator-adaptor-requirements">
<h2><a class="toc-backref" href="#id8" name="iterator-adaptor-requirements"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> requirements</a></h2>
<p><tt class="literal"><span class="pre">static_cast&lt;Derived*&gt;(iterator_adaptor*)</span></tt> shall be well-formed.
The <tt class="literal"><span class="pre">Base</span></tt> argument shall be Assignable and Copy Constructible.</p>
<h2><a class="toc-backref" href="#id8" name="iterator-adaptor-requirements"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> requirements</a></h2>
<p><tt class="docutils literal"><span class="pre">static_cast&lt;Derived*&gt;(iterator_adaptor*)</span></tt> shall be well-formed.
The <tt class="docutils literal"><span class="pre">Base</span></tt> argument shall be Assignable and Copy Constructible.</p>
<a class="target" id="base-parameters" name="base-parameters"></a></div>
<div class="section" id="iterator-adaptor-base-class-parameters">
<h2><a class="toc-backref" href="#id9" name="iterator-adaptor-base-class-parameters"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> base class parameters</a></h2>
<p>The <em>V'</em>, <em>C'</em>, <em>R'</em>, and <em>D'</em> parameters of the <tt class="literal"><span class="pre">iterator_facade</span></tt>
used as a base class in the summary of <tt class="literal"><span class="pre">iterator_adaptor</span></tt>
<h2><a class="toc-backref" href="#id9" name="iterator-adaptor-base-class-parameters"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> base class parameters</a></h2>
<p>The <em>V'</em>, <em>C'</em>, <em>R'</em>, and <em>D'</em> parameters of the <tt class="docutils literal"><span class="pre">iterator_facade</span></tt>
used as a base class in the summary of <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>
above are defined as follows:</p>
<pre class="literal-block">
<em>V'</em> = if (Value is use_default)
@ -204,68 +205,68 @@ expression involving ``Derived`` in those concepts' requirements. -->
<!-- That's why it's removed. We're embracing inheritance, remember? -->
</div>
<div class="section" id="iterator-adaptor-public-operations">
<h2><a class="toc-backref" href="#id10" name="iterator-adaptor-public-operations"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> public operations</a></h2>
<p><tt class="literal"><span class="pre">iterator_adaptor();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<h2><a class="toc-backref" href="#id10" name="iterator-adaptor-public-operations"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> public operations</a></h2>
<p><tt class="docutils literal"><span class="pre">iterator_adaptor();</span></tt></p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Requires:</th><td class="field-body">The <tt class="literal"><span class="pre">Base</span></tt> type must be Default Constructible.</td>
<tr class="field"><th class="field-name">Requires:</th><td class="field-body">The <tt class="docutils literal"><span class="pre">Base</span></tt> type must be Default Constructible.</td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">iterator_adaptor</span></tt> with
<tt class="literal"><span class="pre">m_iterator</span></tt> default constructed.</td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> with
<tt class="docutils literal"><span class="pre">m_iterator</span></tt> default constructed.</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">explicit</span> <span class="pre">iterator_adaptor(Base</span> <span class="pre">iter);</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">explicit</span> <span class="pre">iterator_adaptor(Base</span> <span class="pre">const&amp;</span> <span class="pre">iter);</span></tt></p>
<table class="docutils 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 instance of <tt class="literal"><span class="pre">iterator_adaptor</span></tt> with
<tt class="literal"><span class="pre">m_iterator</span></tt> copy constructed from <tt class="literal"><span class="pre">iter</span></tt>.</td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> with
<tt class="docutils literal"><span class="pre">m_iterator</span></tt> copy constructed from <tt class="docutils literal"><span class="pre">iter</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">Base</span> <span class="pre">const&amp;</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">Base</span> <span class="pre">const&amp;</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
<table class="docutils 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">m_iterator</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_iterator</span></tt></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="iterator-adaptor-protected-member-functions">
<h2><a class="toc-backref" href="#id11" name="iterator-adaptor-protected-member-functions"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> protected member functions</a></h2>
<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">
<h2><a class="toc-backref" href="#id11" name="iterator-adaptor-protected-member-functions"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> protected member functions</a></h2>
<p><tt class="docutils 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="docutils 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">A const reference to <tt class="literal"><span class="pre">m_iterator</span></tt>.</td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">A const reference to <tt class="docutils literal"><span class="pre">m_iterator</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">Base&amp;</span> <span class="pre">base_reference();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">Base&amp;</span> <span class="pre">base_reference();</span></tt></p>
<table class="docutils 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">A non-const reference to <tt class="literal"><span class="pre">m_iterator</span></tt>.</td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">A non-const reference to <tt class="docutils literal"><span class="pre">m_iterator</span></tt>.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="iterator-adaptor-private-member-functions">
<h2><a class="toc-backref" href="#id12" name="iterator-adaptor-private-member-functions"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> private member functions</a></h2>
<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">
<h2><a class="toc-backref" href="#id12" name="iterator-adaptor-private-member-functions"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> private member functions</a></h2>
<p><tt class="docutils 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="docutils 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">*m_iterator</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*m_iterator</span></tt></td>
</tr>
</tbody>
</table>
@ -275,38 +276,38 @@ class OtherDerived, class OtherIterator, class V, class C, class R, class D
&gt;
bool equal(iterator_adaptor&lt;OtherDerived, OtherIterator, V, C, R, D&gt; const&amp; x) const;
</pre>
<table class="field-list" frame="void" rules="none">
<table class="docutils 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">m_iterator</span> <span class="pre">==</span> <span class="pre">x.base()</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_iterator</span> <span class="pre">==</span> <span class="pre">x.base()</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">void</span> <span class="pre">advance(typename</span> <span class="pre">iterator_adaptor::difference_type</span> <span class="pre">n);</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">void</span> <span class="pre">advance(typename</span> <span class="pre">iterator_adaptor::difference_type</span> <span class="pre">n);</span></tt></p>
<table class="docutils 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"><tt class="literal"><span class="pre">m_iterator</span> <span class="pre">+=</span> <span class="pre">n;</span></tt></td>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_iterator</span> <span class="pre">+=</span> <span class="pre">n;</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">void</span> <span class="pre">increment();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">void</span> <span class="pre">increment();</span></tt></p>
<table class="docutils 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"><tt class="literal"><span class="pre">++m_iterator;</span></tt></td>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="docutils literal"><span class="pre">++m_iterator;</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">void</span> <span class="pre">decrement();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">void</span> <span class="pre">decrement();</span></tt></p>
<table class="docutils 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"><tt class="literal"><span class="pre">--m_iterator;</span></tt></td>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="docutils literal"><span class="pre">--m_iterator;</span></tt></td>
</tr>
</tbody>
</table>
@ -317,11 +318,11 @@ template &lt;
typename iterator_adaptor::difference_type distance_to(
iterator_adaptor&lt;OtherDerived, OtherIterator, V, C, R, D&gt; const&amp; y) const;
</pre>
<table class="field-list" frame="void" rules="none">
<table class="docutils 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">y.base()</span> <span class="pre">-</span> <span class="pre">m_iterator</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">y.base()</span> <span class="pre">-</span> <span class="pre">m_iterator</span></tt></td>
</tr>
</tbody>
</table>
@ -332,44 +333,44 @@ typename iterator_adaptor::difference_type distance_to(
<!-- Copyright David Abrahams 2004. Use, modification and distribution is -->
<!-- subject to the Boost Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
<p>In this section we'll further refine the <tt class="literal"><span class="pre">node_iter</span></tt> class
template we developed in the <a class="reference" href="iterator_facade.html#tutorial-example"><tt class="literal"><span class="pre">iterator_facade</span></tt> tutorial</a>. If you haven't already
<p>In this section we'll further refine the <tt class="docutils literal"><span class="pre">node_iter</span></tt> class
template we developed in the <a class="reference" href="iterator_facade.html#tutorial-example"><tt class="docutils literal"><span class="pre">iterator_facade</span></tt> tutorial</a>. If you haven't already
read that material, you should go back now and check it out because
we're going to pick up right where it left off.</p>
<div class="sidebar">
<p class="sidebar-title first"><tt class="literal"><span class="pre">node_base*</span></tt> really <em>is</em> an iterator</p>
<p>It's not really a very interesting iterator, since <tt class="literal"><span class="pre">node_base</span></tt>
is an abstract class: a pointer to a <tt class="literal"><span class="pre">node_base</span></tt> just points
<p class="first sidebar-title"><tt class="docutils literal"><span class="pre">node_base*</span></tt> really <em>is</em> an iterator</p>
<p class="last">It's not really a very interesting iterator, since <tt class="docutils literal"><span class="pre">node_base</span></tt>
is an abstract class: a pointer to a <tt class="docutils literal"><span class="pre">node_base</span></tt> just points
at some base subobject of an instance of some other class, and
incrementing a <tt class="literal"><span class="pre">node_base*</span></tt> moves it past this base subobject
incrementing a <tt class="docutils literal"><span class="pre">node_base*</span></tt> moves it past this base subobject
to who-knows-where? The most we can do with that incremented
position is to compare another <tt class="literal"><span class="pre">node_base*</span></tt> to it. In other
position is to compare another <tt class="docutils literal"><span class="pre">node_base*</span></tt> to it. In other
words, the original iterator traverses a one-element array.</p>
</div>
<p>You probably didn't think of it this way, but the <tt class="literal"><span class="pre">node_base*</span></tt>
object that underlies <tt class="literal"><span class="pre">node_iterator</span></tt> is itself an iterator,
<p>You probably didn't think of it this way, but the <tt class="docutils literal"><span class="pre">node_base*</span></tt>
object that underlies <tt class="docutils literal"><span class="pre">node_iterator</span></tt> is itself an iterator,
just like all other pointers. If we examine that pointer closely
from an iterator perspective, we can see that it has much in common
with the <tt class="literal"><span class="pre">node_iterator</span></tt> we're building. First, they share most
of the same associated types (<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">pointer</span></tt>, and <tt class="literal"><span class="pre">difference_type</span></tt>). Second, even some of the
core functionality is the same: <tt class="literal"><span class="pre">operator*</span></tt> and <tt class="literal"><span class="pre">operator==</span></tt> on
the <tt class="literal"><span class="pre">node_iterator</span></tt> return the result of invoking the same
operations on the underlying pointer, via the <tt class="literal"><span class="pre">node_iterator</span></tt>'s
<a class="reference" href="iterator_facade.html#implementing-the-core-operations"><tt class="literal"><span class="pre">dereference</span></tt> and <tt class="literal"><span class="pre">equal</span></tt> member functions</a>). The only real behavioral difference
between <tt class="literal"><span class="pre">node_base*</span></tt> and <tt class="literal"><span class="pre">node_iterator</span></tt> can be observed when
they are incremented: <tt class="literal"><span class="pre">node_iterator</span></tt> follows the
<tt class="literal"><span class="pre">m_next</span></tt> pointer, while <tt class="literal"><span class="pre">node_base*</span></tt> just applies an address offset.</p>
with the <tt class="docutils literal"><span class="pre">node_iterator</span></tt> we're building. First, they share most
of the same associated types (<tt class="docutils literal"><span class="pre">value_type</span></tt>, <tt class="docutils literal"><span class="pre">reference</span></tt>,
<tt class="docutils literal"><span class="pre">pointer</span></tt>, and <tt class="docutils literal"><span class="pre">difference_type</span></tt>). Second, even some of the
core functionality is the same: <tt class="docutils literal"><span class="pre">operator*</span></tt> and <tt class="docutils literal"><span class="pre">operator==</span></tt> on
the <tt class="docutils literal"><span class="pre">node_iterator</span></tt> return the result of invoking the same
operations on the underlying pointer, via the <tt class="docutils literal"><span class="pre">node_iterator</span></tt>'s
<a class="reference" href="iterator_facade.html#implementing-the-core-operations"><tt class="docutils literal"><span class="pre">dereference</span></tt> and <tt class="docutils literal"><span class="pre">equal</span></tt> member functions</a>). The only real behavioral difference
between <tt class="docutils literal"><span class="pre">node_base*</span></tt> and <tt class="docutils literal"><span class="pre">node_iterator</span></tt> can be observed when
they are incremented: <tt class="docutils literal"><span class="pre">node_iterator</span></tt> follows the
<tt class="docutils literal"><span class="pre">m_next</span></tt> pointer, while <tt class="docutils literal"><span class="pre">node_base*</span></tt> just applies an address offset.</p>
<p>It turns out that the pattern of building an iterator on another
iterator-like type (the <tt class="literal"><span class="pre">Base</span></tt> <a class="footnote-reference" href="#base" id="id3" name="id3"><sup>1</sup></a> type) while modifying
iterator-like type (the <tt class="docutils literal"><span class="pre">Base</span></tt> <a class="footnote-reference" href="#base" id="id3" name="id3">[1]</a> type) while modifying
just a few aspects of the underlying type's behavior is an
extremely common one, and it's the pattern addressed by
<tt class="literal"><span class="pre">iterator_adaptor</span></tt>. Using <tt class="literal"><span class="pre">iterator_adaptor</span></tt> is very much like
using <tt class="literal"><span class="pre">iterator_facade</span></tt>, but because iterator_adaptor tries to
mimic as much of the <tt class="literal"><span class="pre">Base</span></tt> type's behavior as possible, we
neither have to supply a <tt class="literal"><span class="pre">Value</span></tt> argument, nor implement any core
behaviors other than <tt class="literal"><span class="pre">increment</span></tt>. The implementation of
<tt class="literal"><span class="pre">node_iter</span></tt> is thus reduced to:</p>
<tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>. Using <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> is very much like
using <tt class="docutils literal"><span class="pre">iterator_facade</span></tt>, but because iterator_adaptor tries to
mimic as much of the <tt class="docutils literal"><span class="pre">Base</span></tt> type's behavior as possible, we
neither have to supply a <tt class="docutils literal"><span class="pre">Value</span></tt> argument, nor implement any core
behaviors other than <tt class="docutils literal"><span class="pre">increment</span></tt>. The implementation of
<tt class="docutils literal"><span class="pre">node_iter</span></tt> is thus reduced to:</p>
<pre class="literal-block">
template &lt;class Value&gt;
class node_iter
@ -405,40 +406,40 @@ class node_iter
void increment() { this-&gt;base_reference() = this-&gt;base()-&gt;next(); }
};
</pre>
<p>Note the use of <tt class="literal"><span class="pre">node_iter::iterator_adaptor_</span></tt> here: because
<tt class="literal"><span class="pre">iterator_adaptor</span></tt> defines a nested <tt class="literal"><span class="pre">iterator_adaptor_</span></tt> type
<p>Note the use of <tt class="docutils literal"><span class="pre">node_iter::iterator_adaptor_</span></tt> here: because
<tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> defines a nested <tt class="docutils literal"><span class="pre">iterator_adaptor_</span></tt> type
that refers to itself, that gives us a convenient way to refer to
the complicated base class type of <tt class="literal"><span class="pre">node_iter&lt;Value&gt;</span></tt>. [Note:
the complicated base class type of <tt class="docutils literal"><span class="pre">node_iter&lt;Value&gt;</span></tt>. [Note:
this technique is known not to work with Borland C++ 5.6.4 and
Metrowerks CodeWarrior versions prior to 9.0]</p>
<p>You can see an example program that exercises this version of the
node iterators <a class="reference" href="../example/node_iterator3.cpp">here</a>.</p>
<p>In the case of <tt class="literal"><span class="pre">node_iter</span></tt>, it's not very compelling to pass
<tt class="literal"><span class="pre">boost::use_default</span></tt> as <tt class="literal"><span class="pre">iterator_adaptor</span></tt>'s <tt class="literal"><span class="pre">Value</span></tt>
argument; we could have just passed <tt class="literal"><span class="pre">node_iter</span></tt>'s <tt class="literal"><span class="pre">Value</span></tt>
along to <tt class="literal"><span class="pre">iterator_adaptor</span></tt>, and that'd even be shorter! Most
iterator class templates built with <tt class="literal"><span class="pre">iterator_adaptor</span></tt> are
<p>In the case of <tt class="docutils literal"><span class="pre">node_iter</span></tt>, it's not very compelling to pass
<tt class="docutils literal"><span class="pre">boost::use_default</span></tt> as <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>'s <tt class="docutils literal"><span class="pre">Value</span></tt>
argument; we could have just passed <tt class="docutils literal"><span class="pre">node_iter</span></tt>'s <tt class="docutils literal"><span class="pre">Value</span></tt>
along to <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>, and that'd even be shorter! Most
iterator class templates built with <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> are
parameterized on another iterator type, rather than on its
<tt class="literal"><span class="pre">value_type</span></tt>. For example, <tt class="literal"><span class="pre">boost::reverse_iterator</span></tt> takes an
<tt class="docutils literal"><span class="pre">value_type</span></tt>. For example, <tt class="docutils literal"><span class="pre">boost::reverse_iterator</span></tt> takes an
iterator type argument and reverses its direction of traversal,
since the original iterator and the reversed one have all the same
associated types, <tt class="literal"><span class="pre">iterator_adaptor</span></tt>'s delegation of default
types to its <tt class="literal"><span class="pre">Base</span></tt> saves the implementor of
<tt class="literal"><span class="pre">boost::reverse_iterator</span></tt> from writing:</p>
associated types, <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>'s delegation of default
types to its <tt class="docutils literal"><span class="pre">Base</span></tt> saves the implementor of
<tt class="docutils literal"><span class="pre">boost::reverse_iterator</span></tt> from writing:</p>
<pre class="literal-block">
std::iterator_traits&lt;Iterator&gt;::<em>some-associated-type</em>
</pre>
<p>at least four times.</p>
<p>We urge you to review the documentation and implementations of
<a class="reference" href="reverse_iterator.html"><tt class="literal"><span class="pre">reverse_iterator</span></tt></a> and the other Boost <a class="reference" href="index.html#specialized-adaptors">specialized iterator
<a class="reference" href="reverse_iterator.html"><tt class="docutils literal"><span class="pre">reverse_iterator</span></tt></a> and the other Boost <a class="reference" href="index.html#specialized-adaptors">specialized iterator
adaptors</a> to get an idea of the sorts of things you can do with
<tt class="literal"><span class="pre">iterator_adaptor</span></tt>. In particular, have a look at
<a class="reference" href="transform_iterator.html"><tt class="literal"><span class="pre">transform_iterator</span></tt></a>, which is perhaps the most straightforward
adaptor, and also <a class="reference" href="counting_iterator.html"><tt class="literal"><span class="pre">counting_iterator</span></tt></a>, which demonstrates that
<tt class="literal"><span class="pre">iterator_adaptor</span></tt>'s <tt class="literal"><span class="pre">Base</span></tt> type needn't be an iterator.</p>
<tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>. In particular, have a look at
<a class="reference" href="transform_iterator.html"><tt class="docutils literal"><span class="pre">transform_iterator</span></tt></a>, which is perhaps the most straightforward
adaptor, and also <a class="reference" href="counting_iterator.html"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt></a>, which demonstrates that
<tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>'s <tt class="docutils literal"><span class="pre">Base</span></tt> type needn't be an iterator.</p>
</div>
</div>
<hr class="footer" />
<hr class="docutils footer" />
<div class="footer">
<a class="reference" href="iterator_adaptor.rst">View document source</a>.
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.

BIN
doc/iterator_adaptor.pdf
View File

Binary file not shown.

48
doc/iterator_archetypes.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.3.6: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.3.8: http://docutils.sourceforge.net/" />
<title>Iterator Archetype</title>
<meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" />
<meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, Zephyr Associates, Inc." />
@ -12,6 +12,7 @@
<link rel="stylesheet" href="default.css" type="text/css" />
</head>
<body>
<div class="document" id="iterator-archetype">
<h1 class="title">Iterator Archetype</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
@ -30,16 +31,15 @@ Lab</a>, <a class="last reference" href="http://www.styleadvisor.com">Zephyr Ass
<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2004.</td></tr>
</tbody>
</table>
<div class="document" id="iterator-archetype">
<table class="field-list" frame="void" rules="none">
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">abstract:</th><td class="field-body">The <tt class="literal"><span class="pre">iterator_archetype</span></tt> class constructs a minimal implementation of
<tr class="field"><th class="field-name">abstract:</th><td class="field-body">The <tt class="docutils literal"><span class="pre">iterator_archetype</span></tt> class constructs a minimal implementation of
one of the iterator access concepts and one of the iterator traversal concepts.
This is used for doing a compile-time check to see if a the type requirements
of a template are really enough to cover the implementation of the template.
For further information see the documentation for the <a class="reference" href="../../concept_check/index.html"><tt class="literal"><span class="pre">boost::concept_check</span></tt></a> library.</td>
For further information see the documentation for the <a class="reference" href="../../concept_check/index.html"><tt class="docutils literal"><span class="pre">boost::concept_check</span></tt></a> library.</td>
</tr>
</tbody>
</table>
@ -47,11 +47,11 @@ For further information see the documentation for the <a class="reference" href=
<p class="topic-title first"><a name="table-of-contents">Table of Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#reference" id="id1" name="id1">Reference</a><ul>
<li><a class="reference" href="#iterator-archetype-synopsis" id="id2" name="id2"><tt class="literal"><span class="pre">iterator_archetype</span></tt> Synopsis</a></li>
<li><a class="reference" href="#access-category-tags" id="id3" name="id3"><tt class="literal"><span class="pre">Access</span> <span class="pre">Category</span> <span class="pre">Tags</span></tt></a></li>
<li><a class="reference" href="#iterator-archetype-requirements" id="id4" name="id4"><tt class="literal"><span class="pre">iterator_archetype</span></tt> Requirements</a></li>
<li><a class="reference" href="#iterator-archetype-models" id="id5" name="id5"><tt class="literal"><span class="pre">iterator_archetype</span></tt> Models</a></li>
<li><a class="reference" href="#traits" id="id6" name="id6"><tt class="literal"><span class="pre">Traits</span></tt></a></li>
<li><a class="reference" href="#iterator-archetype-synopsis" id="id2" name="id2"><tt class="docutils literal"><span class="pre">iterator_archetype</span></tt> Synopsis</a></li>
<li><a class="reference" href="#access-category-tags" id="id3" name="id3"><tt class="docutils literal"><span class="pre">Access</span> <span class="pre">Category</span> <span class="pre">Tags</span></tt></a></li>
<li><a class="reference" href="#iterator-archetype-requirements" id="id4" name="id4"><tt class="docutils literal"><span class="pre">iterator_archetype</span></tt> Requirements</a></li>
<li><a class="reference" href="#iterator-archetype-models" id="id5" name="id5"><tt class="docutils literal"><span class="pre">iterator_archetype</span></tt> Models</a></li>
<li><a class="reference" href="#traits" id="id6" name="id6"><tt class="docutils literal"><span class="pre">Traits</span></tt></a></li>
</ul>
</li>
</ul>
@ -59,7 +59,7 @@ For further information see the documentation for the <a class="reference" href=
<div class="section" id="reference">
<h1><a class="toc-backref" href="#id1" name="reference">Reference</a></h1>
<div class="section" id="iterator-archetype-synopsis">
<h2><a class="toc-backref" href="#id2" name="iterator-archetype-synopsis"><tt class="literal"><span class="pre">iterator_archetype</span></tt> Synopsis</a></h2>
<h2><a class="toc-backref" href="#id2" name="iterator-archetype-synopsis"><tt class="docutils literal"><span class="pre">iterator_archetype</span></tt> Synopsis</a></h2>
<pre class="literal-block">
namespace iterator_archetypes
{
@ -89,7 +89,7 @@ class iterator_archetype
</pre>
</div>
<div class="section" id="access-category-tags">
<h2><a class="toc-backref" href="#id3" name="access-category-tags"><tt class="literal"><span class="pre">Access</span> <span class="pre">Category</span> <span class="pre">Tags</span></tt></a></h2>
<h2><a class="toc-backref" href="#id3" name="access-category-tags"><tt class="docutils literal"><span class="pre">Access</span> <span class="pre">Category</span> <span class="pre">Tags</span></tt></a></h2>
<p>The access category types provided correspond to the following
standard iterator access concept combinations:</p>
<pre class="literal-block">
@ -115,22 +115,22 @@ writeable_lvalue_iterator_t :=
</pre>
</div>
<div class="section" id="iterator-archetype-requirements">
<h2><a class="toc-backref" href="#id4" name="iterator-archetype-requirements"><tt class="literal"><span class="pre">iterator_archetype</span></tt> Requirements</a></h2>
<p>The <tt class="literal"><span class="pre">AccessCategory</span></tt> argument must be one of the predefined access
category tags. The <tt class="literal"><span class="pre">TraversalCategory</span></tt> must be one of the standard
traversal tags. The <tt class="literal"><span class="pre">Value</span></tt> type must satisfy the requirements of
the iterator concept specified by <tt class="literal"><span class="pre">AccessCategory</span></tt> and
<tt class="literal"><span class="pre">TraversalCategory</span></tt> as implied by the nested traits types.</p>
<h2><a class="toc-backref" href="#id4" name="iterator-archetype-requirements"><tt class="docutils literal"><span class="pre">iterator_archetype</span></tt> Requirements</a></h2>
<p>The <tt class="docutils literal"><span class="pre">AccessCategory</span></tt> argument must be one of the predefined access
category tags. The <tt class="docutils literal"><span class="pre">TraversalCategory</span></tt> must be one of the standard
traversal tags. The <tt class="docutils literal"><span class="pre">Value</span></tt> type must satisfy the requirements of
the iterator concept specified by <tt class="docutils literal"><span class="pre">AccessCategory</span></tt> and
<tt class="docutils literal"><span class="pre">TraversalCategory</span></tt> as implied by the nested traits types.</p>
</div>
<div class="section" id="iterator-archetype-models">
<h2><a class="toc-backref" href="#id5" name="iterator-archetype-models"><tt class="literal"><span class="pre">iterator_archetype</span></tt> Models</a></h2>
<p><tt class="literal"><span class="pre">iterator_archetype</span></tt> models the iterator concepts specified by the
<tt class="literal"><span class="pre">AccessCategory</span></tt> and <tt class="literal"><span class="pre">TraversalCategory</span></tt>
arguments. <tt class="literal"><span class="pre">iterator_archetype</span></tt> does not model any other access
<h2><a class="toc-backref" href="#id5" name="iterator-archetype-models"><tt class="docutils literal"><span class="pre">iterator_archetype</span></tt> Models</a></h2>
<p><tt class="docutils literal"><span class="pre">iterator_archetype</span></tt> models the iterator concepts specified by the
<tt class="docutils literal"><span class="pre">AccessCategory</span></tt> and <tt class="docutils literal"><span class="pre">TraversalCategory</span></tt>
arguments. <tt class="docutils literal"><span class="pre">iterator_archetype</span></tt> does not model any other access
concepts or any more derived traversal concepts.</p>
</div>
<div class="section" id="traits">
<h2><a class="toc-backref" href="#id6" name="traits"><tt class="literal"><span class="pre">Traits</span></tt></a></h2>
<h2><a class="toc-backref" href="#id6" name="traits"><tt class="docutils literal"><span class="pre">Traits</span></tt></a></h2>
<p>The nested trait types are defined as follows:</p>
<pre class="literal-block">
if (AccessCategory == readable_iterator_t)
@ -211,7 +211,7 @@ iterator_category :=
</div>
</div>
</div>
<hr class="footer" />
<hr class="docutils footer" />
<div class="footer">
<a class="reference" href="iterator_archetypes.rst">View document source</a>.
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.

BIN
doc/iterator_archetypes.pdf
View File

Binary file not shown.

12
doc/iterator_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.3.6: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.3.8: http://docutils.sourceforge.net/" />
<title>Iterator Concepts</title>
<meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" />
<meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, Zephyr Associates, Inc." />
@ -12,6 +12,7 @@
<link rel="stylesheet" href="default.css" type="text/css" />
</head>
<body>
<div class="document" id="iterator-concepts">
<h1 class="title">Iterator Concepts</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
@ -30,8 +31,7 @@ Lab</a>, <a class="last reference" href="http://www.styleadvisor.com">Zephyr Ass
<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2004.</td></tr>
</tbody>
</table>
<div class="document" id="iterator-concepts">
<table class="field-list" frame="void" rules="none">
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
@ -43,7 +43,7 @@ the template.</td>
</tbody>
</table>
<p>For an introduction to using concept checking classes, see
the documentation for the <a class="reference" href="../../concept_check/index.html"><tt class="literal"><span class="pre">boost::concept_check</span></tt></a> library.</p>
the documentation for the <a class="reference" href="../../concept_check/index.html"><tt class="docutils literal"><span class="pre">boost::concept_check</span></tt></a> library.</p>
<div class="section" id="reference">
<h1><a name="reference">Reference</a></h1>
<div class="section" id="iterator-access-concepts">
@ -66,7 +66,7 @@ the documentation for the <a class="reference" href="../../concept_check/index.h
</ul>
</div>
<div class="section" id="iterator-concepts-hpp-synopsis">
<h2><a name="iterator-concepts-hpp-synopsis"><tt class="literal"><span class="pre">iterator_concepts.hpp</span></tt> Synopsis</a></h2>
<h2><a name="iterator-concepts-hpp-synopsis"><tt class="docutils literal"><span class="pre">iterator_concepts.hpp</span></tt> Synopsis</a></h2>
<pre class="literal-block">
namespace boost_concepts {
@ -114,7 +114,7 @@ namespace boost_concepts {
</div>
</div>
</div>
<hr class="footer" />
<hr class="docutils footer" />
<div class="footer">
<a class="reference" href="iterator_concepts.rst">View document source</a>.
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.

BIN
doc/iterator_concepts.pdf
View File

Binary file not shown.

542
doc/iterator_facade.html
View File

File diff suppressed because it is too large Load Diff

BIN
doc/iterator_facade.pdf
View File

Binary file not shown.

28
doc/iterator_traits.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.3.6: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.3.8: http://docutils.sourceforge.net/" />
<title>Iterator Traits</title>
<meta name="author" content="David Abrahams" />
<meta name="organization" content="Boost Consulting" />
@ -12,6 +12,7 @@
<link rel="stylesheet" href="default.css" type="text/css" />
</head>
<body>
<div class="document" id="iterator-traits">
<h1 class="title">Iterator Traits</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
@ -29,12 +30,11 @@
<td>Copyright David Abrahams 2004.</td></tr>
</tbody>
</table>
<div class="document" id="iterator-traits">
<table class="field-list" frame="void" rules="none">
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">abstract:</th><td class="field-body">Header <tt class="literal"><span class="pre">&lt;boost/iterator/iterator_traits.hpp&gt;</span></tt> provides
<tr class="field"><th class="field-name">abstract:</th><td class="field-body">Header <tt class="docutils literal"><span class="pre">&lt;boost/iterator/iterator_traits.hpp&gt;</span></tt> provides
the ability to access an iterator's associated types using
MPL-compatible <a class="reference" href="../../mpl/doc/index.html#metafunctions">metafunctions</a>.</td>
</tr>
@ -42,16 +42,16 @@ MPL-compatible <a class="reference" href="../../mpl/doc/index.html#metafunctions
</table>
<div class="section" id="overview">
<h1><a name="overview">Overview</a></h1>
<p><tt class="literal"><span class="pre">std::iterator_traits</span></tt> provides access to five associated types
of any iterator: its <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">pointer</span></tt>,
<tt class="literal"><span class="pre">iterator_category</span></tt>, and <tt class="literal"><span class="pre">difference_type</span></tt>. Unfortunately,
<p><tt class="docutils literal"><span class="pre">std::iterator_traits</span></tt> provides access to five associated types
of any iterator: its <tt class="docutils literal"><span class="pre">value_type</span></tt>, <tt class="docutils literal"><span class="pre">reference</span></tt>, <tt class="docutils literal"><span class="pre">pointer</span></tt>,
<tt class="docutils literal"><span class="pre">iterator_category</span></tt>, and <tt class="docutils literal"><span class="pre">difference_type</span></tt>. Unfortunately,
such a &quot;multi-valued&quot; traits template can be difficult to use in a
metaprogramming context. <tt class="literal"><span class="pre">&lt;boost/iterator/iterator_traits.hpp&gt;</span></tt>
metaprogramming context. <tt class="docutils literal"><span class="pre">&lt;boost/iterator/iterator_traits.hpp&gt;</span></tt>
provides access to these types using a standard <a class="reference" href="../../mpl/doc/index.html#metafunctions">metafunctions</a>.</p>
</div>
<div class="section" id="summary">
<h1><a name="summary">Summary</a></h1>
<p>Header <tt class="literal"><span class="pre">&lt;boost/iterator/iterator_traits.hpp&gt;</span></tt>:</p>
<p>Header <tt class="docutils literal"><span class="pre">&lt;boost/iterator/iterator_traits.hpp&gt;</span></tt>:</p>
<pre class="literal-block">
template &lt;class Iterator&gt;
struct iterator_value
@ -103,15 +103,15 @@ your compiler's standard library.</p>
<p>On compilers that don't support partial specialization, such as
Microsoft Visual C++ 6.0 or 7.0, you may need to manually invoke
<a class="reference" href="../../type_traits/index.html#transformations">BOOST_BROKEN_COMPILER_TYPE_TRAITS_SPECIALIZATION</a> on the
<tt class="literal"><span class="pre">value_type</span></tt> of pointers that are passed to these metafunctions.</p>
<tt class="docutils literal"><span class="pre">value_type</span></tt> of pointers that are passed to these metafunctions.</p>
<p>Because of bugs in the implementation of GCC-2.9x, the name of
<tt class="literal"><span class="pre">iterator_category</span></tt> is changed to <tt class="literal"><span class="pre">iterator_category_</span></tt> on that
compiler. A macro, <tt class="literal"><span class="pre">BOOST_ITERATOR_CATEGORY</span></tt>, that expands to
either <tt class="literal"><span class="pre">iterator_category</span></tt> or <tt class="literal"><span class="pre">iterator_category_</span></tt>, as
<tt class="docutils literal"><span class="pre">iterator_category</span></tt> is changed to <tt class="docutils literal"><span class="pre">iterator_category_</span></tt> on that
compiler. A macro, <tt class="docutils literal"><span class="pre">BOOST_ITERATOR_CATEGORY</span></tt>, that expands to
either <tt class="docutils literal"><span class="pre">iterator_category</span></tt> or <tt class="docutils literal"><span class="pre">iterator_category_</span></tt>, as
appropriate to the platform, is provided for portability.</p>
</div>
</div>
<hr class="footer" />
<hr class="docutils footer" />
<div class="footer">
<a class="reference" href="iterator_traits.rst">View document source</a>.
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.

BIN
doc/iterator_traits.pdf
View File

Binary file not shown.

558
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.3.6: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.3.8: 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, Zephyr Associates, Inc." />
@ -12,6 +12,7 @@
<link rel="stylesheet" href="default.css" type="text/css" />
</head>
<body>
<div class="document" id="new-iterator-concepts">
<h1 class="title">New Iterator Concepts</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
@ -36,10 +37,9 @@ revision of paper <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc22/wg
2003.</td></tr>
</tbody>
</table>
<div class="document" id="new-iterator-concepts">
<!-- Version 1.25 of this ReStructuredText document is the same as
n1550_, the paper accepted by the LWG. -->
<table class="field-list" frame="void" rules="none">
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
@ -59,7 +59,7 @@ of iterators that are used in practice.</td>
<li><a class="reference" href="#possible-but-not-proposed-changes-to-the-working-paper" id="id3" name="id3">Possible (but not proposed) Changes to the Working Paper</a><ul>
<li><a class="reference" href="#changes-to-algorithm-requirements" id="id4" name="id4">Changes to Algorithm Requirements</a></li>
<li><a class="reference" href="#deprecations" id="id5" name="id5">Deprecations</a></li>
<li><a class="reference" href="#vector-bool" id="id6" name="id6"><tt class="literal"><span class="pre">vector&lt;bool&gt;</span></tt></a></li>
<li><a class="reference" href="#vector-bool" id="id6" name="id6"><tt class="docutils literal"><span class="pre">vector&lt;bool&gt;</span></tt></a></li>
</ul>
</li>
</ul>
@ -107,7 +107,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 border="1" class="table">
<table border="1" class="docutils">
<colgroup>
<col width="31%" />
<col width="69%" />
@ -118,17 +118,17 @@ requirements in the iterator categories.</p>
</thead>
<tbody valign="top">
<tr><td>Output Iterator</td>
<td><tt class="literal"><span class="pre">*i</span> <span class="pre">=</span> <span class="pre">a</span></tt></td>
<td><tt class="docutils literal"><span class="pre">*i</span> <span class="pre">=</span> <span class="pre">a</span></tt></td>
</tr>
<tr><td>Input Iterator</td>
<td><tt class="literal"><span class="pre">*i</span></tt> is convertible to <tt class="literal"><span class="pre">T</span></tt></td>
<td><tt class="docutils literal"><span class="pre">*i</span></tt> is convertible to <tt class="docutils literal"><span class="pre">T</span></tt></td>
</tr>
<tr><td>Forward Iterator</td>
<td><tt class="literal"><span class="pre">*i</span></tt> is <tt class="literal"><span class="pre">T&amp;</span></tt> (or <tt class="literal"><span class="pre">const</span> <span class="pre">T&amp;</span></tt> once <a class="reference" href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/lwg-active.html#200">issue 200</a>
<td><tt class="docutils literal"><span class="pre">*i</span></tt> is <tt class="docutils literal"><span class="pre">T&amp;</span></tt> (or <tt class="docutils literal"><span class="pre">const</span> <span class="pre">T&amp;</span></tt> once <a class="reference" href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/lwg-active.html#200">issue 200</a>
is resolved)</td>
</tr>
<tr><td>Random Access Iterator</td>
<td><tt class="literal"><span class="pre">i[n]</span></tt> is convertible to <tt class="literal"><span class="pre">T</span></tt> (also <tt class="literal"><span class="pre">i[n]</span> <span class="pre">=</span> <span class="pre">t</span></tt>
<td><tt class="docutils literal"><span class="pre">i[n]</span></tt> is convertible to <tt class="docutils literal"><span class="pre">T</span></tt> (also <tt class="docutils literal"><span class="pre">i[n]</span> <span class="pre">=</span> <span class="pre">t</span></tt>
is required for mutable iterators once <a class="reference" href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/lwg-active.html#299">issue 299</a>
is resolved)</td>
</tr>
@ -136,30 +136,30 @@ is resolved)</td>
</table>
<p>Because iterator traversal and value access are mixed together in a
single hierarchy, many useful iterators can not be appropriately
categorized. For example, <tt class="literal"><span class="pre">vector&lt;bool&gt;::iterator</span></tt> is almost a
random access iterator, but the return type is not <tt class="literal"><span class="pre">bool&amp;</span></tt> (see
categorized. For example, <tt class="docutils literal"><span class="pre">vector&lt;bool&gt;::iterator</span></tt> is almost a
random access iterator, but the return type is not <tt class="docutils literal"><span class="pre">bool&amp;</span></tt> (see
<a class="reference" href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/lwg-active.html#96">issue 96</a> and Herb Sutter's paper J16/99-0008 = WG21
N1185). Therefore, the iterators of <tt class="literal"><span class="pre">vector&lt;bool&gt;</span></tt> only meet the
N1185). Therefore, the iterators of <tt class="docutils literal"><span class="pre">vector&lt;bool&gt;</span></tt> only meet the
requirements of input iterator and output iterator. This is so
nonintuitive that the C++ standard contradicts itself on this point.
In paragraph 23.2.4/1 it says that a <tt class="literal"><span class="pre">vector</span></tt> is a sequence that
In paragraph 23.2.4/1 it says that a <tt class="docutils literal"><span class="pre">vector</span></tt> is a sequence that
supports random access iterators.</p>
<p>Another difficult-to-categorize iterator is the transform iterator, an
adaptor which applies a unary function object to the dereferenced
value of the some underlying iterator (see <a class="reference" href="http://www.boost.org/libs/utility/transform_iterator.htm">transform_iterator</a>).
For unary functions such as <tt class="literal"><span class="pre">times</span></tt>, the return type of
<tt class="literal"><span class="pre">operator*</span></tt> clearly needs to be the <tt class="literal"><span class="pre">result_type</span></tt> of the function
For unary functions such as <tt class="docutils literal"><span class="pre">times</span></tt>, the return type of
<tt class="docutils literal"><span class="pre">operator*</span></tt> clearly needs to be the <tt class="docutils literal"><span class="pre">result_type</span></tt> of the function
object, which is typically not a reference. Because random access
iterators are required to return lvalues from <tt class="literal"><span class="pre">operator*</span></tt>, if you
wrap <tt class="literal"><span class="pre">int*</span></tt> with a transform iterator, you do not get a random
iterators are required to return lvalues from <tt class="docutils literal"><span class="pre">operator*</span></tt>, if you
wrap <tt class="docutils literal"><span class="pre">int*</span></tt> with a transform iterator, you do not get a random
access iterator as might be expected, but an input iterator.</p>
<p>A third example is found in the vertex and edge iterators of the
<a class="reference" href="http://www.boost.org/libs/graph/doc/table_of_contents.html">Boost Graph Library</a>. These iterators return vertex and edge
descriptors, which are lightweight handles created on-the-fly. They
must be returned by-value. As a result, their current standard
iterator category is <tt class="literal"><span class="pre">input_iterator_tag</span></tt>, which means that,
iterator category is <tt class="docutils literal"><span class="pre">input_iterator_tag</span></tt>, which means that,
strictly speaking, you could not use these iterators with algorithms
like <tt class="literal"><span class="pre">min_element()</span></tt>. As a temporary solution, the concept
like <tt class="docutils literal"><span class="pre">min_element()</span></tt>. As a temporary solution, the concept
<a class="reference" href="http://www.boost.org/libs/utility/MultiPassInputIterator.html">Multi-Pass Input Iterator</a> was introduced to describe the vertex and
edge descriptors, but as the design notes for the concept suggest, a
better solution is needed.</p>
@ -206,57 +206,57 @@ These changes are phrased as textual substitutions, listing the
algorithms to which each textual substitution applies.</p>
<p>Forward Iterator -&gt; Forward Traversal Iterator and Readable Iterator</p>
<blockquote>
<tt class="literal"><span class="pre">find_end,</span> <span class="pre">adjacent_find,</span> <span class="pre">search,</span> <span class="pre">search_n,</span> <span class="pre">rotate_copy,</span>
<tt class="docutils literal"><span class="pre">find_end,</span> <span class="pre">adjacent_find,</span> <span class="pre">search,</span> <span class="pre">search_n,</span> <span class="pre">rotate_copy,</span>
<span class="pre">lower_bound,</span> <span class="pre">upper_bound,</span> <span class="pre">equal_range,</span> <span class="pre">binary_search,</span>
<span class="pre">min_element,</span> <span class="pre">max_element</span></tt></blockquote>
<p>Forward Iterator (1) -&gt; Single Pass Iterator and Readable Iterator,
Forward Iterator (2) -&gt; Forward Traversal Iterator and Readable Iterator</p>
<blockquote>
<tt class="literal"><span class="pre">find_first_of</span></tt></blockquote>
<tt class="docutils literal"><span class="pre">find_first_of</span></tt></blockquote>
<p>Forward Iterator -&gt; Readable Iterator and Writable Iterator</p>
<blockquote>
<tt class="literal"><span class="pre">iter_swap</span></tt></blockquote>
<tt class="docutils literal"><span class="pre">iter_swap</span></tt></blockquote>
<p>Forward Iterator -&gt; Single Pass Iterator and Writable Iterator</p>
<blockquote>
<tt class="literal"><span class="pre">fill,</span> <span class="pre">generate</span></tt></blockquote>
<tt class="docutils literal"><span class="pre">fill,</span> <span class="pre">generate</span></tt></blockquote>
<p>Forward Iterator -&gt; Forward Traversal Iterator and Swappable Iterator</p>
<blockquote>
<tt class="literal"><span class="pre">rotate</span></tt></blockquote>
<tt class="docutils literal"><span class="pre">rotate</span></tt></blockquote>
<p>Forward Iterator (1) -&gt; Swappable Iterator and Single Pass Iterator,
Forward Iterator (2) -&gt; Swappable Iterator and Incrementable Iterator</p>
<blockquote>
<tt class="literal"><span class="pre">swap_ranges</span></tt></blockquote>
<dl>
<tt class="docutils literal"><span class="pre">swap_ranges</span></tt></blockquote>
<dl class="docutils">
<dt>Forward Iterator -&gt; Forward Traversal Iterator and Readable Iterator and Writable Iterator</dt>
<dd><tt class="literal"><span class="pre">remove,</span> <span class="pre">remove_if,</span> <span class="pre">unique</span></tt></dd>
<dd><tt class="docutils literal"><span class="pre">remove,</span> <span class="pre">remove_if,</span> <span class="pre">unique</span></tt></dd>
</dl>
<p>Forward Iterator -&gt; Single Pass Iterator and Readable Iterator and Writable Iterator</p>
<blockquote>
<tt class="literal"><span class="pre">replace,</span> <span class="pre">replace_if</span></tt></blockquote>
<dl>
<tt class="docutils literal"><span class="pre">replace,</span> <span class="pre">replace_if</span></tt></blockquote>
<dl class="docutils">
<dt>Bidirectional Iterator -&gt; Bidirectional Traversal Iterator and Swappable Iterator</dt>
<dd><tt class="literal"><span class="pre">reverse</span></tt></dd>
<dd><tt class="docutils literal"><span class="pre">reverse</span></tt></dd>
<dt>Bidirectional Iterator -&gt; Bidirectional Traversal Iterator and Readable and Swappable Iterator</dt>
<dd><tt class="literal"><span class="pre">partition</span></tt></dd>
<dd><tt class="docutils literal"><span class="pre">partition</span></tt></dd>
</dl>
<p>Bidirectional Iterator (1) -&gt; Bidirectional Traversal Iterator and Readable Iterator,
Bidirectional Iterator (2) -&gt; Bidirectional Traversal Iterator and Writable Iterator</p>
<blockquote>
<tt class="literal"><span class="pre">copy_backwards</span></tt></blockquote>
<dl>
<tt class="docutils literal"><span class="pre">copy_backwards</span></tt></blockquote>
<dl class="docutils">
<dt>Bidirectional Iterator -&gt; Bidirectional Traversal Iterator and Swappable Iterator and Readable Iterator</dt>
<dd><tt class="literal"><span class="pre">next_permutation,</span> <span class="pre">prev_permutation</span></tt></dd>
<dd><tt class="docutils literal"><span class="pre">next_permutation,</span> <span class="pre">prev_permutation</span></tt></dd>
<dt>Bidirectional Iterator -&gt; Bidirectional Traversal Iterator and Readable Iterator and Writable Iterator</dt>
<dd><tt class="literal"><span class="pre">stable_partition,</span> <span class="pre">inplace_merge</span></tt></dd>
<dd><tt class="docutils literal"><span class="pre">stable_partition,</span> <span class="pre">inplace_merge</span></tt></dd>
<dt>Bidirectional Iterator -&gt; Bidirectional Traversal Iterator and Readable Iterator</dt>
<dd><tt class="literal"><span class="pre">reverse_copy</span></tt></dd>
<dd><tt class="docutils literal"><span class="pre">reverse_copy</span></tt></dd>
<dt>Random Access Iterator -&gt; Random Access Traversal Iterator and Readable and Writable Iterator</dt>
<dd><tt class="literal"><span class="pre">random_shuffle,</span> <span class="pre">sort,</span> <span class="pre">stable_sort,</span> <span class="pre">partial_sort,</span> <span class="pre">nth_element,</span> <span class="pre">push_heap,</span> <span class="pre">pop_heap</span>
<dd><tt class="docutils literal"><span class="pre">random_shuffle,</span> <span class="pre">sort,</span> <span class="pre">stable_sort,</span> <span class="pre">partial_sort,</span> <span class="pre">nth_element,</span> <span class="pre">push_heap,</span> <span class="pre">pop_heap</span>
<span class="pre">make_heap,</span> <span class="pre">sort_heap</span></tt></dd>
<dt>Input Iterator (2) -&gt; Incrementable Iterator and Readable Iterator</dt>
<dd><tt class="literal"><span class="pre">equal,</span> <span class="pre">mismatch</span></tt></dd>
<dd><tt class="docutils literal"><span class="pre">equal,</span> <span class="pre">mismatch</span></tt></dd>
<dt>Input Iterator (2) -&gt; Incrementable Iterator and Readable Iterator</dt>
<dd><tt class="literal"><span class="pre">transform</span></tt></dd>
<dd><tt class="docutils literal"><span class="pre">transform</span></tt></dd>
</dl>
</div>
<div class="section" id="deprecations">
@ -267,9 +267,9 @@ std::iterator_traits, since it will be superceded by individual
traits metafunctions.</p>
</div>
<div class="section" id="vector-bool">
<h3><a class="toc-backref" href="#id6" name="vector-bool"><tt class="literal"><span class="pre">vector&lt;bool&gt;</span></tt></a></h3>
<h3><a class="toc-backref" href="#id6" name="vector-bool"><tt class="docutils literal"><span class="pre">vector&lt;bool&gt;</span></tt></a></h3>
<p>For the next working paper (but not for TR1), the committee should
consider reclassifying <tt class="literal"><span class="pre">vector&lt;bool&gt;::iterator</span></tt> as a Random
consider reclassifying <tt class="docutils literal"><span class="pre">vector&lt;bool&gt;::iterator</span></tt> as a Random
Access Traversal Iterator and Readable Iterator and Writable
Iterator.</p>
</div>
@ -285,9 +285,9 @@ of concepts handles the syntax and semantics of value access:</p>
<li>Swappable Iterator</li>
<li>Lvalue Iterator</li>
</ul>
<p>The access concepts describe requirements related to <tt class="literal"><span class="pre">operator*</span></tt> and
<tt class="literal"><span class="pre">operator-&gt;</span></tt>, including the <tt class="literal"><span class="pre">value_type</span></tt>, <tt class="literal"><span class="pre">reference</span></tt>, and
<tt class="literal"><span class="pre">pointer</span></tt> associated types.</p>
<p>The access concepts describe requirements related to <tt class="docutils literal"><span class="pre">operator*</span></tt> and
<tt class="docutils literal"><span class="pre">operator-&gt;</span></tt>, including the <tt class="docutils literal"><span class="pre">value_type</span></tt>, <tt class="docutils literal"><span class="pre">reference</span></tt>, and
<tt class="docutils literal"><span class="pre">pointer</span></tt> associated types.</p>
<p>The other set of concepts handles traversal:</p>
<ul class="simple">
<li>Incrementable Iterator</li>
@ -298,30 +298,30 @@ of concepts handles the syntax and semantics of value access:</p>
</ul>
<p>The refinement relationships for the traversal concepts are in the
following diagram.</p>
<p><img alt="traversal.png" src="traversal.png" /></p>
<div class="image"><img alt="traversal.png" src="traversal.png" /></div>
<p>In addition to the iterator movement operators, such as
<tt class="literal"><span class="pre">operator++</span></tt>, the traversal concepts also include requirements on
position comparison such as <tt class="literal"><span class="pre">operator==</span></tt> and <tt class="literal"><span class="pre">operator&lt;</span></tt>. The
<tt class="docutils literal"><span class="pre">operator++</span></tt>, the traversal concepts also include requirements on
position comparison such as <tt class="docutils literal"><span class="pre">operator==</span></tt> and <tt class="docutils literal"><span class="pre">operator&lt;</span></tt>. The
reason for the fine grain slicing of the concepts into the
Incrementable and Single Pass is to provide concepts that are exact
matches with the original input and output iterator requirements.</p>
<p>This proposal also includes a concept for specifying when an iterator
is interoperable with another iterator, in the sense that <tt class="literal"><span class="pre">int*</span></tt> is
interoperable with <tt class="literal"><span class="pre">int</span> <span class="pre">const*</span></tt>.</p>
is interoperable with another iterator, in the sense that <tt class="docutils literal"><span class="pre">int*</span></tt> is
interoperable with <tt class="docutils literal"><span class="pre">int</span> <span class="pre">const*</span></tt>.</p>
<ul class="simple">
<li>Interoperable Iterators</li>
</ul>
<p>The relationship between the new iterator concepts and the old are
given in the following diagram.</p>
<p><img alt="oldeqnew.png" src="oldeqnew.png" /></p>
<div class="image"><img alt="oldeqnew.png" src="oldeqnew.png" /></div>
<p>Like the old iterator requirements, we provide tags for purposes of
dispatching based on the traversal concepts. The tags are related via
inheritance so that a tag is convertible to another tag if the concept
associated with the first tag is a refinement of the second tag.</p>
<p>Our design reuses <tt class="literal"><span class="pre">iterator_traits&lt;Iter&gt;::iterator_category</span></tt> to
<p>Our design reuses <tt class="docutils literal"><span class="pre">iterator_traits&lt;Iter&gt;::iterator_category</span></tt> to
indicate an iterator's traversal capability. To specify
capabilities not captured by any old-style iterator category, an
iterator designer can use an <tt class="literal"><span class="pre">iterator_category</span></tt> type that is
iterator designer can use an <tt class="docutils literal"><span class="pre">iterator_category</span></tt> type that is
convertible to both the the most-derived old iterator category tag
which fits, and the appropriate new iterator traversal tag.</p>
<!-- dwa2003/1/2: Note that we are not *requiring* convertibility to
@ -331,20 +331,20 @@ Old-style iterators still fit, after all. -->
access concepts, in part because we could not find a way to
automatically infer the right access tags for old-style iterators.
An iterator's writability may be dependent on the assignability of
its <tt class="literal"><span class="pre">value_type</span></tt> and there's no known way to detect whether an
its <tt class="docutils literal"><span class="pre">value_type</span></tt> and there's no known way to detect whether an
arbitrary type is assignable. Fortunately, the need for
dispatching based on access capability is not as great as the need
for dispatching based on traversal capability.</p>
<p>A difficult design decision concerned the <tt class="literal"><span class="pre">operator[]</span></tt>. The direct
approach for specifying <tt class="literal"><span class="pre">operator[]</span></tt> would have a return type of
<tt class="literal"><span class="pre">reference</span></tt>; the same as <tt class="literal"><span class="pre">operator*</span></tt>. However, going in this
<p>A difficult design decision concerned the <tt class="docutils literal"><span class="pre">operator[]</span></tt>. The direct
approach for specifying <tt class="docutils literal"><span class="pre">operator[]</span></tt> would have a return type of
<tt class="docutils literal"><span class="pre">reference</span></tt>; the same as <tt class="docutils literal"><span class="pre">operator*</span></tt>. However, going in this
direction would mean that an iterator satisfying the old Random Access
Iterator requirements would not necessarily be a model of Readable or
Writable Lvalue Iterator. Instead we have chosen a design that
matches the preferred resolution of <a class="reference" href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/lwg-active.html#299">issue 299</a>: <tt class="literal"><span class="pre">operator[]</span></tt> is
only required to return something convertible to the <tt class="literal"><span class="pre">value_type</span></tt>
matches the preferred resolution of <a class="reference" href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/lwg-active.html#299">issue 299</a>: <tt class="docutils literal"><span class="pre">operator[]</span></tt> is
only required to return something convertible to the <tt class="docutils literal"><span class="pre">value_type</span></tt>
(for a Readable Iterator), and is required to support assignment
<tt class="literal"><span class="pre">i[n]</span> <span class="pre">=</span> <span class="pre">t</span></tt> (for a Writable Iterator).</p>
<tt class="docutils literal"><span class="pre">i[n]</span> <span class="pre">=</span> <span class="pre">t</span></tt> (for a Writable Iterator).</p>
</div>
<div class="section" id="proposed-text">
<h1><a class="toc-backref" href="#id8" name="proposed-text">Proposed Text</a></h1>
@ -352,19 +352,19 @@ only required to return something convertible to the <tt class="literal"><span c
<h2><a class="toc-backref" href="#id9" name="addition-to-lib-iterator-requirements">Addition to [lib.iterator.requirements]</a></h2>
<div class="section" id="iterator-value-access-concepts-lib-iterator-value-access">
<h3><a class="toc-backref" href="#id10" name="iterator-value-access-concepts-lib-iterator-value-access">Iterator Value Access Concepts [lib.iterator.value.access]</a></h3>
<p>In the tables below, <tt class="literal"><span class="pre">X</span></tt> is an iterator type, <tt class="literal"><span class="pre">a</span></tt> is a constant
object of type <tt class="literal"><span class="pre">X</span></tt>, <tt class="literal"><span class="pre">R</span></tt> is
<tt class="literal"><span class="pre">std::iterator_traits&lt;X&gt;::reference</span></tt>, <tt class="literal"><span class="pre">T</span></tt> is
<tt class="literal"><span class="pre">std::iterator_traits&lt;X&gt;::value_type</span></tt>, and <tt class="literal"><span class="pre">v</span></tt> is a constant
object of type <tt class="literal"><span class="pre">T</span></tt>.</p>
<p>In the tables below, <tt class="docutils literal"><span class="pre">X</span></tt> is an iterator type, <tt class="docutils literal"><span class="pre">a</span></tt> is a constant
object of type <tt class="docutils literal"><span class="pre">X</span></tt>, <tt class="docutils literal"><span class="pre">R</span></tt> is
<tt class="docutils literal"><span class="pre">std::iterator_traits&lt;X&gt;::reference</span></tt>, <tt class="docutils literal"><span class="pre">T</span></tt> is
<tt class="docutils literal"><span class="pre">std::iterator_traits&lt;X&gt;::value_type</span></tt>, and <tt class="docutils literal"><span class="pre">v</span></tt> is a constant
object of type <tt class="docutils literal"><span class="pre">T</span></tt>.</p>
<a class="target" id="readable-iterator" name="readable-iterator"></a><div class="section" id="readable-iterators-lib-readable-iterators">
<h4><a class="toc-backref" href="#id11" name="readable-iterators-lib-readable-iterators">Readable Iterators [lib.readable.iterators]</a></h4>
<p>A class or built-in type <tt class="literal"><span class="pre">X</span></tt> models the <em>Readable Iterator</em> concept
for value type <tt class="literal"><span class="pre">T</span></tt> if, in addition to <tt class="literal"><span class="pre">X</span></tt> being Assignable and
<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> models the <em>Readable Iterator</em> concept
for value type <tt class="docutils literal"><span class="pre">T</span></tt> if, in addition to <tt class="docutils literal"><span class="pre">X</span></tt> being Assignable and
Copy Constructible, the following expressions are valid and 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>
<table border="1" class="table">
the stated semantics. <tt class="docutils literal"><span class="pre">U</span></tt> is the type of any specified member of
type <tt class="docutils literal"><span class="pre">T</span></tt>.</p>
<table border="1" class="docutils">
<colgroup>
<col width="28%" />
<col width="20%" />
@ -379,22 +379,22 @@ type <tt class="literal"><span class="pre">T</span></tt>.</p>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="literal"><span class="pre">iterator_traits&lt;X&gt;::value_type</span></tt></td>
<td><tt class="literal"><span class="pre">T</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">iterator_traits&lt;X&gt;::value_type</span></tt></td>
<td><tt class="docutils literal"><span class="pre">T</span></tt></td>
<td>Any non-reference,
non-cv-qualified type</td>
</tr>
<tr><td><tt class="literal"><span class="pre">*a</span></tt></td>
<td>Convertible to <tt class="literal"><span class="pre">T</span></tt></td>
<td><dl class="first last">
<dt>pre: <tt class="literal"><span class="pre">a</span></tt> is dereferenceable. If <tt class="literal"><span class="pre">a</span> <span class="pre">==</span> <span class="pre">b</span></tt> then <tt class="literal"><span class="pre">*a</span></tt></dt>
<dd>is equivalent to <tt class="literal"><span class="pre">*b</span></tt>.</dd>
<tr><td><tt class="docutils literal"><span class="pre">*a</span></tt></td>
<td>Convertible to <tt class="docutils literal"><span class="pre">T</span></tt></td>
<td><dl class="first last docutils">
<dt>pre: <tt class="docutils literal"><span class="pre">a</span></tt> is dereferenceable. If <tt class="docutils literal"><span class="pre">a</span> <span class="pre">==</span> <span class="pre">b</span></tt> then <tt class="docutils literal"><span class="pre">*a</span></tt></dt>
<dd>is equivalent to <tt class="docutils literal"><span class="pre">*b</span></tt>.</dd>
</dl>
</td>
</tr>
<tr><td><tt class="literal"><span class="pre">a-&gt;m</span></tt></td>
<td><tt class="literal"><span class="pre">U&amp;</span></tt></td>
<td>pre: <tt class="literal"><span class="pre">pre:</span> <span class="pre">(*a).m</span></tt> is well-defined. Equivalent to <tt class="literal"><span class="pre">(*a).m</span></tt>.</td>
<tr><td><tt class="docutils literal"><span class="pre">a-&gt;m</span></tt></td>
<td><tt class="docutils literal"><span class="pre">U&amp;</span></tt></td>
<td>pre: <tt class="docutils literal"><span class="pre">pre:</span> <span class="pre">(*a).m</span></tt> is well-defined. Equivalent to <tt class="docutils literal"><span class="pre">(*a).m</span></tt>.</td>
</tr>
</tbody>
</table>
@ -402,11 +402,11 @@ non-cv-qualified type</td>
<a class="target" id="writable-iterator" name="writable-iterator"></a></div>
<div class="section" id="writable-iterators-lib-writable-iterators">
<h4><a class="toc-backref" href="#id12" name="writable-iterators-lib-writable-iterators">Writable Iterators [lib.writable.iterators]</a></h4>
<p>A class or built-in type <tt class="literal"><span class="pre">X</span></tt> models the <em>Writable Iterator</em> concept
if, in addition to <tt class="literal"><span class="pre">X</span></tt> being Copy Constructible, the following
<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> models the <em>Writable Iterator</em> concept
if, in addition to <tt class="docutils literal"><span class="pre">X</span></tt> being Copy Constructible, the following
expressions are valid and respect the stated semantics. Writable
Iterators have an associated <em>set of value types</em>.</p>
<table border="1" class="table">
<table border="1" class="docutils">
<colgroup>
<col width="37%" />
<col width="21%" />
@ -421,21 +421,21 @@ Iterators have an associated <em>set of value types</em>.</p>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="literal"><span class="pre">*a</span> <span class="pre">=</span> <span class="pre">o</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">*a</span> <span class="pre">=</span> <span class="pre">o</span></tt></td>
<td>&nbsp;</td>
<td>pre: The type of <tt class="literal"><span class="pre">o</span></tt>
<td>pre: The type of <tt class="docutils literal"><span class="pre">o</span></tt>
is in the set of
value types of <tt class="literal"><span class="pre">X</span></tt></td>
value types of <tt class="docutils literal"><span class="pre">X</span></tt></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="swappable-iterators-lib-swappable-iterators">
<h4><a class="toc-backref" href="#id13" name="swappable-iterators-lib-swappable-iterators">Swappable Iterators [lib.swappable.iterators]</a></h4>
<p>A class or built-in type <tt class="literal"><span class="pre">X</span></tt> models the <em>Swappable Iterator</em> concept
if, in addition to <tt class="literal"><span class="pre">X</span></tt> being Copy Constructible, the following
<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> models the <em>Swappable Iterator</em> concept
if, in addition to <tt class="docutils literal"><span class="pre">X</span></tt> being Copy Constructible, the following
expressions are valid and respect the stated semantics.</p>
<table border="1" class="table">
<table border="1" class="docutils">
<colgroup>
<col width="37%" />
<col width="19%" />
@ -450,8 +450,8 @@ expressions are valid and respect the stated semantics.</p>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="literal"><span class="pre">iter_swap(a,</span> <span class="pre">b)</span></tt></td>
<td><tt class="literal"><span class="pre">void</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">iter_swap(a,</span> <span class="pre">b)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">void</span></tt></td>
<td>the pointed to values are
exchanged</td>
</tr>
@ -464,9 +464,9 @@ Iterator</em>. <em>--end note</em>]</p>
<div class="section" id="lvalue-iterators-lib-lvalue-iterators">
<h4><a class="toc-backref" href="#id14" name="lvalue-iterators-lib-lvalue-iterators">Lvalue Iterators [lib.lvalue.iterators]</a></h4>
<p>The <em>Lvalue Iterator</em> concept adds the requirement that the return
type of <tt class="literal"><span class="pre">operator*</span></tt> type be a reference to the value type of the
type of <tt class="docutils literal"><span class="pre">operator*</span></tt> type be a reference to the value type of the
iterator.</p>
<table border="1" class="table">
<table border="1" class="docutils">
<colgroup>
<col width="22%" />
<col width="19%" />
@ -481,35 +481,35 @@ iterator.</p>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="literal"><span class="pre">*a</span></tt></td>
<td><tt class="literal"><span class="pre">T&amp;</span></tt></td>
<td><tt class="literal"><span class="pre">T</span></tt> is <em>cv</em>
<tt class="literal"><span class="pre">iterator_traits&lt;X&gt;::value_type</span></tt>
<tr><td><tt class="docutils literal"><span class="pre">*a</span></tt></td>
<td><tt class="docutils literal"><span class="pre">T&amp;</span></tt></td>
<td><tt class="docutils literal"><span class="pre">T</span></tt> is <em>cv</em>
<tt class="docutils literal"><span class="pre">iterator_traits&lt;X&gt;::value_type</span></tt>
where <em>cv</em> is an optional
cv-qualification. pre: <tt class="literal"><span class="pre">a</span></tt> is
cv-qualification. pre: <tt class="docutils literal"><span class="pre">a</span></tt> is
dereferenceable.</td>
</tr>
</tbody>
</table>
<p>If <tt class="literal"><span class="pre">X</span></tt> is a <a class="reference" href="#writable-iterator">Writable Iterator</a> then <tt class="literal"><span class="pre">a</span> <span class="pre">==</span> <span class="pre">b</span></tt> if and only if
<tt class="literal"><span class="pre">*a</span></tt> is the same object as <tt class="literal"><span class="pre">*b</span></tt>. If <tt class="literal"><span class="pre">X</span></tt> is a <a class="reference" href="#readable-iterator">Readable
Iterator</a> then <tt class="literal"><span class="pre">a</span> <span class="pre">==</span> <span class="pre">b</span></tt> implies <tt class="literal"><span class="pre">*a</span></tt> is the same object as
<tt class="literal"><span class="pre">*b</span></tt>.</p>
<p>If <tt class="docutils literal"><span class="pre">X</span></tt> is a <a class="reference" href="#writable-iterator">Writable Iterator</a> then <tt class="docutils literal"><span class="pre">a</span> <span class="pre">==</span> <span class="pre">b</span></tt> if and only if
<tt class="docutils literal"><span class="pre">*a</span></tt> is the same object as <tt class="docutils literal"><span class="pre">*b</span></tt>. If <tt class="docutils literal"><span class="pre">X</span></tt> is a <a class="reference" href="#readable-iterator">Readable
Iterator</a> then <tt class="docutils literal"><span class="pre">a</span> <span class="pre">==</span> <span class="pre">b</span></tt> implies <tt class="docutils literal"><span class="pre">*a</span></tt> is the same object as
<tt class="docutils literal"><span class="pre">*b</span></tt>.</p>
</div>
</div>
<div class="section" id="iterator-traversal-concepts-lib-iterator-traversal">
<h3><a class="toc-backref" href="#id15" name="iterator-traversal-concepts-lib-iterator-traversal">Iterator Traversal Concepts [lib.iterator.traversal]</a></h3>
<p>In the tables below, <tt class="literal"><span class="pre">X</span></tt> is an iterator type, <tt class="literal"><span class="pre">a</span></tt> and <tt class="literal"><span class="pre">b</span></tt> are
constant objects of type <tt class="literal"><span class="pre">X</span></tt>, <tt class="literal"><span class="pre">r</span></tt> and <tt class="literal"><span class="pre">s</span></tt> are mutable objects of
type <tt class="literal"><span class="pre">X</span></tt>, <tt class="literal"><span class="pre">T</span></tt> is <tt class="literal"><span class="pre">std::iterator_traits&lt;X&gt;::value_type</span></tt>, and
<tt class="literal"><span class="pre">v</span></tt> is a constant object of type <tt class="literal"><span class="pre">T</span></tt>.</p>
<p>In the tables below, <tt class="docutils literal"><span class="pre">X</span></tt> is an iterator type, <tt class="docutils literal"><span class="pre">a</span></tt> and <tt class="docutils literal"><span class="pre">b</span></tt> are
constant objects of type <tt class="docutils literal"><span class="pre">X</span></tt>, <tt class="docutils literal"><span class="pre">r</span></tt> and <tt class="docutils literal"><span class="pre">s</span></tt> are mutable objects of
type <tt class="docutils literal"><span class="pre">X</span></tt>, <tt class="docutils literal"><span class="pre">T</span></tt> is <tt class="docutils literal"><span class="pre">std::iterator_traits&lt;X&gt;::value_type</span></tt>, and
<tt class="docutils literal"><span class="pre">v</span></tt> is a constant object of type <tt class="docutils literal"><span class="pre">T</span></tt>.</p>
<div class="section" id="incrementable-iterators-lib-incrementable-iterators">
<h4><a class="toc-backref" href="#id16" name="incrementable-iterators-lib-incrementable-iterators">Incrementable Iterators [lib.incrementable.iterators]</a></h4>
<p>A class or built-in type <tt class="literal"><span class="pre">X</span></tt> models the <em>Incrementable Iterator</em>
concept if, in addition to <tt class="literal"><span class="pre">X</span></tt> being Assignable and Copy
<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> models the <em>Incrementable Iterator</em>
concept if, in addition to <tt class="docutils literal"><span class="pre">X</span></tt> being Assignable and Copy
Constructible, the following expressions are valid and respect the
stated semantics.</p>
<table border="1" class="table">
<table border="1" class="docutils">
<colgroup>
<col width="39%" />
<col width="38%" />
@ -524,39 +524,39 @@ stated semantics.</p>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="literal"><span class="pre">++r</span></tt></td>
<td><tt class="literal"><span class="pre">X&amp;</span></tt></td>
<td><tt class="literal"><span class="pre">&amp;r</span> <span class="pre">==</span> <span class="pre">&amp;++r</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">++r</span></tt></td>
<td><tt class="docutils literal"><span class="pre">X&amp;</span></tt></td>
<td><tt class="docutils literal"><span class="pre">&amp;r</span> <span class="pre">==</span> <span class="pre">&amp;++r</span></tt></td>
</tr>
<tr><td><tt class="literal"><span class="pre">r++</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">r++</span></tt></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="literal"><span class="pre">*r++</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">*r++</span></tt></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt></td>
<td>Convertible to
<tt class="literal"><span class="pre">incrementable_traversal_tag</span></tt></td>
<tt class="docutils literal"><span class="pre">incrementable_traversal_tag</span></tt></td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<p>If <tt class="literal"><span class="pre">X</span></tt> is a <a class="reference" href="#writable-iterator">Writable Iterator</a> then <tt class="literal"><span class="pre">X</span> <span class="pre">a(r++);</span></tt> is equivalent
to <tt class="literal"><span class="pre">X</span> <span class="pre">a(r);</span> <span class="pre">++r;</span></tt> and <tt class="literal"><span class="pre">*r++</span> <span class="pre">=</span> <span class="pre">o</span></tt> is equivalent
to <tt class="literal"><span class="pre">*r</span> <span class="pre">=</span> <span class="pre">o;</span> <span class="pre">++r</span></tt>.
If <tt class="literal"><span class="pre">X</span></tt> is a <a class="reference" href="#readable-iterator">Readable Iterator</a> then <tt class="literal"><span class="pre">T</span> <span class="pre">z(*r++);</span></tt> is equivalent
to <tt class="literal"><span class="pre">T</span> <span class="pre">z(*r);</span> <span class="pre">++r;</span></tt>.</p>
<p>If <tt class="docutils literal"><span class="pre">X</span></tt> is a <a class="reference" href="#writable-iterator">Writable Iterator</a> then <tt class="docutils literal"><span class="pre">X</span> <span class="pre">a(r++);</span></tt> is equivalent
to <tt class="docutils literal"><span class="pre">X</span> <span class="pre">a(r);</span> <span class="pre">++r;</span></tt> and <tt class="docutils literal"><span class="pre">*r++</span> <span class="pre">=</span> <span class="pre">o</span></tt> is equivalent
to <tt class="docutils literal"><span class="pre">*r</span> <span class="pre">=</span> <span class="pre">o;</span> <span class="pre">++r</span></tt>.
If <tt class="docutils literal"><span class="pre">X</span></tt> is a <a class="reference" href="#readable-iterator">Readable Iterator</a> then <tt class="docutils literal"><span class="pre">T</span> <span class="pre">z(*r++);</span></tt> is equivalent
to <tt class="docutils literal"><span class="pre">T</span> <span class="pre">z(*r);</span> <span class="pre">++r;</span></tt>.</p>
<!-- TR1: incrementable_iterator_tag changed to
incrementable_traversal_tag for consistency. -->
</div>
<div class="section" id="single-pass-iterators-lib-single-pass-iterators">
<h4><a class="toc-backref" href="#id17" name="single-pass-iterators-lib-single-pass-iterators">Single Pass Iterators [lib.single.pass.iterators]</a></h4>
<p>A class or built-in type <tt class="literal"><span class="pre">X</span></tt> models the <em>Single Pass Iterator</em>
<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> models the <em>Single Pass Iterator</em>
concept if the following expressions are valid and respect the stated
semantics.</p>
<table border="1" class="table">
<table border="1" class="docutils">
<colgroup>
<col width="32%" />
<col width="29%" />
@ -576,28 +576,28 @@ Pre-/Post-condition</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="literal"><span class="pre">++r</span></tt></td>
<td><tt class="literal"><span class="pre">X&amp;</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">++r</span></tt></td>
<td><tt class="docutils literal"><span class="pre">X&amp;</span></tt></td>
<td>&nbsp;</td>
<td>pre: <tt class="literal"><span class="pre">r</span></tt> is
<td>pre: <tt class="docutils literal"><span class="pre">r</span></tt> is
dereferenceable; post:
<tt class="literal"><span class="pre">r</span></tt> is dereferenceable or
<tt class="literal"><span class="pre">r</span></tt> is past-the-end</td>
<tt class="docutils literal"><span class="pre">r</span></tt> is dereferenceable or
<tt class="docutils literal"><span class="pre">r</span></tt> is past-the-end</td>
</tr>
<tr><td><tt class="literal"><span class="pre">a</span> <span class="pre">==</span> <span class="pre">b</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">a</span> <span class="pre">==</span> <span class="pre">b</span></tt></td>
<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
<td>&nbsp;</td>
<td><tt class="literal"><span class="pre">==</span></tt> is an equivalence
<td><tt class="docutils literal"><span class="pre">==</span></tt> is an equivalence
relation over its domain</td>
</tr>
<tr><td><tt class="literal"><span class="pre">a</span> <span class="pre">!=</span> <span class="pre">b</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">!(a</span> <span class="pre">==</span> <span class="pre">b)</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">a</span> <span class="pre">!=</span> <span class="pre">b</span></tt></td>
<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
<td><tt class="docutils literal"><span class="pre">!(a</span> <span class="pre">==</span> <span class="pre">b)</span></tt></td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt></td>
<td>Convertible to
<tt class="literal"><span class="pre">single_pass_traversal_tag</span></tt></td>
<tt class="docutils literal"><span class="pre">single_pass_traversal_tag</span></tt></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
@ -608,11 +608,11 @@ single_pass_traversal_tag for consistency -->
</div>
<div class="section" id="forward-traversal-iterators-lib-forward-traversal-iterators">
<h4><a class="toc-backref" href="#id18" name="forward-traversal-iterators-lib-forward-traversal-iterators">Forward Traversal Iterators [lib.forward.traversal.iterators]</a></h4>
<p>A class or built-in type <tt class="literal"><span class="pre">X</span></tt> models the <em>Forward Traversal Iterator</em>
concept if, in addition to <tt class="literal"><span class="pre">X</span></tt> meeting the requirements of Default
<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> models the <em>Forward Traversal Iterator</em>
concept if, in addition to <tt class="docutils literal"><span class="pre">X</span></tt> meeting the requirements of Default
Constructible and Single Pass Iterator, the following expressions are
valid and respect the stated semantics.</p>
<table border="1" class="table">
<table border="1" class="docutils">
<colgroup>
<col width="38%" />
<col width="34%" />
@ -627,25 +627,25 @@ valid and respect the stated semantics.</p>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="literal"><span class="pre">X</span> <span class="pre">u;</span></tt></td>
<td><tt class="literal"><span class="pre">X&amp;</span></tt></td>
<td>note: <tt class="literal"><span class="pre">u</span></tt> may have a
<tr><td><tt class="docutils literal"><span class="pre">X</span> <span class="pre">u;</span></tt></td>
<td><tt class="docutils literal"><span class="pre">X&amp;</span></tt></td>
<td>note: <tt class="docutils literal"><span class="pre">u</span></tt> may have a
singular value.</td>
</tr>
<tr><td><tt class="literal"><span class="pre">++r</span></tt></td>
<td><tt class="literal"><span class="pre">X&amp;</span></tt></td>
<td><tt class="literal"><span class="pre">r</span> <span class="pre">==</span> <span class="pre">s</span></tt> and <tt class="literal"><span class="pre">r</span></tt> is
<tr><td><tt class="docutils literal"><span class="pre">++r</span></tt></td>
<td><tt class="docutils literal"><span class="pre">X&amp;</span></tt></td>
<td><tt class="docutils literal"><span class="pre">r</span> <span class="pre">==</span> <span class="pre">s</span></tt> and <tt class="docutils literal"><span class="pre">r</span></tt> is
dereferenceable implies
<tt class="literal"><span class="pre">++r</span> <span class="pre">==</span> <span class="pre">++s.</span></tt></td>
<tt class="docutils literal"><span class="pre">++r</span> <span class="pre">==</span> <span class="pre">++s.</span></tt></td>
</tr>
<tr><td><tt class="literal"><span class="pre">iterator_traits&lt;X&gt;::difference_type</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">iterator_traits&lt;X&gt;::difference_type</span></tt></td>
<td>A signed integral type representing
the distance between iterators</td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt></td>
<td>Convertible to
<tt class="literal"><span class="pre">forward_traversal_tag</span></tt></td>
<tt class="docutils literal"><span class="pre">forward_traversal_tag</span></tt></td>
<td>&nbsp;</td>
</tr>
</tbody>
@ -655,11 +655,11 @@ forward_traversal_tag for consistency -->
</div>
<div class="section" id="bidirectional-traversal-iterators-lib-bidirectional-traversal-iterators">
<h4><a class="toc-backref" href="#id19" name="bidirectional-traversal-iterators-lib-bidirectional-traversal-iterators">Bidirectional Traversal Iterators [lib.bidirectional.traversal.iterators]</a></h4>
<p>A class or built-in type <tt class="literal"><span class="pre">X</span></tt> models the <em>Bidirectional Traversal
Iterator</em> concept if, in addition to <tt class="literal"><span class="pre">X</span></tt> meeting the requirements of
<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> models the <em>Bidirectional Traversal
Iterator</em> concept if, in addition to <tt class="docutils literal"><span class="pre">X</span></tt> meeting the requirements of
Forward Traversal Iterator, the following expressions are valid and
respect the stated semantics.</p>
<table border="1" class="table">
<table border="1" class="docutils">
<colgroup>
<col width="33%" />
<col width="32%" />
@ -679,22 +679,22 @@ Pre-/Post-condition</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="literal"><span class="pre">--r</span></tt></td>
<td><tt class="literal"><span class="pre">X&amp;</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">--r</span></tt></td>
<td><tt class="docutils literal"><span class="pre">X&amp;</span></tt></td>
<td>&nbsp;</td>
<td><p class="first">pre: there exists
<tt class="literal"><span class="pre">s</span></tt> such that <tt class="literal"><span class="pre">r</span>
<tt class="docutils literal"><span class="pre">s</span></tt> such that <tt class="docutils literal"><span class="pre">r</span>
<span class="pre">==</span> <span class="pre">++s</span></tt>. post:
<tt class="literal"><span class="pre">s</span></tt> is
<tt class="docutils literal"><span class="pre">s</span></tt> is
dereferenceable.</p>
<p class="last"><tt class="literal"><span class="pre">++(--r)</span> <span class="pre">==</span> <span class="pre">r</span></tt>.
<tt class="literal"><span class="pre">--r</span> <span class="pre">==</span> <span class="pre">--s</span></tt>
implies <tt class="literal"><span class="pre">r</span> <span class="pre">==</span>
<span class="pre">s</span></tt>. <tt class="literal"><span class="pre">&amp;r</span> <span class="pre">==</span> <span class="pre">&amp;--r</span></tt>.</p>
<p class="last"><tt class="docutils literal"><span class="pre">++(--r)</span> <span class="pre">==</span> <span class="pre">r</span></tt>.
<tt class="docutils literal"><span class="pre">--r</span> <span class="pre">==</span> <span class="pre">--s</span></tt>
implies <tt class="docutils literal"><span class="pre">r</span> <span class="pre">==</span>
<span class="pre">s</span></tt>. <tt class="docutils literal"><span class="pre">&amp;r</span> <span class="pre">==</span> <span class="pre">&amp;--r</span></tt>.</p>
</td>
</tr>
<tr><td><tt class="literal"><span class="pre">r--</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">const</span> <span class="pre">X&amp;</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">r--</span></tt></td>
<td>convertible to <tt class="docutils literal"><span class="pre">const</span> <span class="pre">X&amp;</span></tt></td>
<td><pre class="first last literal-block">
{
X tmp = r;
@ -705,9 +705,9 @@ implies <tt class="literal"><span class="pre">r</span> <span class="pre">==</spa
</td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt></td>
<td>Convertible to
<tt class="literal"><span class="pre">bidirectional_traversal_tag</span></tt></td>
<tt class="docutils literal"><span class="pre">bidirectional_traversal_tag</span></tt></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
@ -718,12 +718,12 @@ bidirectional_traversal_tag for consistency -->
</div>
<div class="section" id="random-access-traversal-iterators-lib-random-access-traversal-iterators">
<h4><a class="toc-backref" href="#id20" name="random-access-traversal-iterators-lib-random-access-traversal-iterators">Random Access Traversal Iterators [lib.random.access.traversal.iterators]</a></h4>
<p>A class or built-in type <tt class="literal"><span class="pre">X</span></tt> models the <em>Random Access Traversal
<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> models the <em>Random Access Traversal
Iterator</em> concept if the following expressions are valid and respect
the stated semantics. In the table below, <tt class="literal"><span class="pre">Distance</span></tt> is
<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>
<table border="1" class="table">
the stated semantics. In the table below, <tt class="docutils literal"><span class="pre">Distance</span></tt> is
<tt class="docutils literal"><span class="pre">iterator_traits&lt;X&gt;::difference_type</span></tt> and <tt class="docutils literal"><span class="pre">n</span></tt> represents a
constant object of type <tt class="docutils literal"><span class="pre">Distance</span></tt>.</p>
<table border="1" class="docutils">
<colgroup>
<col width="28%" />
<col width="30%" />
@ -741,8 +741,8 @@ Precondition</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="literal"><span class="pre">r</span> <span class="pre">+=</span> <span class="pre">n</span></tt></td>
<td><tt class="literal"><span class="pre">X&amp;</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">r</span> <span class="pre">+=</span> <span class="pre">n</span></tt></td>
<td><tt class="docutils literal"><span class="pre">X&amp;</span></tt></td>
<td><pre class="first last literal-block">
{
Distance m = n;
@ -758,70 +758,70 @@ Precondition</th>
</td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="literal"><span class="pre">a</span> <span class="pre">+</span> <span class="pre">n</span></tt>, <tt class="literal"><span class="pre">n</span> <span class="pre">+</span> <span class="pre">a</span></tt></td>
<td><tt class="literal"><span class="pre">X</span></tt></td>
<td><tt class="literal"><span class="pre">{</span> <span class="pre">X</span> <span class="pre">tmp</span> <span class="pre">=</span> <span class="pre">a;</span> <span class="pre">return</span> <span class="pre">tmp</span>
<tr><td><tt class="docutils literal"><span class="pre">a</span> <span class="pre">+</span> <span class="pre">n</span></tt>, <tt class="docutils literal"><span class="pre">n</span> <span class="pre">+</span> <span class="pre">a</span></tt></td>
<td><tt class="docutils literal"><span class="pre">X</span></tt></td>
<td><tt class="docutils literal"><span class="pre">{</span> <span class="pre">X</span> <span class="pre">tmp</span> <span class="pre">=</span> <span class="pre">a;</span> <span class="pre">return</span> <span class="pre">tmp</span>
<span class="pre">+=</span> <span class="pre">n;</span> <span class="pre">}</span></tt></td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="literal"><span class="pre">r</span> <span class="pre">-=</span> <span class="pre">n</span></tt></td>
<td><tt class="literal"><span class="pre">X&amp;</span></tt></td>
<td><tt class="literal"><span class="pre">return</span> <span class="pre">r</span> <span class="pre">+=</span> <span class="pre">-n</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">r</span> <span class="pre">-=</span> <span class="pre">n</span></tt></td>
<td><tt class="docutils literal"><span class="pre">X&amp;</span></tt></td>
<td><tt class="docutils literal"><span class="pre">return</span> <span class="pre">r</span> <span class="pre">+=</span> <span class="pre">-n</span></tt></td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="literal"><span class="pre">a</span> <span class="pre">-</span> <span class="pre">n</span></tt></td>
<td><tt class="literal"><span class="pre">X</span></tt></td>
<td><tt class="literal"><span class="pre">{</span> <span class="pre">X</span> <span class="pre">tmp</span> <span class="pre">=</span> <span class="pre">a;</span> <span class="pre">return</span> <span class="pre">tmp</span>
<tr><td><tt class="docutils literal"><span class="pre">a</span> <span class="pre">-</span> <span class="pre">n</span></tt></td>
<td><tt class="docutils literal"><span class="pre">X</span></tt></td>
<td><tt class="docutils literal"><span class="pre">{</span> <span class="pre">X</span> <span class="pre">tmp</span> <span class="pre">=</span> <span class="pre">a;</span> <span class="pre">return</span> <span class="pre">tmp</span>
<span class="pre">-=</span> <span class="pre">n;</span> <span class="pre">}</span></tt></td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="literal"><span class="pre">b</span> <span class="pre">-</span> <span class="pre">a</span></tt></td>
<td><tt class="literal"><span class="pre">Distance</span></tt></td>
<td><tt class="literal"><span class="pre">a</span> <span class="pre">&lt;</span> <span class="pre">b</span> <span class="pre">?</span>&nbsp; <span class="pre">distance(a,b)</span>
<tr><td><tt class="docutils literal"><span class="pre">b</span> <span class="pre">-</span> <span class="pre">a</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Distance</span></tt></td>
<td><tt class="docutils literal"><span class="pre">a</span> <span class="pre">&lt;</span> <span class="pre">b</span> <span class="pre">?</span>&nbsp; <span class="pre">distance(a,b)</span>
<span class="pre">:</span> <span class="pre">-distance(b,a)</span></tt></td>
<td>pre: there exists a
value <tt class="literal"><span class="pre">n</span></tt> of
<tt class="literal"><span class="pre">Distance</span></tt> such that
<tt class="literal"><span class="pre">a</span> <span class="pre">+</span> <span class="pre">n</span> <span class="pre">==</span> <span class="pre">b</span></tt>. <tt class="literal"><span class="pre">b</span>
value <tt class="docutils literal"><span class="pre">n</span></tt> of
<tt class="docutils literal"><span class="pre">Distance</span></tt> such that
<tt class="docutils literal"><span class="pre">a</span> <span class="pre">+</span> <span class="pre">n</span> <span class="pre">==</span> <span class="pre">b</span></tt>. <tt class="docutils literal"><span class="pre">b</span>
<span class="pre">==</span> <span class="pre">a</span> <span class="pre">+</span> <span class="pre">(b</span> <span class="pre">-</span> <span class="pre">a)</span></tt>.</td>
</tr>
<tr><td><tt class="literal"><span class="pre">a[n]</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">a[n]</span></tt></td>
<td>convertible to T</td>
<td><tt class="literal"><span class="pre">*(a</span> <span class="pre">+</span> <span class="pre">n)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">*(a</span> <span class="pre">+</span> <span class="pre">n)</span></tt></td>
<td>pre: a is a <a class="reference" href="#readable-iterator">Readable
Iterator</a></td>
</tr>
<tr><td><tt class="literal"><span class="pre">a[n]</span> <span class="pre">=</span> <span class="pre">v</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">a[n]</span> <span class="pre">=</span> <span class="pre">v</span></tt></td>
<td>convertible to T</td>
<td><tt class="literal"><span class="pre">*(a</span> <span class="pre">+</span> <span class="pre">n)</span> <span class="pre">=</span> <span class="pre">v</span></tt></td>
<td><tt class="docutils literal"><span class="pre">*(a</span> <span class="pre">+</span> <span class="pre">n)</span> <span class="pre">=</span> <span class="pre">v</span></tt></td>
<td>pre: a is a <a class="reference" href="#writable-iterator">Writable
Iterator</a></td>
</tr>
<tr><td><tt class="literal"><span class="pre">a</span> <span class="pre">&lt;</span> <span class="pre">b</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">b</span> <span class="pre">-</span> <span class="pre">a</span> <span class="pre">&gt;</span> <span class="pre">0</span></tt></td>
<td><tt class="literal"><span class="pre">&lt;</span></tt> is a total
<tr><td><tt class="docutils literal"><span class="pre">a</span> <span class="pre">&lt;</span> <span class="pre">b</span></tt></td>
<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
<td><tt class="docutils literal"><span class="pre">b</span> <span class="pre">-</span> <span class="pre">a</span> <span class="pre">&gt;</span> <span class="pre">0</span></tt></td>
<td><tt class="docutils literal"><span class="pre">&lt;</span></tt> is a total
ordering relation</td>
</tr>
<tr><td><tt class="literal"><span class="pre">a</span> <span class="pre">&gt;</span> <span class="pre">b</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">b</span> <span class="pre">&lt;</span> <span class="pre">a</span></tt></td>
<td><tt class="literal"><span class="pre">&gt;</span></tt> is a total
<tr><td><tt class="docutils literal"><span class="pre">a</span> <span class="pre">&gt;</span> <span class="pre">b</span></tt></td>
<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
<td><tt class="docutils literal"><span class="pre">b</span> <span class="pre">&lt;</span> <span class="pre">a</span></tt></td>
<td><tt class="docutils literal"><span class="pre">&gt;</span></tt> is a total
ordering relation</td>
</tr>
<tr><td><tt class="literal"><span class="pre">a</span> <span class="pre">&gt;=</span> <span class="pre">b</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">!(a</span> <span class="pre">&lt;</span> <span class="pre">b)</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">a</span> <span class="pre">&gt;=</span> <span class="pre">b</span></tt></td>
<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
<td><tt class="docutils literal"><span class="pre">!(a</span> <span class="pre">&lt;</span> <span class="pre">b)</span></tt></td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="literal"><span class="pre">a</span> <span class="pre">&lt;=</span> <span class="pre">b</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">!(a</span> <span class="pre">&gt;</span> <span class="pre">b)</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">a</span> <span class="pre">&lt;=</span> <span class="pre">b</span></tt></td>
<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
<td><tt class="docutils literal"><span class="pre">!(a</span> <span class="pre">&gt;</span> <span class="pre">b)</span></tt></td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt></td>
<td>Convertible to
<tt class="literal"><span class="pre">random_access_traversal_tag</span></tt></td>
<tt class="docutils literal"><span class="pre">random_access_traversal_tag</span></tt></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
@ -832,14 +832,14 @@ random_access_traversal_tag for consistency -->
</div>
<div class="section" id="interoperable-iterators-lib-interoperable-iterators">
<h4><a class="toc-backref" href="#id21" name="interoperable-iterators-lib-interoperable-iterators">Interoperable Iterators [lib.interoperable.iterators]</a></h4>
<p>A class or built-in type <tt class="literal"><span class="pre">X</span></tt> that models Single Pass Iterator is
<em>interoperable with</em> a class or built-in type <tt class="literal"><span class="pre">Y</span></tt> that also models
<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> that models Single Pass Iterator is
<em>interoperable with</em> a class or built-in type <tt class="docutils literal"><span class="pre">Y</span></tt> that also models
Single Pass Iterator if the following expressions are valid and
respect the stated semantics. In the tables below, <tt class="literal"><span class="pre">x</span></tt> is an object
of type <tt class="literal"><span class="pre">X</span></tt>, <tt class="literal"><span class="pre">y</span></tt> is an object of type <tt class="literal"><span class="pre">Y</span></tt>, <tt class="literal"><span class="pre">Distance</span></tt> is
<tt class="literal"><span class="pre">iterator_traits&lt;Y&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>
<table border="1" class="table">
respect the stated semantics. In the tables below, <tt class="docutils literal"><span class="pre">x</span></tt> is an object
of type <tt class="docutils literal"><span class="pre">X</span></tt>, <tt class="docutils literal"><span class="pre">y</span></tt> is an object of type <tt class="docutils literal"><span class="pre">Y</span></tt>, <tt class="docutils literal"><span class="pre">Distance</span></tt> is
<tt class="docutils literal"><span class="pre">iterator_traits&lt;Y&gt;::difference_type</span></tt>, and <tt class="docutils literal"><span class="pre">n</span></tt> represents a
constant object of type <tt class="docutils literal"><span class="pre">Distance</span></tt>.</p>
<table border="1" class="docutils">
<colgroup>
<col width="13%" />
<col width="27%" />
@ -852,35 +852,35 @@ constant object of type <tt class="literal"><span class="pre">Distance</span></t
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="literal"><span class="pre">y</span> <span class="pre">=</span> <span class="pre">x</span></tt></td>
<td><tt class="literal"><span class="pre">Y</span></tt></td>
<td>post: <tt class="literal"><span class="pre">y</span> <span class="pre">==</span> <span class="pre">x</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">y</span> <span class="pre">=</span> <span class="pre">x</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Y</span></tt></td>
<td>post: <tt class="docutils literal"><span class="pre">y</span> <span class="pre">==</span> <span class="pre">x</span></tt></td>
</tr>
<tr><td><tt class="literal"><span class="pre">Y(x)</span></tt></td>
<td><tt class="literal"><span class="pre">Y</span></tt></td>
<td>post: <tt class="literal"><span class="pre">Y(x)</span> <span class="pre">==</span> <span class="pre">x</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">Y(x)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Y</span></tt></td>
<td>post: <tt class="docutils literal"><span class="pre">Y(x)</span> <span class="pre">==</span> <span class="pre">x</span></tt></td>
</tr>
<tr><td><tt class="literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">y</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">==</span></tt> is an equivalence relation over its domain.</td>
<tr><td><tt class="docutils literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">y</span></tt></td>
<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
<td><tt class="docutils literal"><span class="pre">==</span></tt> is an equivalence relation over its domain.</td>
</tr>
<tr><td><tt class="literal"><span class="pre">y</span> <span class="pre">==</span> <span class="pre">x</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">==</span></tt> is an equivalence relation over its domain.</td>
<tr><td><tt class="docutils literal"><span class="pre">y</span> <span class="pre">==</span> <span class="pre">x</span></tt></td>
<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
<td><tt class="docutils literal"><span class="pre">==</span></tt> is an equivalence relation over its domain.</td>
</tr>
<tr><td><tt class="literal"><span class="pre">x</span> <span class="pre">!=</span> <span class="pre">y</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">bool(a==b)</span> <span class="pre">!=</span> <span class="pre">bool(a!=b)</span></tt> over its domain.</td>
<tr><td><tt class="docutils literal"><span class="pre">x</span> <span class="pre">!=</span> <span class="pre">y</span></tt></td>
<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
<td><tt class="docutils literal"><span class="pre">bool(a==b)</span> <span class="pre">!=</span> <span class="pre">bool(a!=b)</span></tt> over its domain.</td>
</tr>
<tr><td><tt class="literal"><span class="pre">y</span> <span class="pre">!=</span> <span class="pre">x</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">bool(a==b)</span> <span class="pre">!=</span> <span class="pre">bool(a!=b)</span></tt> over its domain.</td>
<tr><td><tt class="docutils literal"><span class="pre">y</span> <span class="pre">!=</span> <span class="pre">x</span></tt></td>
<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
<td><tt class="docutils literal"><span class="pre">bool(a==b)</span> <span class="pre">!=</span> <span class="pre">bool(a!=b)</span></tt> over its domain.</td>
</tr>
</tbody>
</table>
<p>If <tt class="literal"><span class="pre">X</span></tt> and <tt class="literal"><span class="pre">Y</span></tt> both model Random Access Traversal Iterator then
<p>If <tt class="docutils literal"><span class="pre">X</span></tt> and <tt class="docutils literal"><span class="pre">Y</span></tt> both model Random Access Traversal Iterator then
the following additional requirements must be met.</p>
<table border="1" class="table">
<table border="1" class="docutils">
<colgroup>
<col width="12%" />
<col width="25%" />
@ -895,59 +895,59 @@ the following additional requirements must be met.</p>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="literal"><span class="pre">x</span> <span class="pre">&lt;</span> <span class="pre">y</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">y</span> <span class="pre">-</span> <span class="pre">x</span> <span class="pre">&gt;</span> <span class="pre">0</span></tt></td>
<td><tt class="literal"><span class="pre">&lt;</span></tt> is a total ordering relation</td>
<tr><td><tt class="docutils literal"><span class="pre">x</span> <span class="pre">&lt;</span> <span class="pre">y</span></tt></td>
<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
<td><tt class="docutils literal"><span class="pre">y</span> <span class="pre">-</span> <span class="pre">x</span> <span class="pre">&gt;</span> <span class="pre">0</span></tt></td>
<td><tt class="docutils literal"><span class="pre">&lt;</span></tt> is a total ordering relation</td>
</tr>
<tr><td><tt class="literal"><span class="pre">y</span> <span class="pre">&lt;</span> <span class="pre">x</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">x</span> <span class="pre">-</span> <span class="pre">y</span> <span class="pre">&gt;</span> <span class="pre">0</span></tt></td>
<td><tt class="literal"><span class="pre">&lt;</span></tt> is a total ordering relation</td>
<tr><td><tt class="docutils literal"><span class="pre">y</span> <span class="pre">&lt;</span> <span class="pre">x</span></tt></td>
<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
<td><tt class="docutils literal"><span class="pre">x</span> <span class="pre">-</span> <span class="pre">y</span> <span class="pre">&gt;</span> <span class="pre">0</span></tt></td>
<td><tt class="docutils literal"><span class="pre">&lt;</span></tt> is a total ordering relation</td>
</tr>
<tr><td><tt class="literal"><span class="pre">x</span> <span class="pre">&gt;</span> <span class="pre">y</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">y</span> <span class="pre">&lt;</span> <span class="pre">x</span></tt></td>
<td><tt class="literal"><span class="pre">&gt;</span></tt> is a total ordering relation</td>
<tr><td><tt class="docutils literal"><span class="pre">x</span> <span class="pre">&gt;</span> <span class="pre">y</span></tt></td>
<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
<td><tt class="docutils literal"><span class="pre">y</span> <span class="pre">&lt;</span> <span class="pre">x</span></tt></td>
<td><tt class="docutils literal"><span class="pre">&gt;</span></tt> is a total ordering relation</td>
</tr>
<tr><td><tt class="literal"><span class="pre">y</span> <span class="pre">&gt;</span> <span class="pre">x</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">x</span> <span class="pre">&lt;</span> <span class="pre">y</span></tt></td>
<td><tt class="literal"><span class="pre">&gt;</span></tt> is a total ordering relation</td>
<tr><td><tt class="docutils literal"><span class="pre">y</span> <span class="pre">&gt;</span> <span class="pre">x</span></tt></td>
<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
<td><tt class="docutils literal"><span class="pre">x</span> <span class="pre">&lt;</span> <span class="pre">y</span></tt></td>
<td><tt class="docutils literal"><span class="pre">&gt;</span></tt> is a total ordering relation</td>
</tr>
<tr><td><tt class="literal"><span class="pre">x</span> <span class="pre">&gt;=</span> <span class="pre">y</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">!(x</span> <span class="pre">&lt;</span> <span class="pre">y)</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">x</span> <span class="pre">&gt;=</span> <span class="pre">y</span></tt></td>
<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
<td><tt class="docutils literal"><span class="pre">!(x</span> <span class="pre">&lt;</span> <span class="pre">y)</span></tt></td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="literal"><span class="pre">y</span> <span class="pre">&gt;=</span> <span class="pre">x</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">!(y</span> <span class="pre">&lt;</span> <span class="pre">x)</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">y</span> <span class="pre">&gt;=</span> <span class="pre">x</span></tt></td>
<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
<td><tt class="docutils literal"><span class="pre">!(y</span> <span class="pre">&lt;</span> <span class="pre">x)</span></tt></td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="literal"><span class="pre">x</span> <span class="pre">&lt;=</span> <span class="pre">y</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">!(x</span> <span class="pre">&gt;</span> <span class="pre">y)</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">x</span> <span class="pre">&lt;=</span> <span class="pre">y</span></tt></td>
<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
<td><tt class="docutils literal"><span class="pre">!(x</span> <span class="pre">&gt;</span> <span class="pre">y)</span></tt></td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="literal"><span class="pre">y</span> <span class="pre">&lt;=</span> <span class="pre">x</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">!(y</span> <span class="pre">&gt;</span> <span class="pre">x)</span></tt></td>
<tr><td><tt class="docutils literal"><span class="pre">y</span> <span class="pre">&lt;=</span> <span class="pre">x</span></tt></td>
<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
<td><tt class="docutils literal"><span class="pre">!(y</span> <span class="pre">&gt;</span> <span class="pre">x)</span></tt></td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="literal"><span class="pre">y</span> <span class="pre">-</span> <span class="pre">x</span></tt></td>
<td><tt class="literal"><span class="pre">Distance</span></tt></td>
<td><tt class="literal"><span class="pre">distance(Y(x),y)</span></tt></td>
<td>pre: there exists a value <tt class="literal"><span class="pre">n</span></tt> of
<tt class="literal"><span class="pre">Distance</span></tt> such that <tt class="literal"><span class="pre">x</span> <span class="pre">+</span> <span class="pre">n</span> <span class="pre">==</span> <span class="pre">y</span></tt>.
<tt class="literal"><span class="pre">y</span> <span class="pre">==</span> <span class="pre">x</span> <span class="pre">+</span> <span class="pre">(y</span> <span class="pre">-</span> <span class="pre">x)</span></tt>.</td>
<tr><td><tt class="docutils literal"><span class="pre">y</span> <span class="pre">-</span> <span class="pre">x</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Distance</span></tt></td>
<td><tt class="docutils literal"><span class="pre">distance(Y(x),y)</span></tt></td>
<td>pre: there exists a value <tt class="docutils literal"><span class="pre">n</span></tt> of
<tt class="docutils literal"><span class="pre">Distance</span></tt> such that <tt class="docutils literal"><span class="pre">x</span> <span class="pre">+</span> <span class="pre">n</span> <span class="pre">==</span> <span class="pre">y</span></tt>.
<tt class="docutils literal"><span class="pre">y</span> <span class="pre">==</span> <span class="pre">x</span> <span class="pre">+</span> <span class="pre">(y</span> <span class="pre">-</span> <span class="pre">x)</span></tt>.</td>
</tr>
<tr><td><tt class="literal"><span class="pre">x</span> <span class="pre">-</span> <span class="pre">y</span></tt></td>
<td><tt class="literal"><span class="pre">Distance</span></tt></td>
<td><tt class="literal"><span class="pre">distance(y,Y(x))</span></tt></td>
<td>pre: there exists a value <tt class="literal"><span class="pre">n</span></tt> of
<tt class="literal"><span class="pre">Distance</span></tt> such that <tt class="literal"><span class="pre">y</span> <span class="pre">+</span> <span class="pre">n</span> <span class="pre">==</span> <span class="pre">x</span></tt>.
<tt class="literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">y</span> <span class="pre">+</span> <span class="pre">(x</span> <span class="pre">-</span> <span class="pre">y)</span></tt>.</td>
<tr><td><tt class="docutils literal"><span class="pre">x</span> <span class="pre">-</span> <span class="pre">y</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Distance</span></tt></td>
<td><tt class="docutils literal"><span class="pre">distance(y,Y(x))</span></tt></td>
<td>pre: there exists a value <tt class="docutils literal"><span class="pre">n</span></tt> of
<tt class="docutils literal"><span class="pre">Distance</span></tt> such that <tt class="docutils literal"><span class="pre">y</span> <span class="pre">+</span> <span class="pre">n</span> <span class="pre">==</span> <span class="pre">x</span></tt>.
<tt class="docutils literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">y</span> <span class="pre">+</span> <span class="pre">(x</span> <span class="pre">-</span> <span class="pre">y)</span></tt>.</td>
</tr>
</tbody>
</table>
@ -970,13 +970,13 @@ struct random_access_traversal_tag : bidirectional_traversal_tag { };
</div>
<div class="section" id="addition-to-lib-iterator-traits">
<h2><a class="toc-backref" href="#id23" name="addition-to-lib-iterator-traits">Addition to [lib.iterator.traits]</a></h2>
<p>The <tt class="literal"><span class="pre">is_readable_iterator</span></tt> class
<p>The <tt class="docutils literal"><span class="pre">is_readable_iterator</span></tt> class
template satisfies the <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1519.htm">UnaryTypeTrait</a> requirements.</p>
<p>Given an iterator type <tt class="literal"><span class="pre">X</span></tt>, <tt class="literal"><span class="pre">is_readable_iterator&lt;X&gt;::value</span></tt>
yields <tt class="literal"><span class="pre">true</span></tt> if, for 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</span></tt> is
convertible to <tt class="literal"><span class="pre">iterator_traits&lt;X&gt;::value_type</span></tt>, and <tt class="literal"><span class="pre">false</span></tt>
<p>Given an iterator type <tt class="docutils literal"><span class="pre">X</span></tt>, <tt class="docutils literal"><span class="pre">is_readable_iterator&lt;X&gt;::value</span></tt>
yields <tt class="docutils literal"><span class="pre">true</span></tt> if, for an object <tt class="docutils literal"><span class="pre">a</span></tt> of type <tt class="docutils literal"><span class="pre">X</span></tt>, <tt class="docutils literal"><span class="pre">*a</span></tt> is
convertible to <tt class="docutils literal"><span class="pre">iterator_traits&lt;X&gt;::value_type</span></tt>, and <tt class="docutils literal"><span class="pre">false</span></tt>
otherwise.</p>
<p><tt class="literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt> is</p>
<p><tt class="docutils literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt> is</p>
<pre class="literal-block">
<em>category-to-traversal</em>(iterator_traits&lt;X&gt;::iterator_category)
</pre>
@ -1004,7 +1004,7 @@ otherwise.</p>
<h1><a class="toc-backref" href="#id24" name="footnotes">Footnotes</a></h1>
<p>The UnaryTypeTrait concept is defined in <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1519.htm">n1519</a>; the LWG is
considering adding the requirement that specializations are derived
from their nested <tt class="literal"><span class="pre">::type</span></tt>.</p>
from their nested <tt class="docutils literal"><span class="pre">::type</span></tt>.</p>
<!-- LocalWords: Abrahams Siek Witt const bool Sutter's WG int UL LI href Lvalue
LocalWords: ReadableIterator WritableIterator SwappableIterator cv pre iter
LocalWords: ConstantLvalueIterator MutableLvalueIterator CopyConstructible TR
@ -1014,7 +1014,7 @@ LocalWords: incrementable xxx min prev inplace png oldeqnew AccessTag struct
LocalWords: TraversalTag typename lvalues DWA Hmm JGS mis enum -->
</div>
</div>
<hr class="footer" />
<hr class="docutils footer" />
<div class="footer">
<a class="reference" href="new-iter-concepts.rst">View document source</a>.
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.

1113
doc/new-iter-concepts.pdf
View File

File diff suppressed because it is too large Load Diff

110
doc/permutation_iterator.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.3.6: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.3.8: http://docutils.sourceforge.net/" />
<title>Permutation Iterator</title>
<meta name="author" content="Toon Knapen, David Abrahams, Roland Richter, Jeremy Siek" />
<meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab" />
@ -12,6 +12,7 @@
<link rel="stylesheet" href="default.css" type="text/css" />
</head>
<body>
<div class="document" id="permutation-iterator">
<h1 class="title">Permutation Iterator</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
@ -30,8 +31,7 @@ Lab</a></td></tr>
<td>Copyright Toon Knapen, David Abrahams, Roland Richter, and Jeremy Siek 2003.</td></tr>
</tbody>
</table>
<div class="document" id="permutation-iterator">
<table class="field-list" frame="void" rules="none">
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
@ -46,9 +46,9 @@ in a potentially different order.</td>
<ul class="simple">
<li><a class="reference" href="#introduction" id="id2" name="id2">Introduction</a></li>
<li><a class="reference" href="#reference" id="id3" name="id3">Reference</a><ul>
<li><a class="reference" href="#permutation-iterator-requirements" id="id4" name="id4"><tt class="literal"><span class="pre">permutation_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#permutation-iterator-models" id="id5" name="id5"><tt class="literal"><span class="pre">permutation_iterator</span></tt> models</a></li>
<li><a class="reference" href="#permutation-iterator-operations" id="id6" name="id6"><tt class="literal"><span class="pre">permutation_iterator</span></tt> operations</a></li>
<li><a class="reference" href="#permutation-iterator-requirements" id="id4" name="id4"><tt class="docutils literal"><span class="pre">permutation_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#permutation-iterator-models" id="id5" name="id5"><tt class="docutils literal"><span class="pre">permutation_iterator</span></tt> models</a></li>
<li><a class="reference" href="#permutation-iterator-operations" id="id6" name="id6"><tt class="docutils literal"><span class="pre">permutation_iterator</span></tt> operations</a></li>
</ul>
</li>
<li><a class="reference" href="#example" id="id7" name="id7">Example</a></li>
@ -108,54 +108,54 @@ permutation_iterator&lt;ElementIterator, IndexIterator&gt;
make_permutation_iterator( ElementIterator e, IndexIterator i);
</pre>
<div class="section" id="permutation-iterator-requirements">
<h2><a class="toc-backref" href="#id4" name="permutation-iterator-requirements"><tt class="literal"><span class="pre">permutation_iterator</span></tt> requirements</a></h2>
<p><tt class="literal"><span class="pre">ElementIterator</span></tt> shall model Random Access Traversal Iterator.
<tt class="literal"><span class="pre">IndexIterator</span></tt> shall model Readable Iterator. The value type of
the <tt class="literal"><span class="pre">IndexIterator</span></tt> must be convertible to the difference type of
<tt class="literal"><span class="pre">ElementIterator</span></tt>.</p>
<h2><a class="toc-backref" href="#id4" name="permutation-iterator-requirements"><tt class="docutils literal"><span class="pre">permutation_iterator</span></tt> requirements</a></h2>
<p><tt class="docutils literal"><span class="pre">ElementIterator</span></tt> shall model Random Access Traversal Iterator.
<tt class="docutils literal"><span class="pre">IndexIterator</span></tt> shall model Readable Iterator. The value type of
the <tt class="docutils literal"><span class="pre">IndexIterator</span></tt> must be convertible to the difference type of
<tt class="docutils literal"><span class="pre">ElementIterator</span></tt>.</p>
</div>
<div class="section" id="permutation-iterator-models">
<h2><a class="toc-backref" href="#id5" name="permutation-iterator-models"><tt class="literal"><span class="pre">permutation_iterator</span></tt> models</a></h2>
<p><tt class="literal"><span class="pre">permutation_iterator</span></tt> models the same iterator traversal concepts
as <tt class="literal"><span class="pre">IndexIterator</span></tt> and the same iterator access concepts as
<tt class="literal"><span class="pre">ElementIterator</span></tt>.</p>
<p>If <tt class="literal"><span class="pre">IndexIterator</span></tt> models Single Pass Iterator and
<tt class="literal"><span class="pre">ElementIterator</span></tt> models Readable Iterator then
<tt class="literal"><span class="pre">permutation_iterator</span></tt> models Input Iterator.</p>
<p>If <tt class="literal"><span class="pre">IndexIterator</span></tt> models Forward Traversal Iterator and
<tt class="literal"><span class="pre">ElementIterator</span></tt> models Readable Lvalue Iterator then
<tt class="literal"><span class="pre">permutation_iterator</span></tt> models Forward Iterator.</p>
<p>If <tt class="literal"><span class="pre">IndexIterator</span></tt> models Bidirectional Traversal Iterator and
<tt class="literal"><span class="pre">ElementIterator</span></tt> models Readable Lvalue Iterator then
<tt class="literal"><span class="pre">permutation_iterator</span></tt> models Bidirectional Iterator.</p>
<p>If <tt class="literal"><span class="pre">IndexIterator</span></tt> models Random Access Traversal Iterator and
<tt class="literal"><span class="pre">ElementIterator</span></tt> models Readable Lvalue Iterator then
<tt class="literal"><span class="pre">permutation_iterator</span></tt> models Random Access Iterator.</p>
<p><tt class="literal"><span class="pre">permutation_iterator&lt;E1,</span> <span class="pre">X,</span> <span class="pre">V1,</span> <span class="pre">C2,</span> <span class="pre">R1,</span> <span class="pre">D1&gt;</span></tt> is interoperable
with <tt class="literal"><span class="pre">permutation_iterator&lt;E2,</span> <span class="pre">Y,</span> <span class="pre">V2,</span> <span class="pre">C2,</span> <span class="pre">R2,</span> <span class="pre">D2&gt;</span></tt> if and only if
<tt class="literal"><span class="pre">X</span></tt> is interoperable with <tt class="literal"><span class="pre">Y</span></tt> and <tt class="literal"><span class="pre">E1</span></tt> is convertible
to <tt class="literal"><span class="pre">E2</span></tt>.</p>
<h2><a class="toc-backref" href="#id5" name="permutation-iterator-models"><tt class="docutils literal"><span class="pre">permutation_iterator</span></tt> models</a></h2>
<p><tt class="docutils literal"><span class="pre">permutation_iterator</span></tt> models the same iterator traversal concepts
as <tt class="docutils literal"><span class="pre">IndexIterator</span></tt> and the same iterator access concepts as
<tt class="docutils literal"><span class="pre">ElementIterator</span></tt>.</p>
<p>If <tt class="docutils literal"><span class="pre">IndexIterator</span></tt> models Single Pass Iterator and
<tt class="docutils literal"><span class="pre">ElementIterator</span></tt> models Readable Iterator then
<tt class="docutils literal"><span class="pre">permutation_iterator</span></tt> models Input Iterator.</p>
<p>If <tt class="docutils literal"><span class="pre">IndexIterator</span></tt> models Forward Traversal Iterator and
<tt class="docutils literal"><span class="pre">ElementIterator</span></tt> models Readable Lvalue Iterator then
<tt class="docutils literal"><span class="pre">permutation_iterator</span></tt> models Forward Iterator.</p>
<p>If <tt class="docutils literal"><span class="pre">IndexIterator</span></tt> models Bidirectional Traversal Iterator and
<tt class="docutils literal"><span class="pre">ElementIterator</span></tt> models Readable Lvalue Iterator then
<tt class="docutils literal"><span class="pre">permutation_iterator</span></tt> models Bidirectional Iterator.</p>
<p>If <tt class="docutils literal"><span class="pre">IndexIterator</span></tt> models Random Access Traversal Iterator and
<tt class="docutils literal"><span class="pre">ElementIterator</span></tt> models Readable Lvalue Iterator then
<tt class="docutils literal"><span class="pre">permutation_iterator</span></tt> models Random Access Iterator.</p>
<p><tt class="docutils literal"><span class="pre">permutation_iterator&lt;E1,</span> <span class="pre">X,</span> <span class="pre">V1,</span> <span class="pre">C2,</span> <span class="pre">R1,</span> <span class="pre">D1&gt;</span></tt> is interoperable
with <tt class="docutils literal"><span class="pre">permutation_iterator&lt;E2,</span> <span class="pre">Y,</span> <span class="pre">V2,</span> <span class="pre">C2,</span> <span class="pre">R2,</span> <span class="pre">D2&gt;</span></tt> if and only if
<tt class="docutils literal"><span class="pre">X</span></tt> is interoperable with <tt class="docutils literal"><span class="pre">Y</span></tt> and <tt class="docutils literal"><span class="pre">E1</span></tt> is convertible
to <tt class="docutils literal"><span class="pre">E2</span></tt>.</p>
</div>
<div class="section" id="permutation-iterator-operations">
<h2><a class="toc-backref" href="#id6" name="permutation-iterator-operations"><tt class="literal"><span class="pre">permutation_iterator</span></tt> operations</a></h2>
<h2><a class="toc-backref" href="#id6" name="permutation-iterator-operations"><tt class="docutils literal"><span class="pre">permutation_iterator</span></tt> operations</a></h2>
<p>In addition to those operations required by the concepts that
<tt class="literal"><span class="pre">permutation_iterator</span></tt> models, <tt class="literal"><span class="pre">permutation_iterator</span></tt> provides the
<tt class="docutils literal"><span class="pre">permutation_iterator</span></tt> models, <tt class="docutils literal"><span class="pre">permutation_iterator</span></tt> provides the
following operations.</p>
<p><tt class="literal"><span class="pre">permutation_iterator();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">permutation_iterator();</span></tt></p>
<table class="docutils 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">Default constructs <tt class="literal"><span class="pre">m_elt</span></tt> and <tt class="literal"><span class="pre">m_order</span></tt>.</td>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Default constructs <tt class="docutils literal"><span class="pre">m_elt</span></tt> and <tt class="docutils literal"><span class="pre">m_order</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">explicit</span> <span class="pre">permutation_iterator(ElementIterator</span> <span class="pre">x,</span> <span class="pre">IndexIterator</span> <span class="pre">y);</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">explicit</span> <span class="pre">permutation_iterator(ElementIterator</span> <span class="pre">x,</span> <span class="pre">IndexIterator</span> <span class="pre">y);</span></tt></p>
<table class="docutils 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">Constructs <tt class="literal"><span class="pre">m_elt</span></tt> from <tt class="literal"><span class="pre">x</span></tt> and <tt class="literal"><span class="pre">m_order</span></tt> from <tt class="literal"><span class="pre">y</span></tt>.</td>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Constructs <tt class="docutils literal"><span class="pre">m_elt</span></tt> from <tt class="docutils literal"><span class="pre">x</span></tt> and <tt class="docutils literal"><span class="pre">m_order</span></tt> from <tt class="docutils literal"><span class="pre">y</span></tt>.</td>
</tr>
</tbody>
</table>
@ -167,41 +167,41 @@ permutation_iterator(
, typename enable_if_convertible&lt;OIIter, IndexIterator&gt;::type* = 0
);
</pre>
<table class="field-list" frame="void" rules="none">
<table class="docutils 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">Constructs <tt class="literal"><span class="pre">m_elt</span></tt> from <tt class="literal"><span class="pre">r.m_elt</span></tt> and
<tt class="literal"><span class="pre">m_order</span></tt> from <tt class="literal"><span class="pre">y.m_order</span></tt>.</td>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Constructs <tt class="docutils literal"><span class="pre">m_elt</span></tt> from <tt class="docutils literal"><span class="pre">r.m_elt</span></tt> and
<tt class="docutils literal"><span class="pre">m_order</span></tt> from <tt class="docutils literal"><span class="pre">y.m_order</span></tt>.</td>
</tr>
</tbody>
</table>
<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">
<p><tt class="docutils literal"><span class="pre">reference</span> <span class="pre">operator*()</span> <span class="pre">const;</span></tt></p>
<table class="docutils 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">*(m_elt</span> <span class="pre">+</span> <span class="pre">*m_order)</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*(m_elt</span> <span class="pre">+</span> <span class="pre">*m_order)</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">permutation_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">permutation_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
<table class="docutils 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"><tt class="literal"><span class="pre">++m_order</span></tt></td>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="docutils literal"><span class="pre">++m_order</span></tt></td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">*this</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">ElementIterator</span> <span class="pre">const&amp;</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">ElementIterator</span> <span class="pre">const&amp;</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
<table class="docutils 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">m_order</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_order</span></tt></td>
</tr>
</tbody>
</table>
@ -210,11 +210,11 @@ template &lt;class ElementIterator, class IndexIterator&gt;
permutation_iterator&lt;ElementIterator, IndexIterator&gt;
make_permutation_iterator(ElementIterator e, IndexIterator i);
</pre>
<table class="field-list" frame="void" rules="none">
<table class="docutils 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">permutation_iterator&lt;ElementIterator,</span> <span class="pre">IndexIterator&gt;(e,</span> <span class="pre">i)</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">permutation_iterator&lt;ElementIterator,</span> <span class="pre">IndexIterator&gt;(e,</span> <span class="pre">i)</span></tt></td>
</tr>
</tbody>
</table>
@ -286,7 +286,7 @@ Iterate backward with stride 2 : 6 8
<p>The source code for this example can be found <a class="reference" href="../example/permutation_iter_example.cpp">here</a>.</p>
</div>
</div>
<hr class="footer" />
<hr class="docutils footer" />
<div class="footer">
<a class="reference" href="permutation_iterator.rst">View document source</a>.
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.

BIN
doc/permutation_iterator.pdf
View File

Binary file not shown.

70
doc/pointee.html
View File

@ -3,16 +3,17 @@
<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.3.6: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.3.8: http://docutils.sourceforge.net/" />
<title>pointee and indirect_reference</title>
<meta name="author" content="David Abrahams" />
<meta name="organization" content="Boost Consulting" />
<meta name="date" content="2004-11-01" />
<meta name="date" content="2005-02-27" />
<meta name="copyright" content="Copyright David Abrahams 2004." />
<link rel="stylesheet" href="default.css" type="text/css" />
</head>
<body>
<h1 class="title"><tt class="literal"><span class="pre">pointee</span></tt> and <tt class="literal"><span class="pre">indirect_reference</span></tt></h1>
<div class="document" id="pointee-and-indirect-reference">
<h1 class="title"><tt class="docutils literal"><span class="pre">pointee</span></tt> and <tt class="docutils literal"><span class="pre">indirect_reference</span></tt></h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
@ -24,13 +25,12 @@
<tr><th class="docinfo-name">Organization:</th>
<td><a class="first last reference" href="http://www.boost-consulting.com">Boost Consulting</a></td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2004-11-01</td></tr>
<td>2005-02-27</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>Copyright David Abrahams 2004.</td></tr>
</tbody>
</table>
<div class="document" id="pointee-and-indirect-reference">
<table class="field-list" frame="void" rules="none">
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
@ -54,13 +54,13 @@ void f(Dereferenceable p)
}
</pre>
<div class="section" id="pointee">
<h2><a name="pointee"><tt class="literal"><span class="pre">pointee</span></tt></a></h2>
<h2><a name="pointee"><tt class="docutils literal"><span class="pre">pointee</span></tt></a></h2>
<p>It turns out to be impossible to come up with a fully-general
algorithm to do determine <em>what-goes-here</em> directly, but it is
possible to require that <tt class="literal"><span class="pre">pointee&lt;Dereferenceable&gt;::type</span></tt> is
correct. Naturally, <tt class="literal"><span class="pre">pointee</span></tt> has the same difficulty: it can't
determine the appropriate <tt class="literal"><span class="pre">::type</span></tt> reliably for all
<tt class="literal"><span class="pre">Dereferenceable</span></tt>s, but it makes very good guesses (it works
possible to require that <tt class="docutils literal"><span class="pre">pointee&lt;Dereferenceable&gt;::type</span></tt> is
correct. Naturally, <tt class="docutils literal"><span class="pre">pointee</span></tt> has the same difficulty: it can't
determine the appropriate <tt class="docutils literal"><span class="pre">::type</span></tt> reliably for all
<tt class="docutils literal"><span class="pre">Dereferenceable</span></tt>s, but it makes very good guesses (it works
for all pointers, standard and boost smart pointers, and
iterators), and when it guesses wrongly, it can be specialized as
necessary:</p>
@ -76,21 +76,21 @@ namespace boost
</pre>
</div>
<div class="section" id="indirect-reference">
<h2><a name="indirect-reference"><tt class="literal"><span class="pre">indirect_reference</span></tt></a></h2>
<p><tt class="literal"><span class="pre">indirect_reference&lt;T&gt;::type</span></tt> is rather more specialized than
<tt class="literal"><span class="pre">pointee</span></tt>, and is meant to be used to forward the result of
<h2><a name="indirect-reference"><tt class="docutils literal"><span class="pre">indirect_reference</span></tt></a></h2>
<p><tt class="docutils literal"><span class="pre">indirect_reference&lt;T&gt;::type</span></tt> is rather more specialized than
<tt class="docutils literal"><span class="pre">pointee</span></tt>, and is meant to be used to forward the result of
dereferencing an object of its argument type. Most dereferenceable
types just return a reference to their pointee, but some return
proxy references or return the pointee by value. When that
information is needed, call on <tt class="literal"><span class="pre">indirect_reference</span></tt>.</p>
information is needed, call on <tt class="docutils literal"><span class="pre">indirect_reference</span></tt>.</p>
<p>Both of these templates are essential to the correct functioning of
<a class="reference" href="indirect_iterator.html"><tt class="literal"><span class="pre">indirect_iterator</span></tt></a>.</p>
<a class="reference" href="indirect_iterator.html"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt></a>.</p>
</div>
</div>
<div class="section" id="reference">
<h1><a name="reference">Reference</a></h1>
<div class="section" id="id1">
<h2><a name="id1"><tt class="literal"><span class="pre">pointee</span></tt></a></h2>
<h2><a name="id1"><tt class="docutils literal"><span class="pre">pointee</span></tt></a></h2>
<!-- Copyright David Abrahams 2004. Use, modification and distribution is -->
<!-- subject to the Boost Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
@ -101,22 +101,22 @@ struct pointee
typedef /* see below */ type;
};
</pre>
<table class="field-list" frame="void" rules="none">
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Requires:</th><td class="field-body">For an object <tt class="literal"><span class="pre">x</span></tt> of type <tt class="literal"><span class="pre">Dereferenceable</span></tt>, <tt class="literal"><span class="pre">*x</span></tt>
is well-formed. If <tt class="literal"><span class="pre">++x</span></tt> is ill-formed it shall neither be
<tr class="field"><th class="field-name">Requires:</th><td class="field-body">For an object <tt class="docutils literal"><span class="pre">x</span></tt> of type <tt class="docutils literal"><span class="pre">Dereferenceable</span></tt>, <tt class="docutils literal"><span class="pre">*x</span></tt>
is well-formed. If <tt class="docutils literal"><span class="pre">++x</span></tt> is ill-formed it shall neither be
ambiguous nor shall it violate access control, and
<tt class="literal"><span class="pre">Dereferenceable::element_type</span></tt> shall be an accessible type.
Otherwise <tt class="literal"><span class="pre">iterator_traits&lt;Dereferenceable&gt;::value_type</span></tt> shall
<tt class="docutils literal"><span class="pre">Dereferenceable::element_type</span></tt> shall be an accessible type.
Otherwise <tt class="docutils literal"><span class="pre">iterator_traits&lt;Dereferenceable&gt;::value_type</span></tt> shall
be well formed. [Note: These requirements need not apply to
explicit or partial specializations of <tt class="literal"><span class="pre">pointee</span></tt>]</td>
explicit or partial specializations of <tt class="docutils literal"><span class="pre">pointee</span></tt>]</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">type</span></tt> is determined according to the following algorithm, where
<tt class="literal"><span class="pre">x</span></tt> is an object of type <tt class="literal"><span class="pre">Dereferenceable</span></tt>:</p>
<p><tt class="docutils literal"><span class="pre">type</span></tt> is determined according to the following algorithm, where
<tt class="docutils literal"><span class="pre">x</span></tt> is an object of type <tt class="docutils literal"><span class="pre">Dereferenceable</span></tt>:</p>
<pre class="literal-block">
if ( ++x is ill-formed )
{
@ -134,7 +134,7 @@ else
</pre>
</div>
<div class="section" id="id2">
<h2><a name="id2"><tt class="literal"><span class="pre">indirect_reference</span></tt></a></h2>
<h2><a name="id2"><tt class="docutils literal"><span class="pre">indirect_reference</span></tt></a></h2>
<!-- Copyright David Abrahams 2004. Use, modification and distribution is -->
<!-- subject to the Boost Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
@ -145,22 +145,22 @@ struct indirect_reference
typedef /* see below */ type;
};
</pre>
<table class="field-list" frame="void" rules="none">
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Requires:</th><td class="field-body">For an object <tt class="literal"><span class="pre">x</span></tt> of type <tt class="literal"><span class="pre">Dereferenceable</span></tt>, <tt class="literal"><span class="pre">*x</span></tt>
is well-formed. If <tt class="literal"><span class="pre">++x</span></tt> is ill-formed it shall neither be
<tr class="field"><th class="field-name">Requires:</th><td class="field-body">For an object <tt class="docutils literal"><span class="pre">x</span></tt> of type <tt class="docutils literal"><span class="pre">Dereferenceable</span></tt>, <tt class="docutils literal"><span class="pre">*x</span></tt>
is well-formed. If <tt class="docutils literal"><span class="pre">++x</span></tt> is ill-formed it shall neither be
ambiguous nor shall it violate access control, and
<tt class="literal"><span class="pre">pointee&lt;Dereferenceable&gt;::type&amp;</span></tt> shall be well-formed.
Otherwise <tt class="literal"><span class="pre">iterator_traits&lt;Dereferenceable&gt;::reference</span></tt> shall
<tt class="docutils literal"><span class="pre">pointee&lt;Dereferenceable&gt;::type&amp;</span></tt> shall be well-formed.
Otherwise <tt class="docutils literal"><span class="pre">iterator_traits&lt;Dereferenceable&gt;::reference</span></tt> shall
be well formed. [Note: These requirements need not apply to
explicit or partial specializations of <tt class="literal"><span class="pre">indirect_reference</span></tt>]</td>
explicit or partial specializations of <tt class="docutils literal"><span class="pre">indirect_reference</span></tt>]</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">type</span></tt> is determined according to the following algorithm, where
<tt class="literal"><span class="pre">x</span></tt> is an object of type <tt class="literal"><span class="pre">Dereferenceable</span></tt>:</p>
<p><tt class="docutils literal"><span class="pre">type</span></tt> is determined according to the following algorithm, where
<tt class="docutils literal"><span class="pre">x</span></tt> is an object of type <tt class="docutils literal"><span class="pre">Dereferenceable</span></tt>:</p>
<pre class="literal-block">
if ( ++x is ill-formed )
return ``pointee&lt;Dereferenceable&gt;::type&amp;``
@ -170,7 +170,7 @@ else
</div>
</div>
</div>
<hr class="footer" />
<hr class="docutils footer" />
<div class="footer">
<a class="reference" href="pointee.rst">View document source</a>.
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.

BIN
doc/pointee.pdf
View File

Binary file not shown.

120
doc/reverse_iterator.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.3.6: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.3.8: http://docutils.sourceforge.net/" />
<title>Reverse Iterator</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" />
@ -12,6 +12,7 @@
<link rel="stylesheet" href="default.css" type="text/css" />
</head>
<body>
<div class="document" id="reverse-iterator">
<h1 class="title">Reverse Iterator</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
@ -31,8 +32,7 @@ Railway Operation and Construction</a></td></tr>
<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003.</td></tr>
</tbody>
</table>
<div class="document" id="reverse-iterator">
<table class="field-list" frame="void" rules="none">
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
@ -44,15 +44,15 @@ range in the opposite direction.</td>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first"><a name="table-of-contents">Table of Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#reverse-iterator-synopsis" id="id2" name="id2"><tt class="literal"><span class="pre">reverse_iterator</span></tt> synopsis</a></li>
<li><a class="reference" href="#reverse-iterator-requirements" id="id3" name="id3"><tt class="literal"><span class="pre">reverse_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#reverse-iterator-models" id="id4" name="id4"><tt class="literal"><span class="pre">reverse_iterator</span></tt> models</a></li>
<li><a class="reference" href="#reverse-iterator-operations" id="id5" name="id5"><tt class="literal"><span class="pre">reverse_iterator</span></tt> operations</a></li>
<li><a class="reference" href="#reverse-iterator-synopsis" id="id2" name="id2"><tt class="docutils literal"><span class="pre">reverse_iterator</span></tt> synopsis</a></li>
<li><a class="reference" href="#reverse-iterator-requirements" id="id3" name="id3"><tt class="docutils literal"><span class="pre">reverse_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#reverse-iterator-models" id="id4" name="id4"><tt class="docutils literal"><span class="pre">reverse_iterator</span></tt> models</a></li>
<li><a class="reference" href="#reverse-iterator-operations" id="id5" name="id5"><tt class="docutils literal"><span class="pre">reverse_iterator</span></tt> operations</a></li>
<li><a class="reference" href="#example" id="id6" name="id6">Example</a></li>
</ul>
</div>
<div class="section" id="reverse-iterator-synopsis">
<h1><a class="toc-backref" href="#id2" name="reverse-iterator-synopsis"><tt class="literal"><span class="pre">reverse_iterator</span></tt> synopsis</a></h1>
<h1><a class="toc-backref" href="#id2" name="reverse-iterator-synopsis"><tt class="docutils literal"><span class="pre">reverse_iterator</span></tt> synopsis</a></h1>
<pre class="literal-block">
template &lt;class Iterator&gt;
class reverse_iterator
@ -80,34 +80,34 @@ private:
Iterator m_iterator; // exposition
};
</pre>
<p>If <tt class="literal"><span class="pre">Iterator</span></tt> models Random Access Traversal Iterator and Readable
Lvalue Iterator, then <tt class="literal"><span class="pre">iterator_category</span></tt> is convertible to
<tt class="literal"><span class="pre">random_access_iterator_tag</span></tt>. Otherwise, if
<tt class="literal"><span class="pre">Iterator</span></tt> models Bidirectional Traversal Iterator and Readable
Lvalue Iterator, then <tt class="literal"><span class="pre">iterator_category</span></tt> is convertible to
<tt class="literal"><span class="pre">bidirectional_iterator_tag</span></tt>. Otherwise, <tt class="literal"><span class="pre">iterator_category</span></tt> is
convertible to <tt class="literal"><span class="pre">input_iterator_tag</span></tt>.</p>
<p>If <tt class="docutils literal"><span class="pre">Iterator</span></tt> models Random Access Traversal Iterator and Readable
Lvalue Iterator, then <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible to
<tt class="docutils literal"><span class="pre">random_access_iterator_tag</span></tt>. Otherwise, if
<tt class="docutils literal"><span class="pre">Iterator</span></tt> models Bidirectional Traversal Iterator and Readable
Lvalue Iterator, then <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible to
<tt class="docutils literal"><span class="pre">bidirectional_iterator_tag</span></tt>. Otherwise, <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is
convertible to <tt class="docutils literal"><span class="pre">input_iterator_tag</span></tt>.</p>
</div>
<div class="section" id="reverse-iterator-requirements">
<h1><a class="toc-backref" href="#id3" name="reverse-iterator-requirements"><tt class="literal"><span class="pre">reverse_iterator</span></tt> requirements</a></h1>
<p><tt class="literal"><span class="pre">Iterator</span></tt> must be a model of Bidirectional Traversal Iterator. The
type <tt class="literal"><span class="pre">iterator_traits&lt;Iterator&gt;::reference</span></tt> must be the type of
<tt class="literal"><span class="pre">*i</span></tt>, where <tt class="literal"><span class="pre">i</span></tt> is an object of type <tt class="literal"><span class="pre">Iterator</span></tt>.</p>
<h1><a class="toc-backref" href="#id3" name="reverse-iterator-requirements"><tt class="docutils literal"><span class="pre">reverse_iterator</span></tt> requirements</a></h1>
<p><tt class="docutils literal"><span class="pre">Iterator</span></tt> must be a model of Bidirectional Traversal Iterator. The
type <tt class="docutils literal"><span class="pre">iterator_traits&lt;Iterator&gt;::reference</span></tt> must be the type of
<tt class="docutils literal"><span class="pre">*i</span></tt>, where <tt class="docutils literal"><span class="pre">i</span></tt> is an object of type <tt class="docutils literal"><span class="pre">Iterator</span></tt>.</p>
</div>
<div class="section" id="reverse-iterator-models">
<h1><a class="toc-backref" href="#id4" name="reverse-iterator-models"><tt class="literal"><span class="pre">reverse_iterator</span></tt> models</a></h1>
<p>A specialization of <tt class="literal"><span class="pre">reverse_iterator</span></tt> models the same iterator
traversal and iterator access concepts modeled by its <tt class="literal"><span class="pre">Iterator</span></tt>
<h1><a class="toc-backref" href="#id4" name="reverse-iterator-models"><tt class="docutils literal"><span class="pre">reverse_iterator</span></tt> models</a></h1>
<p>A specialization of <tt class="docutils literal"><span class="pre">reverse_iterator</span></tt> models the same iterator
traversal and iterator access concepts modeled by its <tt class="docutils literal"><span class="pre">Iterator</span></tt>
argument. In addition, it may model old iterator concepts
specified in the following table:</p>
<table border="1" class="table">
<table border="1" class="docutils">
<colgroup>
<col width="53%" />
<col width="47%" />
</colgroup>
<thead valign="bottom">
<tr><th>If <tt class="literal"><span class="pre">I</span></tt> models</th>
<th>then <tt class="literal"><span class="pre">reverse_iterator&lt;I&gt;</span></tt> models</th>
<tr><th>If <tt class="docutils literal"><span class="pre">I</span></tt> models</th>
<th>then <tt class="docutils literal"><span class="pre">reverse_iterator&lt;I&gt;</span></tt> models</th>
</tr>
</thead>
<tbody valign="top">
@ -129,34 +129,34 @@ Random Access Traversal Iterator</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">reverse_iterator&lt;X&gt;</span></tt> is interoperable with
<tt class="literal"><span class="pre">reverse_iterator&lt;Y&gt;</span></tt> if and only if <tt class="literal"><span class="pre">X</span></tt> is interoperable with
<tt class="literal"><span class="pre">Y</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">reverse_iterator&lt;X&gt;</span></tt> is interoperable with
<tt class="docutils literal"><span class="pre">reverse_iterator&lt;Y&gt;</span></tt> if and only if <tt class="docutils literal"><span class="pre">X</span></tt> is interoperable with
<tt class="docutils literal"><span class="pre">Y</span></tt>.</p>
</div>
<div class="section" id="reverse-iterator-operations">
<h1><a class="toc-backref" href="#id5" name="reverse-iterator-operations"><tt class="literal"><span class="pre">reverse_iterator</span></tt> operations</a></h1>
<h1><a class="toc-backref" href="#id5" name="reverse-iterator-operations"><tt class="docutils literal"><span class="pre">reverse_iterator</span></tt> operations</a></h1>
<p>In addition to the operations required by the concepts modeled by
<tt class="literal"><span class="pre">reverse_iterator</span></tt>, <tt class="literal"><span class="pre">reverse_iterator</span></tt> provides the following
<tt class="docutils literal"><span class="pre">reverse_iterator</span></tt>, <tt class="docutils literal"><span class="pre">reverse_iterator</span></tt> provides the following
operations.</p>
<p><tt class="literal"><span class="pre">reverse_iterator();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">reverse_iterator();</span></tt></p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="literal"><span class="pre">Iterator</span></tt> must be Default Constructible.</td>
<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="docutils literal"><span class="pre">Iterator</span></tt> must be Default Constructible.</td>
</tr>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Constructs an instance of <tt class="literal"><span class="pre">reverse_iterator</span></tt> with <tt class="literal"><span class="pre">m_iterator</span></tt>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Constructs an instance of <tt class="docutils literal"><span class="pre">reverse_iterator</span></tt> with <tt class="docutils literal"><span class="pre">m_iterator</span></tt>
default constructed.</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">explicit</span> <span class="pre">reverse_iterator(Iterator</span> <span class="pre">x);</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">explicit</span> <span class="pre">reverse_iterator(Iterator</span> <span class="pre">x);</span></tt></p>
<table class="docutils 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">Constructs an instance of <tt class="literal"><span class="pre">reverse_iterator</span></tt> with
<tt class="literal"><span class="pre">m_iterator</span></tt> copy constructed from <tt class="literal"><span class="pre">x</span></tt>.</td>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Constructs an instance of <tt class="docutils literal"><span class="pre">reverse_iterator</span></tt> with
<tt class="docutils literal"><span class="pre">m_iterator</span></tt> copy constructed from <tt class="docutils literal"><span class="pre">x</span></tt>.</td>
</tr>
</tbody>
</table>
@ -167,28 +167,28 @@ reverse_iterator(
, typename enable_if_convertible&lt;OtherIterator, Iterator&gt;::type* = 0 // exposition
);
</pre>
<table class="field-list" frame="void" rules="none">
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="literal"><span class="pre">OtherIterator</span></tt> is implicitly convertible to <tt class="literal"><span class="pre">Iterator</span></tt>.</td>
<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="docutils literal"><span class="pre">OtherIterator</span></tt> is implicitly convertible to <tt class="docutils literal"><span class="pre">Iterator</span></tt>.</td>
</tr>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Constructs instance of <tt class="literal"><span class="pre">reverse_iterator</span></tt> whose
<tt class="literal"><span class="pre">m_iterator</span></tt> subobject is constructed from <tt class="literal"><span class="pre">y.base()</span></tt>.</td>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Constructs instance of <tt class="docutils literal"><span class="pre">reverse_iterator</span></tt> whose
<tt class="docutils literal"><span class="pre">m_iterator</span></tt> subobject is constructed from <tt class="docutils literal"><span class="pre">y.base()</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">Iterator</span> <span class="pre">const&amp;</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">Iterator</span> <span class="pre">const&amp;</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
<table class="docutils 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">m_iterator</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_iterator</span></tt></td>
</tr>
</tbody>
</table>
<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">
<p><tt class="docutils literal"><span class="pre">reference</span> <span class="pre">operator*()</span> <span class="pre">const;</span></tt></p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
@ -200,25 +200,25 @@ reverse_iterator(
Iterator tmp = m_iterator;
return *--tmp;
</pre>
<p><tt class="literal"><span class="pre">reverse_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">reverse_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
<table class="docutils 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"><tt class="literal"><span class="pre">--m_iterator</span></tt></td>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="docutils literal"><span class="pre">--m_iterator</span></tt></td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">*this</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">reverse_iterator&amp;</span> <span class="pre">operator--();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">reverse_iterator&amp;</span> <span class="pre">operator--();</span></tt></p>
<table class="docutils 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"><tt class="literal"><span class="pre">++m_iterator</span></tt></td>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="docutils literal"><span class="pre">++m_iterator</span></tt></td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">*this</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
</tr>
</tbody>
</table>
@ -227,12 +227,12 @@ template &lt;class BidirectionalIterator&gt;
reverse_iterator&lt;BidirectionalIterator&gt;n
make_reverse_iterator(BidirectionalIterator x);
</pre>
<table class="field-list" frame="void" rules="none">
<table class="docutils 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 instance of <tt class="literal"><span class="pre">reverse_iterator&lt;BidirectionalIterator&gt;</span></tt>
with a <tt class="literal"><span class="pre">current</span></tt> constructed from <tt class="literal"><span class="pre">x</span></tt>.</td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="docutils literal"><span class="pre">reverse_iterator&lt;BidirectionalIterator&gt;</span></tt>
with a <tt class="docutils literal"><span class="pre">current</span></tt> constructed from <tt class="docutils literal"><span class="pre">x</span></tt>.</td>
</tr>
</tbody>
</table>
@ -240,7 +240,7 @@ with a <tt class="literal"><span class="pre">current</span></tt> constructed fro
<div class="section" id="example">
<h1><a class="toc-backref" href="#id6" name="example">Example</a></h1>
<p>The following example prints an array of characters in reverse order
using <tt class="literal"><span class="pre">reverse_iterator</span></tt>.</p>
using <tt class="docutils literal"><span class="pre">reverse_iterator</span></tt>.</p>
<pre class="literal-block">
char letters_[] = &quot;hello world!&quot;;
const int N = sizeof(letters_)/sizeof(char) - 1;
@ -272,7 +272,7 @@ sequence in double-reversed (normal) order: hello world!
<p>The source code for this example can be found <a class="reference" href="../example/reverse_iterator_example.cpp">here</a>.</p>
</div>
</div>
<hr class="footer" />
<hr class="docutils footer" />
<div class="footer">
<a class="reference" href="reverse_iterator.rst">View document source</a>.
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.

BIN
doc/reverse_iterator.pdf
View File

Binary file not shown.

174
doc/transform_iterator.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.3.6: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.3.8: http://docutils.sourceforge.net/" />
<title>Transform Iterator</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" />
@ -12,6 +12,7 @@
<link rel="stylesheet" href="default.css" type="text/css" />
</head>
<body>
<div class="document" id="transform-iterator">
<h1 class="title">Transform Iterator</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
@ -31,13 +32,12 @@ Railway Operation and Construction</a></td></tr>
<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003.</td></tr>
</tbody>
</table>
<div class="document" id="transform-iterator">
<table class="field-list" frame="void" rules="none">
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">abstract:</th><td class="field-body">The transform iterator adapts an iterator by modifying the
<tt class="literal"><span class="pre">operator*</span></tt> to apply a function object to the result of
<tt class="docutils literal"><span class="pre">operator*</span></tt> to apply a function object to the result of
dereferencing the iterator and returning the result.</td>
</tr>
</tbody>
@ -45,15 +45,15 @@ dereferencing the iterator and returning the result.</td>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first"><a name="table-of-contents">Table of Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#transform-iterator-synopsis" id="id2" name="id2"><tt class="literal"><span class="pre">transform_iterator</span></tt> synopsis</a></li>
<li><a class="reference" href="#transform-iterator-requirements" id="id3" name="id3"><tt class="literal"><span class="pre">transform_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#transform-iterator-models" id="id4" name="id4"><tt class="literal"><span class="pre">transform_iterator</span></tt> models</a></li>
<li><a class="reference" href="#transform-iterator-operations" id="id5" name="id5"><tt class="literal"><span class="pre">transform_iterator</span></tt> operations</a></li>
<li><a class="reference" href="#transform-iterator-synopsis" id="id2" name="id2"><tt class="docutils literal"><span class="pre">transform_iterator</span></tt> synopsis</a></li>
<li><a class="reference" href="#transform-iterator-requirements" id="id3" name="id3"><tt class="docutils literal"><span class="pre">transform_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#transform-iterator-models" id="id4" name="id4"><tt class="docutils literal"><span class="pre">transform_iterator</span></tt> models</a></li>
<li><a class="reference" href="#transform-iterator-operations" id="id5" name="id5"><tt class="docutils literal"><span class="pre">transform_iterator</span></tt> operations</a></li>
<li><a class="reference" href="#example" id="id6" name="id6">Example</a></li>
</ul>
</div>
<div class="section" id="transform-iterator-synopsis">
<h1><a class="toc-backref" href="#id2" name="transform-iterator-synopsis"><tt class="literal"><span class="pre">transform_iterator</span></tt> synopsis</a></h1>
<h1><a class="toc-backref" href="#id2" name="transform-iterator-synopsis"><tt class="docutils literal"><span class="pre">transform_iterator</span></tt> synopsis</a></h1>
<!-- Version 1.3 of this document was accepted for TR1 -->
<pre class="literal-block">
template &lt;class UnaryFunction,
@ -88,56 +88,56 @@ private:
UnaryFunction m_f; // exposition only
};
</pre>
<p>If <tt class="literal"><span class="pre">Reference</span></tt> is <tt class="literal"><span class="pre">use_default</span></tt> then the <tt class="literal"><span class="pre">reference</span></tt> member of
<tt class="literal"><span class="pre">transform_iterator</span></tt> is
<tt class="literal"><span class="pre">result_of&lt;UnaryFunction(iterator_traits&lt;Iterator&gt;::reference)&gt;::type</span></tt>.
Otherwise, <tt class="literal"><span class="pre">reference</span></tt> is <tt class="literal"><span class="pre">Reference</span></tt>.</p>
<p>If <tt class="literal"><span class="pre">Value</span></tt> is <tt class="literal"><span class="pre">use_default</span></tt> then the <tt class="literal"><span class="pre">value_type</span></tt> member is
<tt class="literal"><span class="pre">remove_cv&lt;remove_reference&lt;reference&gt;</span> <span class="pre">&gt;::type</span></tt>. Otherwise,
<tt class="literal"><span class="pre">value_type</span></tt> is <tt class="literal"><span class="pre">Value</span></tt>.</p>
<p>If <tt class="literal"><span class="pre">Iterator</span></tt> models Readable Lvalue Iterator and if <tt class="literal"><span class="pre">Iterator</span></tt>
models Random Access Traversal Iterator, then <tt class="literal"><span class="pre">iterator_category</span></tt> is
convertible to <tt class="literal"><span class="pre">random_access_iterator_tag</span></tt>. Otherwise, if
<tt class="literal"><span class="pre">Iterator</span></tt> models Bidirectional Traversal Iterator, then
<tt class="literal"><span class="pre">iterator_category</span></tt> is convertible to
<tt class="literal"><span class="pre">bidirectional_iterator_tag</span></tt>. Otherwise <tt class="literal"><span class="pre">iterator_category</span></tt> is
convertible to <tt class="literal"><span class="pre">forward_iterator_tag</span></tt>. If <tt class="literal"><span class="pre">Iterator</span></tt> does not
model Readable Lvalue Iterator then <tt class="literal"><span class="pre">iterator_category</span></tt> is
convertible to <tt class="literal"><span class="pre">input_iterator_tag</span></tt>.</p>
<p>If <tt class="docutils literal"><span class="pre">Reference</span></tt> is <tt class="docutils literal"><span class="pre">use_default</span></tt> then the <tt class="docutils literal"><span class="pre">reference</span></tt> member of
<tt class="docutils literal"><span class="pre">transform_iterator</span></tt> is
<tt class="docutils literal"><span class="pre">result_of&lt;UnaryFunction(iterator_traits&lt;Iterator&gt;::reference)&gt;::type</span></tt>.
Otherwise, <tt class="docutils literal"><span class="pre">reference</span></tt> is <tt class="docutils literal"><span class="pre">Reference</span></tt>.</p>
<p>If <tt class="docutils literal"><span class="pre">Value</span></tt> is <tt class="docutils literal"><span class="pre">use_default</span></tt> then the <tt class="docutils literal"><span class="pre">value_type</span></tt> member is
<tt class="docutils literal"><span class="pre">remove_cv&lt;remove_reference&lt;reference&gt;</span> <span class="pre">&gt;::type</span></tt>. Otherwise,
<tt class="docutils literal"><span class="pre">value_type</span></tt> is <tt class="docutils literal"><span class="pre">Value</span></tt>.</p>
<p>If <tt class="docutils literal"><span class="pre">Iterator</span></tt> models Readable Lvalue Iterator and if <tt class="docutils literal"><span class="pre">Iterator</span></tt>
models Random Access Traversal Iterator, then <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is
convertible to <tt class="docutils literal"><span class="pre">random_access_iterator_tag</span></tt>. Otherwise, if
<tt class="docutils literal"><span class="pre">Iterator</span></tt> models Bidirectional Traversal Iterator, then
<tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible to
<tt class="docutils literal"><span class="pre">bidirectional_iterator_tag</span></tt>. Otherwise <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is
convertible to <tt class="docutils literal"><span class="pre">forward_iterator_tag</span></tt>. If <tt class="docutils literal"><span class="pre">Iterator</span></tt> does not
model Readable Lvalue Iterator then <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is
convertible to <tt class="docutils literal"><span class="pre">input_iterator_tag</span></tt>.</p>
</div>
<div class="section" id="transform-iterator-requirements">
<h1><a class="toc-backref" href="#id3" name="transform-iterator-requirements"><tt class="literal"><span class="pre">transform_iterator</span></tt> requirements</a></h1>
<p>The type <tt class="literal"><span class="pre">UnaryFunction</span></tt> must be Assignable, Copy Constructible, and
the expression <tt class="literal"><span class="pre">f(*i)</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>, <tt class="literal"><span class="pre">i</span></tt> is an object of type <tt class="literal"><span class="pre">Iterator</span></tt>, and
where the type of <tt class="literal"><span class="pre">f(*i)</span></tt> must be
<tt class="literal"><span class="pre">result_of&lt;UnaryFunction(iterator_traits&lt;Iterator&gt;::reference)&gt;::type</span></tt>.</p>
<p>The argument <tt class="literal"><span class="pre">Iterator</span></tt> shall model Readable Iterator.</p>
<h1><a class="toc-backref" href="#id3" name="transform-iterator-requirements"><tt class="docutils literal"><span class="pre">transform_iterator</span></tt> requirements</a></h1>
<p>The type <tt class="docutils literal"><span class="pre">UnaryFunction</span></tt> must be Assignable, Copy Constructible, and
the expression <tt class="docutils literal"><span class="pre">f(*i)</span></tt> must be valid where <tt class="docutils literal"><span class="pre">f</span></tt> is an object of
type <tt class="docutils literal"><span class="pre">UnaryFunction</span></tt>, <tt class="docutils literal"><span class="pre">i</span></tt> is an object of type <tt class="docutils literal"><span class="pre">Iterator</span></tt>, and
where the type of <tt class="docutils literal"><span class="pre">f(*i)</span></tt> must be
<tt class="docutils literal"><span class="pre">result_of&lt;UnaryFunction(iterator_traits&lt;Iterator&gt;::reference)&gt;::type</span></tt>.</p>
<p>The argument <tt class="docutils literal"><span class="pre">Iterator</span></tt> shall model Readable Iterator.</p>
</div>
<div class="section" id="transform-iterator-models">
<h1><a class="toc-backref" href="#id4" name="transform-iterator-models"><tt class="literal"><span class="pre">transform_iterator</span></tt> models</a></h1>
<p>The resulting <tt class="literal"><span class="pre">transform_iterator</span></tt> models the most refined of the
following that is also modeled by <tt class="literal"><span class="pre">Iterator</span></tt>.</p>
<h1><a class="toc-backref" href="#id4" name="transform-iterator-models"><tt class="docutils literal"><span class="pre">transform_iterator</span></tt> models</a></h1>
<p>The resulting <tt class="docutils literal"><span class="pre">transform_iterator</span></tt> models the most refined of the
following that is also modeled by <tt class="docutils literal"><span class="pre">Iterator</span></tt>.</p>
<blockquote>
<ul class="simple">
<li>Writable Lvalue Iterator if <tt class="literal"><span class="pre">transform_iterator::reference</span></tt> is a non-const reference.</li>
<li>Readable Lvalue Iterator if <tt class="literal"><span class="pre">transform_iterator::reference</span></tt> is a const reference.</li>
<li>Writable Lvalue Iterator if <tt class="docutils literal"><span class="pre">transform_iterator::reference</span></tt> is a non-const reference.</li>
<li>Readable Lvalue Iterator if <tt class="docutils literal"><span class="pre">transform_iterator::reference</span></tt> is a const reference.</li>
<li>Readable Iterator otherwise.</li>
</ul>
</blockquote>
<p>The <tt class="literal"><span class="pre">transform_iterator</span></tt> models the most refined standard traversal
concept that is modeled by the <tt class="literal"><span class="pre">Iterator</span></tt> argument.</p>
<p>If <tt class="literal"><span class="pre">transform_iterator</span></tt> is a model of Readable Lvalue Iterator then
<p>The <tt class="docutils literal"><span class="pre">transform_iterator</span></tt> models the most refined standard traversal
concept that is modeled by the <tt class="docutils literal"><span class="pre">Iterator</span></tt> argument.</p>
<p>If <tt class="docutils literal"><span class="pre">transform_iterator</span></tt> is a model of Readable Lvalue Iterator then
it models the following original iterator concepts depending on what
the <tt class="literal"><span class="pre">Iterator</span></tt> argument models.</p>
<table border="1" class="table">
the <tt class="docutils literal"><span class="pre">Iterator</span></tt> argument models.</p>
<table border="1" class="docutils">
<colgroup>
<col width="47%" />
<col width="53%" />
</colgroup>
<thead valign="bottom">
<tr><th>If <tt class="literal"><span class="pre">Iterator</span></tt> models</th>
<th>then <tt class="literal"><span class="pre">transform_iterator</span></tt> models</th>
<tr><th>If <tt class="docutils literal"><span class="pre">Iterator</span></tt> models</th>
<th>then <tt class="docutils literal"><span class="pre">transform_iterator</span></tt> models</th>
</tr>
</thead>
<tbody valign="top">
@ -155,34 +155,34 @@ the <tt class="literal"><span class="pre">Iterator</span></tt> argument models.<
</tr>
</tbody>
</table>
<p>If <tt class="literal"><span class="pre">transform_iterator</span></tt> models Writable Lvalue Iterator then it is a
<p>If <tt class="docutils literal"><span class="pre">transform_iterator</span></tt> models Writable Lvalue Iterator then it is a
mutable iterator (as defined in the old iterator requirements).</p>
<p><tt class="literal"><span class="pre">transform_iterator&lt;F1,</span> <span class="pre">X,</span> <span class="pre">R1,</span> <span class="pre">V1&gt;</span></tt> is interoperable with
<tt class="literal"><span class="pre">transform_iterator&lt;F2,</span> <span class="pre">Y,</span> <span class="pre">R2,</span> <span class="pre">V2&gt;</span></tt> if and only if <tt class="literal"><span class="pre">X</span></tt> is
interoperable with <tt class="literal"><span class="pre">Y</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">transform_iterator&lt;F1,</span> <span class="pre">X,</span> <span class="pre">R1,</span> <span class="pre">V1&gt;</span></tt> is interoperable with
<tt class="docutils literal"><span class="pre">transform_iterator&lt;F2,</span> <span class="pre">Y,</span> <span class="pre">R2,</span> <span class="pre">V2&gt;</span></tt> if and only if <tt class="docutils literal"><span class="pre">X</span></tt> is
interoperable with <tt class="docutils literal"><span class="pre">Y</span></tt>.</p>
</div>
<div class="section" id="transform-iterator-operations">
<h1><a class="toc-backref" href="#id5" name="transform-iterator-operations"><tt class="literal"><span class="pre">transform_iterator</span></tt> operations</a></h1>
<h1><a class="toc-backref" href="#id5" name="transform-iterator-operations"><tt class="docutils literal"><span class="pre">transform_iterator</span></tt> operations</a></h1>
<p>In addition to the operations required by the concepts modeled by
<tt class="literal"><span class="pre">transform_iterator</span></tt>, <tt class="literal"><span class="pre">transform_iterator</span></tt> provides the following
<tt class="docutils literal"><span class="pre">transform_iterator</span></tt>, <tt class="docutils literal"><span class="pre">transform_iterator</span></tt> provides the following
operations.</p>
<p><tt class="literal"><span class="pre">transform_iterator();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">transform_iterator();</span></tt></p>
<table class="docutils 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 instance of <tt class="literal"><span class="pre">transform_iterator</span></tt> with <tt class="literal"><span class="pre">m_f</span></tt>
and <tt class="literal"><span class="pre">m_iterator</span></tt> default constructed.</td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="docutils literal"><span class="pre">transform_iterator</span></tt> with <tt class="docutils literal"><span class="pre">m_f</span></tt>
and <tt class="docutils literal"><span class="pre">m_iterator</span></tt> default constructed.</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">transform_iterator(Iterator</span> <span class="pre">const&amp;</span> <span class="pre">x,</span> <span class="pre">UnaryFunction</span> <span class="pre">f);</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">transform_iterator(Iterator</span> <span class="pre">const&amp;</span> <span class="pre">x,</span> <span class="pre">UnaryFunction</span> <span class="pre">f);</span></tt></p>
<table class="docutils 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 instance of <tt class="literal"><span class="pre">transform_iterator</span></tt> with <tt class="literal"><span class="pre">m_f</span></tt>
initialized to <tt class="literal"><span class="pre">f</span></tt> and <tt class="literal"><span class="pre">m_iterator</span></tt> initialized to <tt class="literal"><span class="pre">x</span></tt>.</td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="docutils literal"><span class="pre">transform_iterator</span></tt> with <tt class="docutils literal"><span class="pre">m_f</span></tt>
initialized to <tt class="docutils literal"><span class="pre">f</span></tt> and <tt class="docutils literal"><span class="pre">m_iterator</span></tt> initialized to <tt class="docutils literal"><span class="pre">x</span></tt>.</td>
</tr>
</tbody>
</table>
@ -194,64 +194,64 @@ transform_iterator(
, typename enable_if_convertible&lt;F2, UnaryFunction&gt;::type* = 0 // exposition only
);
</pre>
<table class="field-list" frame="void" rules="none">
<table class="docutils 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 instance of <tt class="literal"><span class="pre">transform_iterator</span></tt> with <tt class="literal"><span class="pre">m_f</span></tt>
initialized to <tt class="literal"><span class="pre">t.functor()</span></tt> and <tt class="literal"><span class="pre">m_iterator</span></tt> initialized to
<tt class="literal"><span class="pre">t.base()</span></tt>.</td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="docutils literal"><span class="pre">transform_iterator</span></tt> with <tt class="docutils literal"><span class="pre">m_f</span></tt>
initialized to <tt class="docutils literal"><span class="pre">t.functor()</span></tt> and <tt class="docutils literal"><span class="pre">m_iterator</span></tt> initialized to
<tt class="docutils literal"><span class="pre">t.base()</span></tt>.</td>
</tr>
<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="literal"><span class="pre">OtherIterator</span></tt> is implicitly convertible to <tt class="literal"><span class="pre">Iterator</span></tt>.</td>
<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="docutils literal"><span class="pre">OtherIterator</span></tt> is implicitly convertible to <tt class="docutils literal"><span class="pre">Iterator</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">UnaryFunction</span> <span class="pre">functor()</span> <span class="pre">const;</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">UnaryFunction</span> <span class="pre">functor()</span> <span class="pre">const;</span></tt></p>
<table class="docutils 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">m_f</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_f</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">Iterator</span> <span class="pre">const&amp;</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">Iterator</span> <span class="pre">const&amp;</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
<table class="docutils 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">m_iterator</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_iterator</span></tt></td>
</tr>
</tbody>
</table>
<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">
<p><tt class="docutils literal"><span class="pre">reference</span> <span class="pre">operator*()</span> <span class="pre">const;</span></tt></p>
<table class="docutils 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">m_f(*m_iterator)</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_f(*m_iterator)</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">transform_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">transform_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
<table class="docutils 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"><tt class="literal"><span class="pre">++m_iterator</span></tt></td>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="docutils literal"><span class="pre">++m_iterator</span></tt></td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">*this</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">transform_iterator&amp;</span> <span class="pre">operator--();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">transform_iterator&amp;</span> <span class="pre">operator--();</span></tt></p>
<table class="docutils 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"><tt class="literal"><span class="pre">--m_iterator</span></tt></td>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="docutils literal"><span class="pre">--m_iterator</span></tt></td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">*this</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
</tr>
</tbody>
</table>
@ -260,12 +260,12 @@ template &lt;class UnaryFunction, class Iterator&gt;
transform_iterator&lt;UnaryFunction, Iterator&gt;
make_transform_iterator(Iterator it, UnaryFunction fun);
</pre>
<table class="field-list" frame="void" rules="none">
<table class="docutils 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 instance of <tt class="literal"><span class="pre">transform_iterator&lt;UnaryFunction,</span> <span class="pre">Iterator&gt;</span></tt> with <tt class="literal"><span class="pre">m_f</span></tt>
initialized to <tt class="literal"><span class="pre">f</span></tt> and <tt class="literal"><span class="pre">m_iterator</span></tt> initialized to <tt class="literal"><span class="pre">x</span></tt>.</td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="docutils literal"><span class="pre">transform_iterator&lt;UnaryFunction,</span> <span class="pre">Iterator&gt;</span></tt> with <tt class="docutils literal"><span class="pre">m_f</span></tt>
initialized to <tt class="docutils literal"><span class="pre">f</span></tt> and <tt class="docutils literal"><span class="pre">m_iterator</span></tt> initialized to <tt class="docutils literal"><span class="pre">x</span></tt>.</td>
</tr>
</tbody>
</table>
@ -274,12 +274,12 @@ template &lt;class UnaryFunction, class Iterator&gt;
transform_iterator&lt;UnaryFunction, Iterator&gt;
make_transform_iterator(Iterator it);
</pre>
<table class="field-list" frame="void" rules="none">
<table class="docutils 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 instance of <tt class="literal"><span class="pre">transform_iterator&lt;UnaryFunction,</span> <span class="pre">Iterator&gt;</span></tt> with <tt class="literal"><span class="pre">m_f</span></tt>
default constructed and <tt class="literal"><span class="pre">m_iterator</span></tt> initialized to <tt class="literal"><span class="pre">x</span></tt>.</td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="docutils literal"><span class="pre">transform_iterator&lt;UnaryFunction,</span> <span class="pre">Iterator&gt;</span></tt> with <tt class="docutils literal"><span class="pre">m_f</span></tt>
default constructed and <tt class="docutils literal"><span class="pre">m_iterator</span></tt> initialized to <tt class="docutils literal"><span class="pre">x</span></tt>.</td>
</tr>
</tbody>
</table>
@ -321,7 +321,7 @@ adding 4 to each element in the array:
<p>The source code for this example can be found <a class="reference" href="../example/transform_iterator_example.cpp">here</a>.</p>
</div>
</div>
<hr class="footer" />
<hr class="docutils footer" />
<div class="footer">
<a class="reference" href="transform_iterator.rst">View document source</a>.
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.

BIN
doc/transform_iterator.pdf
View File

Binary file not shown.

156
doc/zip_iterator.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.3.6: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.3.8: http://docutils.sourceforge.net/" />
<title>Zip Iterator</title>
<meta name="author" content="David Abrahams, Thomas Becker" />
<meta name="organization" content="Boost Consulting, Zephyr Associates, Inc." />
@ -12,6 +12,7 @@
<link rel="stylesheet" href="default.css" type="text/css" />
</head>
<body>
<div class="document" id="zip-iterator">
<h1 class="title">Zip Iterator</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
@ -29,8 +30,7 @@
<td>Copyright David Abrahams and Thomas Becker 2003.</td></tr>
</tbody>
</table>
<div class="document" id="zip-iterator">
<table class="field-list" frame="void" rules="none">
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
@ -46,15 +46,15 @@ the results of dereferencing the individual iterators.</td>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first"><a name="table-of-contents">Table of Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#zip-iterator-synopsis" id="id1" name="id1"><tt class="literal"><span class="pre">zip_iterator</span></tt> synopsis</a></li>
<li><a class="reference" href="#zip-iterator-requirements" id="id2" name="id2"><tt class="literal"><span class="pre">zip_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#zip-iterator-models" id="id3" name="id3"><tt class="literal"><span class="pre">zip_iterator</span></tt> models</a></li>
<li><a class="reference" href="#zip-iterator-operations" id="id4" name="id4"><tt class="literal"><span class="pre">zip_iterator</span></tt> operations</a></li>
<li><a class="reference" href="#zip-iterator-synopsis" id="id1" name="id1"><tt class="docutils literal"><span class="pre">zip_iterator</span></tt> synopsis</a></li>
<li><a class="reference" href="#zip-iterator-requirements" id="id2" name="id2"><tt class="docutils literal"><span class="pre">zip_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#zip-iterator-models" id="id3" name="id3"><tt class="docutils literal"><span class="pre">zip_iterator</span></tt> models</a></li>
<li><a class="reference" href="#zip-iterator-operations" id="id4" name="id4"><tt class="docutils literal"><span class="pre">zip_iterator</span></tt> operations</a></li>
<li><a class="reference" href="#examples" id="id5" name="id5">Examples</a></li>
</ul>
</div>
<div class="section" id="zip-iterator-synopsis">
<h1><a class="toc-backref" href="#id1" name="zip-iterator-synopsis"><tt class="literal"><span class="pre">zip_iterator</span></tt> synopsis</a></h1>
<h1><a class="toc-backref" href="#id1" name="zip-iterator-synopsis"><tt class="docutils literal"><span class="pre">zip_iterator</span></tt> synopsis</a></h1>
<pre class="literal-block">
template&lt;typename IteratorTuple&gt;
class zip_iterator
@ -88,67 +88,67 @@ template&lt;typename IteratorTuple&gt;
zip_iterator&lt;IteratorTuple&gt;
make_zip_iterator(IteratorTuple t);
</pre>
<p>The <tt class="literal"><span class="pre">reference</span></tt> member of <tt class="literal"><span class="pre">zip_iterator</span></tt> is the type of the tuple
made of the reference types of the iterator types in the <tt class="literal"><span class="pre">IteratorTuple</span></tt>
<p>The <tt class="docutils literal"><span class="pre">reference</span></tt> member of <tt class="docutils literal"><span class="pre">zip_iterator</span></tt> is the type of the tuple
made of the reference types of the iterator types in the <tt class="docutils literal"><span class="pre">IteratorTuple</span></tt>
argument.</p>
<p>The <tt class="literal"><span class="pre">difference_type</span></tt> member of <tt class="literal"><span class="pre">zip_iterator</span></tt> is the <tt class="literal"><span class="pre">difference_type</span></tt>
of the first of the iterator types in the <tt class="literal"><span class="pre">IteratorTuple</span></tt> argument.</p>
<p>The <tt class="literal"><span class="pre">iterator_category</span></tt> member of <tt class="literal"><span class="pre">zip_iterator</span></tt> is convertible to the
minimum of the traversal categories of the iterator types in the <tt class="literal"><span class="pre">IteratorTuple</span></tt>
argument. For example, if the <tt class="literal"><span class="pre">zip_iterator</span></tt> holds only vector
iterators, then <tt class="literal"><span class="pre">iterator_category</span></tt> is convertible to
<tt class="literal"><span class="pre">boost::random_access_traversal_tag</span></tt>. If you add a list iterator, then
<tt class="literal"><span class="pre">iterator_category</span></tt> will be convertible to <tt class="literal"><span class="pre">boost::bidirectional_traversal_tag</span></tt>,
but no longer to <tt class="literal"><span class="pre">boost::random_access_traversal_tag</span></tt>.</p>
<p>The <tt class="docutils literal"><span class="pre">difference_type</span></tt> member of <tt class="docutils literal"><span class="pre">zip_iterator</span></tt> is the <tt class="docutils literal"><span class="pre">difference_type</span></tt>
of the first of the iterator types in the <tt class="docutils literal"><span class="pre">IteratorTuple</span></tt> argument.</p>
<p>The <tt class="docutils literal"><span class="pre">iterator_category</span></tt> member of <tt class="docutils literal"><span class="pre">zip_iterator</span></tt> is convertible to the
minimum of the traversal categories of the iterator types in the <tt class="docutils literal"><span class="pre">IteratorTuple</span></tt>
argument. For example, if the <tt class="docutils literal"><span class="pre">zip_iterator</span></tt> holds only vector
iterators, then <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible to
<tt class="docutils literal"><span class="pre">boost::random_access_traversal_tag</span></tt>. If you add a list iterator, then
<tt class="docutils literal"><span class="pre">iterator_category</span></tt> will be convertible to <tt class="docutils literal"><span class="pre">boost::bidirectional_traversal_tag</span></tt>,
but no longer to <tt class="docutils literal"><span class="pre">boost::random_access_traversal_tag</span></tt>.</p>
</div>
<div class="section" id="zip-iterator-requirements">
<h1><a class="toc-backref" href="#id2" name="zip-iterator-requirements"><tt class="literal"><span class="pre">zip_iterator</span></tt> requirements</a></h1>
<p>All iterator types in the argument <tt class="literal"><span class="pre">IteratorTuple</span></tt> shall model Readable Iterator.</p>
<h1><a class="toc-backref" href="#id2" name="zip-iterator-requirements"><tt class="docutils literal"><span class="pre">zip_iterator</span></tt> requirements</a></h1>
<p>All iterator types in the argument <tt class="docutils literal"><span class="pre">IteratorTuple</span></tt> shall model Readable Iterator.</p>
</div>
<div class="section" id="zip-iterator-models">
<h1><a class="toc-backref" href="#id3" name="zip-iterator-models"><tt class="literal"><span class="pre">zip_iterator</span></tt> models</a></h1>
<p>The resulting <tt class="literal"><span class="pre">zip_iterator</span></tt> models Readable Iterator.</p>
<p>The fact that the <tt class="literal"><span class="pre">zip_iterator</span></tt> models only Readable Iterator does not
<h1><a class="toc-backref" href="#id3" name="zip-iterator-models"><tt class="docutils literal"><span class="pre">zip_iterator</span></tt> models</a></h1>
<p>The resulting <tt class="docutils literal"><span class="pre">zip_iterator</span></tt> models Readable Iterator.</p>
<p>The fact that the <tt class="docutils literal"><span class="pre">zip_iterator</span></tt> models only Readable Iterator does not
prevent you from modifying the values that the individual iterators point
to. The tuple returned by the <tt class="literal"><span class="pre">zip_iterator</span></tt>'s <tt class="literal"><span class="pre">operator*</span></tt> is a tuple
to. The tuple returned by the <tt class="docutils literal"><span class="pre">zip_iterator</span></tt>'s <tt class="docutils literal"><span class="pre">operator*</span></tt> is a tuple
constructed from the reference types of the individual iterators, not
their value types. For example, if <tt class="literal"><span class="pre">zip_it</span></tt> is a <tt class="literal"><span class="pre">zip_iterator</span></tt> whose
first member iterator is an <tt class="literal"><span class="pre">std::vector&lt;double&gt;::iterator</span></tt>, then the
their value types. For example, if <tt class="docutils literal"><span class="pre">zip_it</span></tt> is a <tt class="docutils literal"><span class="pre">zip_iterator</span></tt> whose
first member iterator is an <tt class="docutils literal"><span class="pre">std::vector&lt;double&gt;::iterator</span></tt>, then the
following line will modify the value which the first member iterator of
<tt class="literal"><span class="pre">zip_it</span></tt> currently points to:</p>
<tt class="docutils literal"><span class="pre">zip_it</span></tt> currently points to:</p>
<pre class="literal-block">
zip_it-&gt;get&lt;0&gt;() = 42.0;
</pre>
<p>Consider the set of standard traversal concepts obtained by taking
the most refined standard traversal concept modeled by each individual
iterator type in the <tt class="literal"><span class="pre">IteratorTuple</span></tt> argument.The <tt class="literal"><span class="pre">zip_iterator</span></tt>
iterator type in the <tt class="docutils literal"><span class="pre">IteratorTuple</span></tt> argument.The <tt class="docutils literal"><span class="pre">zip_iterator</span></tt>
models the least refined standard traversal concept in this set.</p>
<p><tt class="literal"><span class="pre">zip_iterator&lt;IteratorTuple1&gt;</span></tt> is interoperable with
<tt class="literal"><span class="pre">zip_iterator&lt;IteratorTuple2&gt;</span></tt> if and only if <tt class="literal"><span class="pre">IteratorTuple1</span></tt>
is interoperable with <tt class="literal"><span class="pre">IteratorTuple2</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">zip_iterator&lt;IteratorTuple1&gt;</span></tt> is interoperable with
<tt class="docutils literal"><span class="pre">zip_iterator&lt;IteratorTuple2&gt;</span></tt> if and only if <tt class="docutils literal"><span class="pre">IteratorTuple1</span></tt>
is interoperable with <tt class="docutils literal"><span class="pre">IteratorTuple2</span></tt>.</p>
</div>
<div class="section" id="zip-iterator-operations">
<h1><a class="toc-backref" href="#id4" name="zip-iterator-operations"><tt class="literal"><span class="pre">zip_iterator</span></tt> operations</a></h1>
<h1><a class="toc-backref" href="#id4" name="zip-iterator-operations"><tt class="docutils literal"><span class="pre">zip_iterator</span></tt> operations</a></h1>
<p>In addition to the operations required by the concepts modeled by
<tt class="literal"><span class="pre">zip_iterator</span></tt>, <tt class="literal"><span class="pre">zip_iterator</span></tt> provides the following
<tt class="docutils literal"><span class="pre">zip_iterator</span></tt>, <tt class="docutils literal"><span class="pre">zip_iterator</span></tt> provides the following
operations.</p>
<p><tt class="literal"><span class="pre">zip_iterator();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">zip_iterator();</span></tt></p>
<table class="docutils 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 instance of <tt class="literal"><span class="pre">zip_iterator</span></tt> with <tt class="literal"><span class="pre">m_iterator_tuple</span></tt>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="docutils literal"><span class="pre">zip_iterator</span></tt> with <tt class="docutils literal"><span class="pre">m_iterator_tuple</span></tt>
default constructed.</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">zip_iterator(IteratorTuple</span> <span class="pre">iterator_tuple);</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">zip_iterator(IteratorTuple</span> <span class="pre">iterator_tuple);</span></tt></p>
<table class="docutils 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 instance of <tt class="literal"><span class="pre">zip_iterator</span></tt> with <tt class="literal"><span class="pre">m_iterator_tuple</span></tt>
initialized to <tt class="literal"><span class="pre">iterator_tuple</span></tt>.</td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="docutils literal"><span class="pre">zip_iterator</span></tt> with <tt class="docutils literal"><span class="pre">m_iterator_tuple</span></tt>
initialized to <tt class="docutils literal"><span class="pre">iterator_tuple</span></tt>.</td>
</tr>
</tbody>
</table>
@ -161,54 +161,54 @@ zip_iterator(
, IteratorTuple&gt;::type* = 0 // exposition only
);
</pre>
<table class="field-list" frame="void" rules="none">
<table class="docutils 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 instance of <tt class="literal"><span class="pre">zip_iterator</span></tt> that is a copy of <tt class="literal"><span class="pre">other</span></tt>.</td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="docutils literal"><span class="pre">zip_iterator</span></tt> that is a copy of <tt class="docutils literal"><span class="pre">other</span></tt>.</td>
</tr>
<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="literal"><span class="pre">OtherIteratorTuple</span></tt> is implicitly convertible to <tt class="literal"><span class="pre">IteratorTuple</span></tt>.</td>
<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="docutils literal"><span class="pre">OtherIteratorTuple</span></tt> is implicitly convertible to <tt class="docutils literal"><span class="pre">IteratorTuple</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">const</span> <span class="pre">IteratorTuple&amp;</span> <span class="pre">get_iterator_tuple()</span> <span class="pre">const;</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">const</span> <span class="pre">IteratorTuple&amp;</span> <span class="pre">get_iterator_tuple()</span> <span class="pre">const;</span></tt></p>
<table class="docutils 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">m_iterator_tuple</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_iterator_tuple</span></tt></td>
</tr>
</tbody>
</table>
<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">
<p><tt class="docutils literal"><span class="pre">reference</span> <span class="pre">operator*()</span> <span class="pre">const;</span></tt></p>
<table class="docutils 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">A tuple consisting of the results of dereferencing all iterators in
<tt class="literal"><span class="pre">m_iterator_tuple</span></tt>.</td>
<tt class="docutils literal"><span class="pre">m_iterator_tuple</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">zip_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">zip_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
<table class="docutils 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">Increments each iterator in <tt class="literal"><span class="pre">m_iterator_tuple</span></tt>.</td>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Increments each iterator in <tt class="docutils literal"><span class="pre">m_iterator_tuple</span></tt>.</td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">*this</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">zip_iterator&amp;</span> <span class="pre">operator--();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<p><tt class="docutils literal"><span class="pre">zip_iterator&amp;</span> <span class="pre">operator--();</span></tt></p>
<table class="docutils 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">Decrements each iterator in <tt class="literal"><span class="pre">m_iterator_tuple</span></tt>.</td>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Decrements each iterator in <tt class="docutils literal"><span class="pre">m_iterator_tuple</span></tt>.</td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">*this</span></tt></td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
</tr>
</tbody>
</table>
@ -217,12 +217,12 @@ template&lt;typename IteratorTuple&gt;
zip_iterator&lt;IteratorTuple&gt;
make_zip_iterator(IteratorTuple t);
</pre>
<table class="field-list" frame="void" rules="none">
<table class="docutils 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 instance of <tt class="literal"><span class="pre">zip_iterator&lt;IteratorTuple&gt;</span></tt> with <tt class="literal"><span class="pre">m_iterator_tuple</span></tt>
initialized to <tt class="literal"><span class="pre">t</span></tt>.</td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="docutils literal"><span class="pre">zip_iterator&lt;IteratorTuple&gt;</span></tt> with <tt class="docutils literal"><span class="pre">m_iterator_tuple</span></tt>
initialized to <tt class="docutils literal"><span class="pre">t</span></tt>.</td>
</tr>
</tbody>
</table>
@ -231,24 +231,24 @@ template&lt;typename IteratorTuple&gt;
zip_iterator&lt;IteratorTuple&gt;
make_zip_iterator(IteratorTuple t);
</pre>
<table class="field-list" frame="void" rules="none">
<table class="docutils 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 instance of <tt class="literal"><span class="pre">zip_iterator&lt;IteratorTuple&gt;</span></tt> with <tt class="literal"><span class="pre">m_iterator_tuple</span></tt>
initialized to <tt class="literal"><span class="pre">t</span></tt>.</td>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="docutils literal"><span class="pre">zip_iterator&lt;IteratorTuple&gt;</span></tt> with <tt class="docutils literal"><span class="pre">m_iterator_tuple</span></tt>
initialized to <tt class="docutils literal"><span class="pre">t</span></tt>.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples">
<h1><a class="toc-backref" href="#id5" name="examples">Examples</a></h1>
<p>There are two main types of applications of the <tt class="literal"><span class="pre">zip_iterator</span></tt>. The first
<p>There are two main types of applications of the <tt class="docutils literal"><span class="pre">zip_iterator</span></tt>. The first
one concerns runtime efficiency: If one has several controlled sequences
of the same length that must be somehow processed, e.g., with the
<tt class="literal"><span class="pre">for_each</span></tt> algorithm, then it is more efficient to perform just
<tt class="docutils literal"><span class="pre">for_each</span></tt> algorithm, then it is more efficient to perform just
one parallel-iteration rather than several individual iterations. For an
example, assume that <tt class="literal"><span class="pre">vect_of_doubles</span></tt> and <tt class="literal"><span class="pre">vect_of_ints</span></tt>
example, assume that <tt class="docutils literal"><span class="pre">vect_of_doubles</span></tt> and <tt class="docutils literal"><span class="pre">vect_of_ints</span></tt>
are two vectors of equal length containing doubles and ints, respectively,
and consider the following two iterations:</p>
<pre class="literal-block">
@ -272,7 +272,7 @@ std::for_each(
zip_func()
);
</pre>
<p>A non-generic implementation of <tt class="literal"><span class="pre">zip_func</span></tt> could look as follows:</p>
<p>A non-generic implementation of <tt class="docutils literal"><span class="pre">zip_func</span></tt> could look as follows:</p>
<pre class="literal-block">
struct zip_func :
public std::unary_function&lt;const boost::tuple&lt;const double&amp;, const int&amp;&gt;&amp;, void&gt;
@ -288,23 +288,23 @@ private:
func_1 m_f1;
};
</pre>
<p>The second important application of the <tt class="literal"><span class="pre">zip_iterator</span></tt> is as a building block
<p>The second important application of the <tt class="docutils literal"><span class="pre">zip_iterator</span></tt> is as a building block
to make combining iterators. A combining iterator is an iterator
that parallel-iterates over several controlled sequences and, upon
dereferencing, returns the result of applying a functor to the values of the
sequences at the respective positions. This can now be achieved by using the
<tt class="literal"><span class="pre">zip_iterator</span></tt> in conjunction with the <tt class="literal"><span class="pre">transform_iterator</span></tt>.</p>
<tt class="docutils literal"><span class="pre">zip_iterator</span></tt> in conjunction with the <tt class="docutils literal"><span class="pre">transform_iterator</span></tt>.</p>
<p>Suppose, for example, that you have two vectors of doubles, say
<tt class="literal"><span class="pre">vect_1</span></tt> and <tt class="literal"><span class="pre">vect_2</span></tt>, and you need to expose to a client
<tt class="docutils literal"><span class="pre">vect_1</span></tt> and <tt class="docutils literal"><span class="pre">vect_2</span></tt>, and you need to expose to a client
a controlled sequence containing the products of the elements of
<tt class="literal"><span class="pre">vect_1</span></tt> and <tt class="literal"><span class="pre">vect_2</span></tt>. Rather than placing these products
<tt class="docutils literal"><span class="pre">vect_1</span></tt> and <tt class="docutils literal"><span class="pre">vect_2</span></tt>. Rather than placing these products
in a third vector, you can use a combining iterator that calculates the
products on the fly. Let us assume that <tt class="literal"><span class="pre">tuple_multiplies</span></tt> is a
functor that works like <tt class="literal"><span class="pre">std::multiplies</span></tt>, except that it takes
products on the fly. Let us assume that <tt class="docutils literal"><span class="pre">tuple_multiplies</span></tt> is a
functor that works like <tt class="docutils literal"><span class="pre">std::multiplies</span></tt>, except that it takes
its two arguments packaged in a tuple. Then the two iterators
<tt class="literal"><span class="pre">it_begin</span></tt> and <tt class="literal"><span class="pre">it_end</span></tt> defined below delimit a controlled
sequence containing the products of the elements of <tt class="literal"><span class="pre">vect_1</span></tt> and
<tt class="literal"><span class="pre">vect_2</span></tt>:</p>
<tt class="docutils literal"><span class="pre">it_begin</span></tt> and <tt class="docutils literal"><span class="pre">it_end</span></tt> defined below delimit a controlled
sequence containing the products of the elements of <tt class="docutils literal"><span class="pre">vect_1</span></tt> and
<tt class="docutils literal"><span class="pre">vect_2</span></tt>:</p>
<pre class="literal-block">
typedef boost::tuple&lt;
std::vector&lt;double&gt;::const_iterator,
@ -342,7 +342,7 @@ the_transform_iterator it_end(
</pre>
</div>
</div>
<hr class="footer" />
<hr class="docutils footer" />
<div class="footer">
<a class="reference" href="zip_iterator.rst">View document source</a>.
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.

BIN
doc/zip_iterator.pdf
View File

Binary file not shown.