From d2dae622151b983d668261752c1407420591703f Mon Sep 17 00:00:00 2001 From: Jeremy Siek Date: Tue, 13 Jan 2004 21:00:31 +0000 Subject: [PATCH] removed same diff type req from Interoperator and did some work on permutation iterator [SVN r21705] --- doc/new-iter-concepts.html | 22 +++--- doc/new-iter-concepts.rst | 24 +++--- doc/permutation_iterator.html | 129 ++++++++++++++++++++++++------- doc/permutation_iterator_ref.rst | 95 +++++++++++++++++------ 4 files changed, 195 insertions(+), 75 deletions(-) diff --git a/doc/new-iter-concepts.html b/doc/new-iter-concepts.html index a664d40..2655663 100755 --- a/doc/new-iter-concepts.html +++ b/doc/new-iter-concepts.html @@ -827,11 +827,11 @@ random_access_traversal_tag for consistency -->

Interoperable Iterators [lib.interoperable.iterators]

A class or built-in type X that models Single Pass Iterator is interoperable with a class or built-in type Y that also models -Single Pass Iterator if both X and Y have the same difference -type and traversal tag and if the following expressions are valid and -respect the stated semantics. In the tables below, x is an object -of type X, y is an object of type Y, Distance is -iterator_traits<X>::difference_type, and n represents a +Single Pass Iterator if both X and Y have the same traversal +tag and if the following expressions are valid and respect the stated +semantics. In the tables below, x is an object of type X, +y is an object of type Y, Distance is +iterator_traits<Y>::difference_type, and n represents a constant object of type Distance.

If the traversal tag for X and Y is convertible to single_pass_traversal_tag then the following requirements must be @@ -940,8 +940,9 @@ ordering relation y - x Distance -x < y ?  distance(x,y) -: -distance(y,x) +x < y ? +distance(Y(x),y) +: -distance(y,Y(x)) pre: there exists a value n of Distance such that @@ -950,8 +951,9 @@ value n of x - y Distance -y < x ?  distance(y,x) -: -distance(x,y) +y < x ? +distance(y,Y(x)) +: -distance(Y(x),y) pre: there exists a value n of Distance such that @@ -1023,7 +1025,7 @@ LocalWords: TraversalTag typename lvalues DWA Hmm JGS mis enum -->

View document source. -Generated on: 2004-01-13 19:31 UTC. +Generated on: 2004-01-13. Generated by Docutils from reStructuredText source.
diff --git a/doc/new-iter-concepts.rst b/doc/new-iter-concepts.rst index ed382da..a587f0c 100644 --- a/doc/new-iter-concepts.rst +++ b/doc/new-iter-concepts.rst @@ -669,11 +669,11 @@ Interoperable Iterators [lib.interoperable.iterators] A class or built-in type ``X`` that models Single Pass Iterator is *interoperable with* a class or built-in type ``Y`` that also models -Single Pass Iterator if both ``X`` and ``Y`` have the same difference -type and traversal tag and if the following expressions are valid and -respect the stated semantics. In the tables below, ``x`` is an object -of type ``X``, ``y`` is an object of type ``Y``, ``Distance`` is -``iterator_traits::difference_type``, and ``n`` represents a +Single Pass Iterator if both ``X`` and ``Y`` have the same traversal +tag and if the following expressions are valid and respect the stated +semantics. In the tables below, ``x`` is an object of type ``X``, +``y`` is an object of type ``Y``, ``Distance`` is +``iterator_traits::difference_type``, and ``n`` represents a constant object of type ``Distance``. If the traversal tag for ``X`` and ``Y`` is convertible to @@ -724,16 +724,16 @@ be met. +-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ |``y <= x`` |convertible to ``bool`` |``!(y > x)`` | | +-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ -|``y - x`` |``Distance`` |``x < y ? distance(x,y) |pre: there exists a | -| | |: -distance(y,x)`` |value ``n`` of | -| | | |``Distance`` such that| +|``y - x`` |``Distance`` |``x < y ? |pre: there exists a | +| | |distance(Y(x),y) |value ``n`` of | +| | |: -distance(y,Y(x))`` |``Distance`` such that| | | | |``x + n == y``. ``y | | | | |== x + (y - x)``. | +-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ -|``x - y`` |``Distance`` |``y < x ? distance(y,x) |pre: there exists a | -| | |: -distance(x,y)`` |value ``n`` of | -| | | |``Distance`` such that| -| | | |``y + n == x``. ``x | +|``x - y`` |``Distance`` |``y < x ? |pre: there exists a | +| | |distance(y,Y(x)) |value ``n`` of | +| | |: -distance(Y(x),y)`` |``Distance`` such that| +| | | |``y + n == x``. ``x | | | | |== y + (x - y)``. | +-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ diff --git a/doc/permutation_iterator.html b/doc/permutation_iterator.html index 89c38bc..cf344da 100644 --- a/doc/permutation_iterator.html +++ b/doc/permutation_iterator.html @@ -44,17 +44,18 @@ in a potentially different order.
-

Introduction

+

Introduction

The adaptor takes two arguments:

    @@ -74,7 +75,7 @@ end permutation iterator is completely defined by means of the past-the-end iterator to the indices.

-

Reference

+

Reference

 template< class ElementIterator
         , class IndexIterator
@@ -94,9 +95,12 @@ public:
       , typename enable_if_convertible<OEIter, ElementIterator>::type* = 0
       , typename enable_if_convertible<OIIter, IndexIterator>::type* = 0
       );
+  reference operator*() const;
+  permutation_iterator& operator++();
   ElementIterator base() const;
 private:
-  ElementIterator m_iterator; // exposition
+  ElementIterator m_iterator; // exposition only
+  IndexIterator m_order;      // exposition only
 };
 
 template <class ElementIterator, class IndexIterator>
@@ -104,33 +108,87 @@ permutation_iterator<ElementIterator, IndexIterator>
 make_permutation_iterator( ElementIterator e, IndexIterator i);
-

permutation_iterator requirements

-

ElementIterator must be a model of RandomAccessIterator. -IndexIterator must at least be a model ForwardIterator. The -value type of the IndexIterator must be convertible to the -difference type of ElementIterator.

+

permutation_iterator requirements

+

ElementIterator shall model Random Access Traversal Iterator. +IndexIterator shall model Readable Iterator. The value type of +the IndexIterator must be convertible to the difference type of +ElementIterator.

+
+
+

permutation_iterator models

+

permutation_iterator models the same iterator traversal concepts +as IndexIterator and the same iterator access concepts as +ElementIterator.

+

If IndexIterator models Single Pass Iterator and +ElementIterator models Readable Iterator then +permutation_iterator models Input Iterator.

+

If IndexIterator models Forward Traversal Iterator and +ElementIterator models Readable Lvalue Iterator then +permutation_iterator models Forward Iterator.

+

If IndexIterator models Bidirectional Traversal Iterator and +ElementIterator models Readable Lvalue Iterator then +permutation_iterator models Bidirectional Iterator.

+

If IndexIterator models Random Access Traversal Iterator and +ElementIterator models Readable Lvalue Iterator then +permutation_iterator models Random Access Iterator.

-

permutation_iterator operations

-

The permutation iterator implements the member functions and operators -required for the Random Access Iterator concept. However, the -permutation iterator can only meet the complexity guarantees of the -same concept as the IndexIterator. Thus for instance, although the -permutation iterator provides operator+=(distance), this operation -will take linear time in case the IndexIterator is a model of -ForwardIterator instead of amortized constant time.

+

permutation_iterator operations

+

In addition to those operations required by the concepts that +permutation_iterator models, permutation_iterator provides the +following operations.

+

permutation_iterator();

+ +++ + + + +
Effects:Default constructs m_iterator and m_order.
+

explicit permutation_iterator(ElementIterator x, IndexIterator y);

+ +++ + + + +
Effects:Constructs m_iterator from x and m_order from y.
-template <class ElementIterator, class IndexIterator>
-permutation_iterator<ElementIterator, IndexIterator> 
-make_permutation_iterator(ElementIterator e, IndexIterator i);
+template< class OEIter, class OIIter, class V, class C, class R, class D >
+permutation_iterator(
+    permutation_iterator<OEIter, OIIter, V, C, R, D> const& r
+    , typename enable_if_convertible<OEIter, ElementIterator>::type* = 0
+    , typename enable_if_convertible<OIIter, IndexIterator>::type* = 0
+    );
- + + + +
Returns:An instance of permutation_iterator<ElementIterator, IndexIterator> -that views the range of elements starting at e` in the order given -by ``i.
Effects:Constructs m_iterator from r.m_iterator and +m_order from y.m_order.
+

reference operator*() const;

+ +++ + + + +
Returns:*(m_iterator + *m_order)
+

permutation_iterator& operator++();

+ +++ + + +
Effects:++m_order
Returns:*this
@@ -143,10 +201,23 @@ that views the range of elements starting at +template <class ElementIterator, class IndexIterator> +permutation_iterator<ElementIterator, IndexIterator> +make_permutation_iterator(ElementIterator e, IndexIterator i); + + +++ + + + +
Returns:permutation_iterator<ElementIterator, IndexIterator>(e, i)
-

Example

+

Example

 using namespace boost;
 int i = 0;
@@ -214,7 +285,7 @@ Iterate backward with stride 2 : 6 8
 

 

 View document source.
-Generated on: 2004-01-13 14:27 UTC.
+Generated on: 2004-01-13.
 Generated by Docutils from reStructuredText source.
 

 
diff --git a/doc/permutation_iterator_ref.rst b/doc/permutation_iterator_ref.rst
index 1beaabb..132f154 100644
--- a/doc/permutation_iterator_ref.rst
+++ b/doc/permutation_iterator_ref.rst
@@ -18,9 +18,12 @@
 	, typename enable_if_convertible::type* = 0
 	, typename enable_if_convertible::type* = 0
 	);
+    reference operator*() const;
+    permutation_iterator& operator++();
     ElementIterator base() const;
   private:
-    ElementIterator m_iterator; // exposition
+    ElementIterator m_iterator; // exposition only
+    IndexIterator m_order;      // exposition only
   };
 
   template 
@@ -32,30 +35,80 @@
 ``permutation_iterator`` requirements
 -------------------------------------
 
-``ElementIterator`` must be a model of RandomAccessIterator__.
-``IndexIterator`` must at least be a model ForwardIterator__.  The
-value type of the ``IndexIterator`` must be convertible to the
-difference type of ``ElementIterator``.
-
-__ http://www.sgi.com/tech/stl/RandomAccessIterator.html
-
-__ http://www.sgi.com/tech/stl/ForwardIterator.html
+``ElementIterator`` shall model Random Access Traversal Iterator.
+``IndexIterator`` shall model Readable Iterator.  The value type of
+the ``IndexIterator`` must be convertible to the difference type of
+``ElementIterator``.
 
 
+``permutation_iterator`` models
+-------------------------------
+
+``permutation_iterator`` models the same iterator traversal concepts
+as ``IndexIterator`` and the same iterator access concepts as
+``ElementIterator``.
+
+If ``IndexIterator`` models Single Pass Iterator and 
+``ElementIterator`` models Readable Iterator then
+``permutation_iterator`` models Input Iterator.
+
+If ``IndexIterator`` models Forward Traversal Iterator and 
+``ElementIterator`` models Readable Lvalue Iterator then
+``permutation_iterator`` models Forward Iterator.
+
+If ``IndexIterator`` models Bidirectional Traversal Iterator and 
+``ElementIterator`` models Readable Lvalue Iterator then
+``permutation_iterator`` models Bidirectional Iterator.
+
+If ``IndexIterator`` models Random Access Traversal Iterator and
+``ElementIterator`` models Readable Lvalue Iterator then
+``permutation_iterator`` models Random Access Iterator.
 
 
 ``permutation_iterator`` operations
 -----------------------------------
 
-The permutation iterator implements the member functions and operators
-required for the `Random Access Iterator`__ concept. However, the
-permutation iterator can only meet the complexity guarantees of the
-same concept as the IndexIterator. Thus for instance, although the
-permutation iterator provides ``operator+=(distance)``, this operation
-will take linear time in case the IndexIterator is a model of
-ForwardIterator instead of amortized constant time.
+In addition to those operations required by the concepts that
+``permutation_iterator`` models, ``permutation_iterator`` provides the
+following operations.
 
-__ http://www.sgi.com/tech/stl/RandomAccessIterator.html
+``permutation_iterator();``
+
+:Effects: Default constructs ``m_iterator`` and ``m_order``.
+
+
+``explicit permutation_iterator(ElementIterator x, IndexIterator y);``
+
+:Effects: Constructs ``m_iterator`` from ``x`` and ``m_order`` from ``y``.
+
+
+::
+
+    template< class OEIter, class OIIter, class V, class C, class R, class D >
+    permutation_iterator(
+	permutation_iterator const& r
+	, typename enable_if_convertible::type* = 0
+	, typename enable_if_convertible::type* = 0
+	);
+
+:Effects: Constructs ``m_iterator`` from ``r.m_iterator`` and
+  ``m_order`` from ``y.m_order``.
+
+
+``reference operator*() const;``
+
+:Returns: ``*(m_iterator + *m_order)``
+
+
+``permutation_iterator& operator++();``
+
+:Effects: ``++m_order``
+:Returns: ``*this``
+
+
+``ElementIterator base() const;``
+
+:Returns: ``m_iterator``
 
 
 ::
@@ -64,11 +117,5 @@ __ http://www.sgi.com/tech/stl/RandomAccessIterator.html
   permutation_iterator 
   make_permutation_iterator(ElementIterator e, IndexIterator i);
 
-:Returns: An instance of ``permutation_iterator``
-  that views the range of elements starting at ``e` in the order given
-  by ``i``.
+:Returns: ``permutation_iterator(e, i)``
 
-
-``ElementIterator base() const;``
-
-:Returns: ``m_iterator``
\ No newline at end of file