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

Cleaned up some of Jeremy's wording. Added a few comments on changes

Browse Source 
from the accepted paper.  Committed Python doc regeneration scripts.


[SVN r21079]
This commit is contained in:
Dave Abrahams
2003-12-02 13:10:55 +00:00
parent fe52e0d665
commit 593311f43e
4 changed files with 322 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@ -3,13 +3,204 @@
<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.2.8: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.3.1: 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, University of Hanover Institute for Transport Railway Operation and Construction" />
<meta name="date" content="2003-12-01" />
<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved" />
<link rel="stylesheet" href="default.css" type="text/css" />
<style type="text/css"><!--
/*
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:date: $Date$
:version: $Revision$
:copyright: This stylesheet has been placed in the public domain.
Default cascading style sheet for the HTML output of Docutils.
*/
.first {
margin-top: 0 }
.last {
margin-bottom: 0 }
a.toc-backref {
text-decoration: none ;
color: black }
dd {
margin-bottom: 0.5em }
div.abstract {
margin: 2em 5em }
div.abstract p.topic-title {
font-weight: bold ;
text-align: center }
div.attention, div.caution, div.danger, div.error, div.hint,
div.important, div.note, div.tip, div.warning {
margin: 2em ;
border: medium outset ;
padding: 1em }
div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
color: red ;
font-weight: bold ;
font-family: sans-serif }
div.hint p.admonition-title, div.important p.admonition-title,
div.note p.admonition-title, div.tip p.admonition-title {
font-weight: bold ;
font-family: sans-serif }
div.dedication {
margin: 2em 5em ;
text-align: center ;
font-style: italic }
div.dedication p.topic-title {
font-weight: bold ;
font-style: normal }
div.figure {
margin-left: 2em }
div.footer, div.header {
font-size: smaller }
div.system-messages {
margin: 5em }
div.system-messages h1 {
color: red }
div.system-message {
border: medium outset ;
padding: 1em }
div.system-message p.system-message-title {
color: red ;
font-weight: bold }
div.topic {
margin: 2em }
h1.title {
text-align: center }
h2.subtitle {
text-align: center }
hr {
width: 75% }
ol.simple, ul.simple {
margin-bottom: 1em }
ol.arabic {
list-style: decimal }
ol.loweralpha {
list-style: lower-alpha }
ol.upperalpha {
list-style: upper-alpha }
ol.lowerroman {
list-style: lower-roman }
ol.upperroman {
list-style: upper-roman }
p.caption {
font-style: italic }
p.credits {
font-style: italic ;
font-size: smaller }
p.label {
white-space: nowrap }
p.topic-title {
font-weight: bold }
pre.address {
margin-bottom: 0 ;
margin-top: 0 ;
font-family: serif ;
font-size: 100% }
pre.line-block {
font-family: serif ;
font-size: 100% }
pre.literal-block, pre.doctest-block {
margin-left: 2em ;
margin-right: 2em ;
background-color: #eeeeee }
span.classifier {
font-family: sans-serif ;
font-style: oblique }
span.classifier-delimiter {
font-family: sans-serif ;
font-weight: bold }
span.interpreted {
font-family: sans-serif }
span.option-argument {
font-style: italic }
span.pre {
white-space: pre }
span.problematic {
color: red }
table {
margin-top: 0.5em ;
margin-bottom: 0.5em }
table.citation {
border-left: solid thin gray ;
padding-left: 0.5ex }
table.docinfo {
margin: 2em 4em }
table.footnote {
border-left: solid thin black ;
padding-left: 0.5ex }
td, th {
padding-left: 0.5em ;
padding-right: 0.5em ;
vertical-align: top }
th.docinfo-name, th.field-name {
font-weight: bold ;
text-align: left ;
white-space: nowrap }
h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
font-size: 100% }
tt {
background-color: #eeeeee }
ul.auto-toc {
list-style-type: none }
--></style>
</head>
<body>
<div class="document" id="new-iterator-concepts">
@ -107,7 +298,7 @@ geared towards iterator traversal (hence the category names), while
requirements that address value access sneak in at various places. The
following table gives a summary of the current value access
requirements in the iterator categories.</p>
<table class="table" frame="border" rules="all">
<table border class="table">
<colgroup>
<col width="31%" />
<col width="69%" />
@ -317,16 +508,24 @@ given in the following diagram.</p>
<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
associated with the first tag is a refinement of the second tag. Our
design reuses <tt class="literal"><span class="pre">iterator_traits&lt;Iter&gt;::iterator_category</span></tt> as the
access mechanism for the traversal tag. If an iterator wishes to meet
the requirements of both a new iterator concept and an old iterator
concept, it can use an iterator category type that inherits from both
the the old iterator tag and the new traversal tag.</p>
associated with the first tag is a refinement of the second tag.</p>
<p>Our design reuses <tt class="literal"><span class="pre">iterator_traits&lt;Iter&gt;::iterator_category</span></tt> to
indicate an iterator's traversal capability. To specify
capabilities not captured by any old-style iterator category, an
iterator designer can use an <tt class="literal"><span class="pre">iterator_category</span></tt> type that is
convertible to both the the most-derived old iterator category tag
which fits, and the appropriate new iterator traversal tag.</p>
<!-- dwa2003/1/2: Note that we are not *requiring* convertibility to
a new-style traversal tag in order to meet new concepts.
Old-style iterators still fit, after all. -->
<p>We do not provide tags for the purposes of dispatching based on the
access concepts. There are two reasons: we could not find a way to
automatically infer the right access tags for old-style iterators and
the need for dispatching based on the access concepts is not as great.</p>
access concepts, in part because we could not find a way to
automatically infer the right access tags for old-style iterators.
An iterator's writability may be dependent on the assignability of
its <tt class="literal"><span class="pre">value_type</span></tt> and there's no known way to detect whether an
arbitrary type is assignable. Fortunately, the need for
dispatching based on access capability is not as great as the need
for dispatching based on traversal capability.</p>
<p>A difficult design decision concerned the <tt class="literal"><span class="pre">operator[]</span></tt>. The direct
approach for specifying <tt class="literal"><span class="pre">operator[]</span></tt> would have a return type of
<tt class="literal"><span class="pre">reference</span></tt>; the same as <tt class="literal"><span class="pre">operator*</span></tt>. However, going in this
@ -355,7 +554,7 @@ object of type <tt class="literal"><span class="pre">T</span></tt>.</p>
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
member of type <tt class="literal"><span class="pre">T</span></tt>.</p>
<table class="table" frame="border" rules="all">
<table border class="table">
<colgroup>
<col width="42%" />
<col width="29%" />
@ -402,6 +601,10 @@ to <tt class="literal"><span class="pre">(*a).m</span></tt></td>
</tr>
</tbody>
</table>
<!-- TR1: the originally-proposed requirement that typeof(*a) == R
was too restrictive. Now we just require that it's
convertible to R and that accessing a T through that conversion
is equivalent to accessing a T directly. -->
<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>
@ -410,7 +613,7 @@ if the following expressions are valid and respect the stated
semantics. In addition, a model of <em>Writable Iterator</em> must include
in its documentation the <em>set of value types</em> that it allows for
output.</p>
<table class="table" frame="border" rules="all">
<table border class="table">
<colgroup>
<col width="37%" />
<col width="21%" />
@ -439,7 +642,7 @@ value types of <tt class="literal"><span class="pre">X</span></tt></td>
<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
semantics.</p>
<table class="table" frame="border" rules="all">
<table border class="table">
<colgroup>
<col width="37%" />
<col width="19%" />
@ -470,7 +673,7 @@ exchanged</td>
<h4><a class="toc-backref" href="#id14" 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
<tt class="literal"><span class="pre">reference</span></tt> type be a reference to the value type of the iterator.</p>
<table class="table" frame="border" rules="all">
<table border class="table">
<colgroup>
<col width="42%" />
<col width="14%" />
@ -507,7 +710,7 @@ type <tt class="literal"><span class="pre">X</span></tt>, <tt class="literal"><s
<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
semantics.</p>
<table class="table" frame="border" rules="all">
<table border class="table">
<colgroup>
<col width="39%" />
<col width="37%" />
@ -544,13 +747,15 @@ semantics.</p>
</tr>
</tbody>
</table>
<!-- 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>
<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
semantics.</p>
<table class="table" frame="border" rules="all">
<table border class="table">
<colgroup>
<col width="36%" />
<col width="33%" />
@ -590,13 +795,15 @@ relation over its domain</td>
</tr>
</tbody>
</table>
<!-- 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>
<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
semantics.</p>
<table class="table" frame="border" rules="all">
<table border class="table">
<colgroup>
<col width="44%" />
<col width="39%" />
@ -637,13 +844,15 @@ the distance between iterators</td>
</tr>
</tbody>
</table>
<!-- 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>
<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
the stated semantics.</p>
<table class="table" frame="border" rules="all">
<table border class="table">
<colgroup>
<col width="35%" />
<col width="44%" />
@ -689,6 +898,8 @@ implies <tt class="literal"><span class="pre">r</span> <span class="pre">==</spa
</tr>
</tbody>
</table>
<!-- 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>
@ -697,7 +908,7 @@ 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
<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>
<table class="table" frame="border" rules="all">
<table border class="table">
<colgroup>
<col width="31%" />
<col width="35%" />
@ -801,6 +1012,8 @@ ordering relation</td>
</tr>
</tbody>
</table>
<!-- TR1: random_access_traversal_iterator_tag changed to
random_access_traversal_tag for consistency -->
</div>
</div>
</div>
@ -861,5 +1074,11 @@ LocalWords: incrementable xxx min prev inplace png oldeqnew AccessTag struct
LocalWords: TraversalTag typename lvalues DWA Hmm JGS mis enum -->
</div>
</div>
<hr class="footer" />
<div class="footer">
<a class="reference" href="new-iter-concepts.rst">View document source</a>.
Generated on: 2003-12-02 13:08 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>
</html>