Add missing license/copyright

[SVN r35070]
This commit is contained in:
Dave Abrahams
2006-09-11 22:27:29 +00:00
parent f482354ffd
commit 5184d64b80
95 changed files with 10347 additions and 1233 deletions

View File

@ -3,13 +3,295 @@
<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.8: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Iterator Facade</title>
<meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" />
<meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, University of Hanover Institute for Transport Railway Operation and Construction" />
<meta name="date" content="2004-11-01" />
<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003." />
<link rel="stylesheet" href="default.css" type="text/css" />
<style type="text/css">
/*
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:Date: $Date$
:Revision: $Revision$
:Copyright: This stylesheet has been placed in the public domain.
Default cascading style sheet for the HTML output of Docutils.
See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/
/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
border: 0 }
table.borderless td, table.borderless th {
/* Override padding for "table.docutils td" with "! important".
The right padding separates the table cells. */
padding: 0 0.5em 0 0 ! important }
.first {
/* Override more specific margin styles with "! important". */
margin-top: 0 ! important }
.last, .with-subtitle {
margin-bottom: 0 ! important }
.hidden {
display: none }
a.toc-backref {
text-decoration: none ;
color: black }
blockquote.epigraph {
margin: 2em 5em ; }
dl.docutils dd {
margin-bottom: 0.5em }
/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
font-weight: bold }
*/
div.abstract {
margin: 2em 5em }
div.abstract p.topic-title {
font-weight: bold ;
text-align: center }
div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
margin: 2em ;
border: medium outset ;
padding: 1em }
div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
font-weight: bold ;
font-family: sans-serif }
div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
color: red ;
font-weight: bold ;
font-family: sans-serif }
/* Uncomment (and remove this text!) to get reduced vertical space in
compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
margin-bottom: 0.5em }
div.compound .compound-last, div.compound .compound-middle {
margin-top: 0.5em }
*/
div.dedication {
margin: 2em 5em ;
text-align: center ;
font-style: italic }
div.dedication p.topic-title {
font-weight: bold ;
font-style: normal }
div.figure {
margin-left: 2em ;
margin-right: 2em }
div.footer, div.header {
clear: both;
font-size: smaller }
div.line-block {
display: block ;
margin-top: 1em ;
margin-bottom: 1em }
div.line-block div.line-block {
margin-top: 0 ;
margin-bottom: 0 ;
margin-left: 1.5em }
div.sidebar {
margin-left: 1em ;
border: medium outset ;
padding: 1em ;
background-color: #ffffee ;
width: 40% ;
float: right ;
clear: right }
div.sidebar p.rubric {
font-family: sans-serif ;
font-size: medium }
div.system-messages {
margin: 5em }
div.system-messages h1 {
color: red }
div.system-message {
border: medium outset ;
padding: 1em }
div.system-message p.system-message-title {
color: red ;
font-weight: bold }
div.topic {
margin: 2em }
h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
margin-top: 0.4em }
h1.title {
text-align: center }
h2.subtitle {
text-align: center }
hr.docutils {
width: 75% }
img.align-left {
clear: left }
img.align-right {
clear: right }
ol.simple, ul.simple {
margin-bottom: 1em }
ol.arabic {
list-style: decimal }
ol.loweralpha {
list-style: lower-alpha }
ol.upperalpha {
list-style: upper-alpha }
ol.lowerroman {
list-style: lower-roman }
ol.upperroman {
list-style: upper-roman }
p.attribution {
text-align: right ;
margin-left: 50% }
p.caption {
font-style: italic }
p.credits {
font-style: italic ;
font-size: smaller }
p.label {
white-space: nowrap }
p.rubric {
font-weight: bold ;
font-size: larger ;
color: maroon ;
text-align: center }
p.sidebar-title {
font-family: sans-serif ;
font-weight: bold ;
font-size: larger }
p.sidebar-subtitle {
font-family: sans-serif ;
font-weight: bold }
p.topic-title {
font-weight: bold }
pre.address {
margin-bottom: 0 ;
margin-top: 0 ;
font-family: serif ;
font-size: 100% }
pre.literal-block, pre.doctest-block {
margin-left: 2em ;
margin-right: 2em ;
background-color: #eeeeee }
span.classifier {
font-family: sans-serif ;
font-style: oblique }
span.classifier-delimiter {
font-family: sans-serif ;
font-weight: bold }
span.interpreted {
font-family: sans-serif }
span.option {
white-space: nowrap }
span.pre {
white-space: pre }
span.problematic {
color: red }
span.section-subtitle {
/* font-size relative to parent (h1..h6 element) */
font-size: 80% }
table.citation {
border-left: solid 1px gray;
margin-left: 1px }
table.docinfo {
margin: 2em 4em }
table.docutils {
margin-top: 0.5em ;
margin-bottom: 0.5em }
table.footnote {
border-left: solid 1px black;
margin-left: 1px }
table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
padding-left: 0.5em ;
padding-right: 0.5em ;
vertical-align: top }
table.docutils th.field-name, table.docinfo th.docinfo-name {
font-weight: bold ;
text-align: left ;
white-space: nowrap ;
padding-left: 0 }
h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
font-size: 100% }
tt.docutils {
background-color: #eeeeee }
ul.auto-toc {
list-style-type: none }
</style>
</head>
<body>
<div class="document" id="iterator-facade">
@ -32,18 +314,24 @@ Railway Operation and Construction</a></td></tr>
<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003.</td></tr>
</tbody>
</table>
<!-- Distributed under 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) -->
<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="docutils literal"><span class="pre">iterator_facade</span></tt> is a base class template that implements the
<tr class="field"><th class="field-name">abstract:</th><td class="field-body"><!-- Copyright David Abrahams 2006. Distributed under 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) -->
<tt class="docutils literal"><span class="pre">iterator_facade</span></tt> is a base class template that implements the
interface of standard iterators in terms of a few core functions
and associated types, to be supplied by a derived iterator class.</td>
</tr>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first"><a name="table-of-contents">Table of Contents</a></p>
<div class="contents topic">
<p class="topic-title first"><a id="table-of-contents" name="table-of-contents">Table of Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#overview" id="id23" name="id23">Overview</a><ul>
<li><a class="reference" href="#usage" id="id24" name="id24">Usage</a></li>
@ -80,11 +368,14 @@ and associated types, to be supplied by a derived iterator class.</td>
</li>
</ul>
</div>
<div class="section" id="overview">
<h1><a class="toc-backref" href="#id23" name="overview">Overview</a></h1>
<div class="section">
<h1><a class="toc-backref" href="#id23" id="overview" name="overview">Overview</a></h1>
<!-- Distributed under 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) -->
<!-- Version 1.1 of this ReStructuredText document corresponds to
n1530_, the paper accepted by the LWG for TR1. -->
<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. -->
<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. -->
<p>While the iterator interface is rich, there is a core subset of the
interface that is necessary for all the functionality. We have
identified the following core behaviors for iterators:</p>
@ -124,8 +415,8 @@ iterators, and a separate <tt class="docutils literal"><span class="pre">iterato
impossible.</li>
</ol>
</blockquote>
<div class="section" id="usage">
<h2><a class="toc-backref" href="#id24" name="usage">Usage</a></h2>
<div class="section">
<h2><a class="toc-backref" href="#id24" id="usage" name="usage">Usage</a></h2>
<p>The user of <tt class="docutils literal"><span class="pre">iterator_facade</span></tt> derives his iterator class from a
specialization of <tt class="docutils literal"><span class="pre">iterator_facade</span></tt> and passes the derived
iterator class as <tt class="docutils literal"><span class="pre">iterator_facade</span></tt>'s first template parameter.
@ -148,8 +439,8 @@ requirements.</p>
<col width="56%" />
</colgroup>
<thead valign="bottom">
<tr><th>Expression</th>
<th>Effects</th>
<tr><th class="head">Expression</th>
<th class="head">Effects</th>
</tr>
</thead>
<tbody valign="top">
@ -188,8 +479,8 @@ constructor. Finally, if the iterator is to model Forward Traversal
Iterator or a more-refined iterator concept, a default constructor is
required.</p>
</div>
<div class="section" id="iterator-core-access">
<h2><a class="toc-backref" href="#id25" name="iterator-core-access">Iterator Core Access</a></h2>
<div class="section">
<h2><a class="toc-backref" href="#id25" id="iterator-core-access" name="iterator-core-access">Iterator Core Access</a></h2>
<p><tt class="docutils literal"><span class="pre">iterator_facade</span></tt> and the operator implementations need to be able
to access the core member functions in the derived class. Making the
core member functions public would expose an implementation detail to
@ -212,7 +503,7 @@ provided, a class that acts as a gateway to the core member functions
in the derived iterator class. The author of the derived class only
needs to grant friendship to <tt class="docutils literal"><span class="pre">iterator_core_access</span></tt> to make his core
member functions available to the library.</p>
<!-- This is no long uptodate -thw -->
<!-- This is no long uptodate -thw -->
<!-- Yes it is; I made sure of it! -DWA -->
<p><tt class="docutils literal"><span class="pre">iterator_core_access</span></tt> will be typically implemented as an empty
class containing only private static member functions which invoke the
@ -222,8 +513,8 @@ standardize the gateway protocol. Note that even if
open a safety loophole, as every core member function preserves the
invariants of the iterator.</p>
</div>
<div class="section" id="operator">
<h2><a class="toc-backref" href="#id26" name="operator"><tt class="docutils literal"><span class="pre">operator[]</span></tt></a></h2>
<div class="section">
<h2><a class="toc-backref" href="#id26" id="operator" name="operator"><tt class="docutils literal"><span class="pre">operator[]</span></tt></a></h2>
<p>The indexing operator for a generalized iterator presents special
challenges. A random access iterator's <tt class="docutils literal"><span class="pre">operator[]</span></tt> is only
required to return something convertible to its <tt class="docutils literal"><span class="pre">value_type</span></tt>.
@ -245,8 +536,8 @@ the implementation of her iterator is free to implement an
class; it will hide the one supplied by <tt class="docutils literal"><span class="pre">iterator_facade</span></tt> from
clients of her iterator.</p>
</div>
<div class="section" id="id2">
<h2><a class="toc-backref" href="#id27" name="id2"><span class="target" id="operator-arrow"></span><tt class="docutils literal"><span class="pre">operator-&gt;</span></tt></a></h2>
<div class="section">
<h2><a class="toc-backref" href="#id27" id="id2" name="id2"><span id="operator-arrow"></span><tt class="docutils literal"><span class="pre">operator-&gt;</span></tt></a></h2>
<p>The <tt class="docutils literal"><span class="pre">reference</span></tt> type of a readable iterator (and today's input
iterator) need not in fact be a reference, so long as it is
convertible to the iterator's <tt class="docutils literal"><span class="pre">value_type</span></tt>. When the <tt class="docutils literal"><span class="pre">value_type</span></tt>
@ -267,11 +558,14 @@ Patterns, C++ Report, February 1995, pp. 24-27.</td></tr>
</table>
</div>
</div>
<div class="section" id="reference">
<h1><a class="toc-backref" href="#id28" name="reference">Reference</a></h1>
<div class="section">
<h1><a class="toc-backref" href="#id28" id="reference" name="reference">Reference</a></h1>
<!-- Distributed under 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) -->
<!-- Version 1.3 of this ReStructuredText document corresponds to
n1530_, the paper accepted by the LWG for TR1. -->
<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. -->
<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. -->
<pre class="literal-block">
template &lt;
class Derived
@ -355,12 +649,12 @@ template &lt;class Dr, class V, class TC, class R, class D&gt;
Derived operator+ (typename Derived::difference_type n,
iterator_facade&lt;Dr,V,TC,R,D&gt; const&amp;);
</pre>
<span class="target" id="iterator-category"></span><p>The <tt class="docutils literal"><span class="pre">iterator_category</span></tt> member of <tt class="docutils literal"><span class="pre">iterator_facade</span></tt> is</p>
<p id="iterator-category">The <tt class="docutils literal"><span class="pre">iterator_category</span></tt> member of <tt class="docutils literal"><span class="pre">iterator_facade</span></tt> is</p>
<pre class="literal-block">
<em>iterator-category</em>(CategoryOrTraversal, value_type, reference)
</pre>
<p>where <em>iterator-category</em> is defined as follows:</p>
<span class="target" id="id7"></span><pre class="literal-block">
<pre class="literal-block" id="id7">
<em>iterator-category</em>(C,R,V) :=
if (C is convertible to std::input_iterator_tag
|| C is convertible to std::output_iterator_tag
@ -407,10 +701,10 @@ traversal tags would add no information]</p>
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
<p>The <tt class="docutils literal"><span class="pre">enable_if_interoperable</span></tt> template used above is for exposition
purposes. The member operators should only be in an overload set
provided the derived types <tt class="docutils literal"><span class="pre">Dr1</span></tt> and <tt class="docutils literal"><span class="pre">Dr2</span></tt> are interoperable,
provided the derived types <tt class="docutils literal"><span class="pre">Dr1</span></tt> and <tt class="docutils literal"><span class="pre">Dr2</span></tt> are interoperable,
meaning that at least one of the types is convertible to the other. The
<tt class="docutils literal"><span class="pre">enable_if_interoperable</span></tt> approach uses SFINAE to take the operators
out of the overload set when the types are not interoperable.
out of the overload set when the types are not interoperable.
The operators should behave <em>as-if</em> <tt class="docutils literal"><span class="pre">enable_if_interoperable</span></tt>
were defined to be:</p>
<pre class="literal-block">
@ -428,8 +722,8 @@ struct enable_if_interoperable
&gt;
{};
</pre>
<div class="section" id="iterator-facade-requirements">
<h2><a class="toc-backref" href="#id29" name="iterator-facade-requirements"><tt class="docutils literal"><span class="pre">iterator_facade</span></tt> Requirements</a></h2>
<div class="section">
<h2><a class="toc-backref" href="#id29" id="iterator-facade-requirements" name="iterator-facade-requirements"><tt class="docutils literal"><span class="pre">iterator_facade</span></tt> Requirements</a></h2>
<p>The following table describes the typical valid expressions on
<tt class="docutils literal"><span class="pre">iterator_facade</span></tt>'s <tt class="docutils literal"><span class="pre">Derived</span></tt> parameter, depending on the
iterator concept(s) it will model. The operations in the first
@ -442,8 +736,8 @@ object of type <tt class="docutils literal"><span class="pre">X</span></tt>, <tt
object of a single pass iterator type interoperable with <tt class="docutils literal"><span class="pre">X</span></tt>, and <tt class="docutils literal"><span class="pre">z</span></tt>
is a constant object of a random access traversal iterator type
interoperable with <tt class="docutils literal"><span class="pre">X</span></tt>.</p>
<span class="target" id="core-operations"></span><div class="topic">
<p class="topic-title first"><tt class="docutils literal"><span class="pre">iterator_facade</span></tt> Core Operations</p>
<div class="topic">
<p class="topic-title first"><a id="core-operations" name="core-operations"><tt class="docutils literal"><span class="pre">iterator_facade</span></tt> Core Operations</a></p>
<table border="1" class="docutils">
<colgroup>
<col width="21%" />
@ -452,10 +746,10 @@ interoperable with <tt class="docutils literal"><span class="pre">X</span></tt>.
<col width="29%" />
</colgroup>
<thead valign="bottom">
<tr><th>Expression</th>
<th>Return Type</th>
<th>Assertion/Note</th>
<th>Used to implement Iterator
<tr><th class="head">Expression</th>
<th class="head">Return Type</th>
<th class="head">Assertion/Note</th>
<th class="head">Used to implement Iterator
Concept(s)</th>
</tr>
</thead>
@ -502,8 +796,8 @@ Iterator</td>
</table>
</div>
</div>
<div class="section" id="iterator-facade-operations">
<h2><a class="toc-backref" href="#id30" name="iterator-facade-operations"><tt class="docutils literal"><span class="pre">iterator_facade</span></tt> operations</a></h2>
<div class="section">
<h2><a class="toc-backref" href="#id30" id="iterator-facade-operations" name="iterator-facade-operations"><tt class="docutils literal"><span class="pre">iterator_facade</span></tt> operations</a></h2>
<p>The operations in this section are described in terms of operations on
the core interface of <tt class="docutils literal"><span class="pre">Derived</span></tt> which may be inaccessible
(i.e. private). The implementation should access these operations
@ -527,14 +821,14 @@ of type <tt class="docutils literal"><span class="pre">pointer</span></tt> equal
<pre class="literal-block">
&amp;static_cast&lt;Derived const*&gt;(this)-&gt;dereference()
</pre>
<p class="last">Otherwise returns an object of unspecified type such that,
<p class="last">Otherwise returns an object of unspecified type such that,
<tt class="docutils literal"><span class="pre">(*static_cast&lt;Derived</span> <span class="pre">const*&gt;(this))-&gt;m</span></tt> is equivalent to <tt class="docutils literal"><span class="pre">(w</span> <span class="pre">=</span> <span class="pre">**static_cast&lt;Derived</span> <span class="pre">const*&gt;(this),</span>
<span class="pre">w.m)</span></tt> for some temporary object <tt class="docutils literal"><span class="pre">w</span></tt> of type <tt class="docutils literal"><span class="pre">value_type</span></tt>.</p>
</td>
</tr>
</tbody>
</table>
<span class="target" id="brackets"></span><p><em>unspecified</em> <tt class="docutils literal"><span class="pre">operator[](difference_type</span> <span class="pre">n)</span> <span class="pre">const;</span></tt></p>
<p id="brackets"><em>unspecified</em> <tt class="docutils literal"><span class="pre">operator[](difference_type</span> <span class="pre">n)</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" />
@ -675,10 +969,12 @@ operator ==(iterator_facade&lt;Dr1,V1,TC1,R1,D1&gt; const&amp; lhs,
<tbody valign="top">
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">if <tt class="docutils literal"><span class="pre">is_convertible&lt;Dr2,Dr1&gt;::value</span></tt></p>
<dl class="last docutils">
<dt>then </dt>
<dd><tt class="docutils literal"><span class="pre">((Dr1</span> <span class="pre">const&amp;)lhs).equal((Dr2</span> <span class="pre">const&amp;)rhs)</span></tt>.</dd>
<dt>Otherwise, </dt>
<dd><tt class="docutils literal"><span class="pre">((Dr2</span> <span class="pre">const&amp;)rhs).equal((Dr1</span> <span class="pre">const&amp;)lhs)</span></tt>.</dd>
<dt>then</dt>
<dd><p class="first last"><tt class="docutils literal"><span class="pre">((Dr1</span> <span class="pre">const&amp;)lhs).equal((Dr2</span> <span class="pre">const&amp;)rhs)</span></tt>.</p>
</dd>
<dt>Otherwise,</dt>
<dd><p class="first last"><tt class="docutils literal"><span class="pre">((Dr2</span> <span class="pre">const&amp;)rhs).equal((Dr1</span> <span class="pre">const&amp;)lhs)</span></tt>.</p>
</dd>
</dl>
</td>
</tr>
@ -697,10 +993,12 @@ operator !=(iterator_facade&lt;Dr1,V1,TC1,R1,D1&gt; const&amp; lhs,
<tbody valign="top">
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">if <tt class="docutils literal"><span class="pre">is_convertible&lt;Dr2,Dr1&gt;::value</span></tt></p>
<dl class="last docutils">
<dt>then </dt>
<dd><tt class="docutils literal"><span class="pre">!((Dr1</span> <span class="pre">const&amp;)lhs).equal((Dr2</span> <span class="pre">const&amp;)rhs)</span></tt>.</dd>
<dt>Otherwise, </dt>
<dd><tt class="docutils literal"><span class="pre">!((Dr2</span> <span class="pre">const&amp;)rhs).equal((Dr1</span> <span class="pre">const&amp;)lhs)</span></tt>.</dd>
<dt>then</dt>
<dd><p class="first last"><tt class="docutils literal"><span class="pre">!((Dr1</span> <span class="pre">const&amp;)lhs).equal((Dr2</span> <span class="pre">const&amp;)rhs)</span></tt>.</p>
</dd>
<dt>Otherwise,</dt>
<dd><p class="first last"><tt class="docutils literal"><span class="pre">!((Dr2</span> <span class="pre">const&amp;)rhs).equal((Dr1</span> <span class="pre">const&amp;)lhs)</span></tt>.</p>
</dd>
</dl>
</td>
</tr>
@ -719,10 +1017,12 @@ operator &lt;(iterator_facade&lt;Dr1,V1,TC1,R1,D1&gt; const&amp; lhs,
<tbody valign="top">
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">if <tt class="docutils literal"><span class="pre">is_convertible&lt;Dr2,Dr1&gt;::value</span></tt></p>
<dl class="last docutils">
<dt>then </dt>
<dd><tt class="docutils literal"><span class="pre">((Dr1</span> <span class="pre">const&amp;)lhs).distance_to((Dr2</span> <span class="pre">const&amp;)rhs)</span> <span class="pre">&lt;</span> <span class="pre">0</span></tt>.</dd>
<dt>Otherwise, </dt>
<dd><tt class="docutils literal"><span class="pre">((Dr2</span> <span class="pre">const&amp;)rhs).distance_to((Dr1</span> <span class="pre">const&amp;)lhs)</span> <span class="pre">&gt;</span> <span class="pre">0</span></tt>.</dd>
<dt>then</dt>
<dd><p class="first last"><tt class="docutils literal"><span class="pre">((Dr1</span> <span class="pre">const&amp;)lhs).distance_to((Dr2</span> <span class="pre">const&amp;)rhs)</span> <span class="pre">&lt;</span> <span class="pre">0</span></tt>.</p>
</dd>
<dt>Otherwise,</dt>
<dd><p class="first last"><tt class="docutils literal"><span class="pre">((Dr2</span> <span class="pre">const&amp;)rhs).distance_to((Dr1</span> <span class="pre">const&amp;)lhs)</span> <span class="pre">&gt;</span> <span class="pre">0</span></tt>.</p>
</dd>
</dl>
</td>
</tr>
@ -741,10 +1041,12 @@ operator &lt;=(iterator_facade&lt;Dr1,V1,TC1,R1,D1&gt; const&amp; lhs,
<tbody valign="top">
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">if <tt class="docutils literal"><span class="pre">is_convertible&lt;Dr2,Dr1&gt;::value</span></tt></p>
<dl class="last docutils">
<dt>then </dt>
<dd><tt class="docutils literal"><span class="pre">((Dr1</span> <span class="pre">const&amp;)lhs).distance_to((Dr2</span> <span class="pre">const&amp;)rhs)</span> <span class="pre">&lt;=</span> <span class="pre">0</span></tt>.</dd>
<dt>Otherwise, </dt>
<dd><tt class="docutils literal"><span class="pre">((Dr2</span> <span class="pre">const&amp;)rhs).distance_to((Dr1</span> <span class="pre">const&amp;)lhs)</span> <span class="pre">&gt;=</span> <span class="pre">0</span></tt>.</dd>
<dt>then</dt>
<dd><p class="first last"><tt class="docutils literal"><span class="pre">((Dr1</span> <span class="pre">const&amp;)lhs).distance_to((Dr2</span> <span class="pre">const&amp;)rhs)</span> <span class="pre">&lt;=</span> <span class="pre">0</span></tt>.</p>
</dd>
<dt>Otherwise,</dt>
<dd><p class="first last"><tt class="docutils literal"><span class="pre">((Dr2</span> <span class="pre">const&amp;)rhs).distance_to((Dr1</span> <span class="pre">const&amp;)lhs)</span> <span class="pre">&gt;=</span> <span class="pre">0</span></tt>.</p>
</dd>
</dl>
</td>
</tr>
@ -763,10 +1065,12 @@ operator &gt;(iterator_facade&lt;Dr1,V1,TC1,R1,D1&gt; const&amp; lhs,
<tbody valign="top">
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">if <tt class="docutils literal"><span class="pre">is_convertible&lt;Dr2,Dr1&gt;::value</span></tt></p>
<dl class="last docutils">
<dt>then </dt>
<dd><tt class="docutils literal"><span class="pre">((Dr1</span> <span class="pre">const&amp;)lhs).distance_to((Dr2</span> <span class="pre">const&amp;)rhs)</span> <span class="pre">&gt;</span> <span class="pre">0</span></tt>.</dd>
<dt>Otherwise, </dt>
<dd><tt class="docutils literal"><span class="pre">((Dr2</span> <span class="pre">const&amp;)rhs).distance_to((Dr1</span> <span class="pre">const&amp;)lhs)</span> <span class="pre">&lt;</span> <span class="pre">0</span></tt>.</dd>
<dt>then</dt>
<dd><p class="first last"><tt class="docutils literal"><span class="pre">((Dr1</span> <span class="pre">const&amp;)lhs).distance_to((Dr2</span> <span class="pre">const&amp;)rhs)</span> <span class="pre">&gt;</span> <span class="pre">0</span></tt>.</p>
</dd>
<dt>Otherwise,</dt>
<dd><p class="first last"><tt class="docutils literal"><span class="pre">((Dr2</span> <span class="pre">const&amp;)rhs).distance_to((Dr1</span> <span class="pre">const&amp;)lhs)</span> <span class="pre">&lt;</span> <span class="pre">0</span></tt>.</p>
</dd>
</dl>
</td>
</tr>
@ -785,16 +1089,18 @@ operator &gt;=(iterator_facade&lt;Dr1,V1,TC1,R1,D1&gt; const&amp; lhs,
<tbody valign="top">
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">if <tt class="docutils literal"><span class="pre">is_convertible&lt;Dr2,Dr1&gt;::value</span></tt></p>
<dl class="last docutils">
<dt>then </dt>
<dd><tt class="docutils literal"><span class="pre">((Dr1</span> <span class="pre">const&amp;)lhs).distance_to((Dr2</span> <span class="pre">const&amp;)rhs)</span> <span class="pre">&gt;=</span> <span class="pre">0</span></tt>.</dd>
<dt>Otherwise, </dt>
<dd><tt class="docutils literal"><span class="pre">((Dr2</span> <span class="pre">const&amp;)rhs).distance_to((Dr1</span> <span class="pre">const&amp;)lhs)</span> <span class="pre">&lt;=</span> <span class="pre">0</span></tt>.</dd>
<dt>then</dt>
<dd><p class="first last"><tt class="docutils literal"><span class="pre">((Dr1</span> <span class="pre">const&amp;)lhs).distance_to((Dr2</span> <span class="pre">const&amp;)rhs)</span> <span class="pre">&gt;=</span> <span class="pre">0</span></tt>.</p>
</dd>
<dt>Otherwise,</dt>
<dd><p class="first last"><tt class="docutils literal"><span class="pre">((Dr2</span> <span class="pre">const&amp;)rhs).distance_to((Dr1</span> <span class="pre">const&amp;)lhs)</span> <span class="pre">&lt;=</span> <span class="pre">0</span></tt>.</p>
</dd>
</dl>
</td>
</tr>
</tbody>
</table>
<span class="target" id="minus"></span><pre class="literal-block">
<pre class="literal-block" id="minus">
template &lt;class Dr1, class V1, class TC1, class R1, class D1,
class Dr2, class V2, class TC2, class R2, class D2&gt;
typename enable_if_interoperable&lt;Dr1,Dr2,difference&gt;::type
@ -806,23 +1112,27 @@ operator -(iterator_facade&lt;Dr1,V1,TC1,R1,D1&gt; const&amp; lhs,
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Return Type:</th><td class="field-body"><p class="first">if <tt class="docutils literal"><span class="pre">is_convertible&lt;Dr2,Dr1&gt;::value</span></tt></p>
<blockquote class="last">
<blockquote>
<dl class="docutils">
<dt>then </dt>
<dd><tt class="docutils literal"><span class="pre">difference</span></tt> shall be
<tt class="docutils literal"><span class="pre">iterator_traits&lt;Dr1&gt;::difference_type</span></tt>.</dd>
<dt>Otherwise </dt>
<dd><tt class="docutils literal"><span class="pre">difference</span></tt> shall be <tt class="docutils literal"><span class="pre">iterator_traits&lt;Dr2&gt;::difference_type</span></tt></dd>
<dt>then</dt>
<dd><p class="first last"><tt class="docutils literal"><span class="pre">difference</span></tt> shall be
<tt class="docutils literal"><span class="pre">iterator_traits&lt;Dr1&gt;::difference_type</span></tt>.</p>
</dd>
<dt>Otherwise</dt>
<dd><p class="first last"><tt class="docutils literal"><span class="pre">difference</span></tt> shall be <tt class="docutils literal"><span class="pre">iterator_traits&lt;Dr2&gt;::difference_type</span></tt></p>
</dd>
</dl>
</blockquote>
</td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">if <tt class="docutils literal"><span class="pre">is_convertible&lt;Dr2,Dr1&gt;::value</span></tt></p>
<dl class="last docutils">
<dt>then </dt>
<dd><tt class="docutils literal"><span class="pre">-((Dr1</span> <span class="pre">const&amp;)lhs).distance_to((Dr2</span> <span class="pre">const&amp;)rhs)</span></tt>.</dd>
<dt>Otherwise, </dt>
<dd><tt class="docutils literal"><span class="pre">((Dr2</span> <span class="pre">const&amp;)rhs).distance_to((Dr1</span> <span class="pre">const&amp;)lhs)</span></tt>.</dd>
<dt>then</dt>
<dd><p class="first last"><tt class="docutils literal"><span class="pre">-((Dr1</span> <span class="pre">const&amp;)lhs).distance_to((Dr2</span> <span class="pre">const&amp;)rhs)</span></tt>.</p>
</dd>
<dt>Otherwise,</dt>
<dd><p class="first last"><tt class="docutils literal"><span class="pre">((Dr2</span> <span class="pre">const&amp;)rhs).distance_to((Dr1</span> <span class="pre">const&amp;)lhs)</span></tt>.</p>
</dd>
</dl>
</td>
</tr>
@ -830,8 +1140,8 @@ operator -(iterator_facade&lt;Dr1,V1,TC1,R1,D1&gt; const&amp; lhs,
</table>
</div>
</div>
<div class="section" id="tutorial-example">
<h1><a class="toc-backref" href="#id31" name="tutorial-example">Tutorial Example</a></h1>
<div class="section">
<h1><a class="toc-backref" href="#id31" id="tutorial-example" name="tutorial-example">Tutorial Example</a></h1>
<!-- 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) -->
@ -840,8 +1150,8 @@ iterators using <tt class="docutils literal"><span class="pre">iterator_facade</
example of a linked list of polymorphic objects. This example was
inspired by a <a class="reference" href="http://thread.gmane.org/gmane.comp.lib.boost.user/5100">posting</a> by Keith Macdonald on the <a class="reference" href="../../../more/mailing_lists.htm#users">Boost-Users</a>
mailing list.</p>
<div class="section" id="the-problem">
<h2><a class="toc-backref" href="#id32" name="the-problem">The Problem</a></h2>
<div class="section">
<h2><a class="toc-backref" href="#id32" id="the-problem" name="the-problem">The Problem</a></h2>
<p>Say we've written a polymorphic linked list node base class:</p>
<pre class="literal-block">
# include &lt;iostream&gt;
@ -858,16 +1168,16 @@ struct node_base
// print to the stream
virtual void print(std::ostream&amp; s) const = 0;
// double the value
virtual void double_me() = 0;
void append(node_base* p)
{
if (m_next)
m_next-&gt;append(p);
if (m_next)
m_next-&gt;append(p);
else
m_next = p;
m_next = p;
}
private:
@ -902,8 +1212,8 @@ inline std::ostream&amp; operator&lt;&lt;(std::ostream&amp; s, node_base const&a
<p>Our first challenge is to build an appropriate iterator over these
lists.</p>
</div>
<div class="section" id="a-basic-iterator-using-iterator-facade">
<h2><a class="toc-backref" href="#id33" name="a-basic-iterator-using-iterator-facade">A Basic Iterator Using <tt class="docutils literal"><span class="pre">iterator_facade</span></tt></a></h2>
<div class="section">
<h2><a class="toc-backref" href="#id33" id="a-basic-iterator-using-iterator-facade" name="a-basic-iterator-using-iterator-facade">A Basic Iterator Using <tt class="docutils literal"><span class="pre">iterator_facade</span></tt></a></h2>
<p>We will construct a <tt class="docutils literal"><span class="pre">node_iterator</span></tt> class using inheritance from
<tt class="docutils literal"><span class="pre">iterator_facade</span></tt> to implement most of the iterator's operations.</p>
<pre class="literal-block">
@ -916,25 +1226,25 @@ class node_iterator
...
};
</pre>
<div class="section" id="template-arguments-for-iterator-facade">
<h3><a class="toc-backref" href="#id34" name="template-arguments-for-iterator-facade">Template Arguments for <tt class="docutils literal"><span class="pre">iterator_facade</span></tt></a></h3>
<div class="section">
<h3><a class="toc-backref" href="#id34" id="template-arguments-for-iterator-facade" name="template-arguments-for-iterator-facade">Template Arguments for <tt class="docutils literal"><span class="pre">iterator_facade</span></tt></a></h3>
<p><tt class="docutils literal"><span class="pre">iterator_facade</span></tt> has several template parameters, so we must decide
what types to use for the arguments. The parameters are <tt class="docutils literal"><span class="pre">Derived</span></tt>,
<tt class="docutils literal"><span class="pre">Value</span></tt>, <tt class="docutils literal"><span class="pre">CategoryOrTraversal</span></tt>, <tt class="docutils literal"><span class="pre">Reference</span></tt>, and <tt class="docutils literal"><span class="pre">Difference</span></tt>.</p>
<div class="section" id="derived">
<h4><a class="toc-backref" href="#id35" name="derived"><tt class="docutils literal"><span class="pre">Derived</span></tt></a></h4>
<div class="section">
<h4><a class="toc-backref" href="#id35" id="derived" name="derived"><tt class="docutils literal"><span class="pre">Derived</span></tt></a></h4>
<p>Because <tt class="docutils literal"><span class="pre">iterator_facade</span></tt> is meant to be used with the CRTP
<a class="citation-reference" href="#cop95" id="id10" name="id10">[Cop95]</a> the first parameter is the iterator class name itself,
<tt class="docutils literal"><span class="pre">node_iterator</span></tt>.</p>
</div>
<div class="section" id="value">
<h4><a class="toc-backref" href="#id36" name="value"><tt class="docutils literal"><span class="pre">Value</span></tt></a></h4>
<div class="section">
<h4><a class="toc-backref" href="#id36" id="value" name="value"><tt class="docutils literal"><span class="pre">Value</span></tt></a></h4>
<p>The <tt class="docutils literal"><span class="pre">Value</span></tt> parameter determines the <tt class="docutils literal"><span class="pre">node_iterator</span></tt>'s
<tt class="docutils literal"><span class="pre">value_type</span></tt>. In this case, we are iterating over <tt class="docutils literal"><span class="pre">node_base</span></tt>
objects, so <tt class="docutils literal"><span class="pre">Value</span></tt> will be <tt class="docutils literal"><span class="pre">node_base</span></tt>.</p>
</div>
<div class="section" id="categoryortraversal">
<h4><a class="toc-backref" href="#id37" name="categoryortraversal"><tt class="docutils literal"><span class="pre">CategoryOrTraversal</span></tt></a></h4>
<div class="section">
<h4><a class="toc-backref" href="#id37" id="categoryortraversal" name="categoryortraversal"><tt class="docutils literal"><span class="pre">CategoryOrTraversal</span></tt></a></h4>
<p>Now we have to determine which <a class="reference" href="new-iter-concepts.html#iterator-traversal-concepts-lib-iterator-traversal">iterator traversal concept</a> our
<tt class="docutils literal"><span class="pre">node_iterator</span></tt> is going to model. Singly-linked lists only have
forward links, so our iterator can't can't be a <a class="reference" href="new-iter-concepts.html#bidirectional-traversal-iterators-lib-bidirectional-traversal-iterators">bidirectional
@ -953,8 +1263,8 @@ end up being <tt class="docutils literal"><span class="pre">std::forward_iterato
</tbody>
</table>
</div>
<div class="section" id="id12">
<h4><a class="toc-backref" href="#id38" name="id12"><tt class="docutils literal"><span class="pre">Reference</span></tt></a></h4>
<div class="section">
<h4><a class="toc-backref" href="#id38" id="id12" name="id12"><tt class="docutils literal"><span class="pre">Reference</span></tt></a></h4>
<p>The <tt class="docutils literal"><span class="pre">Reference</span></tt> argument becomes the type returned by
<tt class="docutils literal"><span class="pre">node_iterator</span></tt>'s dereference operation, and will also be the
same as <tt class="docutils literal"><span class="pre">std::iterator_traits&lt;node_iterator&gt;::reference</span></tt>. The
@ -962,8 +1272,8 @@ library's default for this parameter is <tt class="docutils literal"><span class
<tt class="docutils literal"><span class="pre">node_base&amp;</span></tt> is a good choice for the iterator's <tt class="docutils literal"><span class="pre">reference</span></tt>
type, we can omit this argument, or pass <tt class="docutils literal"><span class="pre">use_default</span></tt>.</p>
</div>
<div class="section" id="difference">
<h4><a class="toc-backref" href="#id39" name="difference"><tt class="docutils literal"><span class="pre">Difference</span></tt></a></h4>
<div class="section">
<h4><a class="toc-backref" href="#id39" id="difference" name="difference"><tt class="docutils literal"><span class="pre">Difference</span></tt></a></h4>
<p>The <tt class="docutils literal"><span class="pre">Difference</span></tt> argument determines how the distance between
two <tt class="docutils literal"><span class="pre">node_iterator</span></tt>s will be measured and will also be the
same as <tt class="docutils literal"><span class="pre">std::iterator_traits&lt;node_iterator&gt;::difference_type</span></tt>.
@ -989,8 +1299,8 @@ class node_iterator
</pre>
</div>
</div>
<div class="section" id="constructors-and-data-members">
<h3><a class="toc-backref" href="#id40" name="constructors-and-data-members">Constructors and Data Members</a></h3>
<div class="section">
<h3><a class="toc-backref" href="#id40" id="constructors-and-data-members" name="constructors-and-data-members">Constructors and Data Members</a></h3>
<p>Next we need to decide how to represent the iterator's position.
This representation will take the form of data members, so we'll
also need to write constructors to initialize them. The
@ -1034,8 +1344,8 @@ default constructor to leave <tt class="docutils literal"><span class="pre">m_no
</tbody>
</table>
</div>
<div class="section" id="implementing-the-core-operations">
<h3><a class="toc-backref" href="#id41" name="implementing-the-core-operations">Implementing the Core Operations</a></h3>
<div class="section">
<h3><a class="toc-backref" href="#id41" id="implementing-the-core-operations" name="implementing-the-core-operations">Implementing the Core Operations</a></h3>
<p>The last step is to implement the <a class="reference" href="#core-operations">core operations</a> required by
the concepts we want our iterator to model. Referring to the
<a class="reference" href="#core-operations">table</a>, we can see that the first three rows are applicable
@ -1085,8 +1395,8 @@ class node_iterator
iterator! For a working example of its use, see <a class="reference" href="../example/node_iterator1.cpp">this program</a>.</p>
</div>
</div>
<div class="section" id="a-constant-node-iterator">
<h2><a class="toc-backref" href="#id42" name="a-constant-node-iterator">A constant <tt class="docutils literal"><span class="pre">node_iterator</span></tt></a></h2>
<div class="section">
<h2><a class="toc-backref" href="#id42" id="a-constant-node-iterator" name="a-constant-node-iterator">A constant <tt class="docutils literal"><span class="pre">node_iterator</span></tt></a></h2>
<div class="sidebar">
<p class="first sidebar-title">Constant and Mutable iterators</p>
<p>The term <strong>mutable iterator</strong> means an iterator through which
@ -1186,8 +1496,8 @@ typedef node_iter&lt;node_base&gt; node_iterator;
typedef node_iter&lt;node_base const&gt; node_const_iterator;
</pre>
</div>
<div class="section" id="interoperability">
<h2><a class="toc-backref" href="#id43" name="interoperability">Interoperability</a></h2>
<div class="section">
<h2><a class="toc-backref" href="#id43" id="interoperability" name="interoperability">Interoperability</a></h2>
<p>Our <tt class="docutils literal"><span class="pre">const_node_iterator</span></tt> works perfectly well on its own, but
taken together with <tt class="docutils literal"><span class="pre">node_iterator</span></tt> it doesn't quite meet
expectations. For example, we'd like to be able to pass a
@ -1226,7 +1536,7 @@ class node_iter
template &lt;class OtherValue&gt;
bool equal(node_iter&lt;OtherValue&gt; const&amp; other) const
{
{
return this-&gt;m_node == other.m_node;
}
@ -1259,8 +1569,8 @@ traversal iterator</a>, we'd have had to templatize its
<p>You can see an example program which exercises our interoperable
iterators <a class="reference" href="../example/node_iterator2.cpp">here</a>.</p>
</div>
<div class="section" id="telling-the-truth">
<h2><a class="toc-backref" href="#id44" name="telling-the-truth">Telling the Truth</a></h2>
<div class="section">
<h2><a class="toc-backref" href="#id44" id="telling-the-truth" name="telling-the-truth">Telling the Truth</a></h2>
<p>Now <tt class="docutils literal"><span class="pre">node_iterator</span></tt> and <tt class="docutils literal"><span class="pre">node_const_iterator</span></tt> behave exactly as
you'd expect... almost. We can compare them and we can convert in
one direction: from <tt class="docutils literal"><span class="pre">node_iterator</span></tt> to <tt class="docutils literal"><span class="pre">node_const_iterator</span></tt>.
@ -1286,7 +1596,7 @@ appropriate:</p>
...
private:
private:
struct enabler {};
public:
@ -1301,8 +1611,8 @@ public:
: m_node(other.m_node) {}
</pre>
</div>
<div class="section" id="wrap-up">
<h2><a class="toc-backref" href="#id45" name="wrap-up">Wrap Up</a></h2>
<div class="section">
<h2><a class="toc-backref" href="#id45" id="wrap-up" name="wrap-up">Wrap Up</a></h2>
<p>This concludes our <tt class="docutils literal"><span class="pre">iterator_facade</span></tt> tutorial, but before you
stop reading we urge you to take a look at <a class="reference" href="iterator_adaptor.html"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt></a>.
There's another way to approach writing these iterators which might
@ -1310,10 +1620,5 @@ even be superior.</p>
</div>
</div>
</div>
<hr class="docutils footer" />
<div class="footer">
<a class="reference" href="iterator_facade.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.
</div>
</body>
</html>