From 80f6a13e7928bb00b1922dbcc5847dbd9c30087e Mon Sep 17 00:00:00 2001 From: Jeremy Siek Date: Tue, 13 Jan 2004 19:21:18 +0000 Subject: [PATCH] added Interoperable Iterators [SVN r21698] --- doc/iter-issue-list.rst | 71 ++++++++++------- doc/new-iter-concepts.html | 155 +++++++++++++++++++++++++++++++++++-- doc/new-iter-concepts.rst | 80 +++++++++++++++++++ 3 files changed, 271 insertions(+), 35 deletions(-) diff --git a/doc/iter-issue-list.rst b/doc/iter-issue-list.rst index d07d35a..6404592 100644 --- a/doc/iter-issue-list.rst +++ b/doc/iter-issue-list.rst @@ -1049,49 +1049,49 @@ c++std-lib-12641: ``result_of::reference)>::type``. The ``value_type`` is ``remove_cv >::type``. - These are the defaults, right? If the user supplies their own types that's - what gets passed to iterator_adaptor. And again, the specification should - be in terms of the specialization of iterator_adaptor, and not in terms of - the result: +These are the defaults, right? If the user supplies their own types that's +what gets passed to iterator_adaptor. And again, the specification should +be in terms of the specialization of iterator_adaptor, and not in terms of +the result: - Reference argument to iterator_adaptor:: +Reference argument to iterator_adaptor:: - if (Reference != use_default) + if (Reference != use_default) Reference - else + else result_of::reference)>::type - Value argument to iterator_adaptor:: +Value argument to iterator_adaptor:: - if (Value != use_default) + if (Value != use_default) Value - else if (Reference != use_default) + else if (Reference != use_default) remove_reference::type - else + else remove_reference::reference)>::type>::type - There's probably a better way to specify that last alternative, but I've - been at this too long, and it's all turning into a maze of twisty passages, - all alike. +There's probably a better way to specify that last alternative, but I've +been at this too long, and it's all turning into a maze of twisty passages, +all alike. :Proposed resolution: Replace: - The reference type of transform_iterator is - ``result_of::reference)>::type``. The - ``value_type`` is ``remove_cv >::type``. + The reference type of transform_iterator is + ``result_of::reference)>::type``. The + ``value_type`` is ``remove_cv >::type``. with: - If ``Reference`` is ``use_default`` then the ``reference`` member of - ``transform_iterator`` is - ``result_of::reference)>::type``. - Otherwise, ``reference`` is ``Reference``. + If ``Reference`` is ``use_default`` then the ``reference`` member of + ``transform_iterator`` is + ``result_of::reference)>::type``. + Otherwise, ``reference`` is ``Reference``. - If ``Value`` is ``use_default`` then the ``value_type`` member is - ``remove_cv >::type``. Otherwise, - ``value_type`` is ``Value``. + If ``Value`` is ``use_default`` then the ``value_type`` member is + ``remove_cv >::type``. Otherwise, + ``value_type`` is ``Value``. filter_iterator details unspecified @@ -1112,11 +1112,26 @@ The paper says:: /* see details */ > That comment covers the Access, Traversal, Reference, and Difference -arguments. The only specification for any of these in the details is:: +arguments. The only specification for any of these in the details is: - The access category of the filter_iterator will be the same as - the access category of Iterator. + The access category of the filter_iterator will be the same as + the access category of Iterator. Needs more. -:Proposed resolution: **Needs work** (Jeremy) +:Proposed resolution: + +Add to the synopsis:: + + typedef iterator_traits::value_type value_type; + typedef iterator_traits::reference reference; + typedef iterator_traits::pointer pointer; + typedef iterator_traits::difference_type difference_type; + typedef /* see below */ iterator_category; + +and add just after the synopsis: + + If ``Iterator`` models Readable Lvalue Iterator and Forward Traversal + Iterator then ``iterator_category`` is convertible to + ``std::forward_iterator_tag``. Otherwise ``iterator_category`` is + convertible to ``std::input_iterator_tag``. diff --git a/doc/new-iter-concepts.html b/doc/new-iter-concepts.html index 7741941..d6257a0 100755 --- a/doc/new-iter-concepts.html +++ b/doc/new-iter-concepts.html @@ -81,15 +81,16 @@ of iterators that are used in practice.
  • Forward Traversal Iterators [lib.forward.traversal.iterators]
  • Bidirectional Traversal Iterators [lib.bidirectional.traversal.iterators]
  • Random Access Traversal Iterators [lib.random.access.traversal.iterators]
    • +
  • Interoperable Iterators [lib.interoperable.iterators]
    • -
  • Addition to [lib.iterator.synopsis]
    • -
  • Addition to [lib.iterator.traits]
    • +
  • Addition to [lib.iterator.synopsis]
    • +
  • Addition to [lib.iterator.traits]
    • -
  • Footnotes
    • +
  • Footnotes
    • @@ -311,6 +312,12 @@ position comparison such as operator== +

    This proposal also includes a concept for specifying when an iterator +is interoperable with another iterator, in the sense that int* is +interoperable with int const*.

    +
      +
    • Interoperable Iterators
      • +

    The relationship between the new iterator concepts and the old are given in the following diagram.

    oldeqnew.png

    @@ -816,10 +823,144 @@ ordering relation
    +
    +

    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 +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 +met.

    + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ExpressionReturn TypeAssertion/Precondition/Postcondition
    y = xYpost: y == x
    x == yconvertible to bool== is an equivalence relation over its domain.
    y == xconvertible to bool== is an equivalence relation over its domain.
    x != yconvertible to boolbool(a==b) != bool(a!=b) over its domain.
    y != xconvertible to boolbool(a==b) != bool(a!=b) over its domain.
    +

    If the traversal tag for X and Y is convertible to +random_access_traversal_tag then the following requirements must +be met.

    + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ExpressionReturn TypeOperational SemanticsAssertion/ +Precondition
    x < yconvertible to booly - x > 0< is a total +ordering relation
    y < xconvertible to boolx - y > 0< is a total +ordering relation
    x > yconvertible to booly < x> is a total +ordering relation
    y > xconvertible to boolx < y> is a total +ordering relation
    x >= yconvertible to bool!(x < y) 
    y >= xconvertible to bool!(y < x) 
    x <= yconvertible to bool!(x > y) 
    y <= xconvertible to bool!(y > x) 
    y - xDistancex < y ?  distance(x,y) +: -distance(y,x)pre: there exists a +value n of +Distance such that +x + n == y. y +== x + (y - x).
    x - yDistancey < x ?  distance(y,x) +: -distance(x,y)pre: there exists a +value n of +Distance such that +y + n == x. x +== y + (x - y).
    +
    -

    Addition to [lib.iterator.synopsis]

    +

    Addition to [lib.iterator.synopsis]

     // lib.iterator.traits, traits and tags
 template <class Iterator> struct is_readable_iterator;
@@ -833,7 +974,7 @@ struct random_access_traversal_tag : bidirectional_traversal_tag { };
    -

    Addition to [lib.iterator.traits]

    +

    Addition to [lib.iterator.traits]

    The is_readable_iterator and iterator_traversal class templates satisfy the UnaryTypeTrait requirements.

    Given an iterator type X, is_readable_iterator<X>::value @@ -862,7 +1003,7 @@ traversal-category(X) =

    -

    Footnotes

    +

    Footnotes

    The UnaryTypeTrait concept is defined in n1519; the LWG added the requirement that specializations are derived from their nested ::type.

    @@ -878,7 +1019,7 @@ LocalWords: TraversalTag typename lvalues DWA Hmm JGS mis enum -->
    View document source. -Generated on: 2004-01-13 14:26 UTC. +Generated on: 2004-01-13 19:20 UTC. Generated by Docutils from reStructuredText source.
    diff --git a/doc/new-iter-concepts.rst b/doc/new-iter-concepts.rst index 679b1c8..05ee95e 100644 --- a/doc/new-iter-concepts.rst +++ b/doc/new-iter-concepts.rst @@ -291,6 +291,13 @@ reason for the fine grain slicing of the concepts into the Incrementable and Single Pass is to provide concepts that are exact matches with the original input and output iterator requirements. +This proposal also includes a concept for specifying when an iterator +is interoperable with another iterator, in the sense that ``int*`` is +interoperable with ``int const*``. + +- Interoperable Iterators + + The relationship between the new iterator concepts and the old are given in the following diagram. @@ -657,6 +664,79 @@ constant object of type ``Distance``. 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::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 +met. + ++-------------------------------------------+-------------------------------------------------+---------------------------------------------------+ +|Expression |Return Type |Assertion/Precondition/Postcondition | ++===========================================+=================================================+===================================================+ +|``y = x`` |``Y`` |post: ``y == x`` | ++-------------------------------------------+-------------------------------------------------+---------------------------------------------------+ +|``x == y`` |convertible to ``bool`` |``==`` is an equivalence relation over its domain. | ++-------------------------------------------+-------------------------------------------------+---------------------------------------------------+ +|``y == x`` |convertible to ``bool`` |``==`` is an equivalence relation over its domain. | ++-------------------------------------------+-------------------------------------------------+---------------------------------------------------+ +|``x != y`` |convertible to ``bool`` |``bool(a==b) != bool(a!=b)`` over its domain. | ++-------------------------------------------+-------------------------------------------------+---------------------------------------------------+ +|``y != x`` |convertible to ``bool`` |``bool(a==b) != bool(a!=b)`` over its domain. | ++-------------------------------------------+-------------------------------------------------+---------------------------------------------------+ + +If the traversal tag for ``X`` and ``Y`` is convertible to +``random_access_traversal_tag`` then the following requirements must +be met. + ++-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +|Expression |Return Type |Operational Semantics |Assertion/ | +| | | |Precondition | ++===========================================+=================================================+=========================+======================+ +|``x < y`` |convertible to ``bool`` |``y - x > 0`` |``<`` is a total | +| | | |ordering relation | ++-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +|``y < x`` |convertible to ``bool`` |``x - y > 0`` |``<`` is a total | +| | | |ordering relation | ++-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +|``x > y`` |convertible to ``bool`` |``y < x`` |``>`` is a total | +| | | |ordering relation | ++-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +|``y > x`` |convertible to ``bool`` |``x < y`` |``>`` is a total | +| | | |ordering relation | ++-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +|``x >= y`` |convertible to ``bool`` |``!(x < y)`` | | ++-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +|``y >= x`` |convertible to ``bool`` |``!(y < x)`` | | ++-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +|``x <= y`` |convertible to ``bool`` |``!(x > y)`` | | ++-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ +|``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| +| | | |``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 | +| | | |== y + (x - y)``. | ++-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+ + + + Addition to [lib.iterator.synopsis] ===================================