feedc0de/boost_iterator
1
0
Fork 0
forked from boostorg/iterator
Code Pull Requests Activity

Move difference_type from the Forward Traversal Iterator concept to

Browse Source 
the Single Pass Traversal concept, so that input iterators are still
input iterators.  It does make sense to measure the distance between
Single Pass iterators, provided you're willing to throw away the data.


[SVN r33870]
This commit is contained in:
Dave Abrahams
2006-04-30 03:35:16 +00:00
parent e2957cfb0c
commit 230d47e93a
4 changed files with 423 additions and 142 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@ -3,13 +3,291 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.3.8: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>New Iterator Concepts</title>
<meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" />
<meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, Zephyr Associates, Inc." />
<meta name="date" content="2004-11-01" />
<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003." />
<link rel="stylesheet" href="default.css" type="text/css" />
<style type="text/css">
/*
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:Date: $Date$
:Revision: $Revision$
:Copyright: This stylesheet has been placed in the public domain.
Default cascading style sheet for the HTML output of Docutils.
See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/
/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
border: 0 }
table.borderless td, table.borderless th {
/* Override padding for "table.docutils td" with "! important".
The right padding separates the table cells. */
padding: 0 0.5em 0 0 ! important }
.first {
/* Override more specific margin styles with "! important". */
margin-top: 0 ! important }
.last, .with-subtitle {
margin-bottom: 0 ! important }
.hidden {
display: none }
a.toc-backref {
text-decoration: none ;
color: black }
blockquote.epigraph {
margin: 2em 5em ; }
dl.docutils dd {
margin-bottom: 0.5em }
/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
font-weight: bold }
*/
div.abstract {
margin: 2em 5em }
div.abstract p.topic-title {
font-weight: bold ;
text-align: center }
div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
margin: 2em ;
border: medium outset ;
padding: 1em }
div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
font-weight: bold ;
font-family: sans-serif }
div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
color: red ;
font-weight: bold ;
font-family: sans-serif }
/* Uncomment (and remove this text!) to get reduced vertical space in
compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
margin-bottom: 0.5em }
div.compound .compound-last, div.compound .compound-middle {
margin-top: 0.5em }
*/
div.dedication {
margin: 2em 5em ;
text-align: center ;
font-style: italic }
div.dedication p.topic-title {
font-weight: bold ;
font-style: normal }
div.figure {
margin-left: 2em ;
margin-right: 2em }
div.footer, div.header {
clear: both;
font-size: smaller }
div.line-block {
display: block ;
margin-top: 1em ;
margin-bottom: 1em }
div.line-block div.line-block {
margin-top: 0 ;
margin-bottom: 0 ;
margin-left: 1.5em }
div.sidebar {
margin-left: 1em ;
border: medium outset ;
padding: 1em ;
background-color: #ffffee ;
width: 40% ;
float: right ;
clear: right }
div.sidebar p.rubric {
font-family: sans-serif ;
font-size: medium }
div.system-messages {
margin: 5em }
div.system-messages h1 {
color: red }
div.system-message {
border: medium outset ;
padding: 1em }
div.system-message p.system-message-title {
color: red ;
font-weight: bold }
div.topic {
margin: 2em }
h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
margin-top: 0.4em }
h1.title {
text-align: center }
h2.subtitle {
text-align: center }
hr.docutils {
width: 75% }
img.align-left {
clear: left }
img.align-right {
clear: right }
ol.simple, ul.simple {
margin-bottom: 1em }
ol.arabic {
list-style: decimal }
ol.loweralpha {
list-style: lower-alpha }
ol.upperalpha {
list-style: upper-alpha }
ol.lowerroman {
list-style: lower-roman }
ol.upperroman {
list-style: upper-roman }
p.attribution {
text-align: right ;
margin-left: 50% }
p.caption {
font-style: italic }
p.credits {
font-style: italic ;
font-size: smaller }
p.label {
white-space: nowrap }
p.rubric {
font-weight: bold ;
font-size: larger ;
color: maroon ;
text-align: center }
p.sidebar-title {
font-family: sans-serif ;
font-weight: bold ;
font-size: larger }
p.sidebar-subtitle {
font-family: sans-serif ;
font-weight: bold }
p.topic-title {
font-weight: bold }
pre.address {
margin-bottom: 0 ;
margin-top: 0 ;
font-family: serif ;
font-size: 100% }
pre.literal-block, pre.doctest-block {
margin-left: 2em ;
margin-right: 2em }
span.classifier {
font-family: sans-serif ;
font-style: oblique }
span.classifier-delimiter {
font-family: sans-serif ;
font-weight: bold }
span.interpreted {
font-family: sans-serif }
span.option {
white-space: nowrap }
span.pre {
white-space: pre }
span.problematic {
color: red }
span.section-subtitle {
/* font-size relative to parent (h1..h6 element) */
font-size: 80% }
table.citation {
border-left: solid 1px gray;
margin-left: 1px }
table.docinfo {
margin: 2em 4em }
table.docutils {
margin-top: 0.5em ;
margin-bottom: 0.5em }
table.footnote {
border-left: solid 1px black;
margin-left: 1px }
table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
padding-left: 0.5em ;
padding-right: 0.5em ;
vertical-align: top }
table.docutils th.field-name, table.docinfo th.docinfo-name {
font-weight: bold ;
text-align: left ;
white-space: nowrap ;
padding-left: 0 }
h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
font-size: 100% }
ul.auto-toc {
list-style-type: none }
</style>
</head>
<body>
<div class="document" id="new-iterator-concepts">
@ -27,7 +305,7 @@
Lab</a>, <a class="last reference" href="http://www.styleadvisor.com">Zephyr Associates, Inc.</a></td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2004-11-01</td></tr>
<tr class="field"><th class="docinfo-name">Number:</th><td class="field-body">This is a revised version of <a class="reference" href="http://www.open-std.org/jtc1/sc22/WG21/docs/papers/2003/n1550.htm">n1550</a>=03-0133, which was
<tr class="field"><th class="docinfo-name">Number:</th><td class="field-body">This is a revised version of <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1550.html">n1550</a>=03-0133, which was
accepted for Technical Report 1 by the C++ standard
committee's library working group. 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>, <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>
@ -51,8 +329,8 @@ of iterators that are used in practice.</td>
</tr>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first"><a name="table-of-contents">Table of Contents</a></p>
<div class="contents topic">
<p class="topic-title first"><a id="table-of-contents" name="table-of-contents">Table of Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#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><ul>
@ -92,8 +370,8 @@ of iterators that are used in practice.</td>
<li><a class="reference" href="#footnotes" id="id24" name="id24">Footnotes</a></li>
</ul>
</div>
<div class="section" id="motivation">
<h1><a class="toc-backref" href="#id1" name="motivation">Motivation</a></h1>
<div class="section">
<h1><a class="toc-backref" href="#id1" id="motivation" name="motivation">Motivation</a></h1>
<p>The standard iterator categories and requirements are flawed because
they use a single hierarchy of concepts to address two orthogonal
issues: <em>iterator traversal</em> and <em>value access</em>. As a result, many
@ -113,7 +391,7 @@ requirements in the iterator categories.</p>
<col width="69%" />
</colgroup>
<thead valign="bottom">
<tr><th colspan="2">Value Access Requirements in Existing Iterator Categories</th>
<tr><th class="head" colspan="2">Value Access Requirements in Existing Iterator Categories</th>
</tr>
</thead>
<tbody valign="top">
@ -146,7 +424,7 @@ In paragraph 23.2.4/1 it says that a <tt class="docutils literal"><span class="p
supports random access iterators.</p>
<p>Another difficult-to-categorize iterator is the transform iterator, an
adaptor which applies a unary function object to the dereferenced
value of the some underlying iterator (see <a class="reference" href="http://www.boost.org/libs/iterator/doc/transform_iterator.html">transform_iterator</a>).
value of the some underlying iterator (see <a class="reference" href="http://www.boost.org/libs/utility/transform_iterator.htm">transform_iterator</a>).
For unary functions such as <tt class="docutils literal"><span class="pre">times</span></tt>, the return type of
<tt class="docutils literal"><span class="pre">operator*</span></tt> clearly needs to be the <tt class="docutils literal"><span class="pre">result_type</span></tt> of the function
object, which is typically not a reference. Because random access
@ -173,8 +451,8 @@ cannot separate the need for random access or bidirectional
traversal from the need for a true reference return type.</li>
</ul>
</div>
<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>
<div class="section">
<h1><a class="toc-backref" href="#id2" id="impact-on-the-standard" name="impact-on-the-standard">Impact on the Standard</a></h1>
<p>This proposal for TR1 is a pure extension. Further, the new iterator
concepts are backward-compatible with the old iterator requirements,
and old iterators are forward-compatible with the new iterator
@ -189,13 +467,13 @@ made it). -DWA -->
standards conforming input iterator is allowed to have
a tag that is not input_iterator_tag but that
is convertible to input_iterator_tag? -JGS -->
<div class="section" id="possible-but-not-proposed-changes-to-the-working-paper">
<h2><a class="toc-backref" href="#id3" name="possible-but-not-proposed-changes-to-the-working-paper">Possible (but not proposed) Changes to the Working Paper</a></h2>
<div class="section">
<h2><a class="toc-backref" href="#id3" id="possible-but-not-proposed-changes-to-the-working-paper" 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="#id4" name="changes-to-algorithm-requirements">Changes to Algorithm Requirements</a></h3>
<div class="section">
<h3><a class="toc-backref" href="#id4" id="changes-to-algorithm-requirements" name="changes-to-algorithm-requirements">Changes to Algorithm Requirements</a></h3>
<p>The algorithms in the standard library could benefit from the new
iterator concepts because the new concepts provide a more accurate way
to express their type requirements. The result is algorithms that are
@ -239,7 +517,7 @@ Forward Iterator (2) -&gt; Swappable Iterator and Incrementable Iterator</p>
<dt>Bidirectional Iterator -&gt; Bidirectional Traversal Iterator and Readable and Swappable Iterator</dt>
<dd><tt class="docutils literal"><span class="pre">partition</span></tt></dd>
</dl>
<p>Bidirectional Iterator (1) -&gt; Bidirectional Traversal Iterator and Readable Iterator,
<p>Bidirectional Iterator (1) -&gt; Bidirectional Traversal Iterator and Readable Iterator,
Bidirectional Iterator (2) -&gt; Bidirectional Traversal Iterator and Writable Iterator</p>
<blockquote>
<tt class="docutils literal"><span class="pre">copy_backwards</span></tt></blockquote>
@ -259,15 +537,15 @@ Bidirectional Iterator (2) -&gt; Bidirectional Traversal Iterator and Writable I
<dd><tt class="docutils literal"><span class="pre">transform</span></tt></dd>
</dl>
</div>
<div class="section" id="deprecations">
<h3><a class="toc-backref" href="#id5" name="deprecations">Deprecations</a></h3>
<div class="section">
<h3><a class="toc-backref" href="#id5" id="deprecations" 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="#id6" name="vector-bool"><tt class="docutils literal"><span class="pre">vector&lt;bool&gt;</span></tt></a></h3>
<div class="section">
<h3><a class="toc-backref" href="#id6" id="vector-bool" name="vector-bool"><tt class="docutils 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="docutils literal"><span class="pre">vector&lt;bool&gt;::iterator</span></tt> as a Random
Access Traversal Iterator and Readable Iterator and Writable
@ -275,8 +553,8 @@ Iterator.</p>
</div>
</div>
</div>
<div class="section" id="design">
<h1><a class="toc-backref" href="#id7" name="design">Design</a></h1>
<div class="section">
<h1><a class="toc-backref" href="#id7" id="design" name="design">Design</a></h1>
<p>The iterator requirements are to be separated into two groups. One set
of concepts handles the syntax and semantics of value access:</p>
<ul class="simple">
@ -298,7 +576,7 @@ of concepts handles the syntax and semantics of value access:</p>
</ul>
<p>The refinement relationships for the traversal concepts are in the
following diagram.</p>
<div class="image"><img alt="traversal.png" src="traversal.png" /></div>
<img alt="traversal.png" src="traversal.png" />
<p>In addition to the iterator movement operators, such as
<tt class="docutils literal"><span class="pre">operator++</span></tt>, the traversal concepts also include requirements on
position comparison such as <tt class="docutils literal"><span class="pre">operator==</span></tt> and <tt class="docutils literal"><span class="pre">operator&lt;</span></tt>. The
@ -313,7 +591,7 @@ interoperable with <tt class="docutils literal"><span class="pre">int</span> <sp
</ul>
<p>The relationship between the new iterator concepts and the old are
given in the following diagram.</p>
<div class="image"><img alt="oldeqnew.png" src="oldeqnew.png" /></div>
<img alt="oldeqnew.png" src="oldeqnew.png" />
<p>Like the old iterator requirements, we provide tags for purposes of
dispatching based on the traversal concepts. The tags are related via
inheritance so that a tag is convertible to another tag if the concept
@ -346,19 +624,19 @@ only required to return something convertible to the <tt class="docutils literal
(for a Readable Iterator), and is required to support assignment
<tt class="docutils literal"><span class="pre">i[n]</span> <span class="pre">=</span> <span class="pre">t</span></tt> (for a Writable Iterator).</p>
</div>
<div class="section" id="proposed-text">
<h1><a class="toc-backref" href="#id8" name="proposed-text">Proposed Text</a></h1>
<div class="section" id="addition-to-lib-iterator-requirements">
<h2><a class="toc-backref" href="#id9" 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">
<h3><a class="toc-backref" href="#id10" name="iterator-value-access-concepts-lib-iterator-value-access">Iterator Value Access Concepts [lib.iterator.value.access]</a></h3>
<div class="section">
<h1><a class="toc-backref" href="#id8" id="proposed-text" name="proposed-text">Proposed Text</a></h1>
<div class="section">
<h2><a class="toc-backref" href="#id9" id="addition-to-lib-iterator-requirements" name="addition-to-lib-iterator-requirements">Addition to [lib.iterator.requirements]</a></h2>
<div class="section">
<h3><a class="toc-backref" href="#id10" id="iterator-value-access-concepts-lib-iterator-value-access" 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="docutils literal"><span class="pre">X</span></tt> is an iterator type, <tt class="docutils literal"><span class="pre">a</span></tt> is a constant
object of type <tt class="docutils literal"><span class="pre">X</span></tt>, <tt class="docutils literal"><span class="pre">R</span></tt> is
<tt class="docutils literal"><span class="pre">std::iterator_traits&lt;X&gt;::reference</span></tt>, <tt class="docutils literal"><span class="pre">T</span></tt> is
<tt class="docutils literal"><span class="pre">std::iterator_traits&lt;X&gt;::value_type</span></tt>, and <tt class="docutils literal"><span class="pre">v</span></tt> is a constant
object of type <tt class="docutils 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">
<h4><a class="toc-backref" href="#id11" name="readable-iterators-lib-readable-iterators">Readable Iterators [lib.readable.iterators]</a></h4>
<div class="section">
<h4><a class="toc-backref" href="#id11" id="readable-iterators-lib-readable-iterators" name="readable-iterators-lib-readable-iterators"><span id="readable-iterator"></span>Readable Iterators [lib.readable.iterators]</a></h4>
<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> models the <em>Readable Iterator</em> concept
for value type <tt class="docutils literal"><span class="pre">T</span></tt> if, in addition to <tt class="docutils literal"><span class="pre">X</span></tt> being Assignable and
Copy Constructible, the following expressions are valid and respect
@ -371,11 +649,11 @@ type <tt class="docutils literal"><span class="pre">T</span></tt>.</p>
<col width="52%" />
</colgroup>
<thead valign="bottom">
<tr><th colspan="3">Readable Iterator Requirements (in addition to Assignable and Copy Constructible)</th>
<tr><th class="head" colspan="3">Readable Iterator Requirements (in addition to Assignable and Copy Constructible)</th>
</tr>
<tr><th>Expression</th>
<th>Return Type</th>
<th>Note/Precondition</th>
<tr><th class="head">Expression</th>
<th class="head">Return Type</th>
<th class="head">Note/Precondition</th>
</tr>
</thead>
<tbody valign="top">
@ -399,9 +677,9 @@ non-cv-qualified type</td>
</tbody>
</table>
<!-- We won't say anything about iterator_traits<X>::reference until the DR is resolved. -JGS -->
<a class="target" id="writable-iterator" name="writable-iterator"></a></div>
<div class="section" id="writable-iterators-lib-writable-iterators">
<h4><a class="toc-backref" href="#id12" name="writable-iterators-lib-writable-iterators">Writable Iterators [lib.writable.iterators]</a></h4>
</div>
<div class="section">
<h4><a class="toc-backref" href="#id12" id="writable-iterators-lib-writable-iterators" name="writable-iterators-lib-writable-iterators"><span id="writable-iterator"></span>Writable Iterators [lib.writable.iterators]</a></h4>
<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> models the <em>Writable Iterator</em> concept
if, in addition to <tt class="docutils literal"><span class="pre">X</span></tt> being Copy Constructible, the following
expressions are valid and respect the stated semantics. Writable
@ -413,11 +691,11 @@ Iterators have an associated <em>set of value types</em>.</p>
<col width="42%" />
</colgroup>
<thead valign="bottom">
<tr><th colspan="3">Writable Iterator Requirements (in addition to Copy Constructible)</th>
<tr><th class="head" colspan="3">Writable Iterator Requirements (in addition to Copy Constructible)</th>
</tr>
<tr><th>Expression</th>
<th>Return Type</th>
<th>Precondition</th>
<tr><th class="head">Expression</th>
<th class="head">Return Type</th>
<th class="head">Precondition</th>
</tr>
</thead>
<tbody valign="top">
@ -430,8 +708,8 @@ value types of <tt class="docutils literal"><span class="pre">X</span></tt></td>
</tbody>
</table>
</div>
<div class="section" id="swappable-iterators-lib-swappable-iterators">
<h4><a class="toc-backref" href="#id13" name="swappable-iterators-lib-swappable-iterators">Swappable Iterators [lib.swappable.iterators]</a></h4>
<div class="section">
<h4><a class="toc-backref" href="#id13" id="swappable-iterators-lib-swappable-iterators" name="swappable-iterators-lib-swappable-iterators">Swappable Iterators [lib.swappable.iterators]</a></h4>
<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> models the <em>Swappable Iterator</em> concept
if, in addition to <tt class="docutils literal"><span class="pre">X</span></tt> being Copy Constructible, the following
expressions are valid and respect the stated semantics.</p>
@ -442,11 +720,11 @@ expressions are valid and respect the stated semantics.</p>
<col width="43%" />
</colgroup>
<thead valign="bottom">
<tr><th colspan="3">Swappable Iterator Requirements (in addition to Copy Constructible)</th>
<tr><th class="head" colspan="3">Swappable Iterator Requirements (in addition to Copy Constructible)</th>
</tr>
<tr><th>Expression</th>
<th>Return Type</th>
<th>Postcondition</th>
<tr><th class="head">Expression</th>
<th class="head">Return Type</th>
<th class="head">Postcondition</th>
</tr>
</thead>
<tbody valign="top">
@ -461,8 +739,8 @@ exchanged</td>
<a class="reference" href="#writable-iterator">Writable Iterator</a> concepts is also a model of <em>Swappable
Iterator</em>. <em>--end note</em>]</p>
</div>
<div class="section" id="lvalue-iterators-lib-lvalue-iterators">
<h4><a class="toc-backref" href="#id14" name="lvalue-iterators-lib-lvalue-iterators">Lvalue Iterators [lib.lvalue.iterators]</a></h4>
<div class="section">
<h4><a class="toc-backref" href="#id14" id="lvalue-iterators-lib-lvalue-iterators" 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 return
type of <tt class="docutils literal"><span class="pre">operator*</span></tt> type be a reference to the value type of the
iterator.</p>
@ -473,11 +751,11 @@ iterator.</p>
<col width="59%" />
</colgroup>
<thead valign="bottom">
<tr><th colspan="3">Lvalue Iterator Requirements</th>
<tr><th class="head" colspan="3">Lvalue Iterator Requirements</th>
</tr>
<tr><th>Expression</th>
<th>Return Type</th>
<th>Note/Assertion</th>
<tr><th class="head">Expression</th>
<th class="head">Return Type</th>
<th class="head">Note/Assertion</th>
</tr>
</thead>
<tbody valign="top">
@ -497,14 +775,14 @@ Iterator</a> then <tt class="docutils literal"><span class="pre">a</span> <span
<tt class="docutils literal"><span class="pre">*b</span></tt>.</p>
</div>
</div>
<div class="section" id="iterator-traversal-concepts-lib-iterator-traversal">
<h3><a class="toc-backref" href="#id15" name="iterator-traversal-concepts-lib-iterator-traversal">Iterator Traversal Concepts [lib.iterator.traversal]</a></h3>
<div class="section">
<h3><a class="toc-backref" href="#id15" id="iterator-traversal-concepts-lib-iterator-traversal" name="iterator-traversal-concepts-lib-iterator-traversal">Iterator Traversal Concepts [lib.iterator.traversal]</a></h3>
<p>In the tables below, <tt class="docutils literal"><span class="pre">X</span></tt> is an iterator type, <tt class="docutils literal"><span class="pre">a</span></tt> and <tt class="docutils literal"><span class="pre">b</span></tt> are
constant objects of type <tt class="docutils literal"><span class="pre">X</span></tt>, <tt class="docutils literal"><span class="pre">r</span></tt> and <tt class="docutils literal"><span class="pre">s</span></tt> are mutable objects of
type <tt class="docutils literal"><span class="pre">X</span></tt>, <tt class="docutils literal"><span class="pre">T</span></tt> is <tt class="docutils literal"><span class="pre">std::iterator_traits&lt;X&gt;::value_type</span></tt>, and
<tt class="docutils literal"><span class="pre">v</span></tt> is a constant object of type <tt class="docutils literal"><span class="pre">T</span></tt>.</p>
<div class="section" id="incrementable-iterators-lib-incrementable-iterators">
<h4><a class="toc-backref" href="#id16" name="incrementable-iterators-lib-incrementable-iterators">Incrementable Iterators [lib.incrementable.iterators]</a></h4>
<div class="section">
<h4><a class="toc-backref" href="#id16" id="incrementable-iterators-lib-incrementable-iterators" name="incrementable-iterators-lib-incrementable-iterators">Incrementable Iterators [lib.incrementable.iterators]</a></h4>
<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> models the <em>Incrementable Iterator</em>
concept if, in addition to <tt class="docutils literal"><span class="pre">X</span></tt> being Assignable and Copy
Constructible, the following expressions are valid and respect the
@ -516,11 +794,11 @@ stated semantics.</p>
<col width="23%" />
</colgroup>
<thead valign="bottom">
<tr><th colspan="3">Incrementable Iterator Requirements (in addition to Assignable, Copy Constructible)</th>
<tr><th class="head" colspan="3">Incrementable Iterator Requirements (in addition to Assignable, Copy Constructible)</th>
</tr>
<tr><th>Expression</th>
<th>Return Type</th>
<th>Assertion</th>
<tr><th class="head">Expression</th>
<th class="head">Return Type</th>
<th class="head">Assertion</th>
</tr>
</thead>
<tbody valign="top">
@ -551,27 +829,26 @@ to <tt class="docutils literal"><span class="pre">T</span> <span class="pre">z(*
<!-- TR1: incrementable_iterator_tag changed to
incrementable_traversal_tag for consistency. -->
</div>
<div class="section" id="single-pass-iterators-lib-single-pass-iterators">
<h4><a class="toc-backref" href="#id17" name="single-pass-iterators-lib-single-pass-iterators">Single Pass Iterators [lib.single.pass.iterators]</a></h4>
<div class="section">
<h4><a class="toc-backref" href="#id17" id="single-pass-iterators-lib-single-pass-iterators" 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="docutils 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
semantics.</p>
<table border="1" class="docutils">
<colgroup>
<col width="32%" />
<col width="29%" />
<col width="13%" />
<col width="37%" />
<col width="27%" />
<col width="12%" />
<col width="25%" />
</colgroup>
<thead valign="bottom">
<tr><th colspan="4">Single Pass Iterator Requirements (in addition to Incrementable Iterator and Equality
Comparable)</th>
<tr><th class="head" colspan="4">Single Pass Iterator Requirements (in addition to Incrementable Iterator and Equality Comparable)</th>
</tr>
<tr><th>Expression</th>
<th>Return Type</th>
<th>Operational
<tr><th class="head">Expression</th>
<th class="head">Return Type</th>
<th class="head">Operational
Semantics</th>
<th>Assertion/
<th class="head">Assertion/
Pre-/Post-condition</th>
</tr>
</thead>
@ -595,6 +872,13 @@ relation over its domain</td>
<td><tt class="docutils literal"><span class="pre">!(a</span> <span class="pre">==</span> <span class="pre">b)</span></tt></td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">iterator_traits&lt;X&gt;::difference_type</span></tt></td>
<td>A signed integral type
representing the distance
between iterators</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt></td>
<td>Convertible to
<tt class="docutils literal"><span class="pre">single_pass_traversal_tag</span></tt></td>
@ -606,8 +890,8 @@ relation over its domain</td>
<!-- TR1: single_pass_iterator_tag changed to
single_pass_traversal_tag for consistency -->
</div>
<div class="section" id="forward-traversal-iterators-lib-forward-traversal-iterators">
<h4><a class="toc-backref" href="#id18" name="forward-traversal-iterators-lib-forward-traversal-iterators">Forward Traversal Iterators [lib.forward.traversal.iterators]</a></h4>
<div class="section">
<h4><a class="toc-backref" href="#id18" id="forward-traversal-iterators-lib-forward-traversal-iterators" 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="docutils literal"><span class="pre">X</span></tt> models the <em>Forward Traversal Iterator</em>
concept if, in addition to <tt class="docutils literal"><span class="pre">X</span></tt> meeting the requirements of Default
Constructible and Single Pass Iterator, the following expressions are
@ -619,11 +903,11 @@ valid and respect the stated semantics.</p>
<col width="27%" />
</colgroup>
<thead valign="bottom">
<tr><th colspan="3">Forward Traversal Iterator Requirements (in addition to Default Constructible and Single Pass Iterator)</th>
<tr><th class="head" colspan="3">Forward Traversal Iterator Requirements (in addition to Default Constructible and Single Pass Iterator)</th>
</tr>
<tr><th>Expression</th>
<th>Return Type</th>
<th>Assertion/Note</th>
<tr><th class="head">Expression</th>
<th class="head">Return Type</th>
<th class="head">Assertion/Note</th>
</tr>
</thead>
<tbody valign="top">
@ -638,11 +922,6 @@ singular value.</td>
dereferenceable implies
<tt class="docutils literal"><span class="pre">++r</span> <span class="pre">==</span> <span class="pre">++s.</span></tt></td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">iterator_traits&lt;X&gt;::difference_type</span></tt></td>
<td>A signed integral type representing
the distance between iterators</td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt></td>
<td>Convertible to
<tt class="docutils literal"><span class="pre">forward_traversal_tag</span></tt></td>
@ -653,8 +932,8 @@ the distance between iterators</td>
<!-- TR1: forward_traversal_iterator_tag changed to
forward_traversal_tag for consistency -->
</div>
<div class="section" id="bidirectional-traversal-iterators-lib-bidirectional-traversal-iterators">
<h4><a class="toc-backref" href="#id19" name="bidirectional-traversal-iterators-lib-bidirectional-traversal-iterators">Bidirectional Traversal Iterators [lib.bidirectional.traversal.iterators]</a></h4>
<div class="section">
<h4><a class="toc-backref" href="#id19" id="bidirectional-traversal-iterators-lib-bidirectional-traversal-iterators" 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="docutils literal"><span class="pre">X</span></tt> models the <em>Bidirectional Traversal
Iterator</em> concept if, in addition to <tt class="docutils literal"><span class="pre">X</span></tt> meeting the requirements of
Forward Traversal Iterator, the following expressions are valid and
@ -667,14 +946,14 @@ respect the stated semantics.</p>
<col width="21%" />
</colgroup>
<thead valign="bottom">
<tr><th colspan="4">Bidirectional Traversal Iterator Requirements (in addition to Forward Traversal
<tr><th class="head" colspan="4">Bidirectional Traversal Iterator Requirements (in addition to Forward Traversal
Iterator)</th>
</tr>
<tr><th>Expression</th>
<th>Return Type</th>
<th>Operational
<tr><th class="head">Expression</th>
<th class="head">Return Type</th>
<th class="head">Operational
Semantics</th>
<th>Assertion/
<th class="head">Assertion/
Pre-/Post-condition</th>
</tr>
</thead>
@ -716,8 +995,8 @@ implies <tt class="docutils literal"><span class="pre">r</span> <span class="pre
<!-- TR1: bidirectional_traversal_iterator_tag changed to
bidirectional_traversal_tag for consistency -->
</div>
<div class="section" id="random-access-traversal-iterators-lib-random-access-traversal-iterators">
<h4><a class="toc-backref" href="#id20" name="random-access-traversal-iterators-lib-random-access-traversal-iterators">Random Access Traversal Iterators [lib.random.access.traversal.iterators]</a></h4>
<div class="section">
<h4><a class="toc-backref" href="#id20" id="random-access-traversal-iterators-lib-random-access-traversal-iterators" 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="docutils literal"><span class="pre">X</span></tt> models the <em>Random Access Traversal
Iterator</em> concept if the following expressions are valid and respect
the stated semantics. In the table below, <tt class="docutils literal"><span class="pre">Distance</span></tt> is
@ -731,12 +1010,12 @@ constant object of type <tt class="docutils literal"><span class="pre">Distance<
<col width="20%" />
</colgroup>
<thead valign="bottom">
<tr><th colspan="4">Random Access Traversal Iterator Requirements (in addition to Bidirectional Traversal Iterator)</th>
<tr><th class="head" colspan="4">Random Access Traversal Iterator Requirements (in addition to Bidirectional Traversal Iterator)</th>
</tr>
<tr><th>Expression</th>
<th>Return Type</th>
<th>Operational Semantics</th>
<th>Assertion/
<tr><th class="head">Expression</th>
<th class="head">Return Type</th>
<th class="head">Operational Semantics</th>
<th class="head">Assertion/
Precondition</th>
</tr>
</thead>
@ -830,8 +1109,8 @@ 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>
<div class="section">
<h4><a class="toc-backref" href="#id21" id="interoperable-iterators-lib-interoperable-iterators" name="interoperable-iterators-lib-interoperable-iterators">Interoperable Iterators [lib.interoperable.iterators]</a></h4>
<p>A class or built-in type <tt class="docutils 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="docutils literal"><span class="pre">Y</span></tt> that also models
Single Pass Iterator if the following expressions are valid and
@ -846,9 +1125,9 @@ constant object of type <tt class="docutils literal"><span class="pre">Distance<
<col width="60%" />
</colgroup>
<thead valign="bottom">
<tr><th>Expression</th>
<th>Return Type</th>
<th>Assertion/Precondition/Postcondition</th>
<tr><th class="head">Expression</th>
<th class="head">Return Type</th>
<th class="head">Assertion/Precondition/Postcondition</th>
</tr>
</thead>
<tbody valign="top">
@ -888,10 +1167,10 @@ the following additional requirements must be met.</p>
<col width="41%" />
</colgroup>
<thead valign="bottom">
<tr><th>Expression</th>
<th>Return Type</th>
<th>Operational Semantics</th>
<th>Assertion/ Precondition</th>
<tr><th class="head">Expression</th>
<th class="head">Return Type</th>
<th class="head">Operational Semantics</th>
<th class="head">Assertion/ Precondition</th>
</tr>
</thead>
<tbody valign="top">
@ -954,8 +1233,8 @@ the following additional requirements must be met.</p>
</div>
</div>
</div>
<div class="section" id="addition-to-lib-iterator-synopsis">
<h2><a class="toc-backref" href="#id22" name="addition-to-lib-iterator-synopsis">Addition to [lib.iterator.synopsis]</a></h2>
<div class="section">
<h2><a class="toc-backref" href="#id22" id="addition-to-lib-iterator-synopsis" 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;
@ -968,8 +1247,8 @@ struct bidirectional_traversal_tag : forward_traversal_tag { };
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="#id23" name="addition-to-lib-iterator-traits">Addition to [lib.iterator.traits]</a></h2>
<div class="section">
<h2><a class="toc-backref" href="#id23" id="addition-to-lib-iterator-traits" name="addition-to-lib-iterator-traits">Addition to [lib.iterator.traits]</a></h2>
<p>The <tt class="docutils literal"><span class="pre">is_readable_iterator</span></tt> class
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="docutils literal"><span class="pre">X</span></tt>, <tt class="docutils literal"><span class="pre">is_readable_iterator&lt;X&gt;::value</span></tt>
@ -978,10 +1257,10 @@ convertible to <tt class="docutils literal"><span class="pre">iterator_traits&lt
otherwise.</p>
<p><tt class="docutils literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt> is</p>
<pre class="literal-block">
<em>category-to-traversal</em>(iterator_traits&lt;X&gt;::iterator_category)
<em>category-to-traversal</em>(iterator_traits&lt;X&gt;::iterator_category)
</pre>
<p>where <em>category-to-traversal</em> is defined as follows</p>
<a class="target" id="category-to-traversal" name="category-to-traversal"></a><pre class="literal-block">
<pre class="literal-block" id="category-to-traversal">
<em>category-to-traversal</em>(C) =
if (C is convertible to incrementable_traversal_tag)
return C;
@ -1000,8 +1279,8 @@ otherwise.</p>
</pre>
</div>
</div>
<div class="section" id="footnotes">
<h1><a class="toc-backref" href="#id24" name="footnotes">Footnotes</a></h1>
<div class="section">
<h1><a class="toc-backref" href="#id24" id="footnotes" 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 is
considering adding the requirement that specializations are derived
from their nested <tt class="docutils literal"><span class="pre">::type</span></tt>.</p>
@ -1014,10 +1293,11 @@ LocalWords: incrementable xxx min prev inplace png oldeqnew AccessTag struct
LocalWords: TraversalTag typename lvalues DWA Hmm JGS mis enum -->
</div>
</div>
<hr class="docutils footer" />
<div class="footer">
<hr class="footer" />
<a class="reference" href="new-iter-concepts.rst">View document source</a>.
Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div>
</body>
</html>

BIN
doc/new-iter-concepts.pdf
View File

Binary file not shown.

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

@ -492,26 +492,30 @@ concept if the following expressions are valid and respect the stated
semantics.
+--------------------------------------------------------------------------------------------------------+
|Single Pass Iterator Requirements (in addition to Incrementable Iterator and Equality |
|Comparable) |
+--------------------------------+-----------------------------+-------------+---------------------------+
|Expression |Return Type | Operational |Assertion/ |
| | | Semantics |Pre-/Post-condition |
+================================+=============================+=============+===========================+
|``++r`` |``X&`` | |pre: ``r`` is |
| | | |dereferenceable; post: |
| | | |``r`` is dereferenceable or|
| | | |``r`` is past-the-end |
+--------------------------------+-----------------------------+-------------+---------------------------+
|``a == b`` |convertible to ``bool`` | |``==`` is an equivalence |
| | | |relation over its domain |
+--------------------------------+-----------------------------+-------------+---------------------------+
|``a != b`` |convertible to ``bool`` |``!(a == b)``| |
+--------------------------------+-----------------------------+-------------+---------------------------+
|``iterator_traversal<X>::type`` |Convertible to | | |
| |``single_pass_traversal_tag``| | |
+--------------------------------+-----------------------------+-------------+---------------------------+
+----------------------------------------------------------------------------------------------------------------+
|Single Pass Iterator Requirements (in addition to Incrementable Iterator and Equality Comparable) |
| |
+----------------------------------------+-----------------------------+-------------+---------------------------+
|Expression |Return Type | Operational |Assertion/ |
| | | Semantics |Pre-/Post-condition |
+========================================+=============================+=============+===========================+
|``++r`` |``X&`` | |pre: ``r`` is |
| | | |dereferenceable; post: |
| | | |``r`` is dereferenceable or|
| | | |``r`` is past-the-end |
+----------------------------------------+-----------------------------+-------------+---------------------------+
|``a == b`` |convertible to ``bool`` | |``==`` is an equivalence |
| | | |relation over its domain |
+----------------------------------------+-----------------------------+-------------+---------------------------+
|``a != b`` |convertible to ``bool`` |``!(a == b)``| |
+----------------------------------------+-----------------------------+-------------+---------------------------+
|``iterator_traits<X>::difference_type`` |A signed integral type | | |
| |representing the distance | | |
| |between iterators | | |
+----------------------------------------+-----------------------------+-------------+---------------------------+
|``iterator_traversal<X>::type`` |Convertible to | | |
| |``single_pass_traversal_tag``| | |
+----------------------------------------+-----------------------------+-------------+---------------------------+
.. TR1: single_pass_iterator_tag changed to
single_pass_traversal_tag for consistency
@ -537,10 +541,6 @@ valid and respect the stated semantics.
| | |dereferenceable implies |
| | |``++r == ++s.`` |
+---------------------------------------+-----------------------------------+----------------------------+
|``iterator_traits<X>::difference_type``|A signed integral type representing| |
| |the distance between iterators | |
| | | |
+---------------------------------------+-----------------------------------+----------------------------+
|``iterator_traversal<X>::type`` |Convertible to | |
| |``forward_traversal_tag`` | |
+---------------------------------------+-----------------------------------+----------------------------+

3
include/boost/iterator/iterator_archetypes.hpp
View File

@ -196,6 +196,8 @@ namespace detail
explicit archetype(ctor_arg arg)
: traversal_archetype_<Derived, Value, incrementable_traversal_tag>(arg)
{}
typedef std::ptrdiff_t difference_type;
};
};
@ -219,7 +221,6 @@ namespace detail
archetype()
: traversal_archetype_<Derived, Value, single_pass_traversal_tag>(ctor_arg())
{}
typedef std::ptrdiff_t difference_type;
};
};