From 9ac583096c540110c0fa488981e00ab5fe1f9e96 Mon Sep 17 00:00:00 2001 From: Jeremy Siek Date: Mon, 22 Sep 2003 15:45:58 +0000 Subject: [PATCH] added the paper number and resolved some conflicts [SVN r20152] --- doc/new-iter-concepts.html | 261 +++++-------------------------------- doc/new-iter-concepts.rst | 57 ++++---- 2 files changed, 68 insertions(+), 250 deletions(-) diff --git a/doc/new-iter-concepts.html b/doc/new-iter-concepts.html index 26c2651..8a1e639 100755 --- a/doc/new-iter-concepts.html +++ b/doc/new-iter-concepts.html @@ -3,204 +3,13 @@ - + New Iterator Concepts - +
@@ -217,7 +26,7 @@ ul.auto-toc { Boost Consulting, Indiana University Open Systems Lab, University of Hanover Institute for Transport Railway Operation and Construction Date: 2003-09-22 -Number:This document is a revised version of the official N1477=03-0060 +Number:N1531=03-0114 Copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved @@ -232,7 +41,7 @@ access and positioning independently. This allows the concepts to more closely match the requirements of algorithms and provides better categorizations of iterators that are used in practice. This proposal -is a revision of paper n1297. +is a revision of paper n1297 and n1477. @@ -374,7 +183,7 @@ algorithms.

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 (1) -> Single Pass Iterator and Readable Iterator, Forward Iterator (2) -> Forward Traversal Iterator and Readable Iterator

find_first_of
@@ -387,7 +196,7 @@ Forward Iterator (2) -> Forward Traversal Iterator and Readable Iterator

Forward Iterator -> Forward Traversal Iterator and Swappable Iterator

rotate
-

Forward Iterator (1) -> Swappable Iterator and Single Pass Iterator +

Forward Iterator (1) -> Swappable Iterator and Single Pass Iterator, Forward Iterator (2) -> Swappable Iterator and Incrementable Iterator

swap_ranges
@@ -457,30 +266,31 @@ matches with the original input and output iterator requirements.

The relationship between the new iterator concepts and the old are given in the following diagram.

oldeqnew.png

-

As in the existing library, we provide tags for purposes of -dispatching. There are two hierarchies of tags, one for the access -concepts and one for the traversal concepts. The tags are related via +

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. -There is not a tag for Lvalue Iterator because one can easily deduce -whether an iterator is an Lvalue Iterator by checking whether -iterator_traits<Iterator>::reference is a real reference.

+Since the access concepts are not related via refinment, but instead +cover orthogonal issues, we do not use tags for the access concepts, +but instead use the equivalent of a bitfield.

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 that end, a pair of access and -traversal tags are combined into a single type using the following -iterator_tag class.

+traversal tags and access bitfield. Our design reuses +iterator_traits<Iter>::iterator_category as the access +mechanism. To that end, a pair of access and traversal tags are +combined into a single type using the following iterator_tag class.

-template <class AccessTag, class Reference, class TraversalTag>
-struct iterator_tag : /* appropriate old category or categories */
-{
-  typedef AccessTag access;
+enum iterator_access { readable_iterator = 1, writable_iterator = 2, 
+    swappable_iterator = 4, lvalue_iterator = 8 };
+
+template <iterator_access x, class TraversalTag>
+struct iterator_tag : /* appropriate old category or categories */ {
+  static const iterator_access access = x;
   typedef TraversalTag traversal;
 };
 

The iterator_tag class template is derived from the appropriate iterator tag or tags from the old requirements based on the new-style -tags passed as template parameters. The algorithm for determining the +tags passed as template parameters. The algorithm for determining the old tag or tags from the new tags picks the least-refined old concepts that include all of the requirements of the access and traversal concepts (that is, the closest fit), if any such category exists. For @@ -488,15 +298,22 @@ example, a the category tag for a Readable Single Pass Iterator will always be derived from input_iterator_tag, while the category tag for a Single Pass Iterator that is both Readable and Writable will be derived from both input_iterator_tag and output_iterator_tag.

-

We also provide two helper classes that make it convenient to obtain -the access and traversal tags of an iterator. These helper classes -work both for iterators whose iterator_category is +

We also provide several helper classes that make it convenient to +obtain the access and traversal characteristics of an iterator. These +helper classes work both for iterators whose iterator_category is iterator_tag and also for iterators using the original iterator categories.

-
-template <class Iterator> struct access_category { typedef ... type; };
-template <class Iterator> struct traversal_category { typedef ... type; };
-
+
+
::
+

template <class Iterator> struct is_readable { typedef ... type; }; +template <class Iterator> struct is_writable { typedef ... type; }; +template <class Iterator> struct is_swappable { typedef ... type; }; +template <class Iterator> struct traversal_category { typedef ... type; };

+
+
+

We do not include a helper class is_lvalue_iterator because that +can easily be deduced by checking whether +iterator_traits<Iterator>::reference is a real reference.

The most difficult design decision concerned the operator[]. The direct approach for specifying operator[] would have a return type of reference; the same as operator*. However, going in this @@ -1136,11 +953,5 @@ LocalWords: TraversalTag typename lvalues DWA Hmm JGS -->

- - diff --git a/doc/new-iter-concepts.rst b/doc/new-iter-concepts.rst index fdde1cc..90ea9b8 100644 --- a/doc/new-iter-concepts.rst +++ b/doc/new-iter-concepts.rst @@ -6,7 +6,7 @@ :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`_ :date: $Date$ -:Number: **This document is a revised version of the official** N1477=03-0060 +:Number: N1531=03-0114 :copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved .. _`Boost Consulting`: http://www.boost-consulting.com @@ -18,11 +18,12 @@ concepts to more closely match the requirements of algorithms and provides better categorizations of iterators that are used in practice. This proposal - is a revision of paper n1297_. + is a revision of paper n1297_ and n1477_. .. contents:: Table of Contents .. _n1297: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2001/n1297.html +.. _n1477: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1477.html ============ Motivation @@ -144,7 +145,7 @@ Forward Iterator -> Forward Traversal Iterator and Readable Iterator lower_bound, upper_bound, equal_range, binary_search, min_element, max_element`` -Forward Iterator (1) -> Single Pass Iterator and Readable Iterator +Forward Iterator (1) -> Single Pass Iterator and Readable Iterator, Forward Iterator (2) -> Forward Traversal Iterator and Readable Iterator ``find_first_of`` @@ -161,7 +162,7 @@ Forward Iterator -> Forward Traversal Iterator and Swappable Iterator ``rotate`` -Forward Iterator (1) -> Swappable Iterator and Single Pass Iterator +Forward Iterator (1) -> Swappable Iterator and Single Pass Iterator, Forward Iterator (2) -> Swappable Iterator and Incrementable Iterator ``swap_ranges`` @@ -244,34 +245,34 @@ given in the following diagram. .. image:: oldeqnew.png -As in the existing library, we provide tags for purposes of -dispatching. There are two hierarchies of tags, one for the access -concepts and one for the traversal concepts. The tags are related via +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. -There is not a tag for Lvalue Iterator because one can easily deduce -whether an iterator is an Lvalue Iterator by checking whether -``iterator_traits::reference`` is a real reference. - +Since the access concepts are not related via refinment, but instead +cover orthogonal issues, we do not use tags for the access concepts, +but instead use the equivalent of a bitfield. We provide an access mechanism for mapping iterator types to the new -tags. Our design reuses ``iterator_traits::iterator_category`` -as the access mechanism. To that end, a pair of access and -traversal tags are combined into a single type using the following -`iterator_tag` class. +traversal tags and access bitfield. Our design reuses +``iterator_traits::iterator_category`` as the access +mechanism. To that end, a pair of access and traversal tags are +combined into a single type using the following `iterator_tag` class. :: - template - struct iterator_tag : /* appropriate old category or categories */ - { - typedef AccessTag access; + enum iterator_access { readable_iterator = 1, writable_iterator = 2, + swappable_iterator = 4, lvalue_iterator = 8 }; + + template + struct iterator_tag : /* appropriate old category or categories */ { + static const iterator_access access = x; typedef TraversalTag traversal; }; The ``iterator_tag`` class template is derived from the appropriate iterator tag or tags from the old requirements based on the new-style -tags passed as template parameters. The algorithm for determining the +tags passed as template parameters. The algorithm for determining the old tag or tags from the new tags picks the least-refined old concepts that include all of the requirements of the access and traversal concepts (that is, the closest fit), if any such category exists. For @@ -280,18 +281,24 @@ always be derived from ``input_iterator_tag``, while the category tag for a Single Pass Iterator that is both Readable and Writable will be derived from both ``input_iterator_tag`` and ``output_iterator_tag``. -We also provide two helper classes that make it convenient to obtain -the access and traversal tags of an iterator. These helper classes -work both for iterators whose ``iterator_category`` is +We also provide several helper classes that make it convenient to +obtain the access and traversal characteristics of an iterator. These +helper classes work both for iterators whose ``iterator_category`` is ``iterator_tag`` and also for iterators using the original iterator categories. :: - - template struct access_category { typedef ... type; }; + template struct is_readable { typedef ... type; }; + template struct is_writable { typedef ... type; }; + template struct is_swappable { typedef ... type; }; template struct traversal_category { typedef ... type; }; +We do not include a helper class ``is_lvalue_iterator`` because that +can easily be deduced by checking whether +``iterator_traits::reference`` is a real reference. + + The most difficult design decision concerned the ``operator[]``. The direct approach for specifying ``operator[]`` would have a return type of ``reference``; the same as ``operator*``. However, going in this