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

cleaned up language a bit

Browse Source 
[SVN r1171]
This commit is contained in:
Dave Abrahams
2003-04-23 00:35:43 +00:00
parent c47566a424
commit c08669e6e4
1 changed files with 70 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

117
doc/facade-and-adaptor.rst
View File

@@ -125,17 +125,21 @@ The question of iterator interoperability is poorly adressed in the current stan
There are currently two defect reports that are concerned with interoperability There are currently two defect reports that are concerned with interoperability
issues. issues.
Issue `179`_ adresses the question that the standard currently only requires mutable Issue `179`_ concerns the fact that mutable container iterator types
container iterator types to be convertible the corresponding constant iterator are only required to be convertible the corresponding constant
types. This is tedious in praxis and out of line with the way built in types work. iterator types, but objects of these types are not required to
This proposal implements the proposed resolution to issue `179`_, as most interoperate in comparison or subtraction expressions. This situation
standard library implementations do nowadays. I.e. if an iterator type A has an is tedious in practice and out of line with the way built in types
implicit or user defined conversion to an iterator typ B the iterator types work. This proposal implements the proposed resolution to issue
are interoperable and the usual set of operators is supplied. `179`_, as most standard library implementations do nowadays. In other
words, if an iterator type A has an implicit or user defined
conversion to an iterator type B, the iterator types are interoperable
and the usual set of operators are available.
Issue `280`_ is about the current lack of interoperability between reverse iterator Issue `280`_ concerns the current lack of interoperability between
types. The proposed new reverse_iterator template fixes the issues raised in reverse iterator types. The proposed new reverse_iterator template
280. It provides the desired interoperability without introducing unwanted overloads. fixes the issues raised in 280. It provides the desired
interoperability without introducing unwanted overloads.
.. _`179`: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-defects.html#179 .. _`179`: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-defects.html#179
.. _`280`: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-active.html#280 .. _`280`: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-active.html#280
@@ -159,15 +163,27 @@ In addition to the behaviors listed above, the core interface elements
include the associated types exposed through iterator traits: include the associated types exposed through iterator traits:
``value_type``, ``reference``, ``pointer``, and ``iterator_category``. ``value_type``, ``reference``, ``pointer``, and ``iterator_category``.
Iterator facade uses the ``Curiously Recurring Template`` technique so that Iterator facade uses the Curiously Recurring Template Pattern (CRTP)
the user can specifiy the behaviour of ``iterator_facade`` in a derived class. [Cop95]_ so that the user can specifiy the behaviour of
Former designs used policy objects to specifiy the behaviour. ``iterator_facade`` in a derived class. Former designs used policy
The proposal does not use policy objects for two reasons. First the creation objects to specifiy the behaviour. The proposal does not use policy
and eventual copying of the policy object may create overhead that can be objects for several reasons:
avoided with the current approach. Second the policy object approach
does not allow for custom constructors on the created iterator types. 1. the creation and eventual copying of the policy object may create
The latter is an essential feature if ``iterator_facade`` should be used overhead that can be avoided with the current approach.
in other library implementations.
2. The policy object approach does not allow for custom constructors
on the created iterator types, an essential feature if
``iterator_facade`` should be used in other library
implementations.
3. Without the use of CRTP, the standard requirement that an
iterator's ``operator++`` returns the iterator type itself means
that all iterators generated by ``iterator_facade`` would be
instantiations of ``iterator_facade``. Cumbersome type generator
metafunctions would be needed to build new parameterized
iterators, and a separate ``iterator_adaptor`` layer would be
impossible.
The user of ``iterator_facade`` derives his iterator class from an The user of ``iterator_facade`` derives his iterator class from an
instantiation of ``iterator_facade`` and defines member functions instantiation of ``iterator_facade`` and defines member functions
@@ -177,8 +193,10 @@ of the derived iterator type.
In the table below, ``X`` is the derived iterator type, ``a`` is an In the table below, ``X`` is the derived iterator type, ``a`` is an
object of type ``X``, ``b`` and ``c`` are objects of type ``const X``, object of type ``X``, ``b`` and ``c`` are objects of type ``const X``,
``y`` is a constant object of an arbitrary interoperable iterator type, ``n`` is an object of ``X::difference_type``, ``y`` is a constant
and ``n`` is an object of ``X::difference_type`` object of a single pass iterator type interoperable with X, and ``z``
is a constant object of a random access traversal iterator type
interoperable with X.
+----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+ +----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+
| Expression | Return Type | Assertion/Note/Precondition/Postcondition | Required to implement Iterator Concept(s) | | Expression | Return Type | Assertion/Note/Precondition/Postcondition | Required to implement Iterator Concept(s) |
@@ -188,7 +206,7 @@ and ``n`` is an object of ``X::difference_type``
+----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+ +----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+
| ``c.equal(b)`` | convertible to bool |true iff ``b`` and ``c`` are equivalent. | Single Pass Iterator | | ``c.equal(b)`` | convertible to bool |true iff ``b`` and ``c`` are equivalent. | Single Pass Iterator |
+----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+ +----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+
| ``c.equal(y)`` | convertible to bool |true iff ``c`` and ``y`` refer to the same | | | ``c.equal(y)`` | convertible to bool |true iff ``c`` and ``y`` refer to the same | Single Pass Iterator |
| | |position. Implements ``c == y`` and ``c != y``. | | | | |position. Implements ``c == y`` and ``c != y``. | |
+----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+ +----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+
| ``a.advance(n)`` | unused | | Random Access Traversal Iterator | | ``a.advance(n)`` | unused | | Random Access Traversal Iterator |
@@ -199,8 +217,8 @@ and ``n`` is an object of ``X::difference_type``
+----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+ +----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+
| ``c.distance_to(b)`` | convertible to X::difference_type | equivalent to ``distance(c, b)`` | Random Access Traversal Iterator | | ``c.distance_to(b)`` | convertible to X::difference_type | equivalent to ``distance(c, b)`` | Random Access Traversal Iterator |
+----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+ +----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+
| ``c.distance_to(y)`` | convertible to X::difference_type |equivalent to ``distance(c, y)``. Implements ``c| | | ``c.distance_to(z)`` | convertible to X::difference_type |equivalent to ``distance(c, z)``. Implements ``c| Random Access Traversal Iterator |
| | |- y``, ``c < y``, ``c <= y``, ``c > y``, and ``c | | | | |- z``, ``c < z``, ``c <= z``, ``c > z``, and ``c | |
| | |>= c``. | | | | |>= c``. | |
+----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+ +----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+
@@ -210,35 +228,38 @@ and ``n`` is an object of ``X::difference_type``
Iterator Core Access Iterator Core Access
==================== ====================
``iterator_facade`` and the operator implementations need to be able to access the core ``iterator_facade`` and the operator implementations need to be able
interface member functions in the derived class. Making the core interface to access the core interface member functions in the derived class.
member funtions public would expose an implementation detail to the user. Making the core interface member funtions public would expose an
This proposal frees the public interface of the derived iterator type from implementation detail to the user. This proposal frees the public
any implementation detail. interface of the derived iterator type from any implementation detail.
This has two advantages. First there is no possibility for the user to accidently Preventing direct access to the core interface has two advantages.
use a member function of the iterator when a member of the value_type was First, there is no possibility for the user to accidently use a member
intended. This has been an issue with smart pointer implementations in function of the iterator when a member of the value_type was intended.
the past. The second and main advantage is that library implementers This has been an issue with smart pointer implementations in the past.
can freely swap between ``iterator_facade`` based and custom iterator The second and main advantage is that library implementers can freely
implementations. If the iterator core interface is public users exchange a hand-rolled iterator implementation for one based on
will probably start using it. ``iterator_facade`` without fear of breaking code that was accessing
the public core interface directly.
In order to make the core interface public the derived class needs to grant In a naive implementation, keeping the derived class' core interface
friendship to ``iterator_facade`` and to the seven operators. In order to private would require it to grant friendship to ``iterator_facade``
simplify this the proposal provides a type ``iterator_core_access`` that acts and each of the seven operators. In order to reduce the burden of
as a gateway to the core interface in the derived iterator class. limiting access, this proposal provides ``iterator_core_access``, a
The author of the derived class only needs to grant friendship to class that acts as a gateway to the core interface in the derived
``iterator_core_access``. iterator class. The author of the derived class only needs to grant
friendship to ``iterator_core_access`` to make his core interface
available to the library.
``iterator_core_access`` would be typically implemented as an empty ``iterator_core_access`` would be typically implemented as an empty
class containing only static member functions that forward to the class containing only static member functions which invoke the
iterator core interface. There is no need to standardize the gateway iterator core interface. There is, however, no need to standardize the
protocoll. gateway protocol.
It is important to note that ``iterator_core_access`` does not open a It is important to note that ``iterator_core_access`` does not open a
loophole, as every function in the core interface preserves the invariants safety loophole, as every function in the core interface preserves the
of the iterator. invariants of the iterator.
Iterator Adaptor Iterator Adaptor
================ ================
@@ -459,3 +480,5 @@ Standard compliant iterators).
.. [Cop95] [Coplien, 1995] Coplien, J., Curiously Recurring Template
Patterns, C ++Report, February 1995, pp. 24-27.