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