diff --git a/doc/facade-and-adaptor.rst b/doc/facade-and-adaptor.rst index 961ecc9..e5e30cb 100755 --- a/doc/facade-and-adaptor.rst +++ b/doc/facade-and-adaptor.rst @@ -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 issues. -Issue `179`_ adresses the question that the standard currently only requires mutable -container iterator types to be convertible the corresponding constant iterator -types. This is tedious in praxis and out of line with the way built in types work. -This proposal implements the proposed resolution to issue `179`_, as most -standard library implementations do nowadays. I.e. if an iterator type A has an -implicit or user defined conversion to an iterator typ B the iterator types -are interoperable and the usual set of operators is supplied. +Issue `179`_ concerns the fact that mutable container iterator types +are only required to be convertible the corresponding constant +iterator types, but objects of these types are not required to +interoperate in comparison or subtraction expressions. This situation +is tedious in practice and out of line with the way built in types +work. This proposal implements the proposed resolution to issue +`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 -types. The proposed new reverse_iterator template fixes the issues raised in -280. It provides the desired interoperability without introducing unwanted overloads. +Issue `280`_ concerns the current lack of interoperability between +reverse iterator types. The proposed new reverse_iterator template +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 .. _`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: ``value_type``, ``reference``, ``pointer``, and ``iterator_category``. -Iterator facade uses the ``Curiously Recurring Template`` technique so that -the user can specifiy the behaviour of ``iterator_facade`` in a derived class. -Former designs used policy objects to specifiy the behaviour. -The proposal does not use policy objects for two reasons. First the creation -and eventual copying of the policy object may create overhead that can be -avoided with the current approach. Second the policy object approach -does not allow for custom constructors on the created iterator types. -The latter is an essential feature if ``iterator_facade`` should be used -in other library implementations. +Iterator facade uses the Curiously Recurring Template Pattern (CRTP) +[Cop95]_ so that the user can specifiy the behaviour of +``iterator_facade`` in a derived class. Former designs used policy +objects to specifiy the behaviour. The proposal does not use policy +objects for several reasons: + + 1. the creation and eventual copying of the policy object may create + overhead that can be avoided with the current approach. + + 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 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 object of type ``X``, ``b`` and ``c`` are objects of type ``const X``, -``y`` is a constant object of an arbitrary interoperable iterator type, -and ``n`` is an object of ``X::difference_type`` +``n`` is an object of ``X::difference_type``, ``y`` is a constant +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) | @@ -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(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``. | | +----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+ | ``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(y)`` | convertible to X::difference_type |equivalent to ``distance(c, y)``. Implements ``c| | -| | |- y``, ``c < y``, ``c <= y``, ``c > y``, and ``c | | +| ``c.distance_to(z)`` | convertible to X::difference_type |equivalent to ``distance(c, z)``. Implements ``c| Random Access Traversal Iterator | +| | |- z``, ``c < z``, ``c <= z``, ``c > z``, and ``c | | | | |>= c``. | | +----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+ @@ -210,35 +228,38 @@ and ``n`` is an object of ``X::difference_type`` Iterator Core Access ==================== -``iterator_facade`` and the operator implementations need to be able to access the core -interface member functions in the derived class. Making the core interface -member funtions public would expose an implementation detail to the user. -This proposal frees the public interface of the derived iterator type from -any implementation detail. +``iterator_facade`` and the operator implementations need to be able +to access the core interface member functions in the derived class. +Making the core interface member funtions public would expose an +implementation detail to the user. This proposal frees the public +interface of the derived iterator type from any implementation detail. -This has two advantages. First there is no possibility for the user to accidently -use a member function of the iterator when a member of the value_type was -intended. This has been an issue with smart pointer implementations in -the past. The second and main advantage is that library implementers -can freely swap between ``iterator_facade`` based and custom iterator -implementations. If the iterator core interface is public users -will probably start using it. +Preventing direct access to the core interface has two advantages. +First, there is no possibility for the user to accidently use a member +function of the iterator when a member of the value_type was intended. +This has been an issue with smart pointer implementations in the past. +The second and main advantage is that library implementers can freely +exchange a hand-rolled iterator implementation for one based on +``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 -friendship to ``iterator_facade`` and to the seven operators. In order to -simplify this the proposal provides a type ``iterator_core_access`` that acts -as a gateway to the core interface in the derived iterator class. -The author of the derived class only needs to grant friendship to -``iterator_core_access``. +In a naive implementation, keeping the derived class' core interface +private would require it to grant friendship to ``iterator_facade`` +and each of the seven operators. In order to reduce the burden of +limiting access, this proposal provides ``iterator_core_access``, a +class that acts as a gateway to the core interface in the derived +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 -class containing only static member functions that forward to the -iterator core interface. There is no need to standardize the gateway -protocoll. +class containing only static member functions which invoke the +iterator core interface. There is, however, no need to standardize the +gateway protocol. It is important to note that ``iterator_core_access`` does not open a -loophole, as every function in the core interface preserves the invariants -of the iterator. +safety loophole, as every function in the core interface preserves the +invariants of the iterator. 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.