From dd5fb425fa2aa887f6cee60e1e18baf59fd414d0 Mon Sep 17 00:00:00 2001 From: Dave Abrahams Date: Sat, 10 Jan 2004 19:00:48 +0000 Subject: [PATCH] updates [SVN r21577] --- doc/facade-and-adaptor.html | 417 ++++++++++++++++++++++++++--------- doc/index.html | 14 +- doc/index.rst | 13 +- doc/indirect_iterator.html | 115 ++++++---- doc/iterator_facade.html | 84 ++++--- doc/iterator_facade.rst | 15 +- doc/iterator_facade_body.rst | 17 +- 7 files changed, 479 insertions(+), 196 deletions(-) diff --git a/doc/facade-and-adaptor.html b/doc/facade-and-adaptor.html index 465c920..a235706 100755 --- a/doc/facade-and-adaptor.html +++ b/doc/facade-and-adaptor.html @@ -3,12 +3,203 @@ - + Iterator Facade and Adaptor - +
@@ -96,40 +287,41 @@ by adapting other iterators.
  • Indirect iterator
    • -
  • Reverse iterator
      -
    • Class template reverse_iterator
      • -
    • reverse_iterator requirements
      • +
    • Reverse iterator
      • -
    • Transform iterator
        -
      • Class template transform_iterator
        • -
      • transform_iterator requirements
        • -
      • transform_iterator public operations
        • -
      • transform_iterator private operations
        • +
      • Transform iterator
        • -
      • Filter iterator
          -
        • Class template filter_iterator
          • +
        • Filter iterator
          • -
        • filter_iterator requirements
          • -
        • filter_iterator operations
          • -
        • Counting iterator @@ -304,14 +496,15 @@ impossible.

          • Usage

          -

          The user of iterator_facade derives his iterator class from an -specialization of iterator_facade which takes the derived iterator -class as the first template parameter. The order of the other -template parameters to iterator_facade have been carefully chosen -to take advantage of useful defaults. For example, when defining a -constant lvalue iterator, the user can pass a const-qualified version -of the iterator's value_type as iterator_facade's Value -parameter and omit the Reference parameter which follows.

          +

          The user of iterator_facade derives his iterator class from a +specialization of iterator_facade and passes the derived +iterator class as iterator_facade's first template parameter. +The order of the other template parameters have been carefully +chosen to take advantage of useful defaults. For example, when +defining a constant lvalue iterator, the user can pass a +const-qualified version of the iterator's value_type as +iterator_facade's Value parameter and omit the +Reference parameter which follows.

          The derived iterator class must define member functions implementing the iterator's core behaviors. The following table describes expressions which are required to be valid depending on the category @@ -319,7 +512,7 @@ of the derived iterator type. These member functions are described briefly below and in more detail in the iterator facade requirements.

          - +
          @@ -712,7 +905,7 @@ object of type X, X, and z is a constant object of a random access traversal iterator type interoperable with X.

          -
          +
          @@ -1256,17 +1449,14 @@ template < , class Difference = use_default > class indirect_iterator - : public iterator_adaptor< - indirect_iterator<Iterator, Value, Access, Traversal, - Reference, Difference>, - Iterator, - /* Value = see below */, - CategoryOrTraversal, - Reference, - Difference> { - friend class iterator_core_access; public: + typedef /* see below */ value_type; + typedef /* see below */ reference; + typedef /* see below */ pointer; + typedef /* see below */ difference_type; + typedef /* see below */ iterator_category; + indirect_iterator(); indirect_iterator(Iterator x); @@ -1280,54 +1470,71 @@ class indirect_iterator > const& y , typename enable_if_convertible<Iterator2, Iterator>::type* = 0 // exposition ); -private: // as-if specification - typename indirect_iterator::reference dereference() const - { - return **this->base(); - } }; + +

          The member types of indirect_iterator are defined according to the +following pseudo-code. We use the abbreviation +V=iterator_traits<Iterator>::value_type.:

          +
          +if (Value is use_default) then
+    typedef iterator_traits<V>::value_type value_type;
+else
+    typedef remove_const<Value>::type value_type;
 
-template <class Dereferenceable>
-struct referent {
-  typedef /* see below */ type;
-};
-
          -

          If Value is not use_default then the the argument for the -iterator_adaptor base class' Value parameter is Value with -cv-qualifiers removed. If Value is use_default, then the -argument for the iterator_adaptor base class' Value parameter -is computed as follows. We use the abbreviation -V=iterator_traits<Iterator>::value_type and v is an object of -type V.:

          -
          -if (*v returns a constant lvalue or an rvalue) then
-    referent<V>::type
+if (Reference is use_default) then
+    if (Value is use_default) then
+        typedef iterator_traits<V>::reference reference;
+    else
+        typedef Value& reference;
 else
-    add_const<referent<V>::type>::type
-
          -

          The algorithm for the type member of referent traits class is -as follows:

          -
          -if (Dereferenceable is a class and has member element_type)
-    Dereferenceable::element_type
+    typedef Reference reference;
+
+if (Value is use_default) then
+    typedef ?? pointer;
 else
-    iterator_traits<Dereferenceable>::value_type
+    typedef Value* pointer;
+
+if (Difference is use_default)
+    typedef iterator_traits<Iterator>::difference_type difference_type;
+else
+    typedef Difference difference_type;
          +

          The member indirect_iterator::iterator_category is a type that +satisfies the requirements of the concepts modeled by the indirect +iterator as specified in the models section.

          indirect_iterator requirements

          -

          The Iterator type must meet the requirements of Readable -Iterator. Also, the following requirements are placed on -iterator_traits<Iterator>::value_type. Let i be an object of -type iterator_traits<Iterator>::value_type. Then *i must be a -valid expression, and the type of *i must be the same as the -iterator_adaptor::reference. Also, there are further requirements -on the iterator_traits<Iterator>::value_type if the Value -parameter is not use_default, as implied by the algorithm for deducing -the default.

          +

          The Iterator argument shall meet the requirements of Readable +Iterator. The CategoryOrTraversal argument shall be one of the +standard iterator tags or use_default. If CategoryOrTraversal +is an iterator tag, the template parameter Iterator argument shall +meet the traversal requirements corresponding to the iterator tag.

          +

          The expression *v, where v is an object of type +iterator_traits<Iterator>::value_type, must be a valid expression +and must be convertible to indirect_iterator::reference. Also +indirect_iterator::reference must be convertible to +indirect_iterator::value. There are further requirements on the +iterator_traits<Iterator>::value_type if the Value parameter +is not use_default, as implied by the algorithm for deducing the +default for the value_type member.

          +
          +
          +

          indirect_iterator models

          +

          If CategoryOrTraversal is a standard iterator tag, +indirect_iterator is a model of the iterator concept corresponding +to the tag, otherwise indirect_iterator satisfies the requirements +of the most refined standard traversal concept that is satisfied by +the Iterator argument.

          +

          indirect_iterator models Readable Iterator. If +indirect_iterator::reference(*v) = t is a valid expression (where +t is an object of type indirect_iterator::value_type) then +indirect_iterator models Writable Iterator. If +indirect_iterator::reference is a reference then +indirect_iterator models Lvalue Iterator.

          @@ -1376,13 +1583,13 @@ indirect_iterator(
          -

          Reverse iterator

          +

          Reverse iterator

          The reverse iterator adaptor flips the direction of a base iterator's motion. Invoking operator++() moves the base iterator backward and invoking operator--() moves the base iterator forward.

          -

          Class template reverse_iterator

          +

          Class template reverse_iterator

           template <class Iterator>
 class reverse_iterator :
@@ -1421,7 +1628,7 @@ private: // as-if specification
          -

          reverse_iterator requirements

          +

          reverse_iterator requirements

          The base Iterator must be a model of Bidirectional Traversal Iterator. The resulting reverse_iterator will be a model of the most refined standard traversal and access concepts that are modeled @@ -1468,14 +1675,14 @@ reverse_iterator(

          -

          Transform iterator

          +

          Transform iterator

          The transform iterator adapts an iterator by applying some function object to the result of dereferencing the iterator. In other words, the operator* of the transform iterator first dereferences the base iterator, passes the result of this to the function object, and then returns the result.

          -

          Class template transform_iterator

          +

          Class template transform_iterator

           template <class UnaryFunction,
@@ -1505,7 +1712,7 @@ private:
          -

          transform_iterator requirements

          +

          transform_iterator requirements

          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 @@ -1529,7 +1736,7 @@ concept that is modeled by Iterator The value_type is remove_cv<remove_reference<reference> >::type.

          @@ -1578,7 +1785,7 @@ transform_iterator(
          -

          transform_iterator private operations

          +

          transform_iterator private operations

          typename transform_iterator::value_type dereference() const;

          @@ -1591,7 +1798,7 @@ transform_iterator(
          -

          Filter iterator

          +

          Filter iterator

          The filter iterator adaptor creates a view of an iterator range in which some elements of the range are skipped over. A predicate function object controls which elements are skipped. When the @@ -1603,7 +1810,7 @@ of the underlying range. Therefore the constructor of the filter iterator takes two iterator parameters: the position for the filtered iterator and the end of the range.

          -

          Class template filter_iterator

          +

          Class template filter_iterator

           template <class Predicate, class Iterator>
 class filter_iterator
@@ -1645,7 +1852,7 @@ class filter_iterator
          -

          filter_iterator requirements

          +

          filter_iterator requirements

          The base Iterator parameter must be a model of Readable Iterator and Single Pass Iterator. The resulting filter_iterator will be a model of Forward Traversal Iterator @@ -1662,7 +1869,7 @@ expression p(x) must be valid p(x) must be convertible to bool.

          @@ -1736,13 +1943,13 @@ filter_iterator(
          -

          Counting iterator

          +

          Counting iterator

          The counting iterator adaptor implements dereference by returning a reference to the base object. The other operations are implemented by the base m_iterator, as per the inheritance from iterator_adaptor.

          -

          Class template counting_iterator

          +

          Class template counting_iterator

           template <
     class Incrementable
@@ -1781,7 +1988,7 @@ the cases when the Incrementable
          -

          counting_iterator requirements

          +

          counting_iterator requirements

          The Incrementable type must be Default Constructible, Copy Constructible, and Assignable. The default distance is an implementation defined signed integegral type.

          @@ -1809,7 +2016,7 @@ i < j
          -

          counting_iterator operations

          +

          counting_iterator operations

          counting_iterator();

          @@ -1840,7 +2047,7 @@ object copy constructed from x
          -

          Function output iterator

          +

          Function output iterator

          The function output iterator adaptor makes it easier to create custom output iterators. The adaptor takes a unary function and creates a model of Output Iterator. Each item assigned to the output iterator is @@ -1849,7 +2056,7 @@ iterator is that creating a conforming output iterator is non-trivial, particularly because the proper implementation usually requires a proxy object.

          -

          Class template function_output_iterator

          +

          Class template function_output_iterator

           template <class UnaryFunction>
 class function_output_iterator {
@@ -1877,7 +2084,7 @@ public:
          -

          function_output_iterator requirements

          +

          function_output_iterator requirements

          The UnaryFunction must be Assignable, Copy Constructible, and the expression f(x) must be valid, where f is an object of type UnaryFunction and x is an object of a type accepted by f. @@ -1885,7 +2092,7 @@ The resulting function_output_iterator

          -

          function_output_iterator operations

          +

          function_output_iterator operations

          explicit function_output_iterator(const UnaryFunction& f = UnaryFunction());

          @@ -1926,7 +2133,7 @@ a copy of the unary function f
          -

          function_output_iterator::output_proxy operations

          +

          function_output_iterator::output_proxy operations

          output_proxy(UnaryFunction& f);

          @@ -1960,5 +2167,11 @@ LocalWords: OtherIncrementable Coplien --> +
          +
          +View document source. +Generated on: 2004-01-10 18:59 UTC. +Generated by Docutils from reStructuredText source. +
          diff --git a/doc/index.html b/doc/index.html index b3a3a14..d9338c3 100755 --- a/doc/index.html +++ b/doc/index.html @@ -284,11 +284,13 @@ up often. In order to ease the implementation of new iterators, the Boost.Iterator library provides the iterator_facade class template, which implements many useful defaults and compile-time checks designed to help the author iterator ensure that his iterator is -correct. It is common to define a new iterator which behaves like -another iterator, but which modifies some aspect of its behavior. -For that purpose, the library supplies the iterator_adaptor class -template, which is specially designed to take advantage of as much -of the underlying iterator's behavior as possible.

          +correct.

          +

          It is also common to define a new iterator that is similar to some +underlying iterator or iterator-like type, but that modifies some +aspect of the underlying type's behavior. For that purpose, the +library supplies the iterator_adaptor class template, which is specially +designed to take advantage of as much of the underlying type's +behavior as possible.

          Both iterator_facade and iterator_adaptor as well as many of the specialized adaptors mentioned below have been proposed for standardization, and accepted into the first C++ technical report; see our

          @@ -409,7 +411,7 @@ LocalWords: TraversalTag typename lvalues DWA Hmm JGS -->
          View document source. -Generated on: 2003-11-24 04:21 UTC. +Generated on: 2004-01-10 18:59 UTC. Generated by Docutils from reStructuredText source.
          diff --git a/doc/index.rst b/doc/index.rst index d25bad7..cc230fe 100755 --- a/doc/index.rst +++ b/doc/index.rst @@ -84,11 +84,14 @@ up often. In order to ease the implementation of new iterators, the Boost.Iterator library provides the |facade|_ class template, which implements many useful defaults and compile-time checks designed to help the author iterator ensure that his iterator is -correct. It is common to define a new iterator which behaves like -another iterator, but which modifies some aspect of its behavior. -For that purpose, the library supplies the |adaptor|_ class -template, which is specially designed to take advantage of as much -of the underlying iterator's behavior as possible. +correct. + +It is also common to define a new iterator that is similar to some +underlying iterator or iterator-like type, but that modifies some +aspect of the underlying type's behavior. For that purpose, the +library supplies the |adaptor|_ class template, which is specially +designed to take advantage of as much of the underlying type's +behavior as possible. .. |facade| replace:: ``iterator_facade`` .. _facade: iterator_facade.html diff --git a/doc/indirect_iterator.html b/doc/indirect_iterator.html index 7365fc8..f44890e 100644 --- a/doc/indirect_iterator.html +++ b/doc/indirect_iterator.html @@ -242,70 +242,104 @@ iterators over smart pointers, which the impl handles. -JGS -->

          Table of Contents

           template <
     class Iterator
   , class Value = use_default
-  , unsigned Access  = use_default_access
-  , class Traversal  = use_default
+  , class CategoryOrTraversal = use_default
   , class Reference = use_default
   , class Difference = use_default
 >
 class indirect_iterator
-  : public iterator_adaptor</* see discussion */>
 {
-    friend class iterator_core_access;
  public:
+    typedef /* see below */ value_type;
+    typedef /* see below */ reference;
+    typedef /* see below */ pointer;
+    typedef /* see below */ difference_type;
+    typedef /* see below */ iterator_category;
+
     indirect_iterator();
     indirect_iterator(Iterator x);
+
     template <
-        class Iterator2, class Value2, unsigned Access2, class Traversal2
+        class Iterator2, class Value2, class Category2
       , class Reference2, class Difference2
     >
     indirect_iterator(
         indirect_iterator<
-             Iterator2, Value2, Access2, Traversal2, Reference2, Difference2
+             Iterator2, Value2, Category2, Reference2, Difference2
         > const& y
       , typename enable_if_convertible<Iterator2, Iterator>::type* = 0 // exposition
     );
-private: // as-if specification
-    typename indirect_iterator::reference dereference() const
-    {
-        return **this->base();
-    }
 };
          +

          The member types of indirect_iterator are defined according to the +following pseudo-code. We use the abbreviation +V=iterator_traits<Iterator>::value_type.:

          +
          +if (Value is use_default) then
+    typedef iterator_traits<V>::value_type value_type;
+else
+    typedef remove_const<Value>::type value_type;
+
+if (Reference is use_default) then
+    if (Value is use_default) then
+        typedef iterator_traits<V>::reference reference;
+    else
+        typedef Value& reference;
+else
+    typedef Reference reference;
+
+if (Value is use_default) then
+    typedef ?? pointer;
+else
+    typedef Value* pointer;
+
+if (Difference is use_default)
+    typedef iterator_traits<Iterator>::difference_type difference_type;
+else
+    typedef Difference difference_type;
+
          +

          The member indirect_iterator::iterator_category is a type that +satisfies the requirements of the concepts modeled by the indirect +iterator as specified in the models section.

          indirect_iterator requirements

          -

          The value_type of the Iterator template parameter should -itself be dereferenceable. The return type of the operator* for -the value_type must be the same type as the Reference template -parameter. The Value template parameter will be the value_type -for the indirect_iterator, unless Value is const. If Value -is const X, then value_type will be non- const X. The -default for Value is

          -
          -iterator_traits< iterator_traits<Iterator>::value_type >::value_type
-
          -

          If the default is used for Value, then there must be a valid -specialization of iterator_traits for the value type of the base -iterator.

          -

          The Reference parameter will be the reference type of the -indirect_iterator. The default is Value&.

          -

          The Access and Traversal parameters are passed unchanged to -the corresponding parameters of the iterator_adaptor base -class, and the Iterator parameter is passed unchanged as the -Base parameter to the iterator_adaptor base class.

          -

          The indirect iterator will model the most refined standard traversal -concept that is modeled by the Iterator type. The indirect -iterator will model the most refined standard access concept that is -modeled by the value type of Iterator.

          +

          The Iterator argument shall meet the requirements of Readable +Iterator. The CategoryOrTraversal argument shall be one of the +standard iterator tags or use_default. If CategoryOrTraversal +is an iterator tag, the template parameter Iterator argument shall +meet the traversal requirements corresponding to the iterator tag.

          +

          The expression *v, where v is an object of type +iterator_traits<Iterator>::value_type, must be a valid expression +and must be convertible to indirect_iterator::reference. Also +indirect_iterator::reference must be convertible to +indirect_iterator::value. There are further requirements on the +iterator_traits<Iterator>::value_type if the Value parameter +is not use_default, as implied by the algorithm for deducing the +default for the value_type member.

          +
          +
          +

          indirect_iterator models

          +

          If CategoryOrTraversal is a standard iterator tag, +indirect_iterator is a model of the iterator concept corresponding +to the tag, otherwise indirect_iterator satisfies the requirements +of the most refined standard traversal concept that is satisfied by +the Iterator argument.

          +

          indirect_iterator models Readable Iterator. If +indirect_iterator::reference(*v) = t is a valid expression (where +t is an object of type indirect_iterator::value_type) then +indirect_iterator models Writable Iterator. If +indirect_iterator::reference is a reference then +indirect_iterator models Lvalue Iterator.

          @@ -313,8 +347,8 @@ modeled by the value type of Iterator - +
          Requires:Iterator must be Default Constructible.
          Returns:An instance of indirect_iterator with -a default constructed base object.
          Returns:An instance of indirect_iterator with +a default-constructed iterator_adaptor subobject.
          @@ -346,7 +380,8 @@ indirect_iterator( Requires:Iterator2 is implicitly convertible to Iterator. -Returns:An instance of indirect_iterator that is a copy of y. +Returns:An instance of indirect_iterator whose +iterator_adaptor subobject is constructed from y.base(). @@ -355,7 +390,7 @@ indirect_iterator(
          View document source. -Generated on: 2003-11-24 05:00 UTC. +Generated on: 2004-01-10 18:59 UTC. Generated by Docutils from reStructuredText source.
          diff --git a/doc/iterator_facade.html b/doc/iterator_facade.html index 71d630b..07ec2df 100644 --- a/doc/iterator_facade.html +++ b/doc/iterator_facade.html @@ -7,7 +7,7 @@ Iterator Facade - +