From 1710c484b3a51700ed4678f6034b6cd7a8140882 Mon Sep 17 00:00:00 2001 From: Dave Abrahams Date: Mon, 22 Sep 2003 15:10:34 +0000 Subject: [PATCH] Table formatting tweaks for PDF/tex generation. Some minor editing for language improvements. [SVN r20151] --- doc/counting_iterator.html | 6 +- doc/facade-and-adaptor.html | 260 ++++++++++++++++--- doc/filter_iterator.html | 6 +- doc/function_output_iterator.html | 6 +- doc/index.html | 2 +- doc/indirect_iterator.html | 6 +- doc/iterator_adaptor.html | 6 +- doc/iterator_adaptor_ref.rst | 22 +- doc/iterator_facade.html | 6 +- doc/new-iter-concepts.html | 403 +++++++++++++++++++++++------- doc/new-iter-concepts.rst | 373 ++++++++++++++------------- doc/permutation_iterator.html | 6 +- doc/reverse_iterator.html | 6 +- 13 files changed, 782 insertions(+), 326 deletions(-) diff --git a/doc/counting_iterator.html b/doc/counting_iterator.html index 6fd0e36..c5390c2 100644 --- a/doc/counting_iterator.html +++ b/doc/counting_iterator.html @@ -7,7 +7,7 @@ Counting Iterator - + @@ -27,7 +27,7 @@ Lab, University of Hanover Institute for Transport Railway Operation and Construction Date: -2003-08-05 +2003-09-14 Copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved @@ -143,7 +143,7 @@ object copy constructed from x
View document source. -Generated on: 2003-09-14 02:16 UTC. +Generated on: 2003-09-21 09:34 UTC. Generated by Docutils from reStructuredText source.
diff --git a/doc/facade-and-adaptor.html b/doc/facade-and-adaptor.html index aa0cde4..747de28 100755 --- a/doc/facade-and-adaptor.html +++ b/doc/facade-and-adaptor.html @@ -7,9 +7,200 @@ Iterator Facade and Adaptor - + - +
@@ -21,13 +212,13 @@ Author: David Abrahams, Jeremy Siek, Thomas Witt Contact: -dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de +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: -2003-08-05 +2003-09-22 Number:This document is a revised version of the official N1476=03-0059 Copyright: @@ -965,11 +1156,12 @@ class iterator_adaptor expressions involving m_iterator in the specifications of those private member functions of iterator_adaptor that are not redefined by the Derived class and that are needed to model the -concept corresponding to the iterator_adaptor's category -typedef according to the requirements of iterator_facade. The -rest of the template parameters specify the types for the member -typedefs in iterator_facade. The following pseudo-code -specifies the traits types for iterator_adaptor.

+concept corresponding to +iterator_traits<Derived>::iterator_category according to the +requirements of iterator_facade. The rest of the template +parameters specify the types for the member typedefs in +iterator_facade. The following pseudo-code specifies the +traits types for iterator_adaptor.

 if (Value == use_default)
     value_type = iterator_traits<Base>::value_type;
@@ -994,12 +1186,17 @@ if (Category == use_default)
         access_category< Base >,
         traversal_category< Base >
     >
-else if (Category is an access tag)
+else if (Category is convertible to a standard access tag)
     iterator_category = iterator_tag<
         Category
-    ...
+    else if (Category has a nested traversal type)
+         if (reference is not a reference-to-const)
+             Category::access
+         else
+             if (Category
+        
 
-else if (Category is a traversal tag)
+else if (Category is convertable to a standard traversal tag)
     ...
 else
     iterator_category = Category;
@@ -1369,7 +1566,7 @@ then returns the result.

 

 
Class template transform_iterator

 
-template <class AdaptableUnaryFunction,
+template <class UnaryFunction,
           class Iterator, 
           class Reference = use_default, 
           class Value = use_default>
@@ -1379,45 +1576,44 @@ class transform_iterator
   friend class iterator_core_access;
 public:
   transform_iterator();
-  transform_iterator(Iterator const& x, AdaptableUnaryFunction f);
+  transform_iterator(Iterator const& x, UnaryFunction f);
 
   template<class OtherIterator, class R2, class V2>
   transform_iterator(
-        transform_iterator<AdaptableUnaryFunction, OtherIterator, R2, V2> const& t
+        transform_iterator<UnaryFunction, OtherIterator, R2, V2> const& t
       , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
   );
 
-  AdaptableUnaryFunction functor() const;
+  UnaryFunction functor() const;
 private:
   typename transform_iterator::value_type dereference() const;
-  AdaptableUnaryFunction m_f;
+  UnaryFunction m_f;
 };
 

 

 

 
transform_iterator requirements

-
The type AdaptableUnaryFunction must be Assignable, Copy
-Constructible, and the expression f(x) must be valid where f
-is an object of type AdaptableUnaryFunction, x is an object of
-type AdaptableUnaryFunction::argument_type, and where the type of
-f(x) must be AdaptableUnaryFunction::result_type.

+
The type UnaryFunction must be Assignable, Copy Constructible, and
+the expression f(*i) must be valid where f is an object of
+type UnaryFunction, i is an object of type Iterator, and
+where the type of f(*i) must be
+result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type.

 
The type Iterator must at least model Readable Iterator.  The
 resulting transform_iterator models the most refined of the
 following options that is also modeled by Iterator.

 

 
    
-
  • Writable Lvalue Iterator if the result_type of the
-AdaptableUnaryFunction is a non-const reference.
    • 
-
  • Readable Lvalue Iterator if the result_type is a const
+
  • Writable Lvalue Iterator if result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type is a non-const reference.
    • 
+
  • Readable Lvalue Iterator if result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type is a const
 reference.
    • 
 
  • Readable Iterator otherwise.
    • 
 

 

 
The transform_iterator models the most refined standard traversal
 concept that is modeled by Iterator.

-
The value_type of transform_iterator is
-remove_reference<result_type>::type. The reference type is
-result_type.

+
The reference type of transform_iterator is
+result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type.
+The value_type is remove_cv<remove_reference<reference> >::type.

 

 

 
transform_iterator public operations

@@ -1431,7 +1627,7 @@ and m_iterator default constru
 
 
 
-
transform_iterator(Iterator const& x, AdaptableUnaryFunction f);

+
transform_iterator(Iterator const& x, UnaryFunction f);

 @@ -1444,7 +1640,7 @@ initialized to f and 
 template<class OtherIterator, class R2, class V2>
 transform_iterator(
-      transform_iterator<AdaptableUnaryFunction, OtherIterator, R2, V2> const& t
+      transform_iterator<UnaryFunction, OtherIterator, R2, V2> const& t
     , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
 );
 
@@ -1458,7 +1654,7 @@ transform_iterator(
 
 
 

 
 


-
AdaptableUnaryFunction functor() const;

+
UnaryFunction functor() const;

 @@ -1847,7 +2043,7 @@ LocalWords:  OtherIncrementable Coplien -->
 

 View document source.
-Generated on: 2003-09-14 02:16 UTC.
+Generated on: 2003-09-22 14:17 UTC.
 Generated by Docutils from reStructuredText source.
 

diff --git a/doc/filter_iterator.html b/doc/filter_iterator.html
index 4133ae5..2afaf83 100644
--- a/doc/filter_iterator.html
+++ b/doc/filter_iterator.html
@@ -7,7 +7,7 @@
 Filter Iterator
-
+
@@ -27,7 +27,7 @@
 Lab, University of Hanover Institute for Transport
 Railway Operation and Construction
-
+
@@ -189,7 +189,7 @@ filter_iterator(
 

 View document source.
-Generated on: 2003-09-14 02:16 UTC.
+Generated on: 2003-09-21 09:34 UTC.
 Generated by Docutils from reStructuredText source.
 

diff --git a/doc/function_output_iterator.html b/doc/function_output_iterator.html
index 30d4559..90e2d2f 100644
--- a/doc/function_output_iterator.html
+++ b/doc/function_output_iterator.html
@@ -7,7 +7,7 @@
 Function Output Iterator
-
+
@@ -27,7 +27,7 @@
 Lab, University of Hanover Institute for Transport
 Railway Operation and Construction
-
+
@@ -158,7 +158,7 @@ return *this;
 

 View document source.
-Generated on: 2003-09-14 02:16 UTC.
+Generated on: 2003-09-21 09:34 UTC.
 Generated by Docutils from reStructuredText source.
 

diff --git a/doc/index.html b/doc/index.html
index 37421eb..3dfe4a0 100755
--- a/doc/index.html
+++ b/doc/index.html
@@ -181,7 +181,7 @@ LocalWords:  TraversalTag typename lvalues DWA Hmm JGS -->
 

 View document source.
-Generated on: 2003-09-14 02:16 UTC.
+Generated on: 2003-09-21 09:34 UTC.
 Generated by Docutils from reStructuredText source.
 

diff --git a/doc/indirect_iterator.html b/doc/indirect_iterator.html
index 9bbc80b..fafefb5 100644
--- a/doc/indirect_iterator.html
+++ b/doc/indirect_iterator.html
@@ -7,7 +7,7 @@
 Indirect Iterator
-
+
@@ -27,7 +27,7 @@
 Lab, University of Hanover Institute for Transport
 Railway Operation and Construction
-
+
@@ -162,7 +162,7 @@ indirect_iterator(
 

 View document source.
-Generated on: 2003-09-14 02:16 UTC.
+Generated on: 2003-09-21 09:34 UTC.
 Generated by Docutils from reStructuredText source.
 

diff --git a/doc/iterator_adaptor.html b/doc/iterator_adaptor.html
index d34598e..ec328a9 100644
--- a/doc/iterator_adaptor.html
+++ b/doc/iterator_adaptor.html
@@ -7,7 +7,7 @@
 Iterator Adaptor
-
+
@@ -27,7 +27,7 @@
 Lab, University of Hanover Institute for Transport
 Railway Operation and Construction
-
+
@@ -328,7 +328,7 @@ typename iterator_adaptor::difference_type distance_to(
 

 View document source.
-Generated on: 2003-09-14 02:16 UTC.
+Generated on: 2003-09-21 09:34 UTC.
 Generated by Docutils from reStructuredText source.
 

diff --git a/doc/iterator_adaptor_ref.rst b/doc/iterator_adaptor_ref.rst
index 69c6aa7..af910f5 100644
--- a/doc/iterator_adaptor_ref.rst
+++ b/doc/iterator_adaptor_ref.rst
@@ -51,11 +51,12 @@ The ``Derived`` template parameter must be a derived class of
 expressions involving ``m_iterator`` in the specifications of those
 private member functions of ``iterator_adaptor`` that are not
 redefined by the ``Derived`` class and that are needed to model the
-concept corresponding to the ``iterator_adaptor``\ 's ``category``
-typedef according to the requirements of ``iterator_facade``.  The
-rest of the template parameters specify the types for the member
-typedefs in ``iterator_facade``.  The following pseudo-code
-specifies the traits types for ``iterator_adaptor``.
+concept corresponding to
+``iterator_traits::iterator_category`` according to the
+requirements of ``iterator_facade``.  The rest of the template
+parameters specify the types for the member typedefs in
+``iterator_facade``.  The following pseudo-code specifies the
+traits types for ``iterator_adaptor``.
 
 ::
 
@@ -82,12 +83,17 @@ specifies the traits types for ``iterator_adaptor``.
             access_category< Base >,
             traversal_category< Base >
         >
-    else if (Category is an access tag)
+    else if (Category is convertible to a standard access tag)
         iterator_category = iterator_tag<
             Category
-        ...
+        else if (Category has a nested traversal type)
+             if (reference is not a reference-to-const)
+                 Category::access
+             else
+                 if (Category
+            
     
-    else if (Category is a traversal tag)
+    else if (Category is convertable to a standard traversal tag)
         ...
     else
         iterator_category = Category;
diff --git a/doc/iterator_facade.html b/doc/iterator_facade.html
index 84f7e25..af5d672 100644
--- a/doc/iterator_facade.html
+++ b/doc/iterator_facade.html
@@ -7,7 +7,7 @@
 Iterator Facade
 
 
-
+
 
 
 
@@ -27,7 +27,7 @@
 Lab, University of Hanover Institute for Transport
 Railway Operation and Construction
 
-
+
@@ -573,7 +573,7 @@ return tmp -= n;

 View document source.
-Generated on: 2003-09-14 02:16 UTC.
+Generated on: 2003-09-21 09:34 UTC.
 Generated by Docutils from reStructuredText source.
 

diff --git a/doc/new-iter-concepts.html b/doc/new-iter-concepts.html
index f7d1636..26c2651 100755
--- a/doc/new-iter-concepts.html
+++ b/doc/new-iter-concepts.html
@@ -3,13 +3,204 @@
 
-
+New Iterator Concepts
-
+

@@ -21,7 +212,7 @@
 

-
+
@@ -96,6 +287,10 @@ requirements in the iterator categories.

+
+
+
+
@@ -176,7 +371,9 @@ following lists the proposed changes to the type requirements of
 algorithms.
Forward Iterator -> Forward Traversal Iterator and Readable Iterator

-find_end, adjacent_find, search, search_n, rotate_copy, lower_bound, upper_bound, equal_range, binary_search, min_element, max_element

+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 (2) -> Forward Traversal Iterator and Readable Iterator

@@ -229,7 +426,7 @@ Bidirectional Iterator (2) -> Bidirectional Traversal Iterator and Writable I
 
 

 
Design

-
The iterator requirements are be separated into two hierarchies. One
+
The iterator requirements are to be separated into two hierarchies. One
 set of concepts handles the syntax and semantics of value access:

 
    
 
  • Readable Iterator
    • 
@@ -260,7 +457,7 @@ 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
    
-
    Like the old iterator requirements, we provide tags for purposes of
+
    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
 inheritance so that a tag is convertible to another tag if the concept
@@ -270,7 +467,7 @@ whether an iterator is an Lvalue Iterator by checking whether
 iterator_traits<Iterator>::reference is a real reference.
    
 
    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
+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.
    
 
    @@ -327,25 +524,25 @@ object of type T.
    
 for the value type T if the following expressions are valid and
 respect the stated semantics. U is the type of any specified
 member of type T.
    
-
    
 

 
 

 
 
 
 
 
 
 
 
Date:2003-08-05
2003-09-14

 
Copyright:
 Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved

 
 
 
 
 
 
 
 
 
Date:2003-08-05
2003-09-14

 
Copyright:
 Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved

 
 
 
 
 
 
 
 
 
 
 
Date:2003-08-05
2003-09-14

 
Copyright:
 Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved

 
 
 
 
 
 
 
 
 
Date:2003-08-05
2003-09-14

 
Copyright:
 Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved

 
 
 
Date:2003-08-05
2003-09-14

 
Copyright:
 Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved

 
 
 
 
 
 
 
 
 
 
 
 
 
 
Author:
 David Abrahams, Jeremy Siek, Thomas Witt

 
Contact:dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de
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:
 

 
 
Value Access Requirements in Existing Iterator Categories

 
 
Output Iterator
 *i = a
 
 
 
 
---+++
-
+
-
+
-
+
-
+
-
+

 






 
 
 
Readable Iterator Requirements (in addition to CopyConstructible)
 

 
Expression
 Return TypeAssertion/Note/Precondition/PostconditionNote/Precondition
 

 
 
 
iterator_traits<X>::value_type
 TAny non-reference, non-cv-qualified typeAny non-reference,
+non-cv-qualified type
 

 
iterator_traits<X>::reference
 Convertible to
@@ -353,22 +550,24 @@ member of type T.

 		 
 

 
is_readable<X>::typetruetypetrue_type
  
 

 
*a
 iterator_traits<X>::referencepre: a is dereferenceable. If a ==
-b then *a is equivalent to *bpre: a is
+dereferenceable. If a
+== b then *a is
+equivalent to *b
 

 
a->m
 U&pre: (*a).m is well-defined.
-Equivalent to (*a).mpre: (*a).m is
+well-defined.  Equivalent
+to (*a).m
 

 
 

-
 

 

 
Writable Iterators [lib.writable.iterators]

@@ -377,12 +576,11 @@ if the following expressions are valid and respect the stated
 semantics.  In addition, a model of Writable Iterator must include
 in its documentation the set of value types that it allows for
 output.

-

 ++--
@@ -405,19 +603,17 @@ value types of X

 


 


 
 
 
Writable Iterator Requirements (in addition to CopyConstructible)
 

 
 

-

 

 

 
Swappable Iterators [lib.swappable.iterators]

 
A class or built-in type X models the Swappable Iterator concept
 if the following expressions are valid and respect the stated
 semantics.

-

 ---+++
@@ -434,11 +630,11 @@ semantics.

-
+

 






 
 
 
Swappable Iterator Requirements (in addition to CopyConstructible)
 

 
iter_swap(a, b)
 voidpost: the pointed to values are exchangedthe pointed to values are
+exchanged
 

 
 

-

 

 
[Note: An iterator that is a model of the Readable and Writable Iterator concepts

 
is also a model of Swappable Iterator.  --end note]

@@ -448,12 +644,11 @@ semantics.

 
Lvalue Iterators [lib.lvalue.iterators]

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

-

 ---+++
@@ -473,7 +668,6 @@ cv-qualification

 






 
 
 
Lvalue Iterator Requirements
 

 
 

-
@@ -487,12 +681,11 @@ type X, A class or built-in type X models the Incrementable Iterator concept if the following expressions are valid and respect the stated semantics.

-
---+++ @@ -509,47 +702,56 @@ semantics.

- + - +
Incrementable Iterator Requirements (in addition to Assignable, Copy Constructible)
r++ X{ X tmp = r; ++r; return tmp; }
+{
+   X tmp = r;
+   ++r;
+   return tmp;
+}
+
+
traversal_category<X>::typeConvertible to incrementable_iterator_tagConvertible to +incrementable_iterator_tag  
-

Single Pass Iterators [lib.single.pass.iterators]

A class or built-in type X models the Single Pass Iterator concept if the following expressions are valid and respect the stated semantics.

-
+--+ - + - + - + - + @@ -562,19 +764,17 @@ its domain
Single Pass Iterator Requirements (in addition to Incrementable Iterator and Equality Comparable)
Single Pass Iterator Requirements (in addition to Incrementable Iterator and Equality +Comparable)
Expression Return TypeAssertion/Semantics/Pre-/Post-conditionAssertion/Semantics / +Pre-/Post-condition
++r X&pre: r is dereferenceable; post: -r is dereferenceable or r is -past-the-endpre: 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== is an equivalence +relation over its domain
a != b convertible to bool
-

Forward Traversal Iterators [lib.forward.traversal.iterators]

A class or built-in type X models the Forward Traversal Iterator concept if the following expressions are valid and respect the stated semantics.

-
+--+ @@ -587,14 +787,17 @@ semantics.

- + - +
Forward Traversal Iterator Requirements (in addition to Single Pass Iterator)
X u; X&note: u may have a -singular value.note: u may +have a singular +value.
++r X&r == s and r is -dereferenceable implies -++r == ++s.r == s and +r is +dereferenceable +implies ++r +== ++s.
iterator_traits<X>::difference_type A signed integral type representing @@ -608,40 +811,50 @@ the distance between iterators
-

Bidirectional Traversal Iterators [lib.bidirectional.traversal.iterators]

A class or built-in type X models the Bidirectional Traversal Iterator concept if the following expressions are valid and respect the stated semantics.

-
--++ - + - + - +
Bidirectional Traversal Iterator Requirements (in addition to Forward Traversal Iterator)
Expression Return TypeAssertion/Semantics/Pre-/Post-conditionAssertion/Semantics / +Pre-/Post-condition
--r X&pre: there exists s such that r -== ++s. post: s is -dereferenceable. --(++r) == r. ---r == --s implies r == s. &r -== &--r.pre: there exists +s such that r +== ++s. post: +s is +dereferenceable. +--(++r) == r. +--r == --s +implies r == +s. &r == &--r.
r-- convertible to const X&{ X tmp = r; --r; return tmp; }
+{
+  X tmp = r;
+  --r;
+  return tmp;
+}
+
+
traversal_category<X>::type Convertible to @@ -650,7 +863,6 @@ dereferenceable. --(++r)
-

Random Access Traversal Iterators [lib.random.access.traversal.iterators]

@@ -659,13 +871,12 @@ Iterator concept if the following expressions are valid and respect the stated semantics. In the table below, Distance is iterator_traits<X>::difference_type and n represents a constant object of type Distance.

-
--++-+ @@ -673,7 +884,8 @@ constant object of type Distance - + @@ -696,8 +908,8 @@ constant object of type Distance - + @@ -707,19 +919,19 @@ constant object of type Distance - + - - + + @@ -736,14 +948,14 @@ iterator - + - + @@ -763,7 +975,6 @@ relation
Random Access Traversal Iterator Requirements (in addition to Bidirectional Traversal Iterator)Expression Return Type Operational SemanticsAssertion/PreconditionAssertion/ +Precondition
a + n, n + a X{ X tmp = a; return -tmp += n; }{ X tmp = a; return tmp ++= n; }  
r -= n
a - n X{ X tmp = a; return -tmp -= n; }{ X tmp = a; return tmp +-= n; }  
b - a Distancea < b ? -distance(a,b) : --distance(b,a)pre: there exists a value -n of Distance such -that a + n == b. b == -a + (b - a).a < b ?  distance(a,b) +: -distance(b,a)pre: there exists a +value n of +Distance such that +a + n == b. b +== a + (b - a).
a[n] convertible to T
a < b convertible to bool b - a > 0< is a total ordering -relation< is a total +ordering relation
a > b convertible to bool b < a> is a total ordering -relation> is a total +ordering relation
a >= b convertible to bool
-
@@ -925,5 +1136,11 @@ LocalWords: TraversalTag typename lvalues DWA Hmm JGS --> +
+
+View document source. +Generated on: 2003-09-22 15:08 UTC. +Generated by Docutils from reStructuredText source. +
diff --git a/doc/new-iter-concepts.rst b/doc/new-iter-concepts.rst index ef9ecd9..fdde1cc 100644 --- a/doc/new-iter-concepts.rst +++ b/doc/new-iter-concepts.rst @@ -42,7 +42,9 @@ 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. -+------------------------+-----------------------------------------------------+ ++------------------------------------------------------------------------------+ +|Value Access Requirements in Existing Iterator Categories | ++========================+=====================================================+ |Output Iterator |``*i = a`` | +------------------------+-----------------------------------------------------+ |Input Iterator |``*i`` is convertible to ``T`` | @@ -138,7 +140,9 @@ algorithms. Forward Iterator -> Forward Traversal Iterator and Readable Iterator - ``find_end, adjacent_find, search, search_n, rotate_copy, lower_bound, upper_bound, equal_range, binary_search, min_element, max_element`` + ``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 (2) -> Forward Traversal Iterator and Readable Iterator @@ -203,7 +207,7 @@ Input Iterator (2) -> Incrementable Iterator and Readable Iterator Design ======== -The iterator requirements are be separated into two hierarchies. One +The iterator requirements are to be separated into two hierarchies. One set of concepts handles the syntax and semantics of value access: - Readable Iterator @@ -240,7 +244,7 @@ given in the following diagram. .. image:: oldeqnew.png -Like the old iterator requirements, we provide tags for purposes of +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 inheritance so that a tag is convertible to another tag if the concept @@ -252,7 +256,7 @@ whether an iterator is an Lvalue Iterator by checking whether 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 +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. @@ -325,24 +329,28 @@ for the value type ``T`` if the following expressions are valid and respect the stated semantics. ``U`` is the type of any specified member of type ``T``. - +-------------------------------------------------------------------------------------------------------------------+ - |Readable Iterator Requirements (in addition to CopyConstructible) | - +--------------------------------------+----------------------------------+-----------------------------------------+ - |Expression |Return Type |Assertion/Note/Precondition/Postcondition| - +======================================+==================================+=========================================+ - |``iterator_traits::value_type`` |``T`` |Any non-reference, non-cv-qualified type | - +--------------------------------------+----------------------------------+-----------------------------------------+ - |``iterator_traits::reference`` |Convertible to | | - | |``iterator_traits::value_type``| | - +--------------------------------------+----------------------------------+-----------------------------------------+ - |``is_readable::type`` |``truetype`` | | - +--------------------------------------+----------------------------------+-----------------------------------------+ - |``*a`` |``iterator_traits::reference`` |pre: ``a`` is dereferenceable. If ``a == | - | | |b`` then ``*a`` is equivalent to ``*b`` | - +--------------------------------------+----------------------------------+-----------------------------------------+ - |``a->m`` |``U&`` |pre: ``(*a).m`` is well-defined. | - | | |Equivalent to ``(*a).m`` | - +--------------------------------------+----------------------------------+-----------------------------------------+ ++-------------------------------------------------------------------------------------------------+ +|Readable Iterator Requirements (in addition to CopyConstructible) | ++-----------------------------------+-----------------------------------+-------------------------+ +|Expression |Return Type |Note/Precondition | ++===================================+===================================+=========================+ +|``iterator_traits::value_type`` |``T`` |Any non-reference, | +| | |non-cv-qualified type | ++-----------------------------------+-----------------------------------+-------------------------+ +|``iterator_traits::reference`` |Convertible to | | +| |``iterator_traits::value_type`` | | ++-----------------------------------+-----------------------------------+-------------------------+ +|``is_readable::type`` |``true_type`` | | ++-----------------------------------+-----------------------------------+-------------------------+ +|``*a`` |``iterator_traits::reference`` |pre: ``a`` is | +| | |dereferenceable. If ``a | +| | |== b`` then ``*a`` is | +| | |equivalent to ``*b`` | ++-----------------------------------+-----------------------------------+-------------------------+ +|``a->m`` |``U&`` |pre: ``(*a).m`` is | +| | |well-defined. Equivalent| +| | |to ``(*a).m`` | ++-----------------------------------+-----------------------------------+-------------------------+ .. _Writable Iterator: @@ -356,17 +364,17 @@ semantics. In addition, a model of *Writable Iterator* must include in its documentation the *set of value types* that it allows for output. - +---------------------------------------------------------------------------------------------+ - |Writable Iterator Requirements (in addition to CopyConstructible) | - +--------------------------------------+-------------------------+----------------------------+ - |Expression |Return Type |Precondition | - +======================================+=========================+============================+ - |``is_writable::type`` |``true_type`` | | - +--------------------------------------+-------------------------+----------------------------+ - |``*a = o`` | | pre: The type of ``o`` | - | | | is in the set of | - | | | value types of ``X`` | - +--------------------------------------+-------------------------+----------------------------+ ++---------------------------------------------------------------------+ +|Writable Iterator Requirements (in addition to CopyConstructible) | ++-------------------------+--------------+----------------------------+ +|Expression |Return Type |Precondition | ++=========================+==============+============================+ +|``is_writable::type`` |``true_type`` | | ++-------------------------+--------------+----------------------------+ +|``*a = o`` | | pre: The type of ``o`` | +| | | is in the set of | +| | | value types of ``X`` | ++-------------------------+--------------+----------------------------+ @@ -377,15 +385,16 @@ A class or built-in type ``X`` models the *Swappable Iterator* concept if the following expressions are valid and respect the stated semantics. - +------------------------------------------------------------------------------------------------+ - |Swappable Iterator Requirements (in addition to CopyConstructible) | - +------------------------------------+-------------+---------------------------------------------+ - |Expression |Return Type |Postcondition | - +====================================+=============+=============================================+ - |``is_swappable::type`` |``true_type``| | - +------------------------------------+-------------+---------------------------------------------+ - |``iter_swap(a, b)`` |``void`` |post: the pointed to values are exchanged | - +------------------------------------+-------------+---------------------------------------------+ ++---------------------------------------------------------------------+ +|Swappable Iterator Requirements (in addition to CopyConstructible) | ++-------------------------+-------------+-----------------------------+ +|Expression |Return Type |Postcondition | ++=========================+=============+=============================+ +|``is_swappable::type``|``true_type``| | ++-------------------------+-------------+-----------------------------+ +|``iter_swap(a, b)`` |``void`` |the pointed to values are | +| | |exchanged | ++-------------------------+-------------+-----------------------------+ [*Note:* An iterator that is a model of the *Readable* and *Writable Iterator* concepts is also a model of *Swappable Iterator*. *--end note*] @@ -397,16 +406,16 @@ Lvalue Iterators [lib.lvalue.iterators] The *Lvalue Iterator* concept adds the requirement that the ``reference`` type be a reference to the value type of the iterator. - +----------------------------------------------------------------------------------------------------------+ - | Lvalue Iterator Requirements | - +------------------------------------+---------------------------------+-----------------------------------+ - |Expression |Return Type |Assertion | - +====================================+=================================+===================================+ - |``iterator_traits::reference`` |``T&`` |``T`` is *cv* | - | | |``iterator_traits::value_type`` | - | | |where *cv* is an optional | - | | |cv-qualification | - +------------------------------------+---------------------------------+-----------------------------------+ ++---------------------------------------------------------------------------------+ +| Lvalue Iterator Requirements | ++---------------------------------+-----------+-----------------------------------+ +|Expression |Return Type|Assertion | ++=================================+===========+===================================+ +|``iterator_traits::reference``|``T&`` |``T`` is *cv* | +| | |``iterator_traits::value_type`` | +| | |where *cv* is an optional | +| | |cv-qualification | ++---------------------------------+-----------+-----------------------------------+ Iterator Traversal Concepts [lib.iterator.traversal] @@ -426,17 +435,25 @@ concept if the following expressions are valid and respect the stated semantics. - +-------------------------------------------------------------------------------------------------------------------------+ - |Incrementable Iterator Requirements (in addition to Assignable, Copy Constructible) | - +--------------------------------+---------------------------------------------+------------------------------------------+ - |Expression |Return Type |Assertion/Semantics | - +================================+=============================================+==========================================+ - |``++r`` |``X&`` |``&r == &++r`` | - +--------------------------------+---------------------------------------------+------------------------------------------+ - |``r++`` |``X`` |``{ X tmp = r; ++r; return tmp; }`` | - +--------------------------------+---------------------------------------------+------------------------------------------+ - |``traversal_category::type`` |Convertible to ``incrementable_iterator_tag``| | - +--------------------------------+---------------------------------------------+------------------------------------------+ ++-------------------------------------------------------------------------------------+ +|Incrementable Iterator Requirements (in addition to Assignable, Copy Constructible) | +| | ++--------------------------------+-------------------------------+--------------------+ +|Expression |Return Type |Assertion/Semantics | ++================================+===============================+====================+ +|``++r`` |``X&`` |``&r == &++r`` | ++--------------------------------+-------------------------------+--------------------+ +|``r++`` |``X`` |:: | +| | | | +| | | { | +| | | X tmp = r; | +| | | ++r; | +| | | return tmp; | +| | | } | ++--------------------------------+-------------------------------+--------------------+ +|``traversal_category::type`` |Convertible to | | +| |``incrementable_iterator_tag`` | | ++--------------------------------+-------------------------------+--------------------+ Single Pass Iterators [lib.single.pass.iterators] @@ -447,23 +464,26 @@ 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 |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)`` | - +----------------------------------+----------------------------+----------------------------------------+ - |``traversal_category::type`` |Convertible to | | - | |``single_pass_iterator_tag``| | - +----------------------------------+----------------------------+----------------------------------------+ ++------------------------------------------------------------------------------------------+ +|Single Pass Iterator Requirements (in addition to Incrementable Iterator and Equality | +|Comparable) | ++--------------------------------+-----------------------------+---------------------------+ +|Expression |Return Type |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)`` | ++--------------------------------+-----------------------------+---------------------------+ +|``traversal_category::type`` |Convertible to | | +| |``single_pass_iterator_tag`` | | ++--------------------------------+-----------------------------+---------------------------+ Forward Traversal Iterators [lib.forward.traversal.iterators] @@ -473,24 +493,28 @@ A class or built-in type ``X`` models the *Forward Traversal Iterator* concept if the following expressions are valid and respect the stated semantics. - +------------------------------------------------------------------------------------------------------+ - |Forward Traversal Iterator Requirements (in addition to Single Pass Iterator) | - +---------------------------------------+-------------------------------------+------------------------+ - |Expression |Return Type |Assertion/Note | - +=======================================+=====================================+========================+ - |``X u;`` |``X&`` |``note: u may have a | - | | |singular value.`` | - +---------------------------------------+-------------------------------------+------------------------+ - |``++r`` |``X&`` |``r == s`` and ``r`` is | - | | |dereferenceable implies | - | | |``++r == ++s.`` | - +---------------------------------------+-------------------------------------+------------------------+ - |``iterator_traits::difference_type``|A signed integral type representing | | - | |the distance between iterators | | - +---------------------------------------+-------------------------------------+------------------------+ - |``traversal_category::type`` |Convertible to | | - | |``forward_traversal_iterator_tag`` | | - +---------------------------------------+-------------------------------------+------------------------+ ++-------------------------------------------------------------------------------------------+ +|Forward Traversal Iterator Requirements (in addition to Single Pass Iterator) | ++---------------------------------------+-----------------------------------+---------------+ +|Expression |Return Type |Assertion/Note | ++=======================================+===================================+===============+ +|``X u;`` |``X&`` |note: ``u`` may| +| | |have a singular| +| | |value. | ++---------------------------------------+-----------------------------------+---------------+ +|``++r`` |``X&`` |``r == s`` and | +| | |``r`` is | +| | |dereferenceable| +| | |implies ``++r | +| | |== ++s.`` | ++---------------------------------------+-----------------------------------+---------------+ +|``iterator_traits::difference_type``|A signed integral type representing| | +| |the distance between iterators | | +| | | | ++---------------------------------------+-----------------------------------+---------------+ +|``traversal_category::type`` |Convertible to | | +| |``forward_traversal_iterator_tag`` | | ++---------------------------------------+-----------------------------------+---------------+ Bidirectional Traversal Iterators [lib.bidirectional.traversal.iterators] @@ -500,25 +524,34 @@ A class or built-in type ``X`` models the *Bidirectional Traversal Iterator* concept if the following expressions are valid and respect the stated semantics. - +----------------------------------------------------------------------------------------------------------------+ - |Bidirectional Traversal Iterator Requirements (in addition to Forward Traversal Iterator) | - +-------------------------------+----------------------------------------+---------------------------------------+ - |Expression |Return Type |Assertion/Semantics/Pre-/Post-condition| - +===============================+========================================+=======================================+ - |``--r`` |``X&`` |pre: there exists ``s`` such that ``r | - | | |== ++s``. post: ``s`` is | - | | |dereferenceable. ``--(++r) == r``. | - | | |``--r == --s`` implies ``r == s``. ``&r| - | | |== &--r``. | - +-------------------------------+----------------------------------------+---------------------------------------+ - |``r--`` |convertible to ``const X&`` |``{ X tmp = r; --r; return tmp; }`` | - | | | | - | | | | - +-------------------------------+----------------------------------------+---------------------------------------+ - |``traversal_category::type``|Convertible to | | - | |``bidirectional_traversal_iterator_tag``| | - | | | | - +-------------------------------+----------------------------------------+---------------------------------------+ ++--------------------------------------------------------------------------------------------------------+ +|Bidirectional Traversal Iterator Requirements (in addition to Forward Traversal Iterator) | ++------------------------------------+---------------------------------------------+---------------------+ +|Expression |Return Type |Assertion/Semantics /| +| | |Pre-/Post-condition | ++====================================+=============================================+=====================+ +|``--r`` |``X&`` |pre: there exists | +| | |``s`` such that ``r | +| | |== ++s``. post: | +| | |``s`` is | +| | |dereferenceable. | +| | |``--(++r) == r``. | +| | |``--r == --s`` | +| | |implies ``r == | +| | |s``. ``&r == &--r``. | ++------------------------------------+---------------------------------------------+---------------------+ +|``r--`` |convertible to ``const X&`` |:: | +| | | | +| | | { | +| | | X tmp = r; | +| | | --r; | +| | | return tmp; | +| | | } | ++------------------------------------+---------------------------------------------+---------------------+ +|``traversal_category::type`` |Convertible to | | +| |``bidirectional_traversal_iterator_tag`` | | +| | | | ++------------------------------------+---------------------------------------------+---------------------+ Random Access Traversal Iterators [lib.random.access.traversal.iterators] @@ -530,56 +563,60 @@ the stated semantics. In the table below, ``Distance`` is ``iterator_traits::difference_type`` and ``n`` represents a constant object of type ``Distance``. - +------------------------------------------------------------------------------------------------------------------------------+ - |Random Access Traversal Iterator Requirements (in addition to Bidirectional Traversal Iterator) | - +--------------------------------+----------------------------------------+----------------------+-----------------------------+ - | Expression |Return Type | Operational Semantics| Assertion/Precondition | - +================================+========================================+======================+=============================+ - |``r += n`` |``X&`` |:: | | - | | | | | - | | | { | | - | | | Distance m = n; | | - | | | if (m >= 0) | | - | | | while (m--) | | - | | | ++r; | | - | | | else | | - | | | while (m++) | | - | | | --r; | | - | | | return r; | | - | | | } | | - +--------------------------------+----------------------------------------+----------------------+-----------------------------+ - | ``a + n``, ``n + a`` |``X`` |``{ X tmp = a; return | | - | | |tmp += n; }`` | | - +--------------------------------+----------------------------------------+----------------------+-----------------------------+ - |``r -= n`` |``X&`` |``return r += -n`` | | - +--------------------------------+----------------------------------------+----------------------+-----------------------------+ - |``a - n`` |``X`` |``{ X tmp = a; return | | - | | |tmp -= n; }`` | | - +--------------------------------+----------------------------------------+----------------------+-----------------------------+ - |``b - a`` |``Distance`` |``a < b ? |pre: there exists a value | - | | |distance(a,b) : |``n`` of ``Distance`` such | - | | |-distance(b,a)`` |that ``a + n == b``. ``b == | - | | | |a + (b - a)``. | - +--------------------------------+----------------------------------------+----------------------+-----------------------------+ - |``a[n]`` |convertible to T |``*(a + n)`` |pre: a is a `readable | - | | | |iterator`_ | - +--------------------------------+----------------------------------------+----------------------+-----------------------------+ - |``a[n] = v`` |convertible to T |``*(a + n) = v`` |pre: a is a `writable | - | | | |iterator`_ | - +--------------------------------+----------------------------------------+----------------------+-----------------------------+ - |``a < b`` |convertible to ``bool`` |``b - a > 0`` |``<`` is a total ordering | - | | | |relation | - +--------------------------------+----------------------------------------+----------------------+-----------------------------+ - |``a > b`` |convertible to ``bool`` |``b < a`` |``>`` is a total ordering | - | | | |relation | - +--------------------------------+----------------------------------------+----------------------+-----------------------------+ - |``a >= b`` |convertible to ``bool`` |``!(a < b)`` | | - +--------------------------------+----------------------------------------+----------------------+-----------------------------+ - |``a <= b`` |convertible to ``bool`` |``!(a > b)`` | | - +--------------------------------+----------------------------------------+----------------------+-----------------------------+ - |``traversal_category::type`` |Convertible to | | | - | |``random_access_traversal_iterator_tag``| | | - +--------------------------------+----------------------------------------+----------------------+-----------------------------+ ++----------------------------------------------------------------------------------------------------------------------------------------------+ +|Random Access Traversal Iterator Requirements (in addition to Bidirectional Traversal Iterator) | ++-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +|Expression |Return Type |Operational Semantics |Assertion/ | +| | | |Precondition | ++===========================================+=================================================+=========================+======================+ +|``r += n`` |``X&`` |:: | | +| | | | | +| | | { | | +| | | Distance m = n; | | +| | | if (m >= 0) | | +| | | while (m--) | | +| | | ++r; | | +| | | else | | +| | | while (m++) | | +| | | --r; | | +| | | return r; | | +| | | } | | ++-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +|``a + n``, ``n + a`` |``X`` |``{ X tmp = a; return tmp| | +| | |+= n; }`` | | +| | | | | ++-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +|``r -= n`` |``X&`` |``return r += -n`` | | ++-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +|``a - n`` |``X`` |``{ X tmp = a; return tmp| | +| | |-= n; }`` | | +| | | | | ++-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +|``b - a`` |``Distance`` |``a < b ? distance(a,b) |pre: there exists a | +| | |: -distance(b,a)`` |value ``n`` of | +| | | |``Distance`` such that| +| | | |``a + n == b``. ``b | +| | | |== a + (b - a)``. | ++-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +|``a[n]`` |convertible to T |``*(a + n)`` |pre: a is a `readable | +| | | |iterator`_ | ++-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +|``a[n] = v`` |convertible to T |``*(a + n) = v`` |pre: a is a `writable | +| | | |iterator`_ | ++-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +|``a < b`` |convertible to ``bool`` |``b - a > 0`` |``<`` is a total | +| | | |ordering relation | ++-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +|``a > b`` |convertible to ``bool`` |``b < a`` |``>`` is a total | +| | | |ordering relation | ++-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +|``a >= b`` |convertible to ``bool`` |``!(a < b)`` | | ++-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +|``a <= b`` |convertible to ``bool`` |``!(a > b)`` | | ++-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +|``traversal_category::type`` |Convertible to | | | +| |``random_access_traversal_iterator_tag`` | | | ++-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ diff --git a/doc/permutation_iterator.html b/doc/permutation_iterator.html index 4549786..bfa30dd 100644 --- a/doc/permutation_iterator.html +++ b/doc/permutation_iterator.html @@ -7,7 +7,7 @@ Permutation Iterator - + @@ -26,7 +26,7 @@ Boost Consulting, Indiana University Open Systems Lab Date: -2003-08-05 +2003-09-14 Copyright: Copyright Toon Knapen, David Abrahams, Roland Richter, and Jeremy Siek 2003. All rights reserved @@ -121,7 +121,7 @@ ForwardIterator instead of amortized constant time.

View document source. -Generated on: 2003-09-14 02:16 UTC. +Generated on: 2003-09-21 09:35 UTC. Generated by Docutils from reStructuredText source.
diff --git a/doc/reverse_iterator.html b/doc/reverse_iterator.html index 3aba842..ac3ceaf 100644 --- a/doc/reverse_iterator.html +++ b/doc/reverse_iterator.html @@ -7,7 +7,7 @@ Reverse Iterator - + @@ -27,7 +27,7 @@ Lab, University of Hanover Institute for Transport Railway Operation and Construction Date: -2003-08-05 +2003-09-14 Copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved @@ -136,7 +136,7 @@ reverse_iterator(
View document source. -Generated on: 2003-09-14 02:16 UTC. +Generated on: 2003-09-21 09:35 UTC. Generated by Docutils from reStructuredText source.