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

Fixed up definition of facade's iterator_category

Browse Source 
fixed table widths in new-iter-concepts

cross-referenced interoperability concept in iterator_facade_tutorial

iterator_traversal can't satisfy UnaryTypeTrait: that's a boolean trait.


[SVN r21742]
This commit is contained in:
Dave Abrahams 2004-01-14 23:23:54 +00:00
parent 42147b9e86
commit f1f6262be7
7 changed files with 394 additions and 318 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -693,28 +693,53 @@ template <class Derived, class V, class TC, class R, class D>
Derived operator+ (iterator_facade<Derived, V, TC, R, D> const&, Derived operator+ (iterator_facade<Derived, V, TC, R, D> const&,
typename Derived::difference_type n) typename Derived::difference_type n)
</pre> </pre>
<a class="target" id="iterator-category" name="iterator-category"></a><p>The <tt class="literal"><span class="pre">iterator_category</span></tt> member of <tt class="literal"><span class="pre">iterator_facade</span></tt> is <a class="target" id="iterator-category" name="iterator-category"></a><p>The <tt class="literal"><span class="pre">iterator_category</span></tt> member of <tt class="literal"><span class="pre">iterator_facade</span></tt> is</p>
<tt class="literal"><span class="pre">facade_iterator_category(CategoryOrTraversal,</span> <span class="pre">value_type,</span>
<span class="pre">reference)</span></tt>, as specified by the following pseudo-code:</p>
<pre class="literal-block"> <pre class="literal-block">
facade_iterator_category(C, V, R) = <em>iterator-category</em>(CategoryOrTraversal, value_type, reference)
if (C is convertible to input_iterator_tag or output_iterator_tag) then
return C
else if (C is convertible to incrementable_traversal_tag) then
if (R is a reference type
and C is convertible to forward_traversal_tag) then
if (C is convertible to random_access_traversal_tag)
return a type convertible to random_access_iterator_tag
else if (C is convertible to bidirectional_traversal_tag)
return a type convertible to bidirectional_iterator_tag
else
return a type convertible to forward_iterator_tag
else if (C is convertible to single_pass_traversal_tag
and R is convertible to V)
return a type convertible to input_iterator_tag
else
return C
</pre> </pre>
<p>where <em>iterator-category</em> is defined as follows:</p>
<pre class="literal-block">
<em>iterator-category</em>(C,R,V) :=
if (C is convertible to std::input_iterator_tag
|| C is convertible to std::output_iterator_tag
)
return C
else if (C is not convertible to incrementable_traversal_tag)
<em>the program is ill-formed</em>
else return a type X satisfying the following two constraints:
1. X is convertible to X1, and not to any more-derived
type, where X1 is defined by:
if (R is a reference type
&amp;&amp; C is convertible to forward_traversal_tag)
{
if (C is convertible to random_access_traversal_tag)
X1 = random_access_iterator_tag
else if (C is convertible to bidirectional_traversal_tag)
X1 = bidirectional_iterator_tag
else
X1 = forward_iterator_tag
}
else
{
if (C is convertible to single_pass_traversal_tag
&amp;&amp; R is convertible to V)
X1 = input_iterator_tag
else
X1 = C
}
2. <a class="reference" href="new-iter-concepts.html#category-to-traversal"><em>category-to-traversal</em></a>(X) is convertible to the most
derived traversal tag type to which X is also
convertible, and not to any more-derived traversal tag
type.
</pre>
<p>[Note: the intention is to allow <tt class="literal"><span class="pre">iterator_category</span></tt> to be one of
the five original category tags when convertibility to one of the
traversal tags would add no information]</p>
<!-- Copyright David Abrahams 2004. Use, modification and distribution is --> <!-- Copyright David Abrahams 2004. Use, modification and distribution is -->
<!-- subject to the Boost Software License, Version 1.0. (See accompanying --> <!-- 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) --> <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->

53
doc/facade_iterator_category.rst
View File

@ -1,24 +1,49 @@
.. parsed-literal::
*iterator-category*\ (C,R,V) :=
:: if (C is convertible to std::input_iterator_tag
|| C is convertible to std::output_iterator_tag
facade_iterator_category(C, V, R) = )
if (C is convertible to input_iterator_tag or output_iterator_tag) then
return C return C
else if (C is convertible to incrementable_traversal_tag) then
else if (C is not convertible to incrementable_traversal_tag)
*the program is ill-formed*
else return a type X satisfying the following two constraints:
1. X is convertible to X1, and not to any more-derived
type, where X1 is defined by:
if (R is a reference type if (R is a reference type
and C is convertible to forward_traversal_tag) then && C is convertible to forward_traversal_tag)
{
if (C is convertible to random_access_traversal_tag) if (C is convertible to random_access_traversal_tag)
return a type convertible to random_access_iterator_tag X1 = random_access_iterator_tag
else if (C is convertible to bidirectional_traversal_tag) else if (C is convertible to bidirectional_traversal_tag)
return a type convertible to bidirectional_iterator_tag X1 = bidirectional_iterator_tag
else else
return a type convertible to forward_iterator_tag X1 = forward_iterator_tag
else if (C is convertible to single_pass_traversal_tag }
and R is convertible to V)
return a type convertible to input_iterator_tag
else else
return C {
if (C is convertible to single_pass_traversal_tag
&& R is convertible to V)
X1 = input_iterator_tag
else
X1 = C
}
2. |category-to-traversal|_\ (X) is convertible to the most
derived traversal tag type to which X is also
convertible, and not to any more-derived traversal tag
type.
.. |category-to-traversal| replace:: *category-to-traversal*
.. _`category-to-traversal`: new-iter-concepts.html#category-to-traversal
[Note: the intention is to allow ``iterator_category`` to be one of
the five original category tags when convertibility to one of the
traversal tags would add no information]
.. Copyright David Abrahams 2004. Use, modification and distribution is .. Copyright David Abrahams 2004. Use, modification and distribution is
.. subject to the Boost Software License, Version 1.0. (See accompanying .. subject to the Boost Software License, Version 1.0. (See accompanying

159
doc/iterator_facade.html
View File

@ -45,43 +45,43 @@ and associated types, to be supplied by a derived iterator class.</td>
<div class="contents topic" id="table-of-contents"> <div class="contents topic" id="table-of-contents">
<p class="topic-title"><a name="table-of-contents">Table of Contents</a></p> <p class="topic-title"><a name="table-of-contents">Table of Contents</a></p>
<ul class="simple"> <ul class="simple">
<li><a class="reference" href="#overview" id="id20" name="id20">Overview</a><ul> <li><a class="reference" href="#overview" id="id21" name="id21">Overview</a><ul>
<li><a class="reference" href="#usage" id="id21" name="id21">Usage</a></li> <li><a class="reference" href="#usage" id="id22" name="id22">Usage</a></li>
<li><a class="reference" href="#iterator-core-access" id="id22" name="id22">Iterator Core Access</a></li> <li><a class="reference" href="#iterator-core-access" id="id23" name="id23">Iterator Core Access</a></li>
<li><a class="reference" href="#operator" id="id23" name="id23"><tt class="literal"><span class="pre">operator[]</span></tt></a></li> <li><a class="reference" href="#operator" id="id24" name="id24"><tt class="literal"><span class="pre">operator[]</span></tt></a></li>
<li><a class="reference" href="#id2" id="id24" name="id24"><tt class="literal"><span class="pre">operator-&gt;</span></tt></a></li> <li><a class="reference" href="#id2" id="id25" name="id25"><tt class="literal"><span class="pre">operator-&gt;</span></tt></a></li>
</ul> </ul>
</li> </li>
<li><a class="reference" href="#reference" id="id25" name="id25">Reference</a><ul> <li><a class="reference" href="#reference" id="id26" name="id26">Reference</a><ul>
<li><a class="reference" href="#iterator-facade-requirements" id="id26" name="id26"><tt class="literal"><span class="pre">iterator_facade</span></tt> Requirements</a></li> <li><a class="reference" href="#iterator-facade-requirements" id="id27" name="id27"><tt class="literal"><span class="pre">iterator_facade</span></tt> Requirements</a></li>
<li><a class="reference" href="#iterator-facade-operations" id="id27" name="id27"><tt class="literal"><span class="pre">iterator_facade</span></tt> operations</a></li> <li><a class="reference" href="#iterator-facade-operations" id="id28" name="id28"><tt class="literal"><span class="pre">iterator_facade</span></tt> operations</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference" href="#tutorial-example" id="id28" name="id28">Tutorial Example</a><ul> <li><a class="reference" href="#tutorial-example" id="id29" name="id29">Tutorial Example</a><ul>
<li><a class="reference" href="#the-problem" id="id29" name="id29">The Problem</a></li> <li><a class="reference" href="#the-problem" id="id30" name="id30">The Problem</a></li>
<li><a class="reference" href="#a-basic-iterator-using-iterator-facade" id="id30" name="id30">A Basic Iterator Using <tt class="literal"><span class="pre">iterator_facade</span></tt></a><ul> <li><a class="reference" href="#a-basic-iterator-using-iterator-facade" id="id31" name="id31">A Basic Iterator Using <tt class="literal"><span class="pre">iterator_facade</span></tt></a><ul>
<li><a class="reference" href="#template-arguments-for-iterator-facade" id="id31" name="id31">Template Arguments for <tt class="literal"><span class="pre">iterator_facade</span></tt></a><ul> <li><a class="reference" href="#template-arguments-for-iterator-facade" id="id32" name="id32">Template Arguments for <tt class="literal"><span class="pre">iterator_facade</span></tt></a><ul>
<li><a class="reference" href="#derived" id="id32" name="id32"><tt class="literal"><span class="pre">Derived</span></tt></a></li> <li><a class="reference" href="#derived" id="id33" name="id33"><tt class="literal"><span class="pre">Derived</span></tt></a></li>
<li><a class="reference" href="#value" id="id33" name="id33"><tt class="literal"><span class="pre">Value</span></tt></a></li> <li><a class="reference" href="#value" id="id34" name="id34"><tt class="literal"><span class="pre">Value</span></tt></a></li>
<li><a class="reference" href="#categoryortraversal" id="id34" name="id34"><tt class="literal"><span class="pre">CategoryOrTraversal</span></tt></a></li> <li><a class="reference" href="#categoryortraversal" id="id35" name="id35"><tt class="literal"><span class="pre">CategoryOrTraversal</span></tt></a></li>
<li><a class="reference" href="#id10" id="id35" name="id35"><tt class="literal"><span class="pre">Reference</span></tt></a></li> <li><a class="reference" href="#id10" id="id36" name="id36"><tt class="literal"><span class="pre">Reference</span></tt></a></li>
<li><a class="reference" href="#difference" id="id36" name="id36"><tt class="literal"><span class="pre">Difference</span></tt></a></li> <li><a class="reference" href="#difference" id="id37" name="id37"><tt class="literal"><span class="pre">Difference</span></tt></a></li>
</ul> </ul>
</li> </li>
<li><a class="reference" href="#constructors-and-data-members" id="id37" name="id37">Constructors and Data Members</a></li> <li><a class="reference" href="#constructors-and-data-members" id="id38" name="id38">Constructors and Data Members</a></li>
<li><a class="reference" href="#implementing-the-core-operations" id="id38" name="id38">Implementing the Core Operations</a></li> <li><a class="reference" href="#implementing-the-core-operations" id="id39" name="id39">Implementing the Core Operations</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference" href="#a-constant-node-iterator" id="id39" name="id39">A constant <tt class="literal"><span class="pre">node_iterator</span></tt></a></li> <li><a class="reference" href="#a-constant-node-iterator" id="id40" name="id40">A constant <tt class="literal"><span class="pre">node_iterator</span></tt></a></li>
<li><a class="reference" href="#interoperability" id="id40" name="id40">Interoperability</a></li> <li><a class="reference" href="#interoperability" id="id41" name="id41">Interoperability</a></li>
<li><a class="reference" href="#telling-the-truth" id="id41" name="id41">Telling the Truth</a></li> <li><a class="reference" href="#telling-the-truth" id="id42" name="id42">Telling the Truth</a></li>
<li><a class="reference" href="#wrap-up" id="id42" name="id42">Wrap Up</a></li> <li><a class="reference" href="#wrap-up" id="id43" name="id43">Wrap Up</a></li>
</ul> </ul>
</li> </li>
</ul> </ul>
</div> </div>
<div class="section" id="overview"> <div class="section" id="overview">
<h1><a class="toc-backref" href="#id20" name="overview">Overview</a></h1> <h1><a class="toc-backref" href="#id21" name="overview">Overview</a></h1>
<!-- Version 1.1 of this ReStructuredText document corresponds to <!-- Version 1.1 of this ReStructuredText document corresponds to
n1530_, the paper accepted by the LWG for TR1. --> n1530_, the paper accepted by the LWG for TR1. -->
<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All <!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
@ -126,7 +126,7 @@ impossible.</li>
</ol> </ol>
</blockquote> </blockquote>
<div class="section" id="usage"> <div class="section" id="usage">
<h2><a class="toc-backref" href="#id21" name="usage">Usage</a></h2> <h2><a class="toc-backref" href="#id22" name="usage">Usage</a></h2>
<p>The user of <tt class="literal"><span class="pre">iterator_facade</span></tt> derives his iterator class from a <p>The user of <tt class="literal"><span class="pre">iterator_facade</span></tt> derives his iterator class from a
specialization of <tt class="literal"><span class="pre">iterator_facade</span></tt> and passes the derived specialization of <tt class="literal"><span class="pre">iterator_facade</span></tt> and passes the derived
iterator class as <tt class="literal"><span class="pre">iterator_facade</span></tt>'s first template parameter. iterator class as <tt class="literal"><span class="pre">iterator_facade</span></tt>'s first template parameter.
@ -190,7 +190,7 @@ Iterator or a more-refined iterator concept, a default constructor is
required.</p> required.</p>
</div> </div>
<div class="section" id="iterator-core-access"> <div class="section" id="iterator-core-access">
<h2><a class="toc-backref" href="#id22" name="iterator-core-access">Iterator Core Access</a></h2> <h2><a class="toc-backref" href="#id23" name="iterator-core-access">Iterator Core Access</a></h2>
<p><tt class="literal"><span class="pre">iterator_facade</span></tt> and the operator implementations need to be able <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 to access the core member functions in the derived class. Making the
core member functions public would expose an implementation detail to core member functions public would expose an implementation detail to
@ -224,7 +224,7 @@ open a safety loophole, as every core member function preserves the
invariants of the iterator.</p> invariants of the iterator.</p>
</div> </div>
<div class="section" id="operator"> <div class="section" id="operator">
<h2><a class="toc-backref" href="#id23" name="operator"><tt class="literal"><span class="pre">operator[]</span></tt></a></h2> <h2><a class="toc-backref" href="#id24" name="operator"><tt class="literal"><span class="pre">operator[]</span></tt></a></h2>
<p>The indexing operator for a generalized iterator presents special <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 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>. required to return something convertible to its <tt class="literal"><span class="pre">value_type</span></tt>.
@ -247,7 +247,7 @@ class; it will hide the one supplied by <tt class="literal"><span class="pre">it
clients of her iterator.</p> clients of her iterator.</p>
<a class="target" id="operator-arrow" name="operator-arrow"></a></div> <a class="target" id="operator-arrow" name="operator-arrow"></a></div>
<div class="section" id="id2"> <div class="section" id="id2">
<h2><a class="toc-backref" href="#id24" name="id2"><tt class="literal"><span class="pre">operator-&gt;</span></tt></a></h2> <h2><a class="toc-backref" href="#id25" name="id2"><tt class="literal"><span class="pre">operator-&gt;</span></tt></a></h2>
<p>The <tt class="literal"><span class="pre">reference</span></tt> type of a readable iterator (and today's input <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 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> 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>
@ -270,7 +270,7 @@ Patterns, C++ Report, February 1995, pp. 24-27.</td></tr>
</div> </div>
</div> </div>
<div class="section" id="reference"> <div class="section" id="reference">
<h1><a class="toc-backref" href="#id25" name="reference">Reference</a></h1> <h1><a class="toc-backref" href="#id26" name="reference">Reference</a></h1>
<!-- Version 1.3 of this ReStructuredText document corresponds to <!-- Version 1.3 of this ReStructuredText document corresponds to
n1530_, the paper accepted by the LWG for TR1. --> n1530_, the paper accepted by the LWG for TR1. -->
<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All <!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
@ -358,28 +358,53 @@ 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;, Derived operator+ (iterator_facade&lt;Derived, V, TC, R, D&gt; const&amp;,
typename Derived::difference_type n) typename Derived::difference_type n)
</pre> </pre>
<a class="target" id="iterator-category" name="iterator-category"></a><p>The <tt class="literal"><span class="pre">iterator_category</span></tt> member of <tt class="literal"><span class="pre">iterator_facade</span></tt> is <a class="target" id="iterator-category" name="iterator-category"></a><p>The <tt class="literal"><span class="pre">iterator_category</span></tt> member of <tt class="literal"><span class="pre">iterator_facade</span></tt> is</p>
<tt class="literal"><span class="pre">facade_iterator_category(CategoryOrTraversal,</span> <span class="pre">value_type,</span>
<span class="pre">reference)</span></tt>, as specified by the following pseudo-code:</p>
<pre class="literal-block"> <pre class="literal-block">
facade_iterator_category(C, V, R) = <em>iterator-category</em>(CategoryOrTraversal, value_type, reference)
if (C is convertible to input_iterator_tag or output_iterator_tag) then
return C
else if (C is convertible to incrementable_traversal_tag) then
if (R is a reference type
and C is convertible to forward_traversal_tag) then
if (C is convertible to random_access_traversal_tag)
return a type convertible to random_access_iterator_tag
else if (C is convertible to bidirectional_traversal_tag)
return a type convertible to bidirectional_iterator_tag
else
return a type convertible to forward_iterator_tag
else if (C is convertible to single_pass_traversal_tag
and R is convertible to V)
return a type convertible to input_iterator_tag
else
return C
</pre> </pre>
<p>where <em>iterator-category</em> is defined as follows:</p>
<pre class="literal-block">
<em>iterator-category</em>(C,R,V) :=
if (C is convertible to std::input_iterator_tag
|| C is convertible to std::output_iterator_tag
)
return C
else if (C is not convertible to incrementable_traversal_tag)
<em>the program is ill-formed</em>
else return a type X satisfying the following two constraints:
1. X is convertible to X1, and not to any more-derived
type, where X1 is defined by:
if (R is a reference type
&amp;&amp; C is convertible to forward_traversal_tag)
{
if (C is convertible to random_access_traversal_tag)
X1 = random_access_iterator_tag
else if (C is convertible to bidirectional_traversal_tag)
X1 = bidirectional_iterator_tag
else
X1 = forward_iterator_tag
}
else
{
if (C is convertible to single_pass_traversal_tag
&amp;&amp; R is convertible to V)
X1 = input_iterator_tag
else
X1 = C
}
2. <a class="reference" href="new-iter-concepts.html#category-to-traversal"><em>category-to-traversal</em></a>(X) is convertible to the most
derived traversal tag type to which X is also
convertible, and not to any more-derived traversal tag
type.
</pre>
<p>[Note: the intention is to allow <tt class="literal"><span class="pre">iterator_category</span></tt> to be one of
the five original category tags when convertibility to one of the
traversal tags would add no information]</p>
<!-- Copyright David Abrahams 2004. Use, modification and distribution is --> <!-- Copyright David Abrahams 2004. Use, modification and distribution is -->
<!-- subject to the Boost Software License, Version 1.0. (See accompanying --> <!-- 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) --> <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
@ -415,7 +440,7 @@ struct enable_if_interoperable
{}; {};
</pre> </pre>
<div class="section" id="iterator-facade-requirements"> <div class="section" id="iterator-facade-requirements">
<h2><a class="toc-backref" href="#id26" name="iterator-facade-requirements"><tt class="literal"><span class="pre">iterator_facade</span></tt> Requirements</a></h2> <h2><a class="toc-backref" href="#id27" name="iterator-facade-requirements"><tt class="literal"><span class="pre">iterator_facade</span></tt> Requirements</a></h2>
<p>The following table describes the typical valid expressions on <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 <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 iterator concept(s) it will model. The operations in the first
@ -486,7 +511,7 @@ Iterator</td>
</div> </div>
</div> </div>
<div class="section" id="iterator-facade-operations"> <div class="section" id="iterator-facade-operations">
<h2><a class="toc-backref" href="#id27" name="iterator-facade-operations"><tt class="literal"><span class="pre">iterator_facade</span></tt> operations</a></h2> <h2><a class="toc-backref" href="#id28" 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 <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 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 (i.e. private). The implementation should access these operations
@ -627,7 +652,7 @@ return tmp -= n;
</div> </div>
</div> </div>
<div class="section" id="tutorial-example"> <div class="section" id="tutorial-example">
<h1><a class="toc-backref" href="#id28" name="tutorial-example">Tutorial Example</a></h1> <h1><a class="toc-backref" href="#id29" name="tutorial-example">Tutorial Example</a></h1>
<!-- Copyright David Abrahams 2004. Use, modification and distribution is --> <!-- Copyright David Abrahams 2004. Use, modification and distribution is -->
<!-- subject to the Boost Software License, Version 1.0. (See accompanying --> <!-- 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) --> <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
@ -637,7 +662,7 @@ 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> 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> mailing list.</p>
<div class="section" id="the-problem"> <div class="section" id="the-problem">
<h2><a class="toc-backref" href="#id29" name="the-problem">The Problem</a></h2> <h2><a class="toc-backref" href="#id30" name="the-problem">The Problem</a></h2>
<p>Say we've written a polymorphic linked list node base class:</p> <p>Say we've written a polymorphic linked list node base class:</p>
<pre class="literal-block"> <pre class="literal-block">
# include &lt;iostream&gt; # include &lt;iostream&gt;
@ -699,7 +724,7 @@ inline std::ostream&amp; operator&lt;&lt;(std::ostream&amp; s, node_base const&a
lists.</p> lists.</p>
</div> </div>
<div class="section" id="a-basic-iterator-using-iterator-facade"> <div class="section" id="a-basic-iterator-using-iterator-facade">
<h2><a class="toc-backref" href="#id30" name="a-basic-iterator-using-iterator-facade">A Basic Iterator Using <tt class="literal"><span class="pre">iterator_facade</span></tt></a></h2> <h2><a class="toc-backref" href="#id31" name="a-basic-iterator-using-iterator-facade">A Basic Iterator Using <tt class="literal"><span class="pre">iterator_facade</span></tt></a></h2>
<p>We will construct a <tt class="literal"><span class="pre">node_iterator</span></tt> class using inheritance from <p>We will construct a <tt class="literal"><span class="pre">node_iterator</span></tt> class using inheritance from
<tt class="literal"><span class="pre">iterator_facade</span></tt> to implement most of the iterator's operations.</p> <tt class="literal"><span class="pre">iterator_facade</span></tt> to implement most of the iterator's operations.</p>
<pre class="literal-block"> <pre class="literal-block">
@ -713,24 +738,24 @@ class node_iterator
}; };
</pre> </pre>
<div class="section" id="template-arguments-for-iterator-facade"> <div class="section" id="template-arguments-for-iterator-facade">
<h3><a class="toc-backref" href="#id31" name="template-arguments-for-iterator-facade">Template Arguments for <tt class="literal"><span class="pre">iterator_facade</span></tt></a></h3> <h3><a class="toc-backref" href="#id32" name="template-arguments-for-iterator-facade">Template Arguments for <tt class="literal"><span class="pre">iterator_facade</span></tt></a></h3>
<p><tt class="literal"><span class="pre">iterator_facade</span></tt> has several template parameters, so we must decide <p><tt class="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="literal"><span class="pre">Derived</span></tt>, what types to use for the arguments. The parameters are <tt class="literal"><span class="pre">Derived</span></tt>,
<tt class="literal"><span class="pre">Value</span></tt>, <tt class="literal"><span class="pre">CategoryOrTraversal</span></tt>, <tt class="literal"><span class="pre">Reference</span></tt>, and <tt class="literal"><span class="pre">Difference</span></tt>.</p> <tt class="literal"><span class="pre">Value</span></tt>, <tt class="literal"><span class="pre">CategoryOrTraversal</span></tt>, <tt class="literal"><span class="pre">Reference</span></tt>, and <tt class="literal"><span class="pre">Difference</span></tt>.</p>
<div class="section" id="derived"> <div class="section" id="derived">
<h4><a class="toc-backref" href="#id32" name="derived"><tt class="literal"><span class="pre">Derived</span></tt></a></h4> <h4><a class="toc-backref" href="#id33" name="derived"><tt class="literal"><span class="pre">Derived</span></tt></a></h4>
<p>Because <tt class="literal"><span class="pre">iterator_facade</span></tt> is meant to be used with the CRTP <p>Because <tt class="literal"><span class="pre">iterator_facade</span></tt> is meant to be used with the CRTP
<a class="citation-reference" href="#cop95" id="id8" name="id8">[Cop95]</a> the first parameter is the iterator class name itself, <a class="citation-reference" href="#cop95" id="id8" name="id8">[Cop95]</a> the first parameter is the iterator class name itself,
<tt class="literal"><span class="pre">node_iterator</span></tt>.</p> <tt class="literal"><span class="pre">node_iterator</span></tt>.</p>
</div> </div>
<div class="section" id="value"> <div class="section" id="value">
<h4><a class="toc-backref" href="#id33" name="value"><tt class="literal"><span class="pre">Value</span></tt></a></h4> <h4><a class="toc-backref" href="#id34" name="value"><tt class="literal"><span class="pre">Value</span></tt></a></h4>
<p>The <tt class="literal"><span class="pre">Value</span></tt> parameter determines the <tt class="literal"><span class="pre">node_iterator</span></tt>'s <p>The <tt class="literal"><span class="pre">Value</span></tt> parameter determines the <tt class="literal"><span class="pre">node_iterator</span></tt>'s
<tt class="literal"><span class="pre">value_type</span></tt>. In this case, we are iterating over <tt class="literal"><span class="pre">node_base</span></tt> <tt class="literal"><span class="pre">value_type</span></tt>. In this case, we are iterating over <tt class="literal"><span class="pre">node_base</span></tt>
objects, so <tt class="literal"><span class="pre">Value</span></tt> will be <tt class="literal"><span class="pre">node_base</span></tt>.</p> objects, so <tt class="literal"><span class="pre">Value</span></tt> will be <tt class="literal"><span class="pre">node_base</span></tt>.</p>
</div> </div>
<div class="section" id="categoryortraversal"> <div class="section" id="categoryortraversal">
<h4><a class="toc-backref" href="#id34" name="categoryortraversal"><tt class="literal"><span class="pre">CategoryOrTraversal</span></tt></a></h4> <h4><a class="toc-backref" href="#id35" name="categoryortraversal"><tt class="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 <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="literal"><span class="pre">node_iterator</span></tt> is going to model. Singly-linked lists only have <tt class="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 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
@ -750,7 +775,7 @@ end up being <tt class="literal"><span class="pre">std::forward_iterator_tag</sp
</table> </table>
</div> </div>
<div class="section" id="id10"> <div class="section" id="id10">
<h4><a class="toc-backref" href="#id35" name="id10"><tt class="literal"><span class="pre">Reference</span></tt></a></h4> <h4><a class="toc-backref" href="#id36" name="id10"><tt class="literal"><span class="pre">Reference</span></tt></a></h4>
<p>The <tt class="literal"><span class="pre">Reference</span></tt> argument becomes the type returned by <p>The <tt class="literal"><span class="pre">Reference</span></tt> argument becomes the type returned by
<tt class="literal"><span class="pre">node_iterator</span></tt>'s dereference operation, and will also be the <tt class="literal"><span class="pre">node_iterator</span></tt>'s dereference operation, and will also be the
same as <tt class="literal"><span class="pre">std::iterator_traits&lt;node_iterator&gt;::reference</span></tt>. The same as <tt class="literal"><span class="pre">std::iterator_traits&lt;node_iterator&gt;::reference</span></tt>. The
@ -759,7 +784,7 @@ library's default for this parameter is <tt class="literal"><span class="pre">Va
type, we can omit this argument, or pass <tt class="literal"><span class="pre">use_default</span></tt>.</p> type, we can omit this argument, or pass <tt class="literal"><span class="pre">use_default</span></tt>.</p>
</div> </div>
<div class="section" id="difference"> <div class="section" id="difference">
<h4><a class="toc-backref" href="#id36" name="difference"><tt class="literal"><span class="pre">Difference</span></tt></a></h4> <h4><a class="toc-backref" href="#id37" name="difference"><tt class="literal"><span class="pre">Difference</span></tt></a></h4>
<p>The <tt class="literal"><span class="pre">Difference</span></tt> argument determines how the distance between <p>The <tt class="literal"><span class="pre">Difference</span></tt> argument determines how the distance between
two <tt class="literal"><span class="pre">node_iterator</span></tt>s will be measured and will also be the two <tt class="literal"><span class="pre">node_iterator</span></tt>s will be measured and will also be the
same as <tt class="literal"><span class="pre">std::iterator_traits&lt;node_iterator&gt;::difference_type</span></tt>. same as <tt class="literal"><span class="pre">std::iterator_traits&lt;node_iterator&gt;::difference_type</span></tt>.
@ -786,7 +811,7 @@ class node_iterator
</div> </div>
</div> </div>
<div class="section" id="constructors-and-data-members"> <div class="section" id="constructors-and-data-members">
<h3><a class="toc-backref" href="#id37" name="constructors-and-data-members">Constructors and Data Members</a></h3> <h3><a class="toc-backref" href="#id38" name="constructors-and-data-members">Constructors and Data Members</a></h3>
<p>Next we need to decide how to represent the iterator's position. <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 This representation will take the form of data members, so we'll
also need to write constructors to initialize them. The also need to write constructors to initialize them. The
@ -831,7 +856,7 @@ default constructor to leave <tt class="literal"><span class="pre">m_node</span>
</table> </table>
</div> </div>
<div class="section" id="implementing-the-core-operations"> <div class="section" id="implementing-the-core-operations">
<h3><a class="toc-backref" href="#id38" name="implementing-the-core-operations">Implementing the Core Operations</a></h3> <h3><a class="toc-backref" href="#id39" 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 <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 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 <a class="reference" href="#core-operations">table</a>, we can see that the first three rows are applicable
@ -882,7 +907,7 @@ iterator! For a working example of its use, see <a class="reference" href="../e
</div> </div>
</div> </div>
<div class="section" id="a-constant-node-iterator"> <div class="section" id="a-constant-node-iterator">
<h2><a class="toc-backref" href="#id39" name="a-constant-node-iterator">A constant <tt class="literal"><span class="pre">node_iterator</span></tt></a></h2> <h2><a class="toc-backref" href="#id40" name="a-constant-node-iterator">A constant <tt class="literal"><span class="pre">node_iterator</span></tt></a></h2>
<div class="sidebar"> <div class="sidebar">
<p class="sidebar-title">Constant and Mutable iterators</p> <p class="sidebar-title">Constant and Mutable iterators</p>
<p>The term <strong>mutable iterator</strong> means an iterator through which <p>The term <strong>mutable iterator</strong> means an iterator through which
@ -983,7 +1008,7 @@ typedef node_iter&lt;node_base const&gt; node_const_iterator;
</pre> </pre>
</div> </div>
<div class="section" id="interoperability"> <div class="section" id="interoperability">
<h2><a class="toc-backref" href="#id40" name="interoperability">Interoperability</a></h2> <h2><a class="toc-backref" href="#id41" name="interoperability">Interoperability</a></h2>
<p>Our <tt class="literal"><span class="pre">const_node_iterator</span></tt> works perfectly well on its own, but <p>Our <tt class="literal"><span class="pre">const_node_iterator</span></tt> works perfectly well on its own, but
taken together with <tt class="literal"><span class="pre">node_iterator</span></tt> it doesn't quite meet taken together with <tt class="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 expectations. For example, we'd like to be able to pass a
@ -993,7 +1018,7 @@ just as you can with <tt class="literal"><span class="pre">std::list&lt;int&gt;<
<tt class="literal"><span class="pre">node_const_iterator</span></tt> into the same list, we should be able to <tt class="literal"><span class="pre">node_const_iterator</span></tt> into the same list, we should be able to
compare them for equality.</p> compare them for equality.</p>
<p>This expected ability to use two different iterator types together <p>This expected ability to use two different iterator types together
is known as <strong>interoperability</strong>. Achieving interoperability in is known as <a class="reference" href="new-iter-concepts.html#interoperable-iterators-lib-interoperable-iterators"><strong>interoperability</strong></a>. Achieving interoperability in
our case is as simple as templatizing the <tt class="literal"><span class="pre">equal</span></tt> function and our case is as simple as templatizing the <tt class="literal"><span class="pre">equal</span></tt> function and
adding a templatized converting constructor <a class="footnote-reference" href="#broken" id="id14" name="id14"><sup>3</sup></a> <a class="footnote-reference" href="#random" id="id15" name="id15"><sup>4</sup></a>:</p> adding a templatized converting constructor <a class="footnote-reference" href="#broken" id="id14" name="id14"><sup>3</sup></a> <a class="footnote-reference" href="#random" id="id15" name="id15"><sup>4</sup></a>:</p>
<pre class="literal-block"> <pre class="literal-block">
@ -1056,7 +1081,7 @@ traversal iterator</a>, we'd have had to templatize its
iterators <a class="reference" href="../example/node_iterator2.cpp">here</a>.</p> iterators <a class="reference" href="../example/node_iterator2.cpp">here</a>.</p>
</div> </div>
<div class="section" id="telling-the-truth"> <div class="section" id="telling-the-truth">
<h2><a class="toc-backref" href="#id41" name="telling-the-truth">Telling the Truth</a></h2> <h2><a class="toc-backref" href="#id42" name="telling-the-truth">Telling the Truth</a></h2>
<p>Now <tt class="literal"><span class="pre">node_iterator</span></tt> and <tt class="literal"><span class="pre">node_const_iterator</span></tt> behave exactly as <p>Now <tt class="literal"><span class="pre">node_iterator</span></tt> and <tt class="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 you'd expect... almost. We can compare them and we can convert in
one direction: from <tt class="literal"><span class="pre">node_iterator</span></tt> to <tt class="literal"><span class="pre">node_const_iterator</span></tt>. one direction: from <tt class="literal"><span class="pre">node_iterator</span></tt> to <tt class="literal"><span class="pre">node_const_iterator</span></tt>.
@ -1094,7 +1119,7 @@ appropriate:</p>
</pre> </pre>
</div> </div>
<div class="section" id="wrap-up"> <div class="section" id="wrap-up">
<h2><a class="toc-backref" href="#id42" name="wrap-up">Wrap Up</a></h2> <h2><a class="toc-backref" href="#id43" name="wrap-up">Wrap Up</a></h2>
<p>This concludes our <tt class="literal"><span class="pre">iterator_facade</span></tt> tutorial, but before you <p>This concludes our <tt class="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="literal"><span class="pre">iterator_adaptor</span></tt></a>. stop reading we urge you to take a look at <a class="reference" href="iterator_adaptor.html"><tt class="literal"><span class="pre">iterator_adaptor</span></tt></a>.
There's another way to approach writing these iterators which might There's another way to approach writing these iterators which might

8
doc/iterator_facade_ref.rst
View File

@ -98,8 +98,12 @@ __ brackets_
.. _`iterator category`: .. _`iterator category`:
The ``iterator_category`` member of ``iterator_facade`` is The ``iterator_category`` member of ``iterator_facade`` is
``facade_iterator_category(CategoryOrTraversal, value_type,
reference)``, as specified by the following pseudo-code: .. parsed-literal::
*iterator-category*\ (CategoryOrTraversal, value_type, reference)
where *iterator-category* is defined as follows:
.. include:: facade_iterator_category.rst .. include:: facade_iterator_category.rst

5
doc/iterator_facade_tutorial.rst
View File

@ -388,7 +388,7 @@ just as you can with ``std::list<int>``\ 's ``iterator`` and
compare them for equality. compare them for equality.
This expected ability to use two different iterator types together This expected ability to use two different iterator types together
is known as **interoperability**. Achieving interoperability in is known as |interoperability|_. Achieving interoperability in
our case is as simple as templatizing the ``equal`` function and our case is as simple as templatizing the ``equal`` function and
adding a templatized converting constructor [#broken]_ [#random]_:: adding a templatized converting constructor [#broken]_ [#random]_::
@ -432,6 +432,9 @@ adding a templatized converting constructor [#broken]_ [#random]_::
typedef impl::node_iterator<node_base> node_iterator; typedef impl::node_iterator<node_base> node_iterator;
typedef impl::node_iterator<node_base const> node_const_iterator; typedef impl::node_iterator<node_base const> node_const_iterator;
.. |interoperability| replace:: **interoperability**
.. _interoperability: new-iter-concepts.html#interoperable-iterators-lib-interoperable-iterators
.. [#broken] If you're using an older compiler and it can't handle .. [#broken] If you're using an older compiler and it can't handle
this example, see the `example code`__ for workarounds. this example, see the `example code`__ for workarounds.

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

@ -476,9 +476,9 @@ type of <tt class="literal"><span class="pre">operator*</span></tt> type be a re
iterator.</p> iterator.</p>
<table border class="table"> <table border class="table">
<colgroup> <colgroup>
<col width="42%" /> <col width="22%" />
<col width="14%" /> <col width="19%" />
<col width="44%" /> <col width="59%" />
</colgroup> </colgroup>
<thead valign="bottom"> <thead valign="bottom">
<tr><th colspan="3">Lvalue Iterator Requirements</th> <tr><th colspan="3">Lvalue Iterator Requirements</th>
@ -659,12 +659,13 @@ Forward Traversal Iterator, the following expressions are valid and
respect the stated semantics.</p> respect the stated semantics.</p>
<table border class="table"> <table border class="table">
<colgroup> <colgroup>
<col width="35%" /> <col width="38%" />
<col width="44%" /> <col width="37%" />
<col width="21%" /> <col width="25%" />
</colgroup> </colgroup>
<thead valign="bottom"> <thead valign="bottom">
<tr><th colspan="3">Bidirectional Traversal Iterator Requirements (in addition to Forward Traversal Iterator)</th> <tr><th colspan="3">Bidirectional Traversal Iterator Requirements (in addition to Forward Traversal
Iterator)</th>
</tr> </tr>
<tr><th>Expression</th> <tr><th>Expression</th>
<th>Return Type</th> <th>Return Type</th>
@ -715,10 +716,10 @@ the stated semantics. In the table below, <tt class="literal"><span class="pre"
constant object of type <tt class="literal"><span class="pre">Distance</span></tt>.</p> constant object of type <tt class="literal"><span class="pre">Distance</span></tt>.</p>
<table border class="table"> <table border class="table">
<colgroup> <colgroup>
<col width="31%" /> <col width="28%" />
<col width="35%" /> <col width="30%" />
<col width="18%" /> <col width="23%" />
<col width="16%" /> <col width="20%" />
</colgroup> </colgroup>
<thead valign="bottom"> <thead valign="bottom">
<tr><th colspan="4">Random Access Traversal Iterator Requirements (in addition to Bidirectional Traversal Iterator)</th> <tr><th colspan="4">Random Access Traversal Iterator Requirements (in addition to Bidirectional Traversal Iterator)</th>
@ -831,9 +832,9 @@ of type <tt class="literal"><span class="pre">X</span></tt>, <tt class="literal"
constant object of type <tt class="literal"><span class="pre">Distance</span></tt>.</p> constant object of type <tt class="literal"><span class="pre">Distance</span></tt>.</p>
<table border class="table"> <table border class="table">
<colgroup> <colgroup>
<col width="30%" /> <col width="13%" />
<col width="34%" /> <col width="27%" />
<col width="36%" /> <col width="60%" />
</colgroup> </colgroup>
<thead valign="bottom"> <thead valign="bottom">
<tr><th>Expression</th> <tr><th>Expression</th>
@ -872,43 +873,38 @@ constant object of type <tt class="literal"><span class="pre">Distance</span></t
the following additional requirements must be met.</p> the following additional requirements must be met.</p>
<table border class="table"> <table border class="table">
<colgroup> <colgroup>
<col width="31%" /> <col width="12%" />
<col width="35%" /> <col width="25%" />
<col width="18%" /> <col width="23%" />
<col width="16%" /> <col width="41%" />
</colgroup> </colgroup>
<thead valign="bottom"> <thead valign="bottom">
<tr><th>Expression</th> <tr><th>Expression</th>
<th>Return Type</th> <th>Return Type</th>
<th>Operational Semantics</th> <th>Operational Semantics</th>
<th>Assertion/ <th>Assertion/ Precondition</th>
Precondition</th>
</tr> </tr>
</thead> </thead>
<tbody valign="top"> <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> <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>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">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 <td><tt class="literal"><span class="pre">&lt;</span></tt> is a total ordering relation</td>
ordering relation</td>
</tr> </tr>
<tr><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="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>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">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 <td><tt class="literal"><span class="pre">&lt;</span></tt> is a total ordering relation</td>
ordering relation</td>
</tr> </tr>
<tr><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="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>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">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 <td><tt class="literal"><span class="pre">&gt;</span></tt> is a total ordering relation</td>
ordering relation</td>
</tr> </tr>
<tr><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="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>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">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 <td><tt class="literal"><span class="pre">&gt;</span></tt> is a total ordering relation</td>
ordering relation</td>
</tr> </tr>
<tr><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="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>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
@ -933,20 +929,16 @@ ordering relation</td>
<tr><td><tt class="literal"><span class="pre">y</span> <span class="pre">-</span> <span class="pre">x</span></tt></td> <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</span></tt></td>
<td><tt class="literal"><span class="pre">distance(Y(x),y)</span></tt></td> <td><tt class="literal"><span class="pre">distance(Y(x),y)</span></tt></td>
<td>pre: there exists a <td>pre: there exists a value <tt class="literal"><span class="pre">n</span></tt> of
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">Distance</span></tt> such that <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>
<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> </tr>
<tr><td><tt class="literal"><span class="pre">x</span> <span class="pre">-</span> <span class="pre">y</span></tt></td> <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</span></tt></td>
<td><tt class="literal"><span class="pre">distance(y,Y(x))</span></tt></td> <td><tt class="literal"><span class="pre">distance(y,Y(x))</span></tt></td>
<td>pre: there exists a <td>pre: there exists a value <tt class="literal"><span class="pre">n</span></tt> of
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">Distance</span></tt> such that <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>
<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> </tr>
</tbody> </tbody>
</table> </table>
@ -969,27 +961,30 @@ struct random_access_traversal_tag : bidirectional_traversal_tag { };
</div> </div>
<div class="section" id="addition-to-lib-iterator-traits"> <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> <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> and <tt class="literal"><span class="pre">iterator_traversal</span></tt> class <p>The <tt class="literal"><span class="pre">is_readable_iterator</span></tt> class
templates satisfy the <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1519.htm">UnaryTypeTrait</a> requirements.</p> 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> <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 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> 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>
otherwise.</p> otherwise.</p>
<p><tt class="literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt> is defined to be:</p> <p><tt class="literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt> is</p>
<pre class="literal-block"> <pre class="literal-block">
traversal-category(X) = <em>category-to-traversal</em>(iterator_traits&lt;X&gt;::iterator_category)
cat = iterator_traits&lt;X&gt;::iterator_category; </pre>
if (cat is convertible to incrementable_traversal_tag) <p>where <em>category-to-traversal</em> is defined as follows</p>
return cat; <a class="target" id="category-to-traversal" name="category-to-traversal"></a><pre class="literal-block">
else if (cat is convertible to random_access_iterator_tag) <em>category-to-traversal</em>(C) =
if (C is convertible to incrementable_traversal_tag)
return C;
else if (C is convertible to random_access_iterator_tag)
return random_access_traversal_tag; return random_access_traversal_tag;
else if (cat is convertible to bidirectional_iterator_tag) else if (C is convertible to bidirectional_iterator_tag)
return bidirectional_traversal_tag; return bidirectional_traversal_tag;
else if (cat is convertible to forward_iterator_tag) else if (C is convertible to forward_iterator_tag)
return forward_traversal_tag; return forward_traversal_tag;
else if (cat is convertible to input_iterator_tag) else if (C is convertible to input_iterator_tag)
return single_pass_traversal_tag; return single_pass_traversal_tag;
else if (cat is convertible to output_iterator_tag) else if (C is convertible to output_iterator_tag)
return incrementable_traversal_tag; return incrementable_traversal_tag;
else else
<em>the program is ill-formed</em> <em>the program is ill-formed</em>

175
doc/new-iter-concepts.rst
View File

@ -430,11 +430,11 @@ The *Lvalue Iterator* concept adds the requirement that the return
type of ``operator*`` type be a reference to the value type of the type of ``operator*`` type be a reference to the value type of the
iterator. iterator.
+---------------------------------------------------------------------------------+ +-------------------------------------------------------------+
| Lvalue Iterator Requirements | | Lvalue Iterator Requirements |
+---------------------------------+-----------+-----------------------------------+ +-------------+-----------+-----------------------------------+
|Expression |Return Type|Note/Assertion | |Expression |Return Type|Note/Assertion |
+=================================+===========+===================================+ +=============+===========+===================================+
|``*a`` | ``T&`` |``T`` is *cv* | |``*a`` | ``T&`` |``T`` is *cv* |
| | |``iterator_traits<X>::value_type`` | | | |``iterator_traits<X>::value_type`` |
| | |where *cv* is an optional | | | |where *cv* is an optional |
@ -443,7 +443,7 @@ iterator.
| | |dereferenceable. If ``a | | | |dereferenceable. If ``a |
| | |== b`` then ``*a`` is | | | |== b`` then ``*a`` is |
| | |equivalent to ``*b``. | | | |equivalent to ``*b``. |
+---------------------------------+-----------+-----------------------------------+ +-------------+-----------+-----------------------------------+
@ -561,12 +561,13 @@ Iterator* concept if, in addition to ``X`` meeting the requirements of
Forward Traversal Iterator, the following expressions are valid and Forward Traversal Iterator, the following expressions are valid and
respect the stated semantics. respect the stated semantics.
+--------------------------------------------------------------------------------------------------------+ +--------------------------------------------------------------------------------------+
|Bidirectional Traversal Iterator Requirements (in addition to Forward Traversal Iterator) | |Bidirectional Traversal Iterator Requirements (in addition to Forward Traversal |
+------------------------------------+---------------------------------------------+---------------------+ |Iterator) |
+--------------------------------+-------------------------------+---------------------+
|Expression |Return Type |Assertion/Semantics /| |Expression |Return Type |Assertion/Semantics /|
| | |Pre-/Post-condition | | | |Pre-/Post-condition |
+====================================+=============================================+=====================+ +================================+===============================+=====================+
|``--r`` |``X&`` |pre: there exists | |``--r`` |``X&`` |pre: there exists |
| | |``s`` such that ``r | | | |``s`` such that ``r |
| | |== ++s``. post: | | | |== ++s``. post: |
@ -576,7 +577,7 @@ respect the stated semantics.
| | |``--r == --s`` | | | |``--r == --s`` |
| | |implies ``r == | | | |implies ``r == |
| | |s``. ``&r == &--r``. | | | |s``. ``&r == &--r``. |
+------------------------------------+---------------------------------------------+---------------------+ +--------------------------------+-------------------------------+---------------------+
|``r--`` |convertible to ``const X&`` |:: | |``r--`` |convertible to ``const X&`` |:: |
| | | | | | | |
| | | { | | | | { |
@ -584,11 +585,11 @@ respect the stated semantics.
| | | --r; | | | | --r; |
| | | return tmp; | | | | return tmp; |
| | | } | | | | } |
+------------------------------------+---------------------------------------------+---------------------+ +--------------------------------+-------------------------------+---------------------+
|``iterator_traversal<X>::type`` |Convertible to | | |``iterator_traversal<X>::type`` |Convertible to | |
| |``bidirectional_traversal_tag`` | | | |``bidirectional_traversal_tag``| |
| | | | | | | |
+------------------------------------+---------------------------------------------+---------------------+ +--------------------------------+-------------------------------+---------------------+
.. TR1: bidirectional_traversal_iterator_tag changed to .. TR1: bidirectional_traversal_iterator_tag changed to
bidirectional_traversal_tag for consistency bidirectional_traversal_tag for consistency
@ -602,12 +603,12 @@ the stated semantics. In the table below, ``Distance`` is
``iterator_traits<X>::difference_type`` and ``n`` represents a ``iterator_traits<X>::difference_type`` and ``n`` represents a
constant object of type ``Distance``. constant object of type ``Distance``.
+----------------------------------------------------------------------------------------------------------------------------------------------+ +------------------------------------------------------------------------------------------------------------------+
|Random Access Traversal Iterator Requirements (in addition to Bidirectional Traversal Iterator) | |Random Access Traversal Iterator Requirements (in addition to Bidirectional Traversal Iterator) |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +-------------------------------+---------------------------------+-------------------------+----------------------+
|Expression |Return Type |Operational Semantics |Assertion/ | |Expression |Return Type |Operational Semantics |Assertion/ |
| | | |Precondition | | | | |Precondition |
+===========================================+=================================================+=========================+======================+ +===============================+=================================+=========================+======================+
|``r += n`` |``X&`` |:: | | |``r += n`` |``X&`` |:: | |
| | | | | | | | | |
| | | { | | | | | { | |
@ -620,42 +621,42 @@ constant object of type ``Distance``.
| | | --r; | | | | | --r; | |
| | | return r; | | | | | return r; | |
| | | } | | | | | } | |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +-------------------------------+---------------------------------+-------------------------+----------------------+
|``a + n``, ``n + a`` |``X`` |``{ X tmp = a; return tmp| | |``a + n``, ``n + a`` |``X`` |``{ X tmp = a; return tmp| |
| | |+= n; }`` | | | | |+= n; }`` | |
| | | | | | | | | |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +-------------------------------+---------------------------------+-------------------------+----------------------+
|``r -= n`` |``X&`` |``return r += -n`` | | |``r -= n`` |``X&`` |``return r += -n`` | |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +-------------------------------+---------------------------------+-------------------------+----------------------+
|``a - n`` |``X`` |``{ X tmp = a; return tmp| | |``a - n`` |``X`` |``{ X tmp = a; return tmp| |
| | |-= n; }`` | | | | |-= n; }`` | |
| | | | | | | | | |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +-------------------------------+---------------------------------+-------------------------+----------------------+
|``b - a`` |``Distance`` |``a < b ? distance(a,b) |pre: there exists a | |``b - a`` |``Distance`` |``a < b ? distance(a,b) |pre: there exists a |
| | |: -distance(b,a)`` |value ``n`` of | | | |: -distance(b,a)`` |value ``n`` of |
| | | |``Distance`` such that| | | | |``Distance`` such that|
| | | |``a + n == b``. ``b | | | | |``a + n == b``. ``b |
| | | |== a + (b - a)``. | | | | |== a + (b - a)``. |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +-------------------------------+---------------------------------+-------------------------+----------------------+
|``a[n]`` |convertible to T |``*(a + n)`` |pre: a is a `readable | |``a[n]`` |convertible to T |``*(a + n)`` |pre: a is a `readable |
| | | |iterator`_ | | | | |iterator`_ |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +-------------------------------+---------------------------------+-------------------------+----------------------+
|``a[n] = v`` |convertible to T |``*(a + n) = v`` |pre: a is a `writable | |``a[n] = v`` |convertible to T |``*(a + n) = v`` |pre: a is a `writable |
| | | |iterator`_ | | | | |iterator`_ |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +-------------------------------+---------------------------------+-------------------------+----------------------+
|``a < b`` |convertible to ``bool`` |``b - a > 0`` |``<`` is a total | |``a < b`` |convertible to ``bool`` |``b - a > 0`` |``<`` is a total |
| | | |ordering relation | | | | |ordering relation |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +-------------------------------+---------------------------------+-------------------------+----------------------+
|``a > b`` |convertible to ``bool`` |``b < a`` |``>`` is a total | |``a > b`` |convertible to ``bool`` |``b < a`` |``>`` is a total |
| | | |ordering relation | | | | |ordering relation |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +-------------------------------+---------------------------------+-------------------------+----------------------+
|``a >= b`` |convertible to ``bool`` |``!(a < b)`` | | |``a >= b`` |convertible to ``bool`` |``!(a < b)`` | |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +-------------------------------+---------------------------------+-------------------------+----------------------+
|``a <= b`` |convertible to ``bool`` |``!(a > b)`` | | |``a <= b`` |convertible to ``bool`` |``!(a > b)`` | |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +-------------------------------+---------------------------------+-------------------------+----------------------+
|``iterator_traversal<X>::type`` |Convertible to | | | |``iterator_traversal<X>::type``|Convertible to | | |
| |``random_access_traversal_tag`` | | | | |``random_access_traversal_tag`` | | |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +-------------------------------+---------------------------------+-------------------------+----------------------+
.. TR1: random_access_traversal_iterator_tag changed to .. TR1: random_access_traversal_iterator_tag changed to
random_access_traversal_tag for consistency random_access_traversal_tag for consistency
@ -672,61 +673,52 @@ of type ``X``, ``y`` is an object of type ``Y``, ``Distance`` is
``iterator_traits<Y>::difference_type``, and ``n`` represents a ``iterator_traits<Y>::difference_type``, and ``n`` represents a
constant object of type ``Distance``. constant object of type ``Distance``.
+-------------------------------------------+-------------------------------------------------+---------------------------------------------------+ +-----------+-----------------------+---------------------------------------------------+
|Expression |Return Type |Assertion/Precondition/Postcondition | |Expression |Return Type |Assertion/Precondition/Postcondition |
+===========================================+=================================================+===================================================+ +===========+=======================+===================================================+
|``y = x`` |``Y`` |post: ``y == x`` | |``y = x`` |``Y`` |post: ``y == x`` |
+-------------------------------------------+-------------------------------------------------+---------------------------------------------------+ +-----------+-----------------------+---------------------------------------------------+
|``Y(x)`` |``Y`` |post: ``Y(x) == x`` | |``Y(x)`` |``Y`` |post: ``Y(x) == x`` |
+-------------------------------------------+-------------------------------------------------+---------------------------------------------------+ +-----------+-----------------------+---------------------------------------------------+
|``x == y`` |convertible to ``bool`` |``==`` is an equivalence relation over its domain. | |``x == y`` |convertible to ``bool``|``==`` is an equivalence relation over its domain. |
+-------------------------------------------+-------------------------------------------------+---------------------------------------------------+ +-----------+-----------------------+---------------------------------------------------+
|``y == x`` |convertible to ``bool`` |``==`` is an equivalence relation over its domain. | |``y == x`` |convertible to ``bool``|``==`` is an equivalence relation over its domain. |
+-------------------------------------------+-------------------------------------------------+---------------------------------------------------+ +-----------+-----------------------+---------------------------------------------------+
|``x != y`` |convertible to ``bool`` |``bool(a==b) != bool(a!=b)`` over its domain. | |``x != y`` |convertible to ``bool``|``bool(a==b) != bool(a!=b)`` over its domain. |
+-------------------------------------------+-------------------------------------------------+---------------------------------------------------+ +-----------+-----------------------+---------------------------------------------------+
|``y != x`` |convertible to ``bool`` |``bool(a==b) != bool(a!=b)`` over its domain. | |``y != x`` |convertible to ``bool``|``bool(a==b) != bool(a!=b)`` over its domain. |
+-------------------------------------------+-------------------------------------------------+---------------------------------------------------+ +-----------+-----------------------+---------------------------------------------------+
If ``X`` and ``Y`` both model Random Access Traversal Iterator then If ``X`` and ``Y`` both model Random Access Traversal Iterator then
the following additional requirements must be met. the following additional requirements must be met.
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +-----------+-----------------------+---------------------+--------------------------------------+
|Expression |Return Type |Operational Semantics |Assertion/ | |Expression |Return Type |Operational Semantics|Assertion/ Precondition |
| | | |Precondition | +===========+=======================+=====================+======================================+
+===========================================+=================================================+=========================+======================+ |``x < y`` |convertible to ``bool``|``y - x > 0`` |``<`` is a total ordering relation |
|``x < y`` |convertible to ``bool`` |``y - x > 0`` |``<`` is a total | +-----------+-----------------------+---------------------+--------------------------------------+
| | | |ordering relation | |``y < x`` |convertible to ``bool``|``x - y > 0`` |``<`` is a total ordering relation |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +-----------+-----------------------+---------------------+--------------------------------------+
|``y < x`` |convertible to ``bool`` |``x - y > 0`` |``<`` is a total | |``x > y`` |convertible to ``bool``|``y < x`` |``>`` is a total ordering relation |
| | | |ordering relation | +-----------+-----------------------+---------------------+--------------------------------------+
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ |``y > x`` |convertible to ``bool``|``x < y`` |``>`` is a total ordering relation |
|``x > y`` |convertible to ``bool`` |``y < x`` |``>`` is a total | +-----------+-----------------------+---------------------+--------------------------------------+
| | | |ordering relation | |``x >= y`` |convertible to ``bool``|``!(x < y)`` | |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +-----------+-----------------------+---------------------+--------------------------------------+
|``y > x`` |convertible to ``bool`` |``x < y`` |``>`` is a total | |``y >= x`` |convertible to ``bool``|``!(y < x)`` | |
| | | |ordering relation | +-----------+-----------------------+---------------------+--------------------------------------+
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ |``x <= y`` |convertible to ``bool``|``!(x > y)`` | |
|``x >= y`` |convertible to ``bool`` |``!(x < y)`` | | +-----------+-----------------------+---------------------+--------------------------------------+
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ |``y <= x`` |convertible to ``bool``|``!(y > x)`` | |
|``y >= x`` |convertible to ``bool`` |``!(y < x)`` | | +-----------+-----------------------+---------------------+--------------------------------------+
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ |``y - x`` |``Distance`` |``distance(Y(x),y)`` |pre: there exists a value ``n`` of |
|``x <= y`` |convertible to ``bool`` |``!(x > y)`` | | | | | |``Distance`` such that ``x + n == y``.|
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ | | | |``y == x + (y - x)``. |
|``y <= x`` |convertible to ``bool`` |``!(y > x)`` | | +-----------+-----------------------+---------------------+--------------------------------------+
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ |``x - y`` |``Distance`` |``distance(y,Y(x))`` |pre: there exists a value ``n`` of |
|``y - x`` |``Distance`` |``distance(Y(x),y)`` |pre: there exists a | | | | |``Distance`` such that ``y + n == x``.|
| | | |value ``n`` of | | | | |``x == y + (x - y)``. |
| | | |``Distance`` such that| +-----------+-----------------------+---------------------+--------------------------------------+
| | | |``x + n == y``. ``y |
| | | |== x + (y - x)``. |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
|``x - y`` |``Distance`` |``distance(y,Y(x))`` |pre: there exists a |
| | | |value ``n`` of |
| | | |``Distance`` such that|
| | | |``y + n == x``. ``x |
| | | |== y + (x - y)``. |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
@ -749,31 +741,38 @@ Addition to [lib.iterator.synopsis]
Addition to [lib.iterator.traits] Addition to [lib.iterator.traits]
================================= =================================
The ``is_readable_iterator`` and ``iterator_traversal`` class The ``is_readable_iterator`` class
templates satisfy the UnaryTypeTrait_ requirements. template satisfies the UnaryTypeTrait_ requirements.
Given an iterator type ``X``, ``is_readable_iterator<X>::value`` Given an iterator type ``X``, ``is_readable_iterator<X>::value``
yields ``true`` if, for an object ``a`` of type ``X``, ``*a`` is yields ``true`` if, for an object ``a`` of type ``X``, ``*a`` is
convertible to ``iterator_traits<X>::value_type``, and ``false`` convertible to ``iterator_traits<X>::value_type``, and ``false``
otherwise. otherwise.
``iterator_traversal<X>::type`` is defined to be: ``iterator_traversal<X>::type`` is
.. parsed-literal:: .. parsed-literal::
traversal-category(X) = *category-to-traversal*\ (iterator_traits<X>::iterator_category)
cat = iterator_traits<X>::iterator_category;
if (cat is convertible to incrementable_traversal_tag) where *category-to-traversal* is defined as follows
return cat;
else if (cat is convertible to random_access_iterator_tag) .. _`category-to-traversal`:
.. parsed-literal::
*category-to-traversal*\ (C) =
if (C is convertible to incrementable_traversal_tag)
return C;
else if (C is convertible to random_access_iterator_tag)
return random_access_traversal_tag; return random_access_traversal_tag;
else if (cat is convertible to bidirectional_iterator_tag) else if (C is convertible to bidirectional_iterator_tag)
return bidirectional_traversal_tag; return bidirectional_traversal_tag;
else if (cat is convertible to forward_iterator_tag) else if (C is convertible to forward_iterator_tag)
return forward_traversal_tag; return forward_traversal_tag;
else if (cat is convertible to input_iterator_tag) else if (C is convertible to input_iterator_tag)
return single_pass_traversal_tag; return single_pass_traversal_tag;
else if (cat is convertible to output_iterator_tag) else if (C is convertible to output_iterator_tag)
return incrementable_traversal_tag; return incrementable_traversal_tag;
else else
*the program is ill-formed* *the program is ill-formed*