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

Documentation updates, added GNUMakefile for building

Browse Source 
[SVN r20931]
This commit is contained in:
Dave Abrahams
2003-11-24 05:02:46 +00:00
parent ca1ee306b7
commit 09ea8d27e2
21 changed files with 3074 additions and 1270 deletions
Download Patch File Download Diff File Expand all files Collapse all files

492
doc/iterator_facade.html
View File

@ -9,7 +9,198 @@
<meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, University of Hanover Institute for Transport Railway Operation and Construction" />
<meta name="date" content="2003-09-14" />
<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved" />
<link rel="stylesheet" href="../../../rst.css" type="text/css" />
<style type="text/css"><!--
/*
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:date: $Date$
:version: $Revision$
:copyright: This stylesheet has been placed in the public domain.
Default cascading style sheet for the HTML output of Docutils.
*/
.first {
margin-top: 0 }
.last {
margin-bottom: 0 }
a.toc-backref {
text-decoration: none ;
color: black }
dd {
margin-bottom: 0.5em }
div.abstract {
margin: 2em 5em }
div.abstract p.topic-title {
font-weight: bold ;
text-align: center }
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.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 }
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.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 }
div.footer, div.header {
font-size: smaller }
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.title {
text-align: center }
h2.subtitle {
text-align: center }
hr {
width: 75% }
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.caption {
font-style: italic }
p.credits {
font-style: italic ;
font-size: smaller }
p.label {
white-space: nowrap }
p.topic-title {
font-weight: bold }
pre.address {
margin-bottom: 0 ;
margin-top: 0 ;
font-family: serif ;
font-size: 100% }
pre.line-block {
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-argument {
font-style: italic }
span.pre {
white-space: pre }
span.problematic {
color: red }
table {
margin-top: 0.5em ;
margin-bottom: 0.5em }
table.citation {
border-left: solid thin gray ;
padding-left: 0.5ex }
table.docinfo {
margin: 2em 4em }
table.footnote {
border-left: solid thin black ;
padding-left: 0.5ex }
td, th {
padding-left: 0.5em ;
padding-right: 0.5em ;
vertical-align: top }
th.docinfo-name, th.field-name {
font-weight: bold ;
text-align: left ;
white-space: nowrap }
h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
font-size: 100% }
tt {
background-color: #eeeeee }
ul.auto-toc {
list-style-type: none }
--></style>
</head>
<body>
<div class="document" id="iterator-facade">
@ -46,20 +237,25 @@ and associated types, to be supplied by a derived iterator class.</p>
<div class="contents topic" id="table-of-contents">
<p class="topic-title"><a name="table-of-contents">Table of Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#motivation" id="id10" name="id10">Motivation</a></li>
<li><a class="reference" href="#usage" id="id11" name="id11">Usage</a></li>
<li><a class="reference" href="#iterator-core-access" id="id12" name="id12">Iterator Core Access</a></li>
<li><a class="reference" href="#operator" id="id13" name="id13"><tt class="literal"><span class="pre">operator[]</span></tt></a></li>
<li><a class="reference" href="#id3" id="id14" name="id14"><tt class="literal"><span class="pre">operator-&gt;</span></tt></a></li>
<li><a class="reference" href="#reference" id="id15" name="id15">Reference</a><ul>
<li><a class="reference" href="#id8" id="id16" name="id16"><tt class="literal"><span class="pre">iterator_facade</span></tt> requirements</a></li>
<li><a class="reference" href="#iterator-facade-operations" id="id17" name="id17"><tt class="literal"><span class="pre">iterator_facade</span></tt> operations</a></li>
<li><a class="reference" href="#motivation" id="id7" name="id7">Motivation</a></li>
<li><a class="reference" href="#usage" id="id8" name="id8">Usage</a></li>
<li><a class="reference" href="#iterator-core-access" id="id9" name="id9">Iterator Core Access</a></li>
<li><a class="reference" href="#operator" id="id10" name="id10"><tt class="literal"><span class="pre">operator[]</span></tt></a></li>
<li><a class="reference" href="#id2" id="id11" name="id11"><tt class="literal"><span class="pre">operator-&gt;</span></tt></a></li>
<li><a class="reference" href="#reference" id="id12" name="id12">Reference</a><ul>
<li><a class="reference" href="#iterator-facade-usage" id="id13" name="id13"><tt class="literal"><span class="pre">iterator_facade</span></tt> usage</a></li>
<li><a class="reference" href="#iterator-facade-iterator-category" id="id14" name="id14"><tt class="literal"><span class="pre">iterator_facade</span></tt> iterator category</a></li>
<li><a class="reference" href="#iterator-facade-operations" id="id15" name="id15"><tt class="literal"><span class="pre">iterator_facade</span></tt> operations</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="motivation">
<h1><a class="toc-backref" href="#id10" name="motivation">Motivation</a></h1>
<h1><a class="toc-backref" href="#id7" name="motivation">Motivation</a></h1>
<!-- Version 1.1 of this ReStructuredText document corresponds to
n1530_, the paper accepted by the LWG for TR1. -->
<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
rights reserved -->
<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>
@ -91,7 +287,7 @@ implementations.</li>
<li>Without the use of CRTP, the standard requirement that an
iterator's <tt class="literal"><span class="pre">operator++</span></tt> returns the iterator type itself means
that all iterators generated by <tt class="literal"><span class="pre">iterator_facade</span></tt> would be
instantiations of <tt class="literal"><span class="pre">iterator_facade</span></tt>. Cumbersome type generator
specializations of <tt class="literal"><span class="pre">iterator_facade</span></tt>. Cumbersome type generator
metafunctions would be needed to build new parameterized
iterators, and a separate <tt class="literal"><span class="pre">iterator_adaptor</span></tt> layer would be
impossible.</li>
@ -99,9 +295,9 @@ impossible.</li>
</blockquote>
</div>
<div class="section" id="usage">
<h1><a class="toc-backref" href="#id11" name="usage">Usage</a></h1>
<h1><a class="toc-backref" href="#id8" name="usage">Usage</a></h1>
<p>The user of <tt class="literal"><span class="pre">iterator_facade</span></tt> derives his iterator class from an
instantiation of <tt class="literal"><span class="pre">iterator_facade</span></tt> which takes the derived iterator
specialization of <tt class="literal"><span class="pre">iterator_facade</span></tt> which takes the derived iterator
class as the first template parameter. The order of the other
template parameters to <tt class="literal"><span class="pre">iterator_facade</span></tt> have been carefully chosen
to take advantage of useful defaults. For example, when defining a
@ -162,7 +358,7 @@ Iterator or a more-refined iterator concept, a default constructor is
required.</p>
</div>
<div class="section" id="iterator-core-access">
<h1><a class="toc-backref" href="#id12" name="iterator-core-access">Iterator Core Access</a></h1>
<h1><a class="toc-backref" href="#id9" name="iterator-core-access">Iterator Core Access</a></h1>
<p><tt class="literal"><span class="pre">iterator_facade</span></tt> and the operator implementations need to be able
to access the core member functions in the derived class. Making the
core member functions public would expose an implementation detail to
@ -196,18 +392,18 @@ open a safety loophole, as every core member function preserves the
invariants of the iterator.</p>
</div>
<div class="section" id="operator">
<h1><a class="toc-backref" href="#id13" name="operator"><tt class="literal"><span class="pre">operator[]</span></tt></a></h1>
<h1><a class="toc-backref" href="#id10" name="operator"><tt class="literal"><span class="pre">operator[]</span></tt></a></h1>
<p>The indexing operator for a generalized iterator presents special
challenges. A random access iterator's <tt class="literal"><span class="pre">operator[]</span></tt> is only
required to return something convertible to its <tt class="literal"><span class="pre">value_type</span></tt>.
Requiring that it return an lvalue would rule out currently-legal
random-access iterators which hold the referenced value in a data
member (e.g. <a class="reference" href="counting_iterator.html">counting_iterator</a>), because <tt class="literal"><span class="pre">*(p+n)</span></tt> is a reference
member (e.g. <a class="reference" href="counting_iterator.html"><tt class="literal"><span class="pre">counting_iterator</span></tt></a>), because <tt class="literal"><span class="pre">*(p+n)</span></tt> is a reference
into the temporary iterator <tt class="literal"><span class="pre">p+n</span></tt>, which is destroyed when
<tt class="literal"><span class="pre">operator[]</span></tt> returns.</p>
<p>Writable iterators built with <tt class="literal"><span class="pre">iterator_facade</span></tt> implement the
semantics required by the preferred resolution to <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-active.html#299">issue 299</a> and
adopted by proposal <a class="reference" href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/papers/2003/n1477.html">n1477</a>: the result of <tt class="literal"><span class="pre">p[n]</span></tt> is a proxy object
adopted by proposal <a class="reference" href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/papers/2003/n1550.html">n1550</a>: the result of <tt class="literal"><span class="pre">p[n]</span></tt> is a proxy object
containing a copy of <tt class="literal"><span class="pre">p+n</span></tt>, and <tt class="literal"><span class="pre">p[n]</span> <span class="pre">=</span> <span class="pre">x</span></tt> is equivalent to <tt class="literal"><span class="pre">*(p</span>
<span class="pre">+</span> <span class="pre">n)</span> <span class="pre">=</span> <span class="pre">x</span></tt>. This approach will work properly for any random-access
iterator regardless of the other details of its implementation. A
@ -216,8 +412,8 @@ to implement an <tt class="literal"><span class="pre">operator[]</span></tt> whi
iterator class; it will hide the one supplied by <tt class="literal"><span class="pre">iterator_facade</span></tt>
from clients of her iterator.</p>
<a class="target" id="operator-arrow" name="operator-arrow"></a></div>
<div class="section" id="id3">
<h1><a class="toc-backref" href="#id14" name="id3"><tt class="literal"><span class="pre">operator-&gt;</span></tt></a></h1>
<div class="section" id="id2">
<h1><a class="toc-backref" href="#id11" name="id2"><tt class="literal"><span class="pre">operator-&gt;</span></tt></a></h1>
<p>The <tt class="literal"><span class="pre">reference</span></tt> type of a readable iterator (and today's input
iterator) need not in fact be a reference, so long as it is
convertible to the iterator's <tt class="literal"><span class="pre">value_type</span></tt>. When the <tt class="literal"><span class="pre">value_type</span></tt>
@ -227,7 +423,7 @@ type is not in fact a reference must return a proxy containing a copy
of the referenced value from its <tt class="literal"><span class="pre">operator-&gt;</span></tt>.</p>
<p>The return type for <tt class="literal"><span class="pre">operator-&gt;</span></tt> and <tt class="literal"><span class="pre">operator[]</span></tt> is not
explicitly specified. Instead it requires each <tt class="literal"><span class="pre">iterator_facade</span></tt>
instantiation to meet the requirements of its <tt class="literal"><span class="pre">iterator_category</span></tt>.</p>
specialization to meet the requirements of its <tt class="literal"><span class="pre">iterator_category</span></tt>.</p>
<table class="citation" frame="void" id="cop95" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<col />
@ -238,23 +434,26 @@ Patterns, C++ Report, February 1995, pp. 24-27.</td></tr>
</table>
</div>
<div class="section" id="reference">
<h1><a class="toc-backref" href="#id15" name="reference">Reference</a></h1>
<h1><a class="toc-backref" href="#id12" name="reference">Reference</a></h1>
<!-- Version 1.3 of this ReStructuredText document corresponds to
n1530_, the paper accepted by the LWG for TR1. -->
<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
rights reserved -->
<pre class="literal-block">
template &lt;
class Derived
, class Value
, class AccessCategory
, class TraversalCategory
, class Reference = /* see <a class="reference" href="#iterator-facade-requirements">below</a> */
, class CategoryOrTraversal
, class Reference = Value&amp;
, class Difference = ptrdiff_t
&gt;
class iterator_facade {
public:
typedef remove_cv&lt;Value&gt;::type value_type;
typedef remove_const&lt;Value&gt;::type value_type;
typedef Reference reference;
typedef /* see <a class="reference" href="#operator-arrow">description of operator-&gt;</a> */ pointer;
typedef Value* pointer;
typedef Difference difference_type;
typedef iterator_tag&lt;AccessCategory, TraversalCategory&gt; iterator_category;
typedef /* see <a class="reference" href="#facade-iterator-category">below</a> */ iterator_category;
reference operator*() const;
/* see <a class="reference" href="#operator-arrow">below</a> */ operator-&gt;() const;
@ -269,104 +468,114 @@ public:
};
// Comparison operators
template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;
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, bool&gt;::type // exposition
operator ==(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);
operator ==(iterator_facade&lt;Dr1, V1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, TC2, R2, D2&gt; const&amp; rhs);
template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;
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, bool&gt;::type
operator !=(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);
operator !=(iterator_facade&lt;Dr1, V1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, TC2, R2, D2&gt; const&amp; rhs);
template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;
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, bool&gt;::type
operator &lt;(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);
operator &lt;(iterator_facade&lt;Dr1, V1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, TC2, R2, D2&gt; const&amp; rhs);
template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;
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, bool&gt;::type
operator &lt;=(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);
operator &lt;=(iterator_facade&lt;Dr1, V1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, TC2, R2, D2&gt; const&amp; rhs);
template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;
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, bool&gt;::type
operator &gt;(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);
operator &gt;(iterator_facade&lt;Dr1, V1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, TC2, R2, D2&gt; const&amp; rhs);
template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;
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, bool&gt;::type
operator &gt;=(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);
operator &gt;=(iterator_facade&lt;Dr1, V1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, TC2, R2, D2&gt; const&amp; rhs);
template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;
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, bool&gt;::type
operator &gt;=(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);
operator &gt;=(iterator_facade&lt;Dr1, V1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, TC2, R2, D2&gt; const&amp; rhs);
// Iterator difference
template &lt;class Dr1, class V1, class AC1, class TC1, class R1, class D1,
class Dr2, class V2, class AC2, class TC2, class R2, class D2&gt;
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, bool&gt;::type
operator -(iterator_facade&lt;Dr1, V1, AC1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, AC2, TC2, R2, D2&gt; const&amp; rhs);
operator -(iterator_facade&lt;Dr1, V1, TC1, R1, D1&gt; const&amp; lhs,
iterator_facade&lt;Dr2, V2, TC2, R2, D2&gt; const&amp; rhs);
// Iterator addition
template &lt;class Derived, class V, class AC, class TC, class R, class D&gt;
Derived operator+ (iterator_facade&lt;Derived, V, AC, TC, R, D&gt; const&amp;,
template &lt;class Derived, class V, class TC, class R, class D&gt;
Derived operator+ (iterator_facade&lt;Derived, V, TC, R, D&gt; const&amp;,
typename Derived::difference_type n)
</pre>
<p>[<em>Note:</em> The <tt class="literal"><span class="pre">enable_if_interoperable</span></tt> template used above is for exposition
purposes. The member operators should be only be in an overload set
provided the derived types <tt class="literal"><span class="pre">Dr1</span></tt> and <tt class="literal"><span class="pre">Dr2</span></tt> are interoperable, by
which we mean they are convertible to each other. The
<p>The <tt class="literal"><span class="pre">enable_if_interoperable</span></tt> template used above is for exposition
purposes. The member operators should be only be in an overload set
provided the derived types <tt class="literal"><span class="pre">Dr1</span></tt> and <tt class="literal"><span class="pre">Dr2</span></tt> are interoperable,
meaning that at least one of the types is convertible to the other. The
<tt class="literal"><span class="pre">enable_if_interoperable</span></tt> approach uses SFINAE to take the operators
out of the overload set when the types are not interoperable.]</p>
<!-- we need a new label here because the presence of markup in the
title prevents an automatic link from being generated -->
<a class="target" id="iterator-facade-requirements" name="iterator-facade-requirements"></a><div class="section" id="id8">
<h2><a class="toc-backref" href="#id16" name="id8"><tt class="literal"><span class="pre">iterator_facade</span></tt> requirements</a></h2>
<p>The <tt class="literal"><span class="pre">Derived</span></tt> template parameter must be a class derived from
<tt class="literal"><span class="pre">iterator_facade</span></tt>.</p>
<p>The default for the <tt class="literal"><span class="pre">Reference</span></tt> parameter is <tt class="literal"><span class="pre">Value&amp;</span></tt> if the
access category for <tt class="literal"><span class="pre">iterator_facade</span></tt> is implicitly convertible to
<tt class="literal"><span class="pre">writable_iterator_tag</span></tt>, and <tt class="literal"><span class="pre">const</span> <span class="pre">Value&amp;</span></tt> otherwise.</p>
<p>The following table describes the other requirements on the
<tt class="literal"><span class="pre">Derived</span></tt> parameter. Depending on the resulting iterator's
<tt class="literal"><span class="pre">iterator_category</span></tt>, a subset of the expressions listed in the table
are required to be valid. The operations in the first column must be
accessible to member functions of class <tt class="literal"><span class="pre">iterator_core_access</span></tt>.</p>
<p>In the table below, <tt class="literal"><span class="pre">X</span></tt> is the derived iterator type, <tt class="literal"><span class="pre">a</span></tt> is an
out of the overload set when the types are not interoperable.
The operators should behave <em>as-if</em> <tt class="literal"><span class="pre">enable_if_interoperable</span></tt>
were defined to be:</p>
<pre class="literal-block">
template &lt;bool, typename&gt; enable_if_interoperable_impl
{};
template &lt;typename T&gt; enable_if_interoperable_impl&lt;true,T&gt;
{ typedef T type; };
template&lt;typename Dr1, typename Dr2, typename T&gt;
struct enable_if_interoperable
: enable_if_interoperable_impl&lt;
is_convertible&lt;Dr1,Dr2&gt;::value || is_convertible&lt;Dr2,Dr1&gt;::value
, T
&gt;
{};
</pre>
<div class="section" id="iterator-facade-usage">
<h2><a class="toc-backref" href="#id13" name="iterator-facade-usage"><tt class="literal"><span class="pre">iterator_facade</span></tt> usage</a></h2>
<p>The following table describes the typical valid expressions on
<tt class="literal"><span class="pre">iterator_facade</span></tt>'s <tt class="literal"><span class="pre">Derived</span></tt> parameter, depending on the
iterator concept(s) it will model. The operations in the first
column must be made accessible to member functions of class
<tt class="literal"><span class="pre">iterator_core_access</span></tt>.</p>
<p>In the table below, <tt class="literal"><span class="pre">F</span></tt> is <tt class="literal"><span class="pre">iterator_facade&lt;X,V,C,R,D&gt;</span></tt>, <tt class="literal"><span class="pre">a</span></tt> is an
object of type <tt class="literal"><span class="pre">X</span></tt>, <tt class="literal"><span class="pre">b</span></tt> and <tt class="literal"><span class="pre">c</span></tt> are objects of type <tt class="literal"><span class="pre">const</span> <span class="pre">X</span></tt>,
<tt class="literal"><span class="pre">n</span></tt> is an object of <tt class="literal"><span class="pre">X::difference_type</span></tt>, <tt class="literal"><span class="pre">y</span></tt> is a constant
object of a single pass iterator type interoperable with X, and <tt class="literal"><span class="pre">z</span></tt>
<tt class="literal"><span class="pre">n</span></tt> is an object of <tt class="literal"><span class="pre">F::difference_type</span></tt>, <tt class="literal"><span class="pre">y</span></tt> is a constant
object of a single pass iterator type interoperable with <tt class="literal"><span class="pre">X</span></tt>, and <tt class="literal"><span class="pre">z</span></tt>
is a constant object of a random access traversal iterator type
interoperable with <tt class="literal"><span class="pre">X</span></tt>.</p>
<table border class="table">
<colgroup>
<col width="19%" />
<col width="18%" />
<col width="36%" />
<col width="26%" />
<col width="21%" />
<col width="35%" />
<col width="25%" />
</colgroup>
<thead valign="bottom">
<tr><th>Expression</th>
<th>Return Type</th>
<th>Assertion/Note</th>
<th>Required to implement
Iterator Concept(s)</th>
<th>Used to implement Iterator
Concept(s)</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="literal"><span class="pre">c.dereference()</span></tt></td>
<td><tt class="literal"><span class="pre">X::reference</span></tt></td>
<td><tt class="literal"><span class="pre">F::reference</span></tt></td>
<td>&nbsp;</td>
<td>Readable Iterator, Writable
Iterator</td>
@ -403,14 +612,14 @@ Iterator</td>
</tr>
<tr><td><tt class="literal"><span class="pre">c.distance_to(b)</span></tt></td>
<td>convertible to
X::difference_type</td>
<tt class="literal"><span class="pre">F::difference_type</span></tt></td>
<td>equivalent to <tt class="literal"><span class="pre">distance(c,</span> <span class="pre">b)</span></tt></td>
<td>Random Access Traversal
Iterator</td>
</tr>
<tr><td><tt class="literal"><span class="pre">c.distance_to(z)</span></tt></td>
<td>convertible to
X::difference_type</td>
<tt class="literal"><span class="pre">F::difference_type</span></tt></td>
<td>equivalent to <tt class="literal"><span class="pre">distance(c,</span> <span class="pre">z)</span></tt>.
Implements <tt class="literal"><span class="pre">c</span> <span class="pre">-</span> <span class="pre">z</span></tt>, <tt class="literal"><span class="pre">c</span> <span class="pre">&lt;</span> <span class="pre">z</span></tt>, <tt class="literal"><span class="pre">c</span>
<span class="pre">&lt;=</span> <span class="pre">z</span></tt>, <tt class="literal"><span class="pre">c</span> <span class="pre">&gt;</span> <span class="pre">z</span></tt>, and <tt class="literal"><span class="pre">c</span> <span class="pre">&gt;=</span> <span class="pre">c</span></tt>.</td>
@ -419,12 +628,62 @@ Iterator</td>
</tr>
</tbody>
</table>
<!-- We should explain more about how the
functions in the interface of iterator_facade
are there conditionally. -JGS -->
<a class="target" id="facade-iterator-category" name="facade-iterator-category"></a></div>
<div class="section" id="iterator-facade-iterator-category">
<h2><a class="toc-backref" href="#id14" name="iterator-facade-iterator-category"><tt class="literal"><span class="pre">iterator_facade</span></tt> iterator category</a></h2>
<p>The <tt class="literal"><span class="pre">iterator_category</span></tt> member of <tt class="literal"><span class="pre">iterator_facade&lt;X,V,R,C,D&gt;</span></tt>
is a type which satisfies the following conditions:</p>
<blockquote>
<ul>
<li><p class="first">if <tt class="literal"><span class="pre">C</span></tt> is convertible to <tt class="literal"><span class="pre">std::input_iterator_tag</span></tt> or
<tt class="literal"><span class="pre">C</span></tt> is convertible to <tt class="literal"><span class="pre">std::output_iterator_tag</span></tt>,
<tt class="literal"><span class="pre">iterator_category</span></tt> is the same as <tt class="literal"><span class="pre">C</span></tt>.</p>
</li>
<li><p class="first">Otherwise, if <tt class="literal"><span class="pre">C</span></tt> is not convertible to
<tt class="literal"><span class="pre">incrementable_traversal_tag</span></tt>, the program is ill-formed</p>
</li>
<li><p class="first">Otherwise:</p>
<ul>
<li><p class="first"><tt class="literal"><span class="pre">iterator_category</span></tt> is convertible to the iterator
category tag or tags given by the following algorithm, and
not to any more-derived iterator category tag or tags:</p>
<pre class="literal-block">
if (R is a reference type
&amp;&amp; C is convertible to forward_traversal_tag)
{
if (C is convertible to random_access_traversal_tag)
return random_access_iterator_tag
else if (C is convertible to bidirectional_traversal_tag)
return bidirectional_iterator_tag
else
return forward_traversal_tag
}
else
{
if (C is convertible to single_pass_traversal_tag
&amp;&amp; R is convertible to V)
{
if (V is const)
return input_iterator_tag
else
return input_iterator_tag and output_iterator_tag
}
else
return output_iterator_tag
}
</pre>
</li>
<li><p class="first"><tt class="literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt> is convertible to the most
derived traversal tag type to which <tt class="literal"><span class="pre">C</span></tt> is also
convertible, and not to any more-derived traversal tag type.</p>
</li>
</ul>
</li>
</ul>
</blockquote>
</div>
<div class="section" id="iterator-facade-operations">
<h2><a class="toc-backref" href="#id17" name="iterator-facade-operations"><tt class="literal"><span class="pre">iterator_facade</span></tt> operations</a></h2>
<h2><a class="toc-backref" href="#id15" name="iterator-facade-operations"><tt class="literal"><span class="pre">iterator_facade</span></tt> operations</a></h2>
<p>The operations in this section are described in terms of operations on
the core interface of <tt class="literal"><span class="pre">Derived</span></tt> which may be inaccessible
(i.e. private). The implementation should access these operations
@ -443,17 +702,14 @@ through member functions of class <tt class="literal"><span class="pre">iterator
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">If <tt class="literal"><span class="pre">X::reference</span></tt> is a reference type, returns an object
of type <tt class="literal"><span class="pre">X::pointer</span></tt> equal to:</p>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">If <tt class="literal"><span class="pre">reference</span></tt> is a reference type, an object
of type <tt class="literal"><span class="pre">pointer</span></tt> equal to:</p>
<pre class="literal-block">
&amp;static_cast&lt;Derived const*&gt;(this)-&gt;dereference()
</pre>
<p>Otherwise returns an object of unspecified type such that, given an
object <tt class="literal"><span class="pre">a</span></tt> of type <tt class="literal"><span class="pre">X</span></tt>, <tt class="literal"><span class="pre">a-&gt;m</span></tt> is equivalent to <tt class="literal"><span class="pre">(w</span> <span class="pre">=</span> <span class="pre">*a,</span>
<span class="pre">w.m)</span></tt> for some temporary object <tt class="literal"><span class="pre">w</span></tt> of type <tt class="literal"><span class="pre">X::value_type</span></tt>.</p>
<p class="last">The type <tt class="literal"><span class="pre">X::pointer</span></tt> is <tt class="literal"><span class="pre">Value*</span></tt> if the access category for
<tt class="literal"><span class="pre">X</span></tt> is implicitly convertible to <tt class="literal"><span class="pre">writable_iterator_tag</span></tt>, and
<tt class="literal"><span class="pre">Value</span> <span class="pre">const*</span></tt> otherwise.</p>
<p class="last">Otherwise returns an object of unspecified type such that,
<tt class="literal"><span class="pre">(*static_cast&lt;Derived</span> <span class="pre">const*&gt;(this))-&gt;m</span></tt> is equivalent to <tt class="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="literal"><span class="pre">w</span></tt> of type <tt class="literal"><span class="pre">value_type</span></tt>.</p>
</td>
</tr>
</tbody>
@ -463,9 +719,9 @@ object <tt class="literal"><span class="pre">a</span></tt> of type <tt class="li
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">an object convertible to <tt class="literal"><span class="pre">X::reference</span></tt> and holding a copy
<em>p</em> of <tt class="literal"><span class="pre">a+n</span></tt> such that, for a constant object <tt class="literal"><span class="pre">v</span></tt> of type
<tt class="literal"><span class="pre">X::value_type</span></tt>, <tt class="literal"><span class="pre">X::reference(a[n]</span> <span class="pre">=</span> <span class="pre">v)</span></tt> is equivalent
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">an object convertible to <tt class="literal"><span class="pre">reference</span></tt> and holding a copy
<em>p</em> of <tt class="literal"><span class="pre">*static_cast&lt;Derived</span> <span class="pre">const*&gt;(this)</span> <span class="pre">+</span> <span class="pre">n</span></tt> such that, for a constant object <tt class="literal"><span class="pre">v</span></tt> of type
<tt class="literal"><span class="pre">value_type</span></tt>, <tt class="literal"><span class="pre">(*static_cast&lt;Derived</span> <span class="pre">const*&gt;(this))[n]</span> <span class="pre">=</span> <span class="pre">v</span></tt> is equivalent
to <tt class="literal"><span class="pre">p</span> <span class="pre">=</span> <span class="pre">v</span></tt>.</td>
</tr>
</tbody>
@ -477,17 +733,12 @@ to <tt class="literal"><span class="pre">p</span> <span class="pre">=</span> <sp
<tbody valign="top">
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><pre class="first last literal-block">
static_cast&lt;Derived*&gt;(this)-&gt;increment();
return *this;
return *static_cast&lt;Derived*&gt;(this);
</pre>
</td>
</tr>
</tbody>
</table>
<!-- I realize that the committee is moving away from specifying things
like this in terms of code, but I worried about the imprecision of
saying that a core interface function is invoked without describing
the downcast. An alternative to what I did would be to mention it
above where we talk about accessibility. -->
<p><tt class="literal"><span class="pre">Derived</span> <span class="pre">operator++(int);</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
@ -509,7 +760,7 @@ return tmp;
<tbody valign="top">
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><pre class="first last literal-block">
static_cast&lt;Derived*&gt;(this)-&gt;decrement();
return *this;
return static_cast&lt;Derived*&gt;(this);
</pre>
</td>
</tr>
@ -536,7 +787,7 @@ return tmp;
<tbody valign="top">
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><pre class="first last literal-block">
static_cast&lt;Derived*&gt;(this)-&gt;advance(n);
return *this;
return static_cast&lt;Derived*&gt;(this);
</pre>
</td>
</tr>
@ -549,7 +800,7 @@ return *this;
<tbody valign="top">
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><pre class="first last literal-block">
static_cast&lt;Derived*&gt;(this)-&gt;advance(-n);
return *this;
return static_cast&lt;Derived*&gt;(this);
</pre>
</td>
</tr>
@ -560,10 +811,11 @@ return *this;
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Derived tmp(static_cast&lt;Derived const*&gt;(this));
return tmp -= n;</td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">static_cast&lt;Derived</span> <span class="pre">const*&gt;(this)-&gt;advance(-n);</span></tt></td>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><pre class="first last literal-block">
Derived tmp(static_cast&lt;Derived const*&gt;(this));
return tmp -= n;
</pre>
</td>
</tr>
</tbody>
</table>
@ -573,7 +825,7 @@ return tmp -= n;</td>
<hr class="footer" />
<div class="footer">
<a class="reference" href="iterator_facade.rst">View document source</a>.
Generated on: 2003-09-21 09:34 UTC.
Generated on: 2003-11-24 05:00 UTC.
Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div>
</body>