From 2854c5c7612b05ad1683ba15cc88c3baa16424d8 Mon Sep 17 00:00:00 2001 From: Jeremy Siek Date: Wed, 14 Jan 2004 19:57:11 +0000 Subject: [PATCH] added pseudo-code for facade_iterator_category type function [SVN r21736] --- doc/counting_iterator.html | 9 +- doc/counting_iterator_ref.rst | 10 +- doc/facade-and-adaptor.html | 338 ++++++++++++------------------- doc/facade_iterator_category.rst | 50 ++--- doc/indirect_iterator.html | 55 +---- doc/indirect_iterator_ref.rst | 12 +- doc/iterator_facade.html | 170 +++++++--------- doc/iterator_facade_ref.rst | 29 ++- doc/new-iter-concepts.html | 9 +- doc/new-iter-concepts.rst | 29 ++- 10 files changed, 277 insertions(+), 434 deletions(-) diff --git a/doc/counting_iterator.html b/doc/counting_iterator.html index 5d23c46..018ea79 100644 --- a/doc/counting_iterator.html +++ b/doc/counting_iterator.html @@ -95,12 +95,13 @@ type. Otherwise difference_typeIf CategoryOrTraversal is not use_default then the member iterator_category is CategoryOrTraversal. Otherwise, if numeric_limits<Incrementable>::is_specialized, then -iterator_category is a type convertible to -random_access_iterator_tag. Otherwise, iterator_category is -unspecified.

+iterator_category is a +facade_iterator_category(random_access_traversal_tag, Incrementable, const Incrementable&). +Otherwise, iterator_category is +facade_iterator_category(iterator_traversal<Incrementable>::type, Incrementable, const Incrementable&).

[Note: implementers are encouraged to provide an implementation of
-
operator- and a difference_type that avoids overflows in +
operator- and the default difference_type that avoids overflows in the cases when the Incrementable type is a numeric type.]
diff --git a/doc/counting_iterator_ref.rst b/doc/counting_iterator_ref.rst index 160012a..b90adc9 100644 --- a/doc/counting_iterator_ref.rst +++ b/doc/counting_iterator_ref.rst @@ -33,12 +33,14 @@ type. Otherwise ``difference_type`` is ``Difference``. If ``CategoryOrTraversal`` is not ``use_default`` then the member ``iterator_category`` is ``CategoryOrTraversal``. Otherwise, if ``numeric_limits::is_specialized``, then -``iterator_category`` is a type convertible to -``random_access_iterator_tag``. Otherwise, ``iterator_category`` is -unspecified. +``iterator_category`` is a +``facade_iterator_category(random_access_traversal_tag, Incrementable, const Incrementable&)``. +Otherwise, ``iterator_category`` is +``facade_iterator_category(iterator_traversal::type, Incrementable, const Incrementable&)``. + [*Note:* implementers are encouraged to provide an implementation of - ``operator-`` and a ``difference_type`` that avoids overflows in + ``operator-`` and the default ``difference_type`` that avoids overflows in the cases when the ``Incrementable`` type is a numeric type.] ``counting_iterator`` requirements diff --git a/doc/facade-and-adaptor.html b/doc/facade-and-adaptor.html index b7e7293..59e7262 100755 --- a/doc/facade-and-adaptor.html +++ b/doc/facade-and-adaptor.html @@ -77,63 +77,62 @@ by adapting other iterators.
  • Iterator facade [lib.iterator.facade]
    • -
  • Iterator adaptor [lib.iterator.adaptor]
      -
    • Class template iterator_adaptor
      • -
    • iterator_adaptor requirements
      • -
    • iterator_adaptor base class parameters
      • -
    • iterator_adaptor models
      • -
    • iterator_adaptor public operations
      • -
    • iterator_adaptor protected member functions
      • -
    • iterator_adaptor private member functions
      • +
    • Iterator adaptor [lib.iterator.adaptor]
      • -
    • Specialized adaptors [lib.iterator.special.adaptors]
        -
      • Indirect iterator
          -
        • Class template pointee
          • -
        • Class template indirect_reference
          • -
        • Class template indirect_iterator
          • -
        • indirect_iterator requirements
          • -
        • indirect_iterator models
          • -
        • indirect_iterator operations
          • +
        • Specialized adaptors [lib.iterator.special.adaptors]
            +
          • Indirect iterator
            • -
          • Reverse iterator
              -
            • Class template reverse_iterator
              • -
            • reverse_iterator requirements
              • -
            • reverse_iterator models
              • -
            • reverse_iterator operations
              • +
            • Reverse iterator
              • -
            • Transform iterator
                -
              • Class template transform_iterator
                • -
              • transform_iterator requirements
                • -
              • transform_iterator models
                • -
              • transform_iterator operations
                • +
              • Transform iterator
                • -
              • Filter iterator
                  -
                • Class template filter_iterator
                  • -
                • filter_iterator requirements
                  • -
                • filter_iterator models
                  • -
                • filter_iterator operations
                  • +
                • Filter iterator
                  • -
                • Counting iterator
                    -
                  • Class template counting_iterator
                    • -
                  • counting_iterator requirements
                    • -
                  • counting_iterator models
                    • -
                  • counting_iterator operations
                    • +
                  • Counting iterator
                    • -
                  • Function output iterator @@ -625,7 +624,7 @@ public: typedef Reference reference; typedef Value* pointer; typedef Difference difference_type; - typedef /* see below */ iterator_category; + typedef /* see below */ iterator_category; reference operator*() const; /* see below */ operator->() const; @@ -694,6 +693,39 @@ template <class Derived, class V, class TC, class R, class D> Derived operator+ (iterator_facade<Derived, V, TC, R, D> const&, typename Derived::difference_type n) +

                    The iterator_category member of iterator_facade is +facade_iterator_category(CategoryOrTraversal, value_type, +reference), as specified by the following pseudo-code:

                    +
                    +facade_iterator_category(C, V, R) =
+    if (C is convertible to input_iterator_tag or output_iterator_tag) then
+        return C
+    else if (C is convertible to incrementable_traversal_tag) then
+        if (R is a reference type
+            and C is convertible to forward_traversal_tag) then
+            if (C is convertible to random_access_traversal_tag)
+                return a type convertible to random_access_iterator_tag
+            else if (C is convertible to bidirectional_traversal_tag)
+                return a type convertible to bidirectional_iterator_tag
+            else
+                return a type convertible to forward_iterator_tag
+        else if (C is convertible to single_pass_traversal_tag
+                 and R is convertible to V)
+            return a type convertible to input_iterator_tag
+        else
+            return C
+
                    + + + +

                    If CategoryOrTraversal is use_default then +iterator_traversal<Derived>::type is convertible to the most +derived standard traversal tag type to which +iterator_traversal<Iterator>::type is also convertible, and not to +any more-derived traversal tag type. Otherwise +iterator_traversal<Derived>::type is convertible to the most +derived standard traversal tag type to which CategoryOrTraversal +is also convertible, and not to any more-derived traversal tag type.

                    The enable_if_interoperable template used above is for exposition purposes. The member operators should be only be in an overload set provided the derived types Dr1 and Dr2 are interoperable, @@ -758,8 +790,7 @@ Iterator c.equal(y) convertible to bool true iff c and y refer to the -same position. Implements c == y -and c != y. +same position. Single Pass Iterator a.increment() @@ -779,77 +810,19 @@ Iterator Random Access Traversal Iterator -c.distance_to(b) -convertible to -F::difference_type -equivalent to distance(c, b) -Random Access Traversal -Iterator - c.distance_to(z) convertible to F::difference_type -equivalent to distance(c, z). -Implements c - z, c < z, c -<= z, c > z, and c >= c. +equivalent to distance(c, X(z)). Random Access Traversal Iterator - -

                    -

                    iterator_facade iterator category

                    -

                    The iterator_category member of iterator_facade<X,V,R,C,D> -satisfies the following conditions:

                    -
                      -

                    • if C is convertible to std::input_iterator_tag or -C is convertible to std::output_iterator_tag, -iterator_category is the same as C.

                      -
                      • -

                    • Otherwise, if C is not convertible to -incrementable_traversal_tag, the program is ill-formed

                      -
                      • -

                    • Otherwise:

                      -
                        -

                      • iterator_category is convertible to the iterator -category tag or tags given by the following algorithm, and -not to any more-derived iterator category tag or tags:

                        -
                        -if (R is a reference type
-    && C is convertible to forward_traversal_tag)
-{
-    if (C is convertible to random_access_traversal_tag)
-        random_access_iterator_tag
-    else if (C is convertible to bidirectional_traversal_tag)
-        bidirectional_iterator_tag
-    else
-        forward_iterator_tag
-}
-else
-{
-    if (C is convertible to single_pass_traversal_tag
-        && R is convertible to V)
-        input_iterator_tag
-    else
-        C
-}
-
                        -
                        • -

                      • iterator_traversal<X>::type is convertible to the most -derived traversal tag type to which C is also -convertible, and not to any more-derived traversal tag type.

                        -
                        • -
                      -
                      • -
                    - - -
                    -

                    iterator_facade operations

                    +

                    iterator_facade operations

                    The operations in this section are described in terms of operations on the core interface of Derived which may be inaccessible (i.e. private). The implementation should access these operations @@ -887,11 +860,10 @@ of type pointer equal to:

                    Returns:an object convertible to value_type. For constant objects v of type value_type, and n of type -difference_type, and reference p equal to -*static_cast<Derived const*>(this), (*this)[n] = v is -equivalent to *(p+ n) = v, and static_cast<value_type +difference_type, (*this)[n] = v is equivalent to +*(*this + n) = v, and static_cast<value_type const&>((*this)[n]) is equivalent to -static_cast<value_type const&>(*(p+n)) +static_cast<value_type const&>(*(*this + n)) @@ -991,7 +963,7 @@ return tmp -= n;
                    -

                    iterator_adaptor public operations

                    +

                    iterator_adaptor public operations

                    iterator_adaptor();

                    @@ -1136,7 +1108,7 @@ expression involving Derived i
                    -

                    iterator_adaptor protected member functions

                    +

                    iterator_adaptor protected member functions

                    Base const& base_reference() const;

                    @@ -1157,7 +1129,7 @@ expression involving Derived i
                    -

                    iterator_adaptor private member functions

                    +

                    iterator_adaptor private member functions

                    typename iterator_adaptor::reference dereference() const;

                    @@ -1226,7 +1198,7 @@ typename iterator_adaptor::difference_type distance_to(
                    -

                    Specialized adaptors [lib.iterator.special.adaptors]

                    +

                    Specialized adaptors [lib.iterator.special.adaptors]

                    The enable_if_convertible<X,Y>::type expression used in this section is for exposition purposes. The converting constructors for specialized adaptors should be only be in an overload set provided @@ -1255,7 +1227,7 @@ take the constructor out of the overload set when the types are not implicitly convertible. ]

                    -

                    Indirect iterator

                    +

                    Indirect iterator

                    indirect_iterator adapts an iterator by applying an extra dereference inside of operator*(). For example, this iterator adaptor makes it possible to view a container of pointers @@ -1265,7 +1237,7 @@ auxiliary traits, pointee and provide support for underlying iterators whose value_type is not an iterator.

                    -

                    Class template pointee

                    +

                    Class template pointee

                    @@ -1309,7 +1281,7 @@ else
                    -

                    Class template indirect_iterator

                    +

                    Class template indirect_iterator

                     template <
     class Iterator
@@ -1411,60 +1383,13 @@ if (Difference is use_default)
 else
     typedef Difference difference_type;
                    -

                    iterator_category satisfies the following conditions, where -R is reference and V is value_type, and where: if -CategoryOrTraversal is use_default, C is -iterator_traversal<Iterator>::type and otherwise C is -CategoryOrTraversal.

                    -
                    -
                      -

                    • if C is convertible to std::input_iterator_tag or -C is convertible to std::output_iterator_tag, -iterator_category is the same as C.

                      -
                      • -

                    • Otherwise, if C is not convertible to -incrementable_traversal_tag, the program is ill-formed

                      -
                      • -

                    • Otherwise:

                      -
                        -

                      • iterator_category is convertible to the iterator -category tag or tags given by the following algorithm, and -not to any more-derived iterator category tag or tags:

                        -
                        -if (R is a reference type
-    && C is convertible to forward_traversal_tag)
-{
-    if (C is convertible to random_access_traversal_tag)
-        random_access_iterator_tag
-    else if (C is convertible to bidirectional_traversal_tag)
-        bidirectional_iterator_tag
-    else
-        forward_iterator_tag
-}
-else
-{
-    if (C is convertible to single_pass_traversal_tag
-        && R is convertible to V)
-        input_iterator_tag
-    else
-        C
-}
-
                        -
                        • -

                      • iterator_traversal<X>::type is convertible to the most -derived traversal tag type to which C is also -convertible, and not to any more-derived traversal tag type.

                        -
                        • -
                      -
                      • -
                    - - - -
                    +

                    The iterator_category member is facade_iterator_category(C, +value_type, reference) where if CategoryOrTraversal is +use_default, C is iterator_traversal<Iterator>::type and +otherwise C is CategoryOrTraversal.

                    -

                    indirect_iterator requirements

                    +

                    indirect_iterator requirements

                    The expression *v, where v is an object of iterator_traits<Iterator>::value_type, shall be valid expression and convertible to reference. Iterator shall @@ -1478,7 +1403,7 @@ parameter is not use_default, deducing the default for the value_type member.]

                    -

                    indirect_iterator models

                    +

                    indirect_iterator models

                    In addition to the concepts indicated by iterator_category and by iterator_traversal<indirect_iterator>::type, a specialization of indirect_iterator models the following @@ -1499,7 +1424,7 @@ expression (where t is an obje interoperable with iterator Y.

                    -

                    indirect_iterator operations

                    +

                    indirect_iterator operations

                    In addition to the operations required by the concepts described above, specializations of indirect_iterator provide the following operations.

                    @@ -1591,11 +1516,11 @@ indirect_iterator(
                    -

                    Reverse iterator

                    +

                    Reverse iterator

                    The reverse iterator adaptor iterates through the adapted iterator range in the opposite direction.

                    -

                    Class template reverse_iterator

                    +

                    Class template reverse_iterator

                     template <class Iterator>
 class reverse_iterator
@@ -1632,11 +1557,11 @@ Lvalue Iterator, then iterator_categoryinput_iterator_tag.
                    -

                    reverse_iterator requirements

                    +

                    reverse_iterator requirements

                    Iterator must be a model of Bidirectional Traversal Iterator.

                    -

                    reverse_iterator models

                    +

                    reverse_iterator models

                    A specialization of reverse_iterator models the same standard traversal and access iterator concepts modeled by its Iterator argument. In addition, it models the old iterator concepts @@ -1674,7 +1599,7 @@ Random Access Traversal Iterator if and only if iterator X is interoperable with iterator Y.

                    -

                    reverse_iterator operations

                    +

                    reverse_iterator operations

                    In addition to the operations required by the concepts modeled by reverse_iterator, reverse_iterator provides the following operations.

                    @@ -1764,12 +1689,12 @@ return *--tmp;
                    -

                    Transform iterator

                    +

                    Transform iterator

                    The transform iterator adapts an iterator by modifying the operator* to apply a function object to the result of dereferencing the iterator and returning the result.

                    -

                    Class template transform_iterator

                    +

                    Class template transform_iterator

                     template <class UnaryFunction,
@@ -1822,7 +1747,7 @@ model Readable Lvalue Iterator then iterat
 convertible to input_iterator_tag.
                    -

                    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 @@ -1831,7 +1756,7 @@ where the type of f(*i) must b

                    The argument Iterator shall model Readable Iterator.

                    -

                    transform_iterator models

                    +

                    transform_iterator models

                    The resulting transform_iterator models the most refined of the following options that is also modeled by Iterator.

                    @@ -1878,7 +1803,7 @@ mutable iterator (as defined in the old iterator requirements).

                    interoperable with iterator Y.

                    -

                    transform_iterator operations

                    +

                    transform_iterator operations

                    In addition to the operations required by the concepts modeled by transform_iterator, transform_iterator provides the following operations.

                    @@ -1971,7 +1896,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. A predicate function object controls which elements are skipped. When the predicate is @@ -1983,7 +1908,7 @@ underlying range. A filter iterator is therefore constructed with pair of iterators indicating the range of elements in the unfiltered sequence to be traversed.

                    -

                    Class template filter_iterator

                    +

                    Class template filter_iterator

                    @@ -2024,7 +1949,7 @@ Iterator then iterator_categorystd::input_iterator_tag                    .

                    -

                    filter_iterator requirements

                    +

                    filter_iterator requirements

                    The Predicate argument must be Assignable, Copy Constructible, and the expression p(x) must be valid where p is an object of type Predicate, x is an object of type @@ -2035,7 +1960,7 @@ Iterator and Single Pass Iterator or it shall meet the requirements of Input Iterator.

                    -

                    filter_iterator models

                    +

                    filter_iterator models

                    The concepts that filter_iterator models are dependent on which concepts the Iterator argument models, as specified in the following tables.

                    @@ -2106,7 +2031,7 @@ following tables.

                    if and only if iterator X is interoperable with iterator Y.

                    -

                    filter_iterator operations

                    +

                    filter_iterator operations

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

                    @@ -2217,12 +2142,12 @@ or m_pred(*m_iter) -

                    Counting iterator

                    +

                    Counting iterator

                    counting_iterator adapts an object by adding an operator* that returns the current value of the object. All other iterator operations are forwarded to the adapted object.

                    -

                    Class template counting_iterator

                    +

                    Class template counting_iterator

                     template <
     class Incrementable
@@ -2255,17 +2180,18 @@ type. Otherwise difference_typeIf CategoryOrTraversal is not use_default then the member
 iterator_category is CategoryOrTraversal.  Otherwise, if
 numeric_limits<Incrementable>::is_specialized, then
-iterator_category is a type convertible to
-random_access_iterator_tag.  Otherwise, iterator_category is
-unspecified.
                    
+iterator_category is a 
+facade_iterator_category(random_access_traversal_tag, Incrementable, const Incrementable&).
+Otherwise, iterator_category is
+facade_iterator_category(iterator_traversal<Incrementable>::type, Incrementable, const Incrementable&).
                    
 
                    
 
                    [Note: implementers are encouraged to provide an implementation of
                    
-
                    operator- and a difference_type that avoids overflows in
+
                    operator- and the default difference_type that avoids overflows in
 the cases when the Incrementable type is a numeric type.]
                    -

                    counting_iterator requirements

                    +

                    counting_iterator requirements

                    The Incrementable argument shall be Copy Constructible and Assignable.

                    If iterator_category is convertible to forward_iterator_tag or forward_traversal_tag, the following must be well-formed:

                    @@ -2291,7 +2217,7 @@ i < j;
                    -

                    counting_iterator models

                    +

                    counting_iterator models

                    Specializations of counting_iterator model Readable Lvalue Iterator. In addition, they model the concepts corresponding to the iterator tags to which their iterator_category is convertible. @@ -2307,7 +2233,7 @@ concepts modeled by IncrementableY.

                    -

                    counting_iterator operations

                    +

                    counting_iterator operations

                    In addition to the operations required by the concepts modeled by counting_iterator, counting_iterator provides the following operations.

                    @@ -2383,7 +2309,7 @@ operations.

                    -

                    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 @@ -2392,7 +2318,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 {
@@ -2414,16 +2340,16 @@ private:
                    -

                    function_output_iterator requirements

                    +

                    function_output_iterator requirements

                    UnaryFunction must be Assignable and Copy Constructible.

                    -

                    function_output_iterator models

                    +

                    function_output_iterator models

                    function_output_iterator is a model of the Writable and Incrementable Iterator concepts.

                    -

                    function_output_iterator operations

                    +

                    function_output_iterator operations

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

                    diff --git a/doc/facade_iterator_category.rst b/doc/facade_iterator_category.rst index 39e9514..49af535 100755 --- a/doc/facade_iterator_category.rst +++ b/doc/facade_iterator_category.rst @@ -1,38 +1,24 @@ -* if ``C`` is convertible to ``std::input_iterator_tag`` or - ``C`` is convertible to ``std::output_iterator_tag``, - ``iterator_category`` is the same as ``C``. -* Otherwise, if ``C`` is not convertible to - ``incrementable_traversal_tag``, the program is ill-formed -* Otherwise: +:: - - ``iterator_category`` is convertible to the iterator - category tag or tags given by the following algorithm, and - not to any more-derived iterator category tag or tags:: - - if (R is a reference type - && C is convertible to forward_traversal_tag) - { - if (C is convertible to random_access_traversal_tag) - random_access_iterator_tag - else if (C is convertible to bidirectional_traversal_tag) - bidirectional_iterator_tag - else - forward_iterator_tag - } - else - { - if (C is convertible to single_pass_traversal_tag - && R is convertible to V) - input_iterator_tag - else - C - } - - - ``iterator_traversal::type`` is convertible to the most - derived traversal tag type to which ``C`` is also - convertible, and not to any more-derived traversal tag type. + facade_iterator_category(C, V, R) = + if (C is convertible to input_iterator_tag or output_iterator_tag) then + return C + else if (C is convertible to incrementable_traversal_tag) then + if (R is a reference type + and C is convertible to forward_traversal_tag) then + if (C is convertible to random_access_traversal_tag) + return a type convertible to random_access_iterator_tag + else if (C is convertible to bidirectional_traversal_tag) + return a type convertible to bidirectional_iterator_tag + else + return a type convertible to forward_iterator_tag + else if (C is convertible to single_pass_traversal_tag + and R is convertible to V) + return a type convertible to input_iterator_tag + else + return C .. Copyright David Abrahams 2004. Use, modification and distribution is .. subject to the Boost Software License, Version 1.0. (See accompanying diff --git a/doc/indirect_iterator.html b/doc/indirect_iterator.html index 2da9a4b..4cc32e8 100644 --- a/doc/indirect_iterator.html +++ b/doc/indirect_iterator.html @@ -125,57 +125,10 @@ if (Difference is use_default) else typedef Difference difference_type; -

                    iterator_category satisfies the following conditions, where -R is reference and V is value_type, and where: if -CategoryOrTraversal is use_default, C is -iterator_traversal<Iterator>::type and otherwise C is -CategoryOrTraversal.

                    -
                    -
                      -

                    • if C is convertible to std::input_iterator_tag or -C is convertible to std::output_iterator_tag, -iterator_category is the same as C.

                      -
                      • -

                    • Otherwise, if C is not convertible to -incrementable_traversal_tag, the program is ill-formed

                      -
                      • -

                    • Otherwise:

                      -
                        -

                      • iterator_category is convertible to the iterator -category tag or tags given by the following algorithm, and -not to any more-derived iterator category tag or tags:

                        -
                        -if (R is a reference type
-    && C is convertible to forward_traversal_tag)
-{
-    if (C is convertible to random_access_traversal_tag)
-        random_access_iterator_tag
-    else if (C is convertible to bidirectional_traversal_tag)
-        bidirectional_iterator_tag
-    else
-        forward_iterator_tag
-}
-else
-{
-    if (C is convertible to single_pass_traversal_tag
-        && R is convertible to V)
-        input_iterator_tag
-    else
-        C
-}
-
                        -
                        • -

                      • iterator_traversal<X>::type is convertible to the most -derived traversal tag type to which C is also -convertible, and not to any more-derived traversal tag type.

                        -
                        • -
                      -
                      • -
                    - - - -
                    +

                    The iterator_category member is facade_iterator_category(C, +value_type, reference) where if CategoryOrTraversal is +use_default, C is iterator_traversal<Iterator>::type and +otherwise C is CategoryOrTraversal.

                    indirect_iterator requirements

                    diff --git a/doc/indirect_iterator_ref.rst b/doc/indirect_iterator_ref.rst index 9643e7b..22a1c35 100644 --- a/doc/indirect_iterator_ref.rst +++ b/doc/indirect_iterator_ref.rst @@ -66,13 +66,13 @@ following pseudo-code. We use the abbreviation else typedef Difference difference_type; -``iterator_category`` satisfies the following conditions, where -``R`` is ``reference`` and ``V`` is ``value_type``, and where: if -``CategoryOrTraversal`` is ``use_default``, ``C`` is -``iterator_traversal::type`` and otherwise ``C`` is -``CategoryOrTraversal``. - .. include:: facade_iterator_category.rst + +The ``iterator_category`` member is ``facade_iterator_category(C, +value_type, reference)`` where if ``CategoryOrTraversal`` is +``use_default``, ``C`` is ``iterator_traversal::type`` and +otherwise ``C`` is ``CategoryOrTraversal``. + ``indirect_iterator`` requirements .................................. diff --git a/doc/iterator_facade.html b/doc/iterator_facade.html index 1ad7003..ff906c1 100644 --- a/doc/iterator_facade.html +++ b/doc/iterator_facade.html @@ -54,29 +54,28 @@ and associated types, to be supplied by a derived iterator class.
                  • Reference
                    • -
                  • Tutorial Example
                    •  +same position. @@ -443,77 +474,19 @@ Iterator - - - - - - +
                    c.equal(y) convertible to bool true iff c and y refer to the -same position. Implements c == y -and c != y.Single Pass Iterator
                    a.increment()Random Access Traversal Iterator
                    c.distance_to(b)convertible to -F::difference_typeequivalent to distance(c, b)Random Access Traversal -Iterator
                    c.distance_to(z) convertible to F::difference_typeequivalent to distance(c, z). -Implements c - z, c < z, c -<= z, c > z, and c >= c.equivalent to distance(c, X(z)). Random Access Traversal Iterator
                    - -
                    -

                    iterator_facade iterator category

                    -

                    The iterator_category member of iterator_facade<X,V,R,C,D> -satisfies the following conditions:

                    -
                      -

                    • if C is convertible to std::input_iterator_tag or -C is convertible to std::output_iterator_tag, -iterator_category is the same as C.

                      -
                      • -

                    • Otherwise, if C is not convertible to -incrementable_traversal_tag, the program is ill-formed

                      -
                      • -

                    • Otherwise:

                      -
                        -

                      • iterator_category is convertible to the iterator -category tag or tags given by the following algorithm, and -not to any more-derived iterator category tag or tags:

                        -
                        -if (R is a reference type
-    && C is convertible to forward_traversal_tag)
-{
-    if (C is convertible to random_access_traversal_tag)
-        random_access_iterator_tag
-    else if (C is convertible to bidirectional_traversal_tag)
-        bidirectional_iterator_tag
-    else
-        forward_iterator_tag
-}
-else
-{
-    if (C is convertible to single_pass_traversal_tag
-        && R is convertible to V)
-        input_iterator_tag
-    else
-        C
-}
-
                        -
                        • -

                      • iterator_traversal<X>::type is convertible to the most -derived traversal tag type to which C is also -convertible, and not to any more-derived traversal tag type.

                        -
                        • -
                      -
                      • -
                    - - -
                    -

                    iterator_facade operations

                    +

                    iterator_facade operations

                    The operations in this section are described in terms of operations on the core interface of Derived which may be inaccessible (i.e. private). The implementation should access these operations @@ -551,11 +524,10 @@ of type pointer equal to:

                    Returns:an object convertible to value_type. For constant objects v of type value_type, and n of type -difference_type, and reference p equal to -*static_cast<Derived const*>(this), (*this)[n] = v is -equivalent to *(p+ n) = v, and static_cast<value_type +difference_type, (*this)[n] = v is equivalent to +*(*this + n) = v, and static_cast<value_type const&>((*this)[n]) is equivalent to -static_cast<value_type const&>(*(p+n)) +static_cast<value_type const&>(*(*this + n)) @@ -655,7 +627,7 @@ return tmp -= n;
                    -

                    Tutorial Example

                    +

                    Tutorial Example

                    @@ -665,7 +637,7 @@ example of a linked list of polymorphic objects. This example was inspired by a posting by Keith Macdonald on the Boost-Users mailing list.

                    -

                    The Problem

                    +

                    The Problem

                    Say we've written a polymorphic linked list node base class:

                     # include <iostream>
@@ -727,7 +699,7 @@ inline std::ostream& operator<<(std::ostream& s, node_base const&a
 lists.
                    -

                    A Basic Iterator Using iterator_facade

                    +

                    A Basic Iterator Using iterator_facade

                    We will construct a node_iterator class using inheritance from iterator_facade to implement most of the iterator's operations.

                    @@ -741,24 +713,24 @@ class node_iterator
 };
                    -

                    Template Arguments for iterator_facade

                    +

                    Template Arguments for iterator_facade

                    iterator_facade has several template parameters, so we must decide what types to use for the arguments. The parameters are Derived, Value, CategoryOrTraversal, Reference, and Difference.

                    -

                    Derived

                    +

                    Derived

                    Because iterator_facade is meant to be used with the CRTP [Cop95] the first parameter is the iterator class name itself, node_iterator.

                    -

                    Value

                    +

                    Value

                    The Value parameter determines the node_iterator's value_type. In this case, we are iterating over node_base objects, so Value will be node_base.

                    -

                    CategoryOrTraversal

                    +

                    CategoryOrTraversal

                    Now we have to determine which iterator traversal concept our node_iterator is going to model. Singly-linked lists only have forward links, so our iterator can't can't be a bidirectional @@ -778,7 +750,7 @@ end up being std::forward_iterator_tag

                    -

                    Reference

                    +

                    Reference

                    The Reference argument becomes the type returned by node_iterator's dereference operation, and will also be the same as std::iterator_traits<node_iterator>::reference. The @@ -787,7 +759,7 @@ library's default for this parameter is Va type, we can omit this argument, or pass use_default.

                    -

                    Difference

                    +

                    Difference

                    The Difference argument determines how the distance between two node_iterators will be measured and will also be the same as std::iterator_traits<node_iterator>::difference_type. @@ -814,7 +786,7 @@ class node_iterator

                    -

                    Constructors and Data Members

                    +

                    Constructors and Data Members

                    Next we need to decide how to represent the iterator's position. This representation will take the form of data members, so we'll also need to write constructors to initialize them. The @@ -859,7 +831,7 @@ default constructor to leave m_node

                    -

                    Implementing the Core Operations

                    +

                    Implementing the Core Operations

                    The last step is to implement the core operations required by the concepts we want our iterator to model. Referring to the table, we can see that the first three rows are applicable @@ -910,7 +882,7 @@ iterator! For a working example of its use, see -

                    A constant node_iterator

                    +

                    A constant node_iterator

                    Constant and Mutable iterators

                    The term mutable iterator means an iterator through which @@ -1011,7 +983,7 @@ typedef node_iter<node_base const> node_const_iterator;

                    -

                    Interoperability

                    +

                    Interoperability

                    Our const_node_iterator works perfectly well on its own, but taken together with node_iterator it doesn't quite meet expectations. For example, we'd like to be able to pass a @@ -1084,7 +1056,7 @@ traversal iterator, we'd have had to templatize its iterators here.

                    -

                    Telling the Truth

                    +

                    Telling the Truth

                    Now node_iterator and node_const_iterator behave exactly as you'd expect... almost. We can compare them and we can convert in one direction: from node_iterator to node_const_iterator. @@ -1122,7 +1094,7 @@ appropriate:

                    -

                    Wrap Up

                    +

                    Wrap Up

                    This concludes our iterator_facade tutorial, but before you stop reading we urge you to take a look at iterator_adaptor. There's another way to approach writing these iterators which might diff --git a/doc/iterator_facade_ref.rst b/doc/iterator_facade_ref.rst index b0a6e61..420ded1 100644 --- a/doc/iterator_facade_ref.rst +++ b/doc/iterator_facade_ref.rst @@ -89,13 +89,30 @@ Derived operator+ (iterator_facade const&, typename Derived::difference_type n) - -__ `facade iterator category`_ +__ `iterator category`_ __ `operator arrow`_ __ brackets_ +.. _`iterator category`: + +The ``iterator_category`` member of ``iterator_facade`` is +``facade_iterator_category(CategoryOrTraversal, value_type, +reference)``, as specified by the following pseudo-code: + +.. include:: facade_iterator_category.rst + +If ``CategoryOrTraversal`` is ``use_default`` then +``iterator_traversal::type`` is convertible to the most +derived standard traversal tag type to which +``iterator_traversal::type`` is also convertible, and not to +any more-derived traversal tag type. Otherwise +``iterator_traversal::type`` is convertible to the most +derived standard traversal tag type to which ``CategoryOrTraversal`` +is also convertible, and not to any more-derived traversal tag type. + + The ``enable_if_interoperable`` template used above is for exposition purposes. The member operators should be only be in an overload set provided the derived types ``Dr1`` and ``Dr2`` are interoperable, @@ -162,15 +179,7 @@ interoperable with ``X``. | |``F::difference_type``| |Iterator | +--------------------+----------------------+-------------------------------------+---------------------------+ -.. _facade iterator category: -``iterator_facade`` iterator category -------------------------------------- - -The ``iterator_category`` member of ``iterator_facade`` -satisfies the following conditions: - -.. include:: facade_iterator_category.rst ``iterator_facade`` operations ------------------------------ diff --git a/doc/new-iter-concepts.html b/doc/new-iter-concepts.html index 805a43f..660fca2 100755 --- a/doc/new-iter-concepts.html +++ b/doc/new-iter-concepts.html @@ -373,9 +373,9 @@ the stated semantics. U is the type T.

                    -+-+ @@ -401,10 +401,7 @@ non-cv-qualified type - +
                    Readable Iterator Requirements (in addition to Assignable and Copy Constructible)
                    a->m U&pre: static_cast<T const&>(*a).m is well-defined. If -static_cast<T&>(*a).m is well-defined, equivalent to -static_cast<T&>(*a).m; otherwise, equivalent to -static_cast<T const&>(*a).m.pre: pre: (*a).m is well-defined. Equivalent to (*a).m.
                    diff --git a/doc/new-iter-concepts.rst b/doc/new-iter-concepts.rst index 67e6c36..eb5325a 100644 --- a/doc/new-iter-concepts.rst +++ b/doc/new-iter-concepts.rst @@ -367,22 +367,19 @@ Copy Constructible, 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 Assignable and Copy Constructible) | -+-----------------------------------+------------------------+-----------------------------------------------------------+ -|Expression |Return Type |Note/Precondition | -+===================================+========================+===========================================================+ -|``iterator_traits::value_type`` |``T`` |Any non-reference, | -| | |non-cv-qualified type | -+-----------------------------------+------------------------+-----------------------------------------------------------+ -|``*a`` | Convertible to ``T`` |pre: ``a`` is dereferenceable. If ``a == b`` then ``*a`` | -| | | is equivalent to ``*b``. | -+-----------------------------------+------------------------+-----------------------------------------------------------+ -|``a->m`` |``U&`` |pre: ``static_cast(*a).m`` is well-defined. If | -| | |``static_cast(*a).m`` is well-defined, equivalent to | -| | |``static_cast(*a).m``; otherwise, equivalent to | -| | |``static_cast(*a).m``. | -+-----------------------------------+------------------------+-----------------------------------------------------------+ ++-----------------------------------------------------------------------------------------------------------------------------+ +|Readable Iterator Requirements (in addition to Assignable and Copy Constructible) | ++-----------------------------------+------------------------+----------------------------------------------------------------+ +|Expression |Return Type |Note/Precondition | ++===================================+========================+================================================================+ +|``iterator_traits::value_type`` |``T`` |Any non-reference, | +| | |non-cv-qualified type | ++-----------------------------------+------------------------+----------------------------------------------------------------+ +|``*a`` | Convertible to ``T`` |pre: ``a`` is dereferenceable. If ``a == b`` then ``*a`` | +| | | is equivalent to ``*b``. | ++-----------------------------------+------------------------+----------------------------------------------------------------+ +|``a->m`` |``U&`` |pre: ``pre: (*a).m`` is well-defined. Equivalent to ``(*a).m``. | ++-----------------------------------+------------------------+----------------------------------------------------------------+ .. We won't say anything about iterator_traits::reference until the DR is resolved. -JGS