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

Add link to issue 96

Browse Source 
Add appropriate keys for the tables.
Kill meaningless "set of value types"
Fix random traversal interaction with a[n]


[SVN r1225]
This commit is contained in:
Dave Abrahams
2003-04-27 16:52:54 +00:00
parent 408bb7125f
commit a83891fb94
1 changed files with 88 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -68,6 +68,8 @@ requirements of input iterator and output iterator. This is so
nonintuitive that at least one implementation erroneously assigns nonintuitive that at least one implementation erroneously assigns
``random_access_iterator_tag`` as its ``iterator_category``. ``random_access_iterator_tag`` as its ``iterator_category``.
.. _issue 96: http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/lwg-active.html#96
Another difficult-to-categorize iterator is the transform iterator, an Another difficult-to-categorize iterator is the transform iterator, an
adaptor which applies a unary function object to the dereferenced adaptor which applies a unary function object to the dereferenced
value of the some underlying iterator (see `transform_iterator`_). value of the some underlying iterator (see `transform_iterator`_).
@@ -276,6 +278,13 @@ Addition to [lib.iterator.requirements]
Iterator Value Access Concepts [lib.iterator.value.access] Iterator Value Access Concepts [lib.iterator.value.access]
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
In the tables below, ``X`` is an iterator type, ``a`` is a constant
object of type ``X``, ``T`` is
``std::iterator_traits<X>::value_type``, and ``v`` is a constant
object of type ``T``.
.. _Readable Iterator:
Readable Iterators [lib.readable.iterators] Readable Iterators [lib.readable.iterators]
------------------------------------------- -------------------------------------------
@@ -302,24 +311,35 @@ member of type ``T``.
+--------------------------------------+---------------------------------------------------+-----------------------------------------------------------------+ +--------------------------------------+---------------------------------------------------+-----------------------------------------------------------------+
.. _Writable Iterator:
Writable Iterators [lib.writable.iterators] Writable Iterators [lib.writable.iterators]
------------------------------------------- -------------------------------------------
A class or built-in type ``X`` models the *Writable Iterator* concept A class or built-in type ``X`` models the *Writable Iterator* concept
if the following expressions are valid and respect the stated if the following expressions are valid and respect the stated
semantics. A type ``T`` belongs to the *set of value types* of ``X`` semantics.
if, for an object ``t`` of type ``T``, ``*a = t`` is valid.
+------------------------------------------------------------------------------------------------------------------------------+ .. A type ``T`` belongs to the *set of value types* of ``X``
| Writable Iterator Requirements (in addition to CopyConstructible) | if, for an object ``v`` of type ``T``, ``*a = v`` is valid.
+--------------------------------------+------------------------------------------+--------------------------------------------+
| Expression | Return Type | Assertion/Note/Precondition/Postcondition | ** This appears to be a mutual recursion which ends up meaning
+======================================+==========================================+============================================+ nothing. Kill the assertion column?
| ``access_category<X>::type`` | Convertible to ``writable_iterator_tag`` | |
+--------------------------------------+------------------------------------------+--------------------------------------------+ Separate but related question: Is a writable iterator required
| ``*a = t`` | | pre: The type of ``t`` is in the set of | to have a meaningful value_type? If not, we need to use a
| | | value types of ``X`` | different name from ``v`` in this table -DWA
+--------------------------------------+------------------------------------------+--------------------------------------------+
+------------------------------------------------------------------------------------------------------------------------------+
| Writable Iterator Requirements (in addition to CopyConstructible) |
+--------------------------------------+------------------------------------------+--------------------------------------------+
| Expression | Return Type | Assertion/Note/Precondition/Postcondition |
+======================================+==========================================+============================================+
| ``access_category<X>::type`` | Convertible to ``writable_iterator_tag`` | |
+--------------------------------------+------------------------------------------+--------------------------------------------+
| ``*a = v`` | | .. ** pre: The type of ``v`` is in the set |
| | | of value types of ``X`` |
+--------------------------------------+------------------------------------------+--------------------------------------------+
Swappable Iterators [lib.swappable.iterators] Swappable Iterators [lib.swappable.iterators]
@@ -380,6 +400,12 @@ iterator.
Iterator Traversal Concepts [lib.iterator.traversal] Iterator Traversal Concepts [lib.iterator.traversal]
++++++++++++++++++++++++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++++++++++++++++++++++++
In the tables below, ``X`` is an iterator type, ``a`` and ``b`` are
constant objects of type ``X``, ``r`` and ``s`` are mutable objects of
type ``X``, ``T`` is ``std::iterator_traits<X>::value_type``, and
``v`` is a constant object of type ``T``.
Incrementable Iterators [lib.incrementable.iterators] Incrementable Iterators [lib.incrementable.iterators]
----------------------------------------------------- -----------------------------------------------------
@@ -460,8 +486,8 @@ the stated semantics.
| | |``--r == --s`` implies ``r == s``. ``&r == &--r``. | | | |``--r == --s`` implies ``r == s``. ``&r == &--r``. |
+-----------------------------------------+-------------+-----------------------------------------------------+ +-----------------------------------------+-------------+-----------------------------------------------------+
|``r--`` |convertible |``{ X tmp = r; --r; return tmp; }`` | |``r--`` |convertible |``{ X tmp = r; --r; return tmp; }`` |
| |to const | | | |to ``const | |
| |``X&`` | | | |X&`` | |
+-----------------------------------------+-------------+-----------------------------------------------------+ +-----------------------------------------+-------------+-----------------------------------------------------+
| ``traversal_category<X>::type`` | | Convertible to | | ``traversal_category<X>::type`` | | Convertible to |
| | | ``bidirectional_traversal_iterator_tag`` | | | | ``bidirectional_traversal_iterator_tag`` |
@@ -474,44 +500,55 @@ Random Access Traversal Iterators [lib.random.access.traversal.iterators]
A class or built-in type ``X`` models the *Random Access Traversal A class or built-in type ``X`` models the *Random Access Traversal
Iterator* concept if the following expressions are valid and respect Iterator* concept if the following expressions are valid and respect
the stated semantics. 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) | | Random Access Traversal Iterator Requirements (in addition to Bidirectional Traversal Iterator) |
+--------------------------------+---------------------------------------+------------------------------+----------------------------------------+ +--------------------------------+---------------------------------------+--------------------------+----------------------------------------+
| Expression | Return Type | Operational Semantics | Assertion/Note/Pre/Post-condition | | Expression | Return Type | Operational Semantics | Assertion/Note/Pre/Post-condition |
+================================+=======================================+==============================+========================================+ +================================+=======================================+==========================+========================================+
|``r += n`` | ``X&`` |``{ Distance m = n; if (m >= | | |``r += n`` | ``X&`` |:: | |
| | |0) while (m--) ++r; else while| | | | | | |
| | |(m++) --r; return r; }`` | | | | | { | |
+--------------------------------+---------------------------------------+------------------------------+----------------------------------------+ | | | Distance m = n; | |
| ``a + n``, ``n + a`` | ``X`` |``{ X tmp = a; return tmp += | | | | | if (m >= 0) | |
| | |n; }`` | | | | | 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`` | | |``r -= n`` | ``X&`` |``return r += -n`` | |
+--------------------------------+---------------------------------------+------------------------------+----------------------------------------+ +--------------------------------+---------------------------------------+--------------------------+----------------------------------------+
|``a - n`` | ``X`` |``{ X tmp = a; return tmp -= | | |``a - n`` | ``X`` |``{ X tmp = a; return tmp | |
| | |n; }`` | | | | |-= n; }`` | |
+--------------------------------+---------------------------------------+------------------------------+----------------------------------------+ +--------------------------------+---------------------------------------+--------------------------+----------------------------------------+
|``b - a`` |``Distance`` |``a < b ? distance(a,b) : |pre: there exists a value ``n`` of | |``b - a`` |``Distance`` |``a < b ? distance(a,b) : |pre: there exists a value ``n`` of |
| | |-distance(b,a)`` |``Distance`` such that ``a + n == b``. | | | |-distance(b,a)`` |``Distance`` such that ``a + n == b``. |
| | | |``b == a + (b - a)``. | | | | |``b == a + (b - a)``. |
+--------------------------------+---------------------------------------+------------------------------+----------------------------------------+ +--------------------------------+---------------------------------------+--------------------------+----------------------------------------+
|``a[n]`` |convertible to T |``*(a + n)`` |Not required to return an lvalue | |``a[n]`` |convertible to T |``*(a + n)`` |pre: a is a `readable iterator`_ |
+--------------------------------+---------------------------------------+------------------------------+----------------------------------------+ +--------------------------------+---------------------------------------+--------------------------+----------------------------------------+
|``a[n] = t`` |convertible to T |``*(a + n) = t`` |Not required to return an lvalue | |``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 > 0`` |``<`` is a total ordering relation |
+--------------------------------+---------------------------------------+------------------------------+----------------------------------------+ +--------------------------------+---------------------------------------+--------------------------+----------------------------------------+
|``a > b`` |convertible to ``bool`` |``b < a`` |``>`` 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)`` | |
+--------------------------------+---------------------------------------+------------------------------+----------------------------------------+ +--------------------------------+---------------------------------------+--------------------------+----------------------------------------+
|``a <= b`` |convertible to ``bool`` |``!(a > b)`` | | |``a <= b`` |convertible to ``bool`` |``!(a > b)`` | |
+--------------------------------+---------------------------------------+------------------------------+----------------------------------------+ +--------------------------------+---------------------------------------+--------------------------+----------------------------------------+
| ``traversal_category<X>::type``| | |Convertible to | |``traversal_category<X>::type`` | | |Convertible to |
| | | |``random_access_traversal_iterator_tag``| | | | |``random_access_traversal_iterator_tag``|
+--------------------------------+---------------------------------------+------------------------------+----------------------------------------+ +--------------------------------+---------------------------------------+--------------------------+----------------------------------------+