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

Edits for committee meeting, moving algorithm changes to suggestions for WP.

Browse Source 
[SVN r20568]
This commit is contained in:
Dave Abrahams
2003-10-30 21:11:10 +00:00
parent 15abd4c56e
commit e888f18b5a
2 changed files with 223 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@ -7,7 +7,7 @@
<title>New Iterator Concepts</title> <title>New Iterator Concepts</title>
<meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" /> <meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" />
<meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, University of Hanover Institute for Transport Railway Operation and Construction" /> <meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, University of Hanover Institute for Transport Railway Operation and Construction" />
<meta name="date" content="2003-09-22" /> <meta name="date" content="2003-10-16" />
<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved" /> <meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved" />
<style type="text/css"><!-- <style type="text/css"><!--
@ -214,10 +214,12 @@ ul.auto-toc {
<tr><th class="docinfo-name">Contact:</th> <tr><th class="docinfo-name">Contact:</th>
<td><a class="first reference" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="last reference" href="mailto:witt&#64;acm.org">witt&#64;acm.org</a></td></tr> <td><a class="first reference" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="last reference" href="mailto:witt&#64;acm.org">witt&#64;acm.org</a></td></tr>
<tr><th class="docinfo-name">Organization:</th> <tr><th class="docinfo-name">Organization:</th>
<td><a class="first reference" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference" href="http://www.osl.iu.edu">Open Systems Lab</a>, University of Hanover <a class="last reference" href="http://www.ive.uni-hannover.de">Institute for Transport Railway Operation and Construction</a></td></tr> <td><a class="first reference" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference" href="http://www.osl.iu.edu">Open
Systems Lab</a>, University of Hanover <a class="last reference" href="http://www.ive.uni-hannover.de">Institute for
Transport Railway Operation and Construction</a></td></tr>
<tr><th class="docinfo-name">Date:</th> <tr><th class="docinfo-name">Date:</th>
<td>2003-09-22</td></tr> <td>2003-10-16</td></tr>
<tr class="field"><th class="docinfo-name">Number:</th><td class="field-body">N1531=03-0114</td> <tr class="field"><th class="docinfo-name">Number:</th><td class="field-body">N1530=03-0133</td>
</tr> </tr>
<tr><th class="docinfo-name">Copyright:</th> <tr><th class="docinfo-name">Copyright:</th>
<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved</td></tr> <td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved</td></tr>
@ -232,7 +234,7 @@ access and positioning independently. This allows the
concepts to more closely match the requirements concepts to more closely match the requirements
of algorithms and provides better categorizations of algorithms and provides better categorizations
of iterators that are used in practice. This proposal of iterators that are used in practice. This proposal
is a revision of paper <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2001/n1297.html">n1297</a> and <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1477.html">n1477</a>.</td> is a revision of paper <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2001/n1297.html">n1297</a>, <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1477.html">n1477</a>, and <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1531.html">n1531</a>.</td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
@ -240,29 +242,38 @@ is a revision of paper <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc
<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="#motivation" id="id1" name="id1">Motivation</a></li> <li><a class="reference" href="#motivation" id="id1" name="id1">Motivation</a></li>
<li><a class="reference" href="#impact-on-the-standard" id="id2" name="id2">Impact on the Standard</a></li> <li><a class="reference" href="#impact-on-the-standard" id="id2" name="id2">Impact on the Standard</a><ul>
<li><a class="reference" href="#design" id="id3" name="id3">Design</a></li> <li><a class="reference" href="#proposed-changes-for-tr1" id="id3" name="id3">Proposed Changes for TR1</a></li>
<li><a class="reference" href="#proposed-text" id="id4" name="id4">Proposed Text</a><ul> <li><a class="reference" href="#possible-but-not-proposed-changes-to-the-working-paper" id="id4" name="id4">Possible (but not proposed) Changes to the Working Paper</a><ul>
<li><a class="reference" href="#addition-to-lib-iterator-requirements" id="id5" name="id5">Addition to [lib.iterator.requirements]</a><ul> <li><a class="reference" href="#changes-to-algorithm-requirements" id="id5" name="id5">Changes to Algorithm Requirements</a></li>
<li><a class="reference" href="#iterator-value-access-concepts-lib-iterator-value-access" id="id6" name="id6">Iterator Value Access Concepts [lib.iterator.value.access]</a><ul> <li><a class="reference" href="#deprecations" id="id6" name="id6">Deprecations</a></li>
<li><a class="reference" href="#readable-iterators-lib-readable-iterators" id="id7" name="id7">Readable Iterators [lib.readable.iterators]</a></li> <li><a class="reference" href="#vector-bool" id="id7" name="id7"><tt class="literal"><span class="pre">vector&lt;bool&gt;</span></tt></a></li>
<li><a class="reference" href="#writable-iterators-lib-writable-iterators" id="id8" name="id8">Writable Iterators [lib.writable.iterators]</a></li>
<li><a class="reference" href="#swappable-iterators-lib-swappable-iterators" id="id9" name="id9">Swappable Iterators [lib.swappable.iterators]</a></li>
<li><a class="reference" href="#lvalue-iterators-lib-lvalue-iterators" id="id10" name="id10">Lvalue Iterators [lib.lvalue.iterators]</a></li>
</ul>
</li>
<li><a class="reference" href="#iterator-traversal-concepts-lib-iterator-traversal" id="id11" name="id11">Iterator Traversal Concepts [lib.iterator.traversal]</a><ul>
<li><a class="reference" href="#incrementable-iterators-lib-incrementable-iterators" id="id12" name="id12">Incrementable Iterators [lib.incrementable.iterators]</a></li>
<li><a class="reference" href="#single-pass-iterators-lib-single-pass-iterators" id="id13" name="id13">Single Pass Iterators [lib.single.pass.iterators]</a></li>
<li><a class="reference" href="#forward-traversal-iterators-lib-forward-traversal-iterators" id="id14" name="id14">Forward Traversal Iterators [lib.forward.traversal.iterators]</a></li>
<li><a class="reference" href="#bidirectional-traversal-iterators-lib-bidirectional-traversal-iterators" id="id15" name="id15">Bidirectional Traversal Iterators [lib.bidirectional.traversal.iterators]</a></li>
<li><a class="reference" href="#random-access-traversal-iterators-lib-random-access-traversal-iterators" id="id16" name="id16">Random Access Traversal Iterators [lib.random.access.traversal.iterators]</a></li>
</ul> </ul>
</li> </li>
</ul> </ul>
</li> </li>
<li><a class="reference" href="#addition-to-lib-iterator-synopsis" id="id17" name="id17">Addition to [lib.iterator.synopsis]</a></li> <li><a class="reference" href="#design" id="id8" name="id8">Design</a></li>
<li><a class="reference" href="#addition-to-lib-iterator-traits" id="id18" name="id18">Addition to [lib.iterator.traits]</a></li> <li><a class="reference" href="#proposed-text" id="id9" name="id9">Proposed Text</a><ul>
<li><a class="reference" href="#addition-to-lib-iterator-requirements" id="id10" name="id10">Addition to [lib.iterator.requirements]</a><ul>
<li><a class="reference" href="#iterator-value-access-concepts-lib-iterator-value-access" id="id11" name="id11">Iterator Value Access Concepts [lib.iterator.value.access]</a><ul>
<li><a class="reference" href="#readable-iterators-lib-readable-iterators" id="id12" name="id12">Readable Iterators [lib.readable.iterators]</a></li>
<li><a class="reference" href="#writable-iterators-lib-writable-iterators" id="id13" name="id13">Writable Iterators [lib.writable.iterators]</a></li>
<li><a class="reference" href="#swappable-iterators-lib-swappable-iterators" id="id14" name="id14">Swappable Iterators [lib.swappable.iterators]</a></li>
<li><a class="reference" href="#lvalue-iterators-lib-lvalue-iterators" id="id15" name="id15">Lvalue Iterators [lib.lvalue.iterators]</a></li>
</ul>
</li>
<li><a class="reference" href="#iterator-traversal-concepts-lib-iterator-traversal" id="id16" name="id16">Iterator Traversal Concepts [lib.iterator.traversal]</a><ul>
<li><a class="reference" href="#incrementable-iterators-lib-incrementable-iterators" id="id17" name="id17">Incrementable Iterators [lib.incrementable.iterators]</a></li>
<li><a class="reference" href="#single-pass-iterators-lib-single-pass-iterators" id="id18" name="id18">Single Pass Iterators [lib.single.pass.iterators]</a></li>
<li><a class="reference" href="#forward-traversal-iterators-lib-forward-traversal-iterators" id="id19" name="id19">Forward Traversal Iterators [lib.forward.traversal.iterators]</a></li>
<li><a class="reference" href="#bidirectional-traversal-iterators-lib-bidirectional-traversal-iterators" id="id20" name="id20">Bidirectional Traversal Iterators [lib.bidirectional.traversal.iterators]</a></li>
<li><a class="reference" href="#random-access-traversal-iterators-lib-random-access-traversal-iterators" id="id21" name="id21">Random Access Traversal Iterators [lib.random.access.traversal.iterators]</a></li>
</ul>
</li>
</ul>
</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> </ul>
</li> </li>
</ul> </ul>
@ -284,12 +295,15 @@ following table gives a summary of the current value access
requirements in the iterator categories.</p> requirements in the iterator categories.</p>
<table border class="table"> <table border class="table">
<colgroup> <colgroup>
<col width="31%" /> <col width="39%" />
<col width="69%" /> <col width="61%" />
</colgroup> </colgroup>
<thead valign="bottom"> <thead valign="bottom">
<tr><th colspan="2">Value Access Requirements in Existing Iterator Categories</th> <tr><th colspan="2">Value Access Requirements in Existing Iterator Categories</th>
</tr> </tr>
<tr><th>Existing Category</th>
<th>Requirement</th>
</tr>
</thead> </thead>
<tbody valign="top"> <tbody valign="top">
<tr><td>Output Iterator</td> <tr><td>Output Iterator</td>
@ -299,12 +313,13 @@ requirements in the iterator categories.</p>
<td><tt class="literal"><span class="pre">*i</span></tt> is convertible to <tt class="literal"><span class="pre">T</span></tt></td> <td><tt class="literal"><span class="pre">*i</span></tt> is convertible to <tt class="literal"><span class="pre">T</span></tt></td>
</tr> </tr>
<tr><td>Forward Iterator</td> <tr><td>Forward Iterator</td>
<td><tt class="literal"><span class="pre">*i</span></tt> is <tt class="literal"><span class="pre">T&amp;</span></tt> (or <tt class="literal"><span class="pre">const</span> <span class="pre">T&amp;</span></tt> once <a class="reference" href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/lwg-active.html#200">issue 200</a> <td><tt class="literal"><span class="pre">*i</span></tt> is <tt class="literal"><span class="pre">T&amp;</span></tt> (or <tt class="literal"><span class="pre">const</span> <span class="pre">T&amp;</span></tt>
is resolved)</td> once <a class="reference" href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/lwg-active.html#200">issue 200</a> is resolved)</td>
</tr> </tr>
<tr><td>Random Access Iterator</td> <tr><td>Random Access Iterator</td>
<td><tt class="literal"><span class="pre">i[n]</span></tt> is convertible to <tt class="literal"><span class="pre">T</span></tt> (also <tt class="literal"><span class="pre">i[n]</span> <span class="pre">=</span> <span class="pre">t</span></tt> <td><tt class="literal"><span class="pre">i[n]</span></tt> is convertible to <tt class="literal"><span class="pre">T</span></tt>
is required for mutable iterators once <a class="reference" href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/lwg-active.html#299">issue 299</a> (also <tt class="literal"><span class="pre">i[n]</span> <span class="pre">=</span> <span class="pre">t</span></tt> is required for
mutable iterators once <a class="reference" href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/lwg-active.html#299">issue 299</a>
is resolved)</td> is resolved)</td>
</tr> </tr>
</tbody> </tbody>
@ -350,6 +365,8 @@ traversal from the need for a true reference return type.</li>
</div> </div>
<div class="section" id="impact-on-the-standard"> <div class="section" id="impact-on-the-standard">
<h1><a class="toc-backref" href="#id2" name="impact-on-the-standard">Impact on the Standard</a></h1> <h1><a class="toc-backref" href="#id2" name="impact-on-the-standard">Impact on the Standard</a></h1>
<div class="section" id="proposed-changes-for-tr1">
<h2><a class="toc-backref" href="#id3" name="proposed-changes-for-tr1">Proposed Changes for TR1</a></h2>
<p>The new iterator concepts are backward-compatible with the old <p>The new iterator concepts are backward-compatible with the old
iterator requirements, and old iterators are forward-compatible with iterator requirements, and old iterators are forward-compatible with
the new iterator concepts. That is to say, iterators that satisfy the the new iterator concepts. That is to say, iterators that satisfy the
@ -366,9 +383,18 @@ is convertible to input_iterator_tag? -JGS -->
<p>The algorithms in the standard library benefit from the new iterator <p>The algorithms in the standard library benefit from the new iterator
concepts because the new concepts provide a more accurate way to concepts because the new concepts provide a more accurate way to
express their type requirements. The result is algorithms that are express their type requirements. The result is algorithms that are
usable in more situations and have fewer type requirements. The usable in more situations and have fewer type requirements.</p>
following lists the proposed changes to the type requirements of </div>
algorithms.</p> <div class="section" id="possible-but-not-proposed-changes-to-the-working-paper">
<h2><a class="toc-backref" href="#id4" name="possible-but-not-proposed-changes-to-the-working-paper">Possible (but not proposed) Changes to the Working Paper</a></h2>
<p>The extensions in this paper suggest several changes we might make
to the working paper for the next standard. These changes are not
a formal part of this proposal for TR1.</p>
<div class="section" id="changes-to-algorithm-requirements">
<h3><a class="toc-backref" href="#id5" name="changes-to-algorithm-requirements">Changes to Algorithm Requirements</a></h3>
<p>The following lists possible (but not proposed) changes to the type
requirements of algorithms, phrased as textual substitutions,
listing the algorithms to which each textual substitution applies.</p>
<p>Forward Iterator -&gt; Forward Traversal Iterator and Readable Iterator</p> <p>Forward Iterator -&gt; Forward Traversal Iterator and Readable Iterator</p>
<blockquote> <blockquote>
<tt class="literal"><span class="pre">find_end,</span> <span class="pre">adjacent_find,</span> <span class="pre">search,</span> <span class="pre">search_n,</span> <span class="pre">rotate_copy,</span> <tt class="literal"><span class="pre">find_end,</span> <span class="pre">adjacent_find,</span> <span class="pre">search,</span> <span class="pre">search_n,</span> <span class="pre">rotate_copy,</span>
@ -424,8 +450,24 @@ Bidirectional Iterator (2) -&gt; Bidirectional Traversal Iterator and Writable I
<dd><tt class="literal"><span class="pre">transform</span></tt></dd> <dd><tt class="literal"><span class="pre">transform</span></tt></dd>
</dl> </dl>
</div> </div>
<div class="section" id="deprecations">
<h3><a class="toc-backref" href="#id6" name="deprecations">Deprecations</a></h3>
<p>For the next working paper (but not for TR1), the committee should
consider deprecating the old iterator tags, and
std::iterator_traits, since it will be superceded by individual
traits metafunctions.</p>
</div>
<div class="section" id="vector-bool">
<h3><a class="toc-backref" href="#id7" name="vector-bool"><tt class="literal"><span class="pre">vector&lt;bool&gt;</span></tt></a></h3>
<p>For the next working paper (but not for TR1), the committee should
consider reclassifying <tt class="literal"><span class="pre">vector&lt;bool&gt;::iterator</span></tt> as a Random
Access Traversal Iterator and Readable Iterator and Writable
Iterator.</p>
</div>
</div>
</div>
<div class="section" id="design"> <div class="section" id="design">
<h1><a class="toc-backref" href="#id3" name="design">Design</a></h1> <h1><a class="toc-backref" href="#id8" name="design">Design</a></h1>
<p>The iterator requirements are to be separated into two groups. One set <p>The iterator requirements are to be separated into two groups. One set
of concepts handles the syntax and semantics of value access:</p> of concepts handles the syntax and semantics of value access:</p>
<ul class="simple"> <ul class="simple">
@ -527,17 +569,17 @@ only required to return something convertible to the <tt class="literal"><span c
<tt class="literal"><span class="pre">i[n]</span> <span class="pre">=</span> <span class="pre">t</span></tt> (for a Writable Iterator).</p> <tt class="literal"><span class="pre">i[n]</span> <span class="pre">=</span> <span class="pre">t</span></tt> (for a Writable Iterator).</p>
</div> </div>
<div class="section" id="proposed-text"> <div class="section" id="proposed-text">
<h1><a class="toc-backref" href="#id4" name="proposed-text">Proposed Text</a></h1> <h1><a class="toc-backref" href="#id9" name="proposed-text">Proposed Text</a></h1>
<div class="section" id="addition-to-lib-iterator-requirements"> <div class="section" id="addition-to-lib-iterator-requirements">
<h2><a class="toc-backref" href="#id5" name="addition-to-lib-iterator-requirements">Addition to [lib.iterator.requirements]</a></h2> <h2><a class="toc-backref" href="#id10" name="addition-to-lib-iterator-requirements">Addition to [lib.iterator.requirements]</a></h2>
<div class="section" id="iterator-value-access-concepts-lib-iterator-value-access"> <div class="section" id="iterator-value-access-concepts-lib-iterator-value-access">
<h3><a class="toc-backref" href="#id6" name="iterator-value-access-concepts-lib-iterator-value-access">Iterator Value Access Concepts [lib.iterator.value.access]</a></h3> <h3><a class="toc-backref" href="#id11" name="iterator-value-access-concepts-lib-iterator-value-access">Iterator Value Access Concepts [lib.iterator.value.access]</a></h3>
<p>In the tables below, <tt class="literal"><span class="pre">X</span></tt> is an iterator type, <tt class="literal"><span class="pre">a</span></tt> is a constant <p>In the tables below, <tt class="literal"><span class="pre">X</span></tt> is an iterator type, <tt class="literal"><span class="pre">a</span></tt> is a constant
object of type <tt class="literal"><span class="pre">X</span></tt>, <tt class="literal"><span class="pre">T</span></tt> is object of type <tt class="literal"><span class="pre">X</span></tt>, <tt class="literal"><span class="pre">T</span></tt> is
<tt class="literal"><span class="pre">std::iterator_traits&lt;X&gt;::value_type</span></tt>, and <tt class="literal"><span class="pre">v</span></tt> is a constant <tt class="literal"><span class="pre">std::iterator_traits&lt;X&gt;::value_type</span></tt>, and <tt class="literal"><span class="pre">v</span></tt> is a constant
object of type <tt class="literal"><span class="pre">T</span></tt>.</p> object of type <tt class="literal"><span class="pre">T</span></tt>.</p>
<a class="target" id="readable-iterator" name="readable-iterator"></a><div class="section" id="readable-iterators-lib-readable-iterators"> <a class="target" id="readable-iterator" name="readable-iterator"></a><div class="section" id="readable-iterators-lib-readable-iterators">
<h4><a class="toc-backref" href="#id7" name="readable-iterators-lib-readable-iterators">Readable Iterators [lib.readable.iterators]</a></h4> <h4><a class="toc-backref" href="#id12" name="readable-iterators-lib-readable-iterators">Readable Iterators [lib.readable.iterators]</a></h4>
<p>A class or built-in type <tt class="literal"><span class="pre">X</span></tt> models the <em>Readable Iterator</em> concept <p>A class or built-in type <tt class="literal"><span class="pre">X</span></tt> models the <em>Readable Iterator</em> concept
for the value type <tt class="literal"><span class="pre">T</span></tt> if the following expressions are valid and for the value type <tt class="literal"><span class="pre">T</span></tt> if the following expressions are valid and
respect the stated semantics. <tt class="literal"><span class="pre">U</span></tt> is the type of any specified respect the stated semantics. <tt class="literal"><span class="pre">U</span></tt> is the type of any specified
@ -557,12 +599,13 @@ member of type <tt class="literal"><span class="pre">T</span></tt>.</p>
</tr> </tr>
</thead> </thead>
<tbody valign="top"> <tbody valign="top">
<tr><td><tt class="literal"><span class="pre">iterator_traits&lt;X&gt;::value_type</span></tt></td> <tr><td><tt class="literal"><span class="pre">iterator_traits&lt;</span> <span class="pre">X</span>
<span class="pre">&gt;::value_type</span></tt></td>
<td><tt class="literal"><span class="pre">T</span></tt></td> <td><tt class="literal"><span class="pre">T</span></tt></td>
<td>Any non-reference, <td>Any non-reference,
non-cv-qualified type</td> non-cv-qualified type</td>
</tr> </tr>
<tr><td><tt class="literal"><span class="pre">iterator_traits&lt;X&gt;::reference</span></tt></td> <tr><td><tt class="literal"><span class="pre">iterator_traits&lt;</span> <span class="pre">X&gt;::reference</span></tt></td>
<td>Convertible to <td>Convertible to
<tt class="literal"><span class="pre">iterator_traits&lt;X&gt;::value_type</span></tt></td> <tt class="literal"><span class="pre">iterator_traits&lt;X&gt;::value_type</span></tt></td>
<td>&nbsp;</td> <td>&nbsp;</td>
@ -588,7 +631,7 @@ to <tt class="literal"><span class="pre">(*a).m</span></tt></td>
</table> </table>
<a class="target" id="writable-iterator" name="writable-iterator"></a></div> <a class="target" id="writable-iterator" name="writable-iterator"></a></div>
<div class="section" id="writable-iterators-lib-writable-iterators"> <div class="section" id="writable-iterators-lib-writable-iterators">
<h4><a class="toc-backref" href="#id8" name="writable-iterators-lib-writable-iterators">Writable Iterators [lib.writable.iterators]</a></h4> <h4><a class="toc-backref" href="#id13" name="writable-iterators-lib-writable-iterators">Writable Iterators [lib.writable.iterators]</a></h4>
<p>A class or built-in type <tt class="literal"><span class="pre">X</span></tt> models the <em>Writable Iterator</em> concept <p>A class or built-in type <tt class="literal"><span class="pre">X</span></tt> models the <em>Writable Iterator</em> concept
if the following expressions are valid and respect the stated if the following expressions are valid and respect the stated
semantics. In addition, a model of <em>Writable Iterator</em> must include semantics. In addition, a model of <em>Writable Iterator</em> must include
@ -623,7 +666,7 @@ value types of <tt class="literal"><span class="pre">X</span></tt></td>
</table> </table>
</div> </div>
<div class="section" id="swappable-iterators-lib-swappable-iterators"> <div class="section" id="swappable-iterators-lib-swappable-iterators">
<h4><a class="toc-backref" href="#id9" name="swappable-iterators-lib-swappable-iterators">Swappable Iterators [lib.swappable.iterators]</a></h4> <h4><a class="toc-backref" href="#id14" name="swappable-iterators-lib-swappable-iterators">Swappable Iterators [lib.swappable.iterators]</a></h4>
<p>A class or built-in type <tt class="literal"><span class="pre">X</span></tt> models the <em>Swappable Iterator</em> concept <p>A class or built-in type <tt class="literal"><span class="pre">X</span></tt> models the <em>Swappable Iterator</em> concept
if the following expressions are valid and respect the stated if the following expressions are valid and respect the stated
semantics.</p> semantics.</p>
@ -659,7 +702,7 @@ exchanged</td>
</dl> </dl>
</div> </div>
<div class="section" id="lvalue-iterators-lib-lvalue-iterators"> <div class="section" id="lvalue-iterators-lib-lvalue-iterators">
<h4><a class="toc-backref" href="#id10" name="lvalue-iterators-lib-lvalue-iterators">Lvalue Iterators [lib.lvalue.iterators]</a></h4> <h4><a class="toc-backref" href="#id15" name="lvalue-iterators-lib-lvalue-iterators">Lvalue Iterators [lib.lvalue.iterators]</a></h4>
<p>The <em>Lvalue Iterator</em> concept adds the requirement that the <p>The <em>Lvalue Iterator</em> concept adds the requirement that the
<tt class="literal"><span class="pre">reference</span></tt> type be a reference to the value type of the iterator.</p> <tt class="literal"><span class="pre">reference</span></tt> type be a reference to the value type of the iterator.</p>
<table border class="table"> <table border class="table">
@ -689,13 +732,13 @@ cv-qualification</td>
</div> </div>
</div> </div>
<div class="section" id="iterator-traversal-concepts-lib-iterator-traversal"> <div class="section" id="iterator-traversal-concepts-lib-iterator-traversal">
<h3><a class="toc-backref" href="#id11" name="iterator-traversal-concepts-lib-iterator-traversal">Iterator Traversal Concepts [lib.iterator.traversal]</a></h3> <h3><a class="toc-backref" href="#id16" name="iterator-traversal-concepts-lib-iterator-traversal">Iterator Traversal Concepts [lib.iterator.traversal]</a></h3>
<p>In the tables below, <tt class="literal"><span class="pre">X</span></tt> is an iterator type, <tt class="literal"><span class="pre">a</span></tt> and <tt class="literal"><span class="pre">b</span></tt> are <p>In the tables below, <tt class="literal"><span class="pre">X</span></tt> is an iterator type, <tt class="literal"><span class="pre">a</span></tt> and <tt class="literal"><span class="pre">b</span></tt> are
constant objects of type <tt class="literal"><span class="pre">X</span></tt>, <tt class="literal"><span class="pre">r</span></tt> and <tt class="literal"><span class="pre">s</span></tt> are mutable objects of constant objects of type <tt class="literal"><span class="pre">X</span></tt>, <tt class="literal"><span class="pre">r</span></tt> and <tt class="literal"><span class="pre">s</span></tt> are mutable objects of
type <tt class="literal"><span class="pre">X</span></tt>, <tt class="literal"><span class="pre">T</span></tt> is <tt class="literal"><span class="pre">std::iterator_traits&lt;X&gt;::value_type</span></tt>, and type <tt class="literal"><span class="pre">X</span></tt>, <tt class="literal"><span class="pre">T</span></tt> is <tt class="literal"><span class="pre">std::iterator_traits&lt;X&gt;::value_type</span></tt>, and
<tt class="literal"><span class="pre">v</span></tt> is a constant object of type <tt class="literal"><span class="pre">T</span></tt>.</p> <tt class="literal"><span class="pre">v</span></tt> is a constant object of type <tt class="literal"><span class="pre">T</span></tt>.</p>
<div class="section" id="incrementable-iterators-lib-incrementable-iterators"> <div class="section" id="incrementable-iterators-lib-incrementable-iterators">
<h4><a class="toc-backref" href="#id12" name="incrementable-iterators-lib-incrementable-iterators">Incrementable Iterators [lib.incrementable.iterators]</a></h4> <h4><a class="toc-backref" href="#id17" name="incrementable-iterators-lib-incrementable-iterators">Incrementable Iterators [lib.incrementable.iterators]</a></h4>
<p>A class or built-in type <tt class="literal"><span class="pre">X</span></tt> models the <em>Incrementable Iterator</em> <p>A class or built-in type <tt class="literal"><span class="pre">X</span></tt> models the <em>Incrementable Iterator</em>
concept if the following expressions are valid and respect the stated concept if the following expressions are valid and respect the stated
semantics.</p> semantics.</p>
@ -738,7 +781,7 @@ semantics.</p>
</table> </table>
</div> </div>
<div class="section" id="single-pass-iterators-lib-single-pass-iterators"> <div class="section" id="single-pass-iterators-lib-single-pass-iterators">
<h4><a class="toc-backref" href="#id13" name="single-pass-iterators-lib-single-pass-iterators">Single Pass Iterators [lib.single.pass.iterators]</a></h4> <h4><a class="toc-backref" href="#id18" name="single-pass-iterators-lib-single-pass-iterators">Single Pass Iterators [lib.single.pass.iterators]</a></h4>
<p>A class or built-in type <tt class="literal"><span class="pre">X</span></tt> models the <em>Single Pass Iterator</em> <p>A class or built-in type <tt class="literal"><span class="pre">X</span></tt> models the <em>Single Pass Iterator</em>
concept if the following expressions are valid and respect the stated concept if the following expressions are valid and respect the stated
semantics.</p> semantics.</p>
@ -784,7 +827,7 @@ relation over its domain</td>
</table> </table>
</div> </div>
<div class="section" id="forward-traversal-iterators-lib-forward-traversal-iterators"> <div class="section" id="forward-traversal-iterators-lib-forward-traversal-iterators">
<h4><a class="toc-backref" href="#id14" name="forward-traversal-iterators-lib-forward-traversal-iterators">Forward Traversal Iterators [lib.forward.traversal.iterators]</a></h4> <h4><a class="toc-backref" href="#id19" name="forward-traversal-iterators-lib-forward-traversal-iterators">Forward Traversal Iterators [lib.forward.traversal.iterators]</a></h4>
<p>A class or built-in type <tt class="literal"><span class="pre">X</span></tt> models the <em>Forward Traversal Iterator</em> <p>A class or built-in type <tt class="literal"><span class="pre">X</span></tt> models the <em>Forward Traversal Iterator</em>
concept if the following expressions are valid and respect the stated concept if the following expressions are valid and respect the stated
semantics.</p> semantics.</p>
@ -831,14 +874,14 @@ the distance between iterators</td>
</table> </table>
</div> </div>
<div class="section" id="bidirectional-traversal-iterators-lib-bidirectional-traversal-iterators"> <div class="section" id="bidirectional-traversal-iterators-lib-bidirectional-traversal-iterators">
<h4><a class="toc-backref" href="#id15" name="bidirectional-traversal-iterators-lib-bidirectional-traversal-iterators">Bidirectional Traversal Iterators [lib.bidirectional.traversal.iterators]</a></h4> <h4><a class="toc-backref" href="#id20" name="bidirectional-traversal-iterators-lib-bidirectional-traversal-iterators">Bidirectional Traversal Iterators [lib.bidirectional.traversal.iterators]</a></h4>
<p>A class or built-in type <tt class="literal"><span class="pre">X</span></tt> models the <em>Bidirectional Traversal <p>A class or built-in type <tt class="literal"><span class="pre">X</span></tt> models the <em>Bidirectional Traversal
Iterator</em> concept if the following expressions are valid and respect Iterator</em> concept if the following expressions are valid and respect
the stated semantics.</p> the stated semantics.</p>
<table border class="table"> <table border class="table">
<colgroup> <colgroup>
<col width="35%" /> <col width="37%" />
<col width="44%" /> <col width="42%" />
<col width="21%" /> <col width="21%" />
</colgroup> </colgroup>
<thead valign="bottom"> <thead valign="bottom">
@ -883,7 +926,7 @@ implies <tt class="literal"><span class="pre">r</span> <span class="pre">==</spa
</table> </table>
</div> </div>
<div class="section" id="random-access-traversal-iterators-lib-random-access-traversal-iterators"> <div class="section" id="random-access-traversal-iterators-lib-random-access-traversal-iterators">
<h4><a class="toc-backref" href="#id16" name="random-access-traversal-iterators-lib-random-access-traversal-iterators">Random Access Traversal Iterators [lib.random.access.traversal.iterators]</a></h4> <h4><a class="toc-backref" href="#id21" name="random-access-traversal-iterators-lib-random-access-traversal-iterators">Random Access Traversal Iterators [lib.random.access.traversal.iterators]</a></h4>
<p>A class or built-in type <tt class="literal"><span class="pre">X</span></tt> models the <em>Random Access Traversal <p>A class or built-in type <tt class="literal"><span class="pre">X</span></tt> models the <em>Random Access Traversal
Iterator</em> concept if the following expressions are valid and respect Iterator</em> concept if the following expressions are valid and respect
the stated semantics. In the table below, <tt class="literal"><span class="pre">Distance</span></tt> is the stated semantics. In the table below, <tt class="literal"><span class="pre">Distance</span></tt> is
@ -892,8 +935,8 @@ constant object of type <tt class="literal"><span class="pre">Distance</span></t
<table border class="table"> <table border class="table">
<colgroup> <colgroup>
<col width="31%" /> <col width="31%" />
<col width="35%" /> <col width="38%" />
<col width="18%" /> <col width="15%" />
<col width="16%" /> <col width="16%" />
</colgroup> </colgroup>
<thead valign="bottom"> <thead valign="bottom">
@ -926,8 +969,8 @@ Precondition</th>
</tr> </tr>
<tr><td><tt class="literal"><span class="pre">a</span> <span class="pre">+</span> <span class="pre">n</span></tt>, <tt class="literal"><span class="pre">n</span> <span class="pre">+</span> <span class="pre">a</span></tt></td> <tr><td><tt class="literal"><span class="pre">a</span> <span class="pre">+</span> <span class="pre">n</span></tt>, <tt class="literal"><span class="pre">n</span> <span class="pre">+</span> <span class="pre">a</span></tt></td>
<td><tt class="literal"><span class="pre">X</span></tt></td> <td><tt class="literal"><span class="pre">X</span></tt></td>
<td><tt class="literal"><span class="pre">{</span> <span class="pre">X</span> <span class="pre">tmp</span> <span class="pre">=</span> <span class="pre">a;</span> <span class="pre">return</span> <span class="pre">tmp</span> <td><tt class="literal"><span class="pre">{</span> <span class="pre">X</span> <span class="pre">tmp</span> <span class="pre">=</span> <span class="pre">a;</span> <span class="pre">return</span>
<span class="pre">+=</span> <span class="pre">n;</span> <span class="pre">}</span></tt></td> <span class="pre">tmp</span> <span class="pre">+=</span> <span class="pre">n;</span> <span class="pre">}</span></tt></td>
<td>&nbsp;</td> <td>&nbsp;</td>
</tr> </tr>
<tr><td><tt class="literal"><span class="pre">r</span> <span class="pre">-=</span> <span class="pre">n</span></tt></td> <tr><td><tt class="literal"><span class="pre">r</span> <span class="pre">-=</span> <span class="pre">n</span></tt></td>
@ -937,14 +980,15 @@ Precondition</th>
</tr> </tr>
<tr><td><tt class="literal"><span class="pre">a</span> <span class="pre">-</span> <span class="pre">n</span></tt></td> <tr><td><tt class="literal"><span class="pre">a</span> <span class="pre">-</span> <span class="pre">n</span></tt></td>
<td><tt class="literal"><span class="pre">X</span></tt></td> <td><tt class="literal"><span class="pre">X</span></tt></td>
<td><tt class="literal"><span class="pre">{</span> <span class="pre">X</span> <span class="pre">tmp</span> <span class="pre">=</span> <span class="pre">a;</span> <span class="pre">return</span> <span class="pre">tmp</span> <td><tt class="literal"><span class="pre">{</span> <span class="pre">X</span> <span class="pre">tmp</span> <span class="pre">=</span> <span class="pre">a;</span> <span class="pre">return</span>
<span class="pre">-=</span> <span class="pre">n;</span> <span class="pre">}</span></tt></td> <span class="pre">tmp</span> <span class="pre">-=</span> <span class="pre">n;</span> <span class="pre">}</span></tt></td>
<td>&nbsp;</td> <td>&nbsp;</td>
</tr> </tr>
<tr><td><tt class="literal"><span class="pre">b</span> <span class="pre">-</span> <span class="pre">a</span></tt></td> <tr><td><tt class="literal"><span class="pre">b</span> <span class="pre">-</span> <span class="pre">a</span></tt></td>
<td><tt class="literal"><span class="pre">Distance</span></tt></td> <td><tt class="literal"><span class="pre">Distance</span></tt></td>
<td><tt class="literal"><span class="pre">a</span> <span class="pre">&lt;</span> <span class="pre">b</span> <span class="pre">?</span>&nbsp; <span class="pre">distance(a,b)</span> <td><tt class="literal"><span class="pre">a</span> <span class="pre">&lt;</span> <span class="pre">b</span> <span class="pre">?</span>
<span class="pre">:</span> <span class="pre">-distance(b,a)</span></tt></td> <span class="pre">distance(a,b)</span> <span class="pre">:</span>
<span class="pre">-distance(b,a)</span></tt></td>
<td>pre: there exists a <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">Distance</span></tt> such that
@ -997,7 +1041,7 @@ ordering relation</td>
</div> </div>
</div> </div>
<div class="section" id="addition-to-lib-iterator-synopsis"> <div class="section" id="addition-to-lib-iterator-synopsis">
<h2><a class="toc-backref" href="#id17" 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"> <pre class="literal-block">
// lib.iterator.traits, traits and tags // lib.iterator.traits, traits and tags
template &lt;class Iterator&gt; struct is_readable; template &lt;class Iterator&gt; struct is_readable;
@ -1027,7 +1071,7 @@ struct input_output_iterator_tag : input_iterator_tag, output_iterator_tag {};
</pre> </pre>
</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="#id18" 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">iterator_tag</span></tt> class template is an iterator category tag that <p>The <tt class="literal"><span class="pre">iterator_tag</span></tt> class template is an iterator category tag that
encodes the access enum and traversal tag in addition to being compatible encodes the access enum and traversal tag in addition to being compatible
with the original iterator tags. The <tt class="literal"><span class="pre">iterator_tag</span></tt> class inherits with the original iterator tags. The <tt class="literal"><span class="pre">iterator_tag</span></tt> class inherits
@ -1086,8 +1130,12 @@ is-writable(Iterator) =
cat = iterator_traits&lt;Iterator&gt;::iterator_category; cat = iterator_traits&lt;Iterator&gt;::iterator_category;
if (cat == iterator_tag&lt;Access,Traversal&gt;) if (cat == iterator_tag&lt;Access,Traversal&gt;)
return Access &amp; writable_iterator; return Access &amp; writable_iterator;
else if (cat is convertible to forward_iterator_tag else if (cat is convertible to output_iterator_tag)
or output_iterator_tag) return true;
else if (
cat is convertible to forward_iterator_tag
and iterator_traits&lt;Iterator&gt;::reference is a
mutable reference)
return true; return true;
else else
return false; return false;
@ -1157,7 +1205,7 @@ LocalWords: TraversalTag typename lvalues DWA Hmm JGS mis enum -->
<hr class="footer" /> <hr class="footer" />
<div class="footer"> <div class="footer">
<a class="reference" href="new-iter-concepts.rst">View document source</a>. <a class="reference" href="new-iter-concepts.rst">View document source</a>.
Generated on: 2003-09-22 19:48 UTC. Generated on: 2003-10-30 20:56 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. 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> </div>
</body> </body>

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

@ -4,15 +4,18 @@
:Author: David Abrahams, Jeremy Siek, Thomas Witt :Author: David Abrahams, Jeremy Siek, Thomas Witt
:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@acm.org :Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@acm.org
:organization: `Boost Consulting`_, Indiana University `Open Systems Lab`_, University of Hanover `Institute for Transport Railway Operation and Construction`_ :organization: `Boost Consulting`_, Indiana University `Open
Systems Lab`_, University of Hanover `Institute for
Transport Railway Operation and Construction`_
:date: $Date$ :date: $Date$
:Number: revised from `N1531=03-0114`__ :Number: N1530=03-0133
:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved :copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved
.. __: n1531_
.. _`Boost Consulting`: http://www.boost-consulting.com .. _`Boost Consulting`: http://www.boost-consulting.com
.. _`Open Systems Lab`: http://www.osl.iu.edu .. _`Open Systems Lab`: http://www.osl.iu.edu
.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de
.. _`Institute for Transport Railway Operation and Construction`:
http://www.ive.uni-hannover.de
:Abstract: We propose a new system of iterator concepts that treat :Abstract: We propose a new system of iterator concepts that treat
access and positioning independently. This allows the access and positioning independently. This allows the
@ -118,6 +121,9 @@ things happen:
Impact on the Standard Impact on the Standard
======================== ========================
Proposed Changes for TR1
========================
The new iterator concepts are backward-compatible with the old The new iterator concepts are backward-compatible with the old
iterator requirements, and old iterators are forward-compatible with iterator requirements, and old iterators are forward-compatible with
the new iterator concepts. That is to say, iterators that satisfy the the new iterator concepts. That is to say, iterators that satisfy the
@ -134,12 +140,107 @@ appropriate old requirements.
a tag that is not input_iterator_tag but that a tag that is not input_iterator_tag but that
is convertible to input_iterator_tag? -JGS is convertible to input_iterator_tag? -JGS
The algorithms in the standard library could benefit from the new The algorithms in the standard library benefit from the new iterator
iterator concepts because the new concepts provide a more accurate way concepts because the new concepts provide a more accurate way to
to express their type requirements. The result is algorithms that are express their type requirements. The result is algorithms that are
usable in more situations, have fewer type requirements, and that are usable in more situations and have fewer type requirements.
backward compatible. However, this proposal does not include making
these changes. Possible (but not proposed) Changes to the Working Paper
========================================================
The extensions in this paper suggest several changes we might make
to the working paper for the next standard. These changes are not
a formal part of this proposal for TR1.
Changes to Algorithm Requirements
+++++++++++++++++++++++++++++++++
For the next working paper (but not for TR1), the committee should
consider the following changes to the type requirements of
algorithms. These changes are phrased as phrased as textual
substitutions, listing the algorithms to which each textual
substitution applies.
Forward Iterator -> Forward Traversal Iterator and Readable Iterator
``find_end, adjacent_find, search, search_n, rotate_copy,
lower_bound, upper_bound, equal_range, binary_search,
min_element, max_element``
Forward Iterator (1) -> Single Pass Iterator and Readable Iterator,
Forward Iterator (2) -> Forward Traversal Iterator and Readable Iterator
``find_first_of``
Forward Iterator -> Readable Iterator and Writable Iterator
``iter_swap``
Forward Iterator -> Single Pass Iterator and Writable Iterator
``fill, generate``
Forward Iterator -> Forward Traversal Iterator and Swappable Iterator
``rotate``
Forward Iterator (1) -> Swappable Iterator and Single Pass Iterator,
Forward Iterator (2) -> Swappable Iterator and Incrementable Iterator
``swap_ranges``
Forward Iterator -> Forward Traversal Iterator and Readable Iterator and Writable Iterator
``remove, remove_if, unique``
Forward Iterator -> Single Pass Iterator and Readable Iterator and Writable Iterator
``replace, replace_if``
Bidirectional Iterator -> Bidirectional Traversal Iterator and Swappable Iterator
``reverse``
Bidirectional Iterator -> Bidirectional Traversal Iterator and Readable and Swappable Iterator
``partition``
Bidirectional Iterator (1) -> Bidirectional Traversal Iterator and Readable Iterator,
Bidirectional Iterator (2) -> Bidirectional Traversal Iterator and Writable Iterator
``copy_backwards``
Bidirectional Iterator -> Bidirectional Traversal Iterator and Swappable Iterator and Readable Iterator
``next_permutation, prev_permutation``
Bidirectional Iterator -> Bidirectional Traversal Iterator and Readable Iterator and Writable Iterator
``stable_partition, inplace_merge``
Bidirectional Iterator -> Bidirectional Traversal Iterator and Readable Iterator
``reverse_copy``
Random Access Iterator -> Random Access Traversal Iterator and Readable and Writable Iterator
``random_shuffle, sort, stable_sort, partial_sort, nth_element, push_heap, pop_heap
make_heap, sort_heap``
Input Iterator (2) -> Incrementable Iterator and Readable Iterator
``equal, mismatch``
Input Iterator (2) -> Incrementable Iterator and Readable Iterator
``transform``
Deprecations
++++++++++++
For the next working paper (but not for TR1), the committee should
consider deprecating the old iterator tags, and
std::iterator_traits, since it will be superceded by individual
traits metafunctions.
``vector<bool>``
++++++++++++++++
For the next working paper (but not for TR1), the committee should
consider reclassifying ``vector<bool>::iterator`` as a Random
Access Traversal Iterator and Readable Iterator and Writable
Iterator.
======== ========
Design Design