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

edits and commentary

Browse Source 
[SVN r1183]
This commit is contained in:
Dave Abrahams
2003-04-25 14:39:47 +00:00
parent 4126ea29ed
commit 4bc2915135
1 changed files with 80 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -14,8 +14,8 @@
.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de .. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de
:abstract: We propose a set of class templates that help programmers :abstract: We propose a set of class templates that help programmers
build standard-conforming iterators and iterators build standard-conforming iterators, both from scratch and
that adapt other iterators. by adapting other iterators.
.. contents:: Table of Contents .. contents:: Table of Contents
@@ -190,38 +190,24 @@ 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
implementing the core behaviors. The following table describes implementing the core behaviors. The following table describes
expressions which are required to be valid depending on the category expressions which are required to be valid depending on the category
of the derived iterator type. of the derived iterator type. These member functions are described
briefly below and in more detail in the `iterator facade requirements`_.
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``, | Expression | Effects |
``n`` is an object of ``X::difference_type``, ``y`` is a constant +========================================+===========================================+
object of a single pass iterator type interoperable with X, and ``z`` | ``i.dereference()`` | Access the value referred to |
is a constant object of a random access traversal iterator type +----------------------------------------+-------------------------------------------+
interoperable with X. | ``i.equal(j)`` | Compare for equality with ``j`` |
+----------------------------------------+-------------------------------------------+
+----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+ | ``i.increment()`` | Advance by one position |
| Expression | Return Type | Assertion/Note/Precondition/Postcondition | Required to implement Iterator Concept(s) | +----------------------------------------+-------------------------------------------+
| | | | | | ``i.decrement()`` | Retreat by one position |
+========================================+========================================+=================================================+===========================================+ +----------------------------------------+-------------------------------------------+
| ``c.dereference()`` | ``X::reference`` | | Readable Iterator, Writable Iterator | | ``i.advance(n)`` | Advance by ``n`` positions |
+----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+ +----------------------------------------+-------------------------------------------+
| ``c.equal(b)`` | convertible to bool |true iff ``b`` and ``c`` are equivalent. | Single Pass Iterator | | ``i.distance_to(j)`` | Measure the distance to ``j`` |
+----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+ +----------------------------------------+-------------------------------------------+
| ``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 |
+----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+
| ``a.increment()`` | unused | | Incrementable Iterator |
+----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+
| ``a.decrement()`` | unused | | Bidirectional Traversal Iterator |
+----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+
| ``c.distance_to(b)`` | convertible to X::difference_type | equivalent to ``distance(c, b)`` | Random Access Traversal Iterator |
+----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+
| ``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``. | |
+----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+
.. Should we add a comment that a zero overhead implementation of iterator_facade .. Should we add a comment that a zero overhead implementation of iterator_facade
is possible with proper inlining? is possible with proper inlining?
@@ -330,8 +316,8 @@ which were easily implemented using ``iterator_adaptor``:
Based on examples in the Boost library, users have generated many new Based on examples in the Boost library, users have generated many new
adaptors, among them a permutation adaptor which applies some adaptors, among them a permutation adaptor which applies some
permutation to a Random Access Iterator, and a strided adaptor, which permutation to a random access iterator, and a strided adaptor, which
adapts a Random Access Iterator by multiplying its unit of motion by a adapts a random access iterator by multiplying its unit of motion by a
constant factor. In addition, the Boost Graph Library (BGL) uses constant factor. In addition, the Boost Graph Library (BGL) uses
iterator adaptors to adapt other graph libraries, such as LEDA [10] iterator adaptors to adapt other graph libraries, such as LEDA [10]
and Stanford GraphBase [8], to the BGL interface (which requires C++ and Stanford GraphBase [8], to the BGL interface (which requires C++
@@ -349,7 +335,7 @@ Header ``<iterator_helper>`` synopsis [lib.iterator.helper.synopsis]
:: ::
struct use_default { }; struct use_default;
struct iterator_core_access { /* implementation detail */ }; struct iterator_core_access { /* implementation detail */ };
@@ -408,6 +394,7 @@ Header ``<iterator_helper>`` synopsis [lib.iterator.helper.synopsis]
Iterator facade [lib.iterator.facade] Iterator facade [lib.iterator.facade]
===================================== =====================================
The iterator requirements define a rich interface, containing many The iterator requirements define a rich interface, containing many
redundant operators, so that using iterators is convenient. The redundant operators, so that using iterators is convenient. The
``iterator_facade`` class template makes it easier to create iterators ``iterator_facade`` class template makes it easier to create iterators
@@ -416,7 +403,30 @@ few core functions. The user of ``iterator_facade`` derives his
iterator class from an instantiation of ``iterator_facade`` and iterator class from an instantiation of ``iterator_facade`` and
defines member functions implementing the core behaviors. defines member functions implementing the core behaviors.
.. Jeremy, I think this text is rather inappropriate for the
standard. This is not the place to discuss motivation, for
example. Compare with the standard text for vector:
1 A vector is a kind of sequence that supports random access
iterators. In addition, it supports (amortized) constant time
insert and erase operations at the end; insert and erase in the
middle take linear time. Storage management is handled
automatically, though hints can be given to improve efficiency.
2 A vector satisfies all of the requirements of a container and
of a reversible container (given in two tables in 23.1) and of a
sequence, including most of the optional sequence requirements
(23.1.1). The exceptions are the push_front and pop_front member
functions, which are not provided. Descriptions are pro- vided
here only for operations on vector that are not described in one
of these tables or for operations where there is additional
semantic information.
I suggest, instead:
``iterator_facade`` is a base class template which implements the
interface of standard iterators in terms of a few core functions
and associated types, to be supplied by a derived iterator class.
Template class ``iterator_facade`` Template class ``iterator_facade``
---------------------------------- ----------------------------------
@@ -507,8 +517,11 @@ Template class ``iterator_facade``
typename Derived::difference_type n) typename Derived::difference_type n)
.. nothing
.. we need a new label here because the presence of markup in the
title prevents an automatic link from being generated
.. _iterator facade requirements:
``iterator_facade`` requirements ``iterator_facade`` requirements
-------------------------------- --------------------------------
@@ -657,24 +670,25 @@ interoperable with X.
Iterator adaptor [lib.iterator.adaptor] Iterator adaptor [lib.iterator.adaptor]
======================================= =======================================
.. Jeremy, the same argument about appropriateness applies here as well.
A common pattern of iterator construction is the adaptation of one A common pattern of iterator construction is the adaptation of one
iterator to form a new one. The functionality of an iterator is iterator to form a new one. The functionality of an iterator is
composed of four orthogonal aspects: traversal, indirection, equality composed of four orthogonal aspects: traversal, indirection, equality
comparison and distance measurement. Adapting an old iterator to comparison, and distance measurement. Adapting an old iterator to
create a new one often saves work because one can reuse one aspect of create a new one often saves work because one can change a few aspects
functionality while redefining the other. For example, the Standard of the functionality while retaining the rest. For example, the
provides ``reverse_iterator``, which adapts any Bidirectional Iterator Standard provides ``reverse_iterator``, which adapts any Bidirectional
by inverting its direction of traversal. Iterator by inverting its direction of traversal.
The ``iterator_adaptor`` class template fulfills the need for The ``iterator_adaptor`` class template fulfills the need for
constructing adaptors. Instantiations of ``iterator_adaptor`` serve constructing adaptors. Instantiations of ``iterator_adaptor`` serve
as a base classes for new iterators, providing the default behaviour as a base classes for new iterators, providing the default behaviour
of forwarding all operations to the underlying iterator. The deriving of forwarding all operations to the underlying iterator. The user can
class can selectively replace these features in the derived iterator selectively replace these features in the derived iterator class.
class.
The ``iterator_adaptor`` class template adapts a ``Base`` type to The ``iterator_adaptor`` class template adapts a ``Base`` type to
create a new iterator ("base" here means the type being adapted) . create a new iterator ("base" here means the type being adapted).
The ``iterator_adaptor`` forwards all operations to an instance of the The ``iterator_adaptor`` forwards all operations to an instance of the
``Base`` type, which it stores as a member. The user of ``Base`` type, which it stores as a member. The user of
``iterator_adaptor`` creates a class derived from an instantiation of ``iterator_adaptor`` creates a class derived from an instantiation of
@@ -684,7 +698,6 @@ described in [lib.iterator.facade]. The ``Base`` type need not meet
the full requirements for an iterator. It need only support the the full requirements for an iterator. It need only support the
operations that are not overriden by the users derived class. operations that are not overriden by the users derived class.
Template class ``iterator_adaptor`` Template class ``iterator_adaptor``
----------------------------------- -----------------------------------
@@ -713,12 +726,18 @@ Template class ``iterator_adaptor``
Write me. Write me.
.. Make sure to mention that this words for both old and new .. Make sure to mention that this words for both old and new
style iterators. -JGS style iterators. -JGS
.. I'm not sure we should say that in the standard text; let other
people add non-normative in editing if they feel the need
;-) -DWA
Specialized adaptors [lib.iterator.special.adaptors] Specialized adaptors [lib.iterator.special.adaptors]
==================================================== ====================================================
.. The requirements for all of these need to be written *much* more
formally -DWA
Indirect iterator Indirect iterator
----------------- -----------------
@@ -731,7 +750,7 @@ adaptor makes it possible to view a container of pointers
Template class ``indirect_iterator`` Template class ``indirect_iterator``
++++++++++++++++++++++++++++++++++++ ....................................
:: ::
@@ -776,7 +795,7 @@ Template class ``indirect_iterator``
``indirect_iterator`` requirements ``indirect_iterator`` requirements
++++++++++++++++++++++++++++++++++ ..................................
The ``value_type`` of the ``Iterator`` template parameter should The ``value_type`` of the ``Iterator`` template parameter should
itself be dereferenceable. The return type of the ``operator*`` for itself be dereferenceable. The return type of the ``operator*`` for
@@ -808,7 +827,10 @@ The indirect iterator will model whichever standard iterator concepts
are modeled by the base iterator. For example, if the base iterator is are modeled by the base iterator. For example, if the base iterator is
a model of Random Access Traversal Iterator then so is the resulting a model of Random Access Traversal Iterator then so is the resulting
indirect iterator. indirect iterator.
.. I don't believe the above statement is true anymore in light of the
new categories. I think it only applies to the traversal part of
the concept.
Reverse iterator Reverse iterator
---------------- ----------------
@@ -823,7 +845,7 @@ comparisons and conversions between the mutable and const versions are
implemented correctly. implemented correctly.
Template class ``reverse_iterator`` Template class ``reverse_iterator``
+++++++++++++++++++++++++++++++++++ ...................................
:: ::
@@ -868,7 +890,7 @@ Template class ``reverse_iterator``
``reverse_iterator`` requirements ``reverse_iterator`` requirements
+++++++++++++++++++++++++++++++++ .................................
The base iterator must be a model of Bidirectional Traversal The base iterator must be a model of Bidirectional Traversal
Iterator. The reverse iterator will model whichever standard iterator Iterator. The reverse iterator will model whichever standard iterator
@@ -888,7 +910,7 @@ then returns the result.
Template class ``transform_iterator`` Template class ``transform_iterator``
+++++++++++++++++++++++++++++++++++++ .....................................
:: ::
@@ -923,7 +945,7 @@ Template class ``transform_iterator``
``transform_iterator`` requirements ``transform_iterator`` requirements
+++++++++++++++++++++++++++++++++++ ...................................
Write me. Use ``result_of``? Write me. Use ``result_of``?
@@ -940,7 +962,7 @@ skipped over.
Template class ``filter_iterator`` Template class ``filter_iterator``
++++++++++++++++++++++++++++++++++ ..................................
:: ::
@@ -972,7 +994,7 @@ Counting iterator
Template class ``counting_iterator`` Template class ``counting_iterator``
++++++++++++++++++++++++++++++++++++ ....................................
:: ::
@@ -1002,7 +1024,7 @@ proxy object.
Template class ``function_output_iterator`` Template class ``function_output_iterator``
+++++++++++++++++++++++++++++++++++++++++++ ...........................................
:: ::