feedc0de/boost_iterator
1
0
Fork 0
forked from boostorg/iterator
Code Pull Requests Activity

Fixed up definition of facade's iterator_category

Browse Source 
fixed table widths in new-iter-concepts

cross-referenced interoperability concept in iterator_facade_tutorial

iterator_traversal can't satisfy UnaryTypeTrait: that's a boolean trait.


[SVN r21742]
This commit is contained in:
Dave Abrahams
2004-01-14 23:23:54 +00:00
parent 42147b9e86
commit f1f6262be7
7 changed files with 394 additions and 318 deletions
Download Patch File Download Diff File Expand all files Collapse all files

317
doc/new-iter-concepts.rst
View File

@ -430,20 +430,20 @@ The *Lvalue Iterator* concept adds the requirement that the return
type of ``operator*`` type be a reference to the value type of the
iterator.
+---------------------------------------------------------------------------------+
| Lvalue Iterator Requirements |
+---------------------------------+-----------+-----------------------------------+
|Expression |Return Type|Note/Assertion |
+=================================+===========+===================================+
|``*a`` | ``T&`` |``T`` is *cv* |
| | |``iterator_traits<X>::value_type`` |
| | |where *cv* is an optional |
| | |cv-qualification. |
| | |pre: ``a`` is |
| | |dereferenceable. If ``a |
| | |== b`` then ``*a`` is |
| | |equivalent to ``*b``. |
+---------------------------------+-----------+-----------------------------------+
+-------------------------------------------------------------+
| Lvalue Iterator Requirements |
+-------------+-----------+-----------------------------------+
|Expression |Return Type|Note/Assertion |
+=============+===========+===================================+
|``*a`` | ``T&`` |``T`` is *cv* |
| | |``iterator_traits<X>::value_type`` |
| | |where *cv* is an optional |
| | |cv-qualification. |
| | |pre: ``a`` is |
| | |dereferenceable. If ``a |
| | |== b`` then ``*a`` is |
| | |equivalent to ``*b``. |
+-------------+-----------+-----------------------------------+
@ -561,34 +561,35 @@ Iterator* concept if, in addition to ``X`` meeting the requirements of
Forward Traversal Iterator, the following expressions are valid and
respect the stated semantics.
+--------------------------------------------------------------------------------------------------------+
|Bidirectional Traversal Iterator Requirements (in addition to Forward Traversal Iterator) |
+------------------------------------+---------------------------------------------+---------------------+
|Expression |Return Type |Assertion/Semantics /|
| | |Pre-/Post-condition |
+====================================+=============================================+=====================+
|``--r`` |``X&`` |pre: there exists |
| | |``s`` such that ``r |
| | |== ++s``. post: |
| | |``s`` is |
| | |dereferenceable. |
| | |``--(++r) == r``. |
| | |``--r == --s`` |
| | |implies ``r == |
| | |s``. ``&r == &--r``. |
+------------------------------------+---------------------------------------------+---------------------+
|``r--`` |convertible to ``const X&`` |:: |
| | | |
| | | { |
| | | X tmp = r; |
| | | --r; |
| | | return tmp; |
| | | } |
+------------------------------------+---------------------------------------------+---------------------+
|``iterator_traversal<X>::type`` |Convertible to | |
| |``bidirectional_traversal_tag`` | |
| | | |
+------------------------------------+---------------------------------------------+---------------------+
+--------------------------------------------------------------------------------------+
|Bidirectional Traversal Iterator Requirements (in addition to Forward Traversal |
|Iterator) |
+--------------------------------+-------------------------------+---------------------+
|Expression |Return Type |Assertion/Semantics /|
| | |Pre-/Post-condition |
+================================+===============================+=====================+
|``--r`` |``X&`` |pre: there exists |
| | |``s`` such that ``r |
| | |== ++s``. post: |
| | |``s`` is |
| | |dereferenceable. |
| | |``--(++r) == r``. |
| | |``--r == --s`` |
| | |implies ``r == |
| | |s``. ``&r == &--r``. |
+--------------------------------+-------------------------------+---------------------+
|``r--`` |convertible to ``const X&`` |:: |
| | | |
| | | { |
| | | X tmp = r; |
| | | --r; |
| | | return tmp; |
| | | } |
+--------------------------------+-------------------------------+---------------------+
|``iterator_traversal<X>::type`` |Convertible to | |
| |``bidirectional_traversal_tag``| |
| | | |
+--------------------------------+-------------------------------+---------------------+
.. TR1: bidirectional_traversal_iterator_tag changed to
bidirectional_traversal_tag for consistency
@ -602,60 +603,60 @@ the stated semantics. In the table below, ``Distance`` is
``iterator_traits<X>::difference_type`` and ``n`` represents a
constant object of type ``Distance``.
+----------------------------------------------------------------------------------------------------------------------------------------------+
|Random Access Traversal Iterator Requirements (in addition to Bidirectional Traversal Iterator) |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
|Expression |Return Type |Operational Semantics |Assertion/ |
| | | |Precondition |
+===========================================+=================================================+=========================+======================+
|``r += n`` |``X&`` |:: | |
| | | | |
| | | { | |
| | | Distance m = n; | |
| | | if (m >= 0) | |
| | | while (m--) | |
| | | ++r; | |
| | | else | |
| | | while (m++) | |
| | | --r; | |
| | | return r; | |
| | | } | |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
|``a + n``, ``n + a`` |``X`` |``{ X tmp = a; return tmp| |
| | |+= n; }`` | |
| | | | |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
|``r -= n`` |``X&`` |``return r += -n`` | |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
|``a - n`` |``X`` |``{ X tmp = a; return tmp| |
| | |-= n; }`` | |
| | | | |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
|``b - a`` |``Distance`` |``a < b ? distance(a,b) |pre: there exists a |
| | |: -distance(b,a)`` |value ``n`` of |
| | | |``Distance`` such that|
| | | |``a + n == b``. ``b |
| | | |== a + (b - a)``. |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
|``a[n]`` |convertible to T |``*(a + n)`` |pre: a is a `readable |
| | | |iterator`_ |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
|``a[n] = v`` |convertible to T |``*(a + n) = v`` |pre: a is a `writable |
| | | |iterator`_ |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
|``a < b`` |convertible to ``bool`` |``b - a > 0`` |``<`` is a total |
| | | |ordering relation |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
|``a > b`` |convertible to ``bool`` |``b < a`` |``>`` is a total |
| | | |ordering relation |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
|``a >= b`` |convertible to ``bool`` |``!(a < b)`` | |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
|``a <= b`` |convertible to ``bool`` |``!(a > b)`` | |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
|``iterator_traversal<X>::type`` |Convertible to | | |
| |``random_access_traversal_tag`` | | |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
+------------------------------------------------------------------------------------------------------------------+
|Random Access Traversal Iterator Requirements (in addition to Bidirectional Traversal Iterator) |
+-------------------------------+---------------------------------+-------------------------+----------------------+
|Expression |Return Type |Operational Semantics |Assertion/ |
| | | |Precondition |
+===============================+=================================+=========================+======================+
|``r += n`` |``X&`` |:: | |
| | | | |
| | | { | |
| | | Distance m = n; | |
| | | if (m >= 0) | |
| | | while (m--) | |
| | | ++r; | |
| | | else | |
| | | while (m++) | |
| | | --r; | |
| | | return r; | |
| | | } | |
+-------------------------------+---------------------------------+-------------------------+----------------------+
|``a + n``, ``n + a`` |``X`` |``{ X tmp = a; return tmp| |
| | |+= n; }`` | |
| | | | |
+-------------------------------+---------------------------------+-------------------------+----------------------+
|``r -= n`` |``X&`` |``return r += -n`` | |
+-------------------------------+---------------------------------+-------------------------+----------------------+
|``a - n`` |``X`` |``{ X tmp = a; return tmp| |
| | |-= n; }`` | |
| | | | |
+-------------------------------+---------------------------------+-------------------------+----------------------+
|``b - a`` |``Distance`` |``a < b ? distance(a,b) |pre: there exists a |
| | |: -distance(b,a)`` |value ``n`` of |
| | | |``Distance`` such that|
| | | |``a + n == b``. ``b |
| | | |== a + (b - a)``. |
+-------------------------------+---------------------------------+-------------------------+----------------------+
|``a[n]`` |convertible to T |``*(a + n)`` |pre: a is a `readable |
| | | |iterator`_ |
+-------------------------------+---------------------------------+-------------------------+----------------------+
|``a[n] = v`` |convertible to T |``*(a + n) = v`` |pre: a is a `writable |
| | | |iterator`_ |
+-------------------------------+---------------------------------+-------------------------+----------------------+
|``a < b`` |convertible to ``bool`` |``b - a > 0`` |``<`` is a total |
| | | |ordering relation |
+-------------------------------+---------------------------------+-------------------------+----------------------+
|``a > b`` |convertible to ``bool`` |``b < a`` |``>`` is a total |
| | | |ordering relation |
+-------------------------------+---------------------------------+-------------------------+----------------------+
|``a >= b`` |convertible to ``bool`` |``!(a < b)`` | |
+-------------------------------+---------------------------------+-------------------------+----------------------+
|``a <= b`` |convertible to ``bool`` |``!(a > b)`` | |
+-------------------------------+---------------------------------+-------------------------+----------------------+
|``iterator_traversal<X>::type``|Convertible to | | |
| |``random_access_traversal_tag`` | | |
+-------------------------------+---------------------------------+-------------------------+----------------------+
.. TR1: random_access_traversal_iterator_tag changed to
random_access_traversal_tag for consistency
@ -672,61 +673,52 @@ 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``.
+-------------------------------------------+-------------------------------------------------+---------------------------------------------------+
|Expression |Return Type |Assertion/Precondition/Postcondition |
+===========================================+=================================================+===================================================+
|``y = x`` |``Y`` |post: ``y == x`` |
+-------------------------------------------+-------------------------------------------------+---------------------------------------------------+
|``Y(x)`` |``Y`` |post: ``Y(x) == 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. |
+-------------------------------------------+-------------------------------------------------+---------------------------------------------------+
+-----------+-----------------------+---------------------------------------------------+
|Expression |Return Type |Assertion/Precondition/Postcondition |
+===========+=======================+===================================================+
|``y = x`` |``Y`` |post: ``y == x`` |
+-----------+-----------------------+---------------------------------------------------+
|``Y(x)`` |``Y`` |post: ``Y(x) == 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 ``X`` and ``Y`` both model Random Access Traversal Iterator then
the following additional 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`` |``distance(Y(x),y)`` |pre: there exists a |
| | | |value ``n`` of |
| | | |``Distance`` such that|
| | | |``x + n == y``. ``y |
| | | |== x + (y - x)``. |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
|``x - y`` |``Distance`` |``distance(y,Y(x))`` |pre: there exists a |
| | | |value ``n`` of |
| | | |``Distance`` such that|
| | | |``y + n == x``. ``x |
| | | |== y + (x - y)``. |
+-------------------------------------------+-------------------------------------------------+-------------------------+----------------------+
+-----------+-----------------------+---------------------+--------------------------------------+
|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`` |``distance(Y(x),y)`` |pre: there exists a value ``n`` of |
| | | |``Distance`` such that ``x + n == y``.|
| | | |``y == x + (y - x)``. |
+-----------+-----------------------+---------------------+--------------------------------------+
|``x - y`` |``Distance`` |``distance(y,Y(x))`` |pre: there exists a value ``n`` of |
| | | |``Distance`` such that ``y + n == x``.|
| | | |``x == y + (x - y)``. |
+-----------+-----------------------+---------------------+--------------------------------------+
@ -749,31 +741,38 @@ Addition to [lib.iterator.synopsis]
Addition to [lib.iterator.traits]
=================================
The ``is_readable_iterator`` and ``iterator_traversal`` class
templates satisfy the UnaryTypeTrait_ requirements.
The ``is_readable_iterator`` class
template satisfies the UnaryTypeTrait_ requirements.
Given an iterator type ``X``, ``is_readable_iterator<X>::value``
yields ``true`` if, for an object ``a`` of type ``X``, ``*a`` is
convertible to ``iterator_traits<X>::value_type``, and ``false``
otherwise.
``iterator_traversal<X>::type`` is defined to be:
``iterator_traversal<X>::type`` is
.. parsed-literal::
traversal-category(X) =
cat = iterator_traits<X>::iterator_category;
if (cat is convertible to incrementable_traversal_tag)
return cat;
else if (cat is convertible to random_access_iterator_tag)
*category-to-traversal*\ (iterator_traits<X>::iterator_category)
where *category-to-traversal* is defined as follows
.. _`category-to-traversal`:
.. parsed-literal::
*category-to-traversal*\ (C) =
if (C is convertible to incrementable_traversal_tag)
return C;
else if (C is convertible to random_access_iterator_tag)
return random_access_traversal_tag;
else if (cat is convertible to bidirectional_iterator_tag)
else if (C is convertible to bidirectional_iterator_tag)
return bidirectional_traversal_tag;
else if (cat is convertible to forward_iterator_tag)
else if (C is convertible to forward_iterator_tag)
return forward_traversal_tag;
else if (cat is convertible to input_iterator_tag)
else if (C is convertible to input_iterator_tag)
return single_pass_traversal_tag;
else if (cat is convertible to output_iterator_tag)
else if (C is convertible to output_iterator_tag)
return incrementable_traversal_tag;
else
*the program is ill-formed*