From 1c41a7d0ec94c1cdc7f8e57392e4424494ca4286 Mon Sep 17 00:00:00 2001 From: Jeremy Siek Date: Sun, 21 Sep 2003 00:30:15 +0000 Subject: [PATCH] some edits based on comments from Howard Hinnant [SVN r20125] --- doc/new-iter-concepts.html | 58 +++++++++++++++++++++----------------- doc/new-iter-concepts.rst | 31 ++++++++++++-------- 2 files changed, 51 insertions(+), 38 deletions(-) diff --git a/doc/new-iter-concepts.html b/doc/new-iter-concepts.html index 2bcf044..0df8278 100755 --- a/doc/new-iter-concepts.html +++ b/doc/new-iter-concepts.html @@ -3,11 +3,11 @@ - + New Iterator Concepts - + @@ -25,7 +25,7 @@ Organization: Boost Consulting, Indiana University Open Systems Lab, University of Hanover Institute for Transport Railway Operation and Construction Date: -2003-09-14 +2003-09-20 Number:This document is a revised version of the official N1477=03-0060 Copyright: @@ -92,7 +92,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.

- +
@@ -121,9 +121,10 @@ categorized. For example, vector<bool&g random access iterator, but the return type is not bool& (see issue 96 and Herb Sutter's paper J16/99-0008 = WG21 N1185). Therefore, the iterators of vector<bool> only meet the -requirements of input iterator and output iterator. This is so -nonintuitive that at least one implementation erroneously assigns -random_access_iterator_tag as its iterator_category.

+requirements of input iterator and output iterator. This is so +nonintuitive that the C++ standard contradicts itself on this point. +In paragraph 23.2.4/1 it says that a vector is a sequence that +supports random access iterators.

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 transform_iterator). @@ -218,11 +219,11 @@ Bidirectional Iterator (2) -> Bidirectional Traversal Iterator and Writable I

stable_partition, inplace_merge
Bidirectional Iterator -> Bidirectional Traversal Iterator and Readable Iterator
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 make_heap, sort_heap
Input Iterator (2) -> Incrementable Iterator and Readable Iterator
-
equal
+
equal, mismatch
Input Iterator (2) -> Incrementable Iterator and Readable Iterator
transform
@@ -266,11 +267,17 @@ given in the following diagram.

oldeqnew.png

Like the old iterator requirements, we provide tags for purposes of dispatching. There are two hierarchies of tags, one for the access -concepts and one for the traversal concepts. We provide an access -mechanism for mapping iterator types to these 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.

+concepts and one for 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. We +use virtual inheritance of the diamonds in the current hierarchy, and +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.

 template <class AccessTag, class TraversalTag>
 struct iterator_tag : /* appropriate old category or categories */
@@ -326,7 +333,7 @@ for the value type T if the fo
 respect the stated semantics. U is the type of any specified
 member of type T.

 

-
+
@@ -377,7 +384,7 @@ semantics. In addition, a model of Writable Iterator must include in its documentation the set of value types that it allows for output.

-
+
@@ -413,7 +420,7 @@ value types of X if the following expressions are valid and respect the stated semantics.

-
+
@@ -445,7 +452,7 @@ semantics.

The Readable Lvalue Iterator concept adds the requirement that the reference type be a reference to the value type of the iterator.

-
+
@@ -482,7 +489,7 @@ cv-qualification reference type be a non-const reference to the value type of the iterator.

-
+
@@ -518,7 +525,7 @@ type X,
-
+
@@ -555,7 +562,7 @@ semantics.

concept if the following expressions are valid and respect the stated semantics.

-
+
@@ -600,7 +607,7 @@ its domain concept if the following expressions are valid and respect the stated semantics.

-
+
@@ -646,7 +653,7 @@ the distance between iterators Iterator concept if the following expressions are valid and respect the stated semantics.

-
+
@@ -690,7 +697,7 @@ the stated semantics. In the table below, iterator_traits<X>::difference_type and n represents a constant object of type Distance.

-
+
@@ -874,8 +881,7 @@ inherit-category(access-tag, traversal-tag) = convertible to one or more of: readable_iterator_tag, writable_iterator_tag, swappable_iterator_tag, or if the argument for TraversalTag is not convertible to -incrementable_iterator_tag then the behavior of iterator_tag -is not defined.

+incrementable_iterator_tag then the programm is ill-formed.

The access_category and traversal_category class templates are traits classes. For iterators whose iterator_traits<Iter>::iterator_category type is iterator_tag, diff --git a/doc/new-iter-concepts.rst b/doc/new-iter-concepts.rst index e721c3a..8a6a293 100644 --- a/doc/new-iter-concepts.rst +++ b/doc/new-iter-concepts.rst @@ -65,9 +65,10 @@ categorized. For example, ``vector::iterator`` is almost a random access iterator, but the return type is not ``bool&`` (see `issue 96`_ and Herb Sutter's paper J16/99-0008 = WG21 N1185). Therefore, the iterators of ``vector`` only meet the -requirements of input iterator and output iterator. This is so -nonintuitive that at least one implementation erroneously assigns -``random_access_iterator_tag`` as its ``iterator_category``. +requirements of input iterator and output iterator. This is so +nonintuitive that the C++ standard contradicts itself on this point. +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 @@ -188,12 +189,12 @@ Bidirectional Iterator -> Bidirectional Traversal Iterator and Readable Iterator Bidirectional Iterator -> Bidirectional Traversal Iterator and Readable Iterator ``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 make_heap, sort_heap`` Input Iterator (2) -> Incrementable Iterator and Readable Iterator - ``equal`` + ``equal, mismatch`` Input Iterator (2) -> Incrementable Iterator and Readable Iterator ``transform`` @@ -247,11 +248,18 @@ given in the following diagram. Like the old iterator requirements, we provide tags for purposes of dispatching. There are two hierarchies of tags, one for the access -concepts and one for the traversal concepts. We provide an access -mechanism for mapping iterator types to these new tags. Our design -reuses ``iterator_traits::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. +concepts and one for 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. We +use virtual inheritance of the diamonds in the current hierarchy, and +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::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``, ``writable_iterator_tag``, ``swappable_iterator_tag``, or if the argument for ``TraversalTag`` is not convertible to -``incrementable_iterator_tag`` then the behavior of ``iterator_tag`` -is not defined. +``incrementable_iterator_tag`` then the programm is ill-formed. The ``access_category`` and ``traversal_category`` class templates are traits classes. For iterators whose