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

some edits based on comments from Howard Hinnant

Browse Source 
[SVN r20125]
This commit is contained in:
Jeremy Siek
2003-09-21 00:30:15 +00:00
parent 85873e924a
commit 1c41a7d0ec
2 changed files with 51 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@ -3,11 +3,11 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <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.0: http://docutils.sourceforge.net/" />
<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-14" /> <meta name="date" content="2003-09-20" />
<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" />
<link rel="stylesheet" href="default.css" type="text/css" /> <link rel="stylesheet" href="default.css" type="text/css" />
</head> </head>
@ -25,7 +25,7 @@
<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-14</td></tr> <td>2003-09-20</td></tr>
<tr class="field"><th class="docinfo-name">Number:</th><td class="field-body"><strong>This document is a revised version of the official</strong> N1477=03-0060</td> <tr class="field"><th class="docinfo-name">Number:</th><td class="field-body"><strong>This document is a revised version of the official</strong> N1477=03-0060</td>
</tr> </tr>
<tr><th class="docinfo-name">Copyright:</th> <tr><th class="docinfo-name">Copyright:</th>
@ -92,7 +92,7 @@ geared towards iterator traversal (hence the category names), while
requirements that address value access sneak in at various places. The requirements that address value access sneak in at various places. The
following table gives a summary of the current value access following table gives a summary of the current value access
requirements in the iterator categories.</p> requirements in the iterator categories.</p>
<table class="table" frame="border" rules="all"> <table border class="table">
<colgroup> <colgroup>
<col width="31%" /> <col width="31%" />
<col width="69%" /> <col width="69%" />
@ -121,9 +121,10 @@ categorized. For example, <tt class="literal"><span class="pre">vector&lt;bool&g
random access iterator, but the return type is not <tt class="literal"><span class="pre">bool&amp;</span></tt> (see random access iterator, but the return type is not <tt class="literal"><span class="pre">bool&amp;</span></tt> (see
<a class="reference" href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/lwg-active.html#96">issue 96</a> and Herb Sutter's paper J16/99-0008 = WG21 <a class="reference" href="http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/lwg-active.html#96">issue 96</a> and Herb Sutter's paper J16/99-0008 = WG21
N1185). Therefore, the iterators of <tt class="literal"><span class="pre">vector&lt;bool&gt;</span></tt> only meet the N1185). Therefore, the iterators of <tt class="literal"><span class="pre">vector&lt;bool&gt;</span></tt> only meet the
requirements of input iterator and output iterator. This is so requirements of input iterator and output iterator. This is so
nonintuitive that at least one implementation erroneously assigns nonintuitive that the C++ standard contradicts itself on this point.
<tt class="literal"><span class="pre">random_access_iterator_tag</span></tt> as its <tt class="literal"><span class="pre">iterator_category</span></tt>.</p> In paragraph 23.2.4/1 it says that a <tt class="literal"><span class="pre">vector</span></tt> is a sequence that
supports random access iterators.</p>
<p>Another difficult-to-categorize iterator is the transform iterator, an <p>Another difficult-to-categorize iterator is the transform iterator, an
adaptor which applies a unary function object to the dereferenced 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/utility/transform_iterator.htm">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>).
@ -218,11 +219,11 @@ Bidirectional Iterator (2) -&gt; Bidirectional Traversal Iterator and Writable I
<dd><tt class="literal"><span class="pre">stable_partition,</span> <span class="pre">inplace_merge</span></tt></dd> <dd><tt class="literal"><span class="pre">stable_partition,</span> <span class="pre">inplace_merge</span></tt></dd>
<dt>Bidirectional Iterator -&gt; Bidirectional Traversal Iterator and Readable Iterator</dt> <dt>Bidirectional Iterator -&gt; Bidirectional Traversal Iterator and Readable Iterator</dt>
<dd><tt class="literal"><span class="pre">reverse_copy</span></tt></dd> <dd><tt class="literal"><span class="pre">reverse_copy</span></tt></dd>
<dt>Random Access Iterator -&gt; Random Access Traversal Iterator and Readable and Swappable Iterator</dt> <dt>Random Access Iterator -&gt; Random Access Traversal Iterator and Readable and Writable Iterator</dt>
<dd><tt class="literal"><span class="pre">random_shuffle,</span> <span class="pre">sort,</span> <span class="pre">stable_sort,</span> <span class="pre">partial_sort,</span> <span class="pre">nth_element,</span> <span class="pre">push_heap,</span> <span class="pre">pop_heap</span> <dd><tt class="literal"><span class="pre">random_shuffle,</span> <span class="pre">sort,</span> <span class="pre">stable_sort,</span> <span class="pre">partial_sort,</span> <span class="pre">nth_element,</span> <span class="pre">push_heap,</span> <span class="pre">pop_heap</span>
<span class="pre">make_heap,</span> <span class="pre">sort_heap</span></tt></dd> <span class="pre">make_heap,</span> <span class="pre">sort_heap</span></tt></dd>
<dt>Input Iterator (2) -&gt; Incrementable Iterator and Readable Iterator</dt> <dt>Input Iterator (2) -&gt; Incrementable Iterator and Readable Iterator</dt>
<dd><tt class="literal"><span class="pre">equal</span></tt></dd> <dd><tt class="literal"><span class="pre">equal,</span> <span class="pre">mismatch</span></tt></dd>
<dt>Input Iterator (2) -&gt; Incrementable Iterator and Readable Iterator</dt> <dt>Input Iterator (2) -&gt; Incrementable Iterator and Readable Iterator</dt>
<dd><tt class="literal"><span class="pre">transform</span></tt></dd> <dd><tt class="literal"><span class="pre">transform</span></tt></dd>
</dl> </dl>
@ -266,11 +267,17 @@ given in the following diagram.</p>
<p><img alt="oldeqnew.png" src="oldeqnew.png" /></p> <p><img alt="oldeqnew.png" src="oldeqnew.png" /></p>
<p>Like the old iterator requirements, we provide tags for purposes of <p>Like the old iterator requirements, we provide tags for purposes of
dispatching. There are two hierarchies of tags, one for the access dispatching. There are two hierarchies of tags, one for the access
concepts and one for the traversal concepts. We provide an access concepts and one for the traversal concepts. The tags are related via
mechanism for mapping iterator types to these new tags. Our design inheritance so that a tag is convertible to another tag if the concept
reuses <tt class="literal"><span class="pre">iterator_traits&lt;Iter&gt;::iterator_category</span></tt> as the access associated with the first tag is a refinement of the second tag. We
mechanism. To enable this, a pair of access and traversal tags are use virtual inheritance of the diamonds in the current hierarchy, and
combined into a single type using the following <cite>iterator_tag</cite> class.</p> because of possible diamonds that could be created when programmers
define new iterator concepts and the corresponding tags.</p>
<p>We provide an access mechanism for mapping iterator types to the new
tags. Our design reuses <tt class="literal"><span class="pre">iterator_traits&lt;Iter&gt;::iterator_category</span></tt>
as the access mechanism. To enable this, a pair of access and
traversal tags are combined into a single type using the following
<cite>iterator_tag</cite> class.</p>
<pre class="literal-block"> <pre class="literal-block">
template &lt;class AccessTag, class TraversalTag&gt; template &lt;class AccessTag, class TraversalTag&gt;
struct iterator_tag : /* appropriate old category or categories */ struct iterator_tag : /* appropriate old category or categories */
@ -326,7 +333,7 @@ for the value type <tt class="literal"><span class="pre">T</span></tt> if the fo
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
member of type <tt class="literal"><span class="pre">T</span></tt>.</p> member of type <tt class="literal"><span class="pre">T</span></tt>.</p>
<blockquote> <blockquote>
<table class="table" frame="border" rules="all"> <table border class="table">
<colgroup> <colgroup>
<col width="34%" /> <col width="34%" />
<col width="30%" /> <col width="30%" />
@ -377,7 +384,7 @@ 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 in its documentation the <em>set of value types</em> that it allows for
output.</p> output.</p>
<blockquote> <blockquote>
<table class="table" frame="border" rules="all"> <table border class="table">
<colgroup> <colgroup>
<col width="42%" /> <col width="42%" />
<col width="27%" /> <col width="27%" />
@ -413,7 +420,7 @@ value types of <tt class="literal"><span class="pre">X</span></tt></td>
if the following expressions are valid and respect the stated if the following expressions are valid and respect the stated
semantics.</p> semantics.</p>
<blockquote> <blockquote>
<table class="table" frame="border" rules="all"> <table border class="table">
<colgroup> <colgroup>
<col width="38%" /> <col width="38%" />
<col width="14%" /> <col width="14%" />
@ -445,7 +452,7 @@ semantics.</p>
<p>The <em>Readable Lvalue Iterator</em> concept adds the requirement that the <p>The <em>Readable 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>
<blockquote> <blockquote>
<table class="table" frame="border" rules="all"> <table border class="table">
<colgroup> <colgroup>
<col width="35%" /> <col width="35%" />
<col width="32%" /> <col width="32%" />
@ -482,7 +489,7 @@ cv-qualification</td>
<tt class="literal"><span class="pre">reference</span></tt> type be a non-const reference to the value type of the <tt class="literal"><span class="pre">reference</span></tt> type be a non-const reference to the value type of the
iterator.</p> iterator.</p>
<blockquote> <blockquote>
<table class="table" frame="border" rules="all"> <table border class="table">
<colgroup> <colgroup>
<col width="45%" /> <col width="45%" />
<col width="55%" /> <col width="55%" />
@ -518,7 +525,7 @@ type <tt class="literal"><span class="pre">X</span></tt>, <tt class="literal"><s
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>
<blockquote> <blockquote>
<table class="table" frame="border" rules="all"> <table border class="table">
<colgroup> <colgroup>
<col width="27%" /> <col width="27%" />
<col width="38%" /> <col width="38%" />
@ -555,7 +562,7 @@ semantics.</p>
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>
<blockquote> <blockquote>
<table class="table" frame="border" rules="all"> <table border class="table">
<colgroup> <colgroup>
<col width="33%" /> <col width="33%" />
<col width="27%" /> <col width="27%" />
@ -600,7 +607,7 @@ its domain</td>
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>
<blockquote> <blockquote>
<table class="table" frame="border" rules="all"> <table border class="table">
<colgroup> <colgroup>
<col width="39%" /> <col width="39%" />
<col width="37%" /> <col width="37%" />
@ -646,7 +653,7 @@ the distance between iterators</td>
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>
<blockquote> <blockquote>
<table class="table" frame="border" rules="all"> <table border class="table">
<colgroup> <colgroup>
<col width="28%" /> <col width="28%" />
<col width="36%" /> <col width="36%" />
@ -690,7 +697,7 @@ the stated semantics. In the table below, <tt class="literal"><span class="pre"
<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 <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> constant object of type <tt class="literal"><span class="pre">Distance</span></tt>.</p>
<blockquote> <blockquote>
<table class="table" frame="border" rules="all"> <table border class="table">
<colgroup> <colgroup>
<col width="26%" /> <col width="26%" />
<col width="33%" /> <col width="33%" />
@ -874,8 +881,7 @@ inherit-category(access-tag, traversal-tag) =
convertible to one or more of: <tt class="literal"><span class="pre">readable_iterator_tag</span></tt>, convertible to one or more of: <tt class="literal"><span class="pre">readable_iterator_tag</span></tt>,
<tt class="literal"><span class="pre">writable_iterator_tag</span></tt>, <tt class="literal"><span class="pre">swappable_iterator_tag</span></tt>, or if the <tt class="literal"><span class="pre">writable_iterator_tag</span></tt>, <tt class="literal"><span class="pre">swappable_iterator_tag</span></tt>, or if the
argument for <tt class="literal"><span class="pre">TraversalTag</span></tt> is not convertible to argument for <tt class="literal"><span class="pre">TraversalTag</span></tt> is not convertible to
<tt class="literal"><span class="pre">incrementable_iterator_tag</span></tt> then the behavior of <tt class="literal"><span class="pre">iterator_tag</span></tt> <tt class="literal"><span class="pre">incrementable_iterator_tag</span></tt> then the programm is ill-formed.</p>
is not defined.</p>
<p>The <tt class="literal"><span class="pre">access_category</span></tt> and <tt class="literal"><span class="pre">traversal_category</span></tt> class templates are <p>The <tt class="literal"><span class="pre">access_category</span></tt> and <tt class="literal"><span class="pre">traversal_category</span></tt> class templates are
traits classes. For iterators whose traits classes. For iterators whose
<tt class="literal"><span class="pre">iterator_traits&lt;Iter&gt;::iterator_category</span></tt> type is <tt class="literal"><span class="pre">iterator_tag</span></tt>, <tt class="literal"><span class="pre">iterator_traits&lt;Iter&gt;::iterator_category</span></tt> type is <tt class="literal"><span class="pre">iterator_tag</span></tt>,

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

@ -65,9 +65,10 @@ categorized. For example, ``vector<bool>::iterator`` is almost a
random access iterator, but the return type is not ``bool&`` (see random access iterator, but the return type is not ``bool&`` (see
`issue 96`_ and Herb Sutter's paper J16/99-0008 = WG21 `issue 96`_ and Herb Sutter's paper J16/99-0008 = WG21
N1185). Therefore, the iterators of ``vector<bool>`` only meet the N1185). Therefore, the iterators of ``vector<bool>`` only meet the
requirements of input iterator and output iterator. This is so requirements of input iterator and output iterator. This is so
nonintuitive that at least one implementation erroneously assigns nonintuitive that the C++ standard contradicts itself on this point.
``random_access_iterator_tag`` as its ``iterator_category``. In paragraph 23.2.4/1 it says that a ``vector`` is a sequence that
supports random access iterators.
.. _issue 96: http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/lwg-active.html#96 .. _issue 96: http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/lwg-active.html#96
@ -188,12 +189,12 @@ Bidirectional Iterator -> Bidirectional Traversal Iterator and Readable Iterator
Bidirectional Iterator -> Bidirectional Traversal Iterator and Readable Iterator Bidirectional Iterator -> Bidirectional Traversal Iterator and Readable Iterator
``reverse_copy`` ``reverse_copy``
Random Access Iterator -> Random Access Traversal Iterator and Readable and Swappable Iterator 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 ``random_shuffle, sort, stable_sort, partial_sort, nth_element, push_heap, pop_heap
make_heap, sort_heap`` make_heap, sort_heap``
Input Iterator (2) -> Incrementable Iterator and Readable Iterator Input Iterator (2) -> Incrementable Iterator and Readable Iterator
``equal`` ``equal, mismatch``
Input Iterator (2) -> Incrementable Iterator and Readable Iterator Input Iterator (2) -> Incrementable Iterator and Readable Iterator
``transform`` ``transform``
@ -247,11 +248,18 @@ given in the following diagram.
Like the old iterator requirements, we provide tags for purposes of Like the old iterator requirements, we provide tags for purposes of
dispatching. There are two hierarchies of tags, one for the access dispatching. There are two hierarchies of tags, one for the access
concepts and one for the traversal concepts. We provide an access concepts and one for the traversal concepts. The tags are related via
mechanism for mapping iterator types to these new tags. Our design inheritance so that a tag is convertible to another tag if the concept
reuses ``iterator_traits<Iter>::iterator_category`` as the access associated with the first tag is a refinement of the second tag. We
mechanism. To enable this, a pair of access and traversal tags are use virtual inheritance of the diamonds in the current hierarchy, and
combined into a single type using the following `iterator_tag` class. because of possible diamonds that could be created when programmers
define new iterator concepts and the corresponding tags.
We provide an access mechanism for mapping iterator types to the new
tags. Our design reuses ``iterator_traits<Iter>::iterator_category``
as the access mechanism. To enable this, a pair of access and
traversal tags are combined into a single type using the following
`iterator_tag` class.
:: ::
@ -684,8 +692,7 @@ If the argument for the template parameter ``AccessTag`` is not
convertible to one or more of: ``readable_iterator_tag``, convertible to one or more of: ``readable_iterator_tag``,
``writable_iterator_tag``, ``swappable_iterator_tag``, or if the ``writable_iterator_tag``, ``swappable_iterator_tag``, or if the
argument for ``TraversalTag`` is not convertible to argument for ``TraversalTag`` is not convertible to
``incrementable_iterator_tag`` then the behavior of ``iterator_tag`` ``incrementable_iterator_tag`` then the programm is ill-formed.
is not defined.
The ``access_category`` and ``traversal_category`` class templates are The ``access_category`` and ``traversal_category`` class templates are
traits classes. For iterators whose traits classes. For iterators whose