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

added Interoperable Iterators

Browse Source 
[SVN r21698]
This commit is contained in:
Jeremy Siek
2004-01-13 19:21:18 +00:00
parent 0f8aa07e5c
commit 80f6a13e79
3 changed files with 271 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
doc/iter-issue-list.rst
View File

@ -1112,11 +1112,26 @@ The paper says::
/* see details */ >
That comment covers the Access, Traversal, Reference, and Difference
arguments. The only specification for any of these in the details is::
arguments. The only specification for any of these in the details is:
The access category of the filter_iterator will be the same as
the access category of Iterator.
Needs more.
:Proposed resolution: **Needs work** (Jeremy)
:Proposed resolution:
Add to the synopsis::
typedef iterator_traits<Iterator>::value_type value_type;
typedef iterator_traits<Iterator>::reference reference;
typedef iterator_traits<Iterator>::pointer pointer;
typedef iterator_traits<Iterator>::difference_type difference_type;
typedef /* see below */ iterator_category;
and add just after the synopsis:
If ``Iterator`` models Readable Lvalue Iterator and Forward Traversal
Iterator then ``iterator_category`` is convertible to
``std::forward_iterator_tag``. Otherwise ``iterator_category`` is
convertible to ``std::input_iterator_tag``.

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

@ -81,15 +81,16 @@ of iterators that are used in practice.</td>
<li><a class="reference" href="#forward-traversal-iterators-lib-forward-traversal-iterators" id="id18" name="id18">Forward Traversal Iterators [lib.forward.traversal.iterators]</a></li>
<li><a class="reference" href="#bidirectional-traversal-iterators-lib-bidirectional-traversal-iterators" id="id19" name="id19">Bidirectional Traversal Iterators [lib.bidirectional.traversal.iterators]</a></li>
<li><a class="reference" href="#random-access-traversal-iterators-lib-random-access-traversal-iterators" id="id20" name="id20">Random Access Traversal Iterators [lib.random.access.traversal.iterators]</a></li>
<li><a class="reference" href="#interoperable-iterators-lib-interoperable-iterators" id="id21" name="id21">Interoperable Iterators [lib.interoperable.iterators]</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference" href="#addition-to-lib-iterator-synopsis" id="id21" name="id21">Addition to [lib.iterator.synopsis]</a></li>
<li><a class="reference" href="#addition-to-lib-iterator-traits" id="id22" name="id22">Addition to [lib.iterator.traits]</a></li>
<li><a class="reference" href="#addition-to-lib-iterator-synopsis" id="id22" name="id22">Addition to [lib.iterator.synopsis]</a></li>
<li><a class="reference" href="#addition-to-lib-iterator-traits" id="id23" name="id23">Addition to [lib.iterator.traits]</a></li>
</ul>
</li>
<li><a class="reference" href="#footnotes" id="id23" name="id23">Footnotes</a></li>
<li><a class="reference" href="#footnotes" id="id24" name="id24">Footnotes</a></li>
</ul>
</div>
<div class="section" id="motivation">
@ -311,6 +312,12 @@ position comparison such as <tt class="literal"><span class="pre">operator==</sp
reason for the fine grain slicing of the concepts into the
Incrementable and Single Pass is to provide concepts that are exact
matches with the original input and output iterator requirements.</p>
<p>This proposal also includes a concept for specifying when an iterator
is interoperable with another iterator, in the sense that <tt class="literal"><span class="pre">int*</span></tt> is
interoperable with <tt class="literal"><span class="pre">int</span> <span class="pre">const*</span></tt>.</p>
<ul class="simple">
<li>Interoperable Iterators</li>
</ul>
<p>The relationship between the new iterator concepts and the old are
given in the following diagram.</p>
<p><img alt="oldeqnew.png" src="oldeqnew.png" /></p>
@ -816,10 +823,144 @@ ordering relation</td>
<!-- TR1: random_access_traversal_iterator_tag changed to
random_access_traversal_tag for consistency -->
</div>
<div class="section" id="interoperable-iterators-lib-interoperable-iterators">
<h4><a class="toc-backref" href="#id21" name="interoperable-iterators-lib-interoperable-iterators">Interoperable Iterators [lib.interoperable.iterators]</a></h4>
<p>A class or built-in type <tt class="literal"><span class="pre">X</span></tt> that models Single Pass Iterator is
<em>interoperable with</em> a class or built-in type <tt class="literal"><span class="pre">Y</span></tt> that also models
Single Pass Iterator if both <tt class="literal"><span class="pre">X</span></tt> and <tt class="literal"><span class="pre">Y</span></tt> have the same difference
type and traversal tag and if the following expressions are valid and
respect the stated semantics. In the tables below, <tt class="literal"><span class="pre">x</span></tt> is an object
of type <tt class="literal"><span class="pre">X</span></tt>, <tt class="literal"><span class="pre">y</span></tt> is an object of type <tt class="literal"><span class="pre">Y</span></tt>, <tt class="literal"><span class="pre">Distance</span></tt> is
<tt class="literal"><span class="pre">iterator_traits&lt;X&gt;::difference_type</span></tt>, and <tt class="literal"><span class="pre">n</span></tt> represents a
constant object of type <tt class="literal"><span class="pre">Distance</span></tt>.</p>
<p>If the traversal tag for <tt class="literal"><span class="pre">X</span></tt> and <tt class="literal"><span class="pre">Y</span></tt> is convertible to
<tt class="literal"><span class="pre">single_pass_traversal_tag</span></tt> then the following requirements must be
met.</p>
<table border class="table">
<colgroup>
<col width="30%" />
<col width="34%" />
<col width="36%" />
</colgroup>
<thead valign="bottom">
<tr><th>Expression</th>
<th>Return Type</th>
<th>Assertion/Precondition/Postcondition</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="literal"><span class="pre">y</span> <span class="pre">=</span> <span class="pre">x</span></tt></td>
<td><tt class="literal"><span class="pre">Y</span></tt></td>
<td>post: <tt class="literal"><span class="pre">y</span> <span class="pre">==</span> <span class="pre">x</span></tt></td>
</tr>
<tr><td><tt class="literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">y</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">==</span></tt> is an equivalence relation over its domain.</td>
</tr>
<tr><td><tt class="literal"><span class="pre">y</span> <span class="pre">==</span> <span class="pre">x</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">==</span></tt> is an equivalence relation over its domain.</td>
</tr>
<tr><td><tt class="literal"><span class="pre">x</span> <span class="pre">!=</span> <span class="pre">y</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">bool(a==b)</span> <span class="pre">!=</span> <span class="pre">bool(a!=b)</span></tt> over its domain.</td>
</tr>
<tr><td><tt class="literal"><span class="pre">y</span> <span class="pre">!=</span> <span class="pre">x</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">bool(a==b)</span> <span class="pre">!=</span> <span class="pre">bool(a!=b)</span></tt> over its domain.</td>
</tr>
</tbody>
</table>
<p>If the traversal tag for <tt class="literal"><span class="pre">X</span></tt> and <tt class="literal"><span class="pre">Y</span></tt> is convertible to
<tt class="literal"><span class="pre">random_access_traversal_tag</span></tt> then the following requirements must
be met.</p>
<table border class="table">
<colgroup>
<col width="31%" />
<col width="35%" />
<col width="18%" />
<col width="16%" />
</colgroup>
<thead valign="bottom">
<tr><th>Expression</th>
<th>Return Type</th>
<th>Operational Semantics</th>
<th>Assertion/
Precondition</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="literal"><span class="pre">x</span> <span class="pre">&lt;</span> <span class="pre">y</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">y</span> <span class="pre">-</span> <span class="pre">x</span> <span class="pre">&gt;</span> <span class="pre">0</span></tt></td>
<td><tt class="literal"><span class="pre">&lt;</span></tt> is a total
ordering relation</td>
</tr>
<tr><td><tt class="literal"><span class="pre">y</span> <span class="pre">&lt;</span> <span class="pre">x</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">x</span> <span class="pre">-</span> <span class="pre">y</span> <span class="pre">&gt;</span> <span class="pre">0</span></tt></td>
<td><tt class="literal"><span class="pre">&lt;</span></tt> is a total
ordering relation</td>
</tr>
<tr><td><tt class="literal"><span class="pre">x</span> <span class="pre">&gt;</span> <span class="pre">y</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">y</span> <span class="pre">&lt;</span> <span class="pre">x</span></tt></td>
<td><tt class="literal"><span class="pre">&gt;</span></tt> is a total
ordering relation</td>
</tr>
<tr><td><tt class="literal"><span class="pre">y</span> <span class="pre">&gt;</span> <span class="pre">x</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">x</span> <span class="pre">&lt;</span> <span class="pre">y</span></tt></td>
<td><tt class="literal"><span class="pre">&gt;</span></tt> is a total
ordering relation</td>
</tr>
<tr><td><tt class="literal"><span class="pre">x</span> <span class="pre">&gt;=</span> <span class="pre">y</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">!(x</span> <span class="pre">&lt;</span> <span class="pre">y)</span></tt></td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="literal"><span class="pre">y</span> <span class="pre">&gt;=</span> <span class="pre">x</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">!(y</span> <span class="pre">&lt;</span> <span class="pre">x)</span></tt></td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="literal"><span class="pre">x</span> <span class="pre">&lt;=</span> <span class="pre">y</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">!(x</span> <span class="pre">&gt;</span> <span class="pre">y)</span></tt></td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="literal"><span class="pre">y</span> <span class="pre">&lt;=</span> <span class="pre">x</span></tt></td>
<td>convertible to <tt class="literal"><span class="pre">bool</span></tt></td>
<td><tt class="literal"><span class="pre">!(y</span> <span class="pre">&gt;</span> <span class="pre">x)</span></tt></td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="literal"><span class="pre">y</span> <span class="pre">-</span> <span class="pre">x</span></tt></td>
<td><tt class="literal"><span class="pre">Distance</span></tt></td>
<td><tt class="literal"><span class="pre">x</span> <span class="pre">&lt;</span> <span class="pre">y</span> <span class="pre">?</span>&nbsp; <span class="pre">distance(x,y)</span>
<span class="pre">:</span> <span class="pre">-distance(y,x)</span></tt></td>
<td>pre: there exists a
value <tt class="literal"><span class="pre">n</span></tt> of
<tt class="literal"><span class="pre">Distance</span></tt> such that
<tt class="literal"><span class="pre">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><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">y</span> <span class="pre">&lt;</span> <span class="pre">x</span> <span class="pre">?</span>&nbsp; <span class="pre">distance(y,x)</span>
<span class="pre">:</span> <span class="pre">-distance(x,y)</span></tt></td>
<td>pre: there exists a
value <tt class="literal"><span class="pre">n</span></tt> of
<tt class="literal"><span class="pre">Distance</span></tt> such that
<tt class="literal"><span class="pre">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>
</tbody>
</table>
</div>
</div>
</div>
<div class="section" id="addition-to-lib-iterator-synopsis">
<h2><a class="toc-backref" href="#id21" name="addition-to-lib-iterator-synopsis">Addition to [lib.iterator.synopsis]</a></h2>
<h2><a class="toc-backref" href="#id22" name="addition-to-lib-iterator-synopsis">Addition to [lib.iterator.synopsis]</a></h2>
<pre class="literal-block">
// lib.iterator.traits, traits and tags
template &lt;class Iterator&gt; struct is_readable_iterator;
@ -833,7 +974,7 @@ struct random_access_traversal_tag : bidirectional_traversal_tag { };
</pre>
</div>
<div class="section" id="addition-to-lib-iterator-traits">
<h2><a class="toc-backref" href="#id22" 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
templates satisfy 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>
@ -862,7 +1003,7 @@ traversal-category(X) =
</div>
</div>
<div class="section" id="footnotes">
<h1><a class="toc-backref" href="#id23" name="footnotes">Footnotes</a></h1>
<h1><a class="toc-backref" href="#id24" name="footnotes">Footnotes</a></h1>
<p>The UnaryTypeTrait concept is defined in <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1519.htm">n1519</a>; the LWG added the
requirement that specializations are derived from their nested
<tt class="literal"><span class="pre">::type</span></tt>.</p>
@ -878,7 +1019,7 @@ LocalWords: TraversalTag typename lvalues DWA Hmm JGS mis enum -->
<hr class="footer" />
<div class="footer">
<a class="reference" href="new-iter-concepts.rst">View document source</a>.
Generated on: 2004-01-13 14:26 UTC.
Generated on: 2004-01-13 19:20 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>

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

@ -291,6 +291,13 @@ reason for the fine grain slicing of the concepts into the
Incrementable and Single Pass is to provide concepts that are exact
matches with the original input and output iterator requirements.
This proposal also includes a concept for specifying when an iterator
is interoperable with another iterator, in the sense that ``int*`` is
interoperable with ``int const*``.
- Interoperable Iterators
The relationship between the new iterator concepts and the old are
given in the following diagram.
@ -657,6 +664,79 @@ constant object of type ``Distance``.
random_access_traversal_tag for consistency
Interoperable Iterators [lib.interoperable.iterators]
-----------------------------------------------------
A class or built-in type ``X`` that models Single Pass Iterator is
*interoperable with* a class or built-in type ``Y`` that also models
Single Pass Iterator if both ``X`` and ``Y`` have the same difference
type and traversal tag and if the following expressions are valid and
respect the stated semantics. In the tables below, ``x`` is an object
of type ``X``, ``y`` is an object of type ``Y``, ``Distance`` is
``iterator_traits<X>::difference_type``, and ``n`` represents a
constant object of type ``Distance``.
If the traversal tag for ``X`` and ``Y`` is convertible to
``single_pass_traversal_tag`` then the following requirements must be
met.
+-------------------------------------------+-------------------------------------------------+---------------------------------------------------+
|Expression |Return Type |Assertion/Precondition/Postcondition |
+===========================================+=================================================+===================================================+
|``y = x`` |``Y`` |post: ``y == x`` |
+-------------------------------------------+-------------------------------------------------+---------------------------------------------------+
|``x == y`` |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. |
+-------------------------------------------+-------------------------------------------------+---------------------------------------------------+
|``y != x`` |convertible to ``bool`` |``bool(a==b) != bool(a!=b)`` over its domain. |
+-------------------------------------------+-------------------------------------------------+---------------------------------------------------+
If the traversal tag for ``X`` and ``Y`` is convertible to
``random_access_traversal_tag`` then the following requirements must
be met.
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
|Expression |Return Type |Operational Semantics |Assertion/ |
| | | |Precondition |
+===========================================+=================================================+=========================+======================+
|``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 |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
|``x > y`` |convertible to ``bool`` |``y < x`` |``>`` is a total |
| | | |ordering relation |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
|``y > x`` |convertible to ``bool`` |``x < y`` |``>`` is a total |
| | | |ordering relation |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
|``x >= y`` |convertible to ``bool`` |``!(x < y)`` | |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
|``y >= x`` |convertible to ``bool`` |``!(y < x)`` | |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
|``x <= y`` |convertible to ``bool`` |``!(x > y)`` | |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
|``y <= x`` |convertible to ``bool`` |``!(y > x)`` | |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
|``y - x`` |``Distance`` |``x < y ? distance(x,y) |pre: there exists a |
| | |: -distance(y,x)`` |value ``n`` of |
| | | |``Distance`` such that|
| | | |``x + n == y``. ``y |
| | | |== x + (y - x)``. |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
|``x - y`` |``Distance`` |``y < x ? distance(y,x) |pre: there exists a |
| | |: -distance(x,y)`` |value ``n`` of |
| | | |``Distance`` such that|
| | | |``y + n == x``. ``x |
| | | |== y + (x - y)``. |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
Addition to [lib.iterator.synopsis]
===================================