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

Some Updates

Browse Source 
[SVN r1166]
This commit is contained in:
Dave Abrahams
2003-04-20 02:45:23 +00:00
parent 9a02b10067
commit 0f4cbb126b
2 changed files with 63 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -13,9 +13,9 @@
.. _`Open Systems Lab`: http://www.osl.iu.edu .. _`Open Systems Lab`: http://www.osl.iu.edu
.. _`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 as set of class templates that help programmers :abstract: We propose a set of class templates that help programmers
build standard-conforming iterators and build iterators build standard-conforming iterators and to build iterators
that adapt of other iterators. that adapt other iterators.
.. contents:: Table of Contents .. contents:: Table of Contents
@@ -136,42 +136,64 @@ In addition to the behaviors listed above, the core interface elements
include the associated types exposed through iterator traits: value include the associated types exposed through iterator traits: value
type, reference, pointer, and iterator category. type, reference, pointer, and iterator category.
The user of the ``iterator_facade`` creates a class the derives from The user of the ``iterator_facade`` creates a class derived from an
``iterator_facade`` and defines member functions that implement the instantiation of ``iterator_facade`` which defines member functions
core behaviours. The member functions are required to have the implementing the core behaviors. The following table describes
following interface. In the following, ``self`` is the type of the expressions which are required to be valid depending on the category
derived iterator. 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 iterator type, and ``n`` is
an object of ``X::difference_type``
reference dereference() const; +----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+
bool equal(self const& x) const; | Expression | Return Type | Assertion/Note/Precondition/Postcondition | Required to implement Iterator Concept(s) |
void advance(difference_type n); | | | | |
void increment(); +========================================+========================================+=================================================+===========================================+
void decrement(); | ``c.dereference()`` | ``X::reference`` | | Readable Iterator, Writable Iterator |
difference_type distance_to(self const& y) const; +----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+
| ``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 | |
| | |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(y)`` | convertible to X::difference_type |equivalent to ``distance(c, y)``. Implements ``c| |
| | |- y``, ``c < y``, ``c <= y``, ``c > y``, and ``c | |
| | |>= c``. | |
+----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+
Iterator Adaptor Iterator Adaptor
================ ================
The ``iterator_adaptor`` class template adapts some ``Base``{#base]_ The ``iterator_adaptor`` class template adapts some ``Base`` [#base]_
type to create a new iterator. ``iterator_adaptor`` derives from type to create a new iterator. Instantiations of ``iterator_adaptor``
``iterator_facade`` and implements the core interface in terms of the are derived from a corresponding instantiation of ``iterator_facade``
``Base`` type. In essense, the ``iterator_adaptor`` merely forwards and implement the core behaviors in terms of the ``Base`` type. In
all operations to the ``Base`` type. An object of the ``Base`` type is essence, the ``iterator_adaptor`` merely forwards all operations to
a data member of ``iterator_adaptor``. the ``Base`` type. An object of the ``Base`` type is a data member of
``iterator_adaptor``.
.. [#base] The term "Base" here is not meant to imply the .. [#base] The term "Base" here does not refer to a base class and is
class being inherited from. We have followed the lead of the not meant to imply the use of derivation. We have followed the lead
standard library, which provides a base() function to access the of the standard library, which provides a base() function to access
underlying iterator object of a ``reverse_iterator`` adaptor. the underlying iterator object of a ``reverse_iterator`` adaptor.
The user of ``iterator_adaptor`` constructs a class that derives from The user of ``iterator_adaptor`` creates a class derived from an
``iterator_adaptor`` and then selectively overrides some of the core instantiation of ``iterator_adaptor`` and then selectively overrides
operations. In addition, the derived class will typically need to some of the core operations by implementing the (non-virtual) member
define some constructors. functions described in the table above. In addition, the derived
class will typically need to define some constructors.
The library also contains several examples of specialized adaptors The library also contains several examples of specialized adaptors
which were easily implemented using ``iterator_adaptor``: which were easily implemented using ``iterator_adaptor``:

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

@@ -229,11 +229,16 @@ are combined using the new `iterator_tag` class.
typedef TraversalTag traversal; typedef TraversalTag traversal;
}; };
The ``iterator_tag`` class template inherits the appropriate iterator The ``iterator_tag`` class template is derived from the appropriate
tag from the old requirements based on the new tags of the iterator tag or tags from the old requirements based on the new-style
iterator. The algorithm for determining the old tag from the new tags tags passed as template parameters. The algorithm for determining the
picks the smallest old concept that includes all of the requirements old tag or tags from the new tags picks the least-refined old concepts
of the access and traversal concepts. that include all of the requirements of the access and traversal
concepts, if any such category exists. For example, a the category
tag for a Readable Single Pass Iterator will always be derived from
``input_iterator_tag``, while the category tag for a Single Pass
Iterator that is both Readable and Writable will be derived from both
``input_iterator_tag`` and ``writable_iterator_tag``.
We also provide two helper classes that make it convenient to obtain We also provide two helper classes that make it convenient to obtain
the access and traversal tags of an iterator. These helper classes the access and traversal tags of an iterator. These helper classes
@@ -408,6 +413,8 @@ semantics.
+==================================+=========================+=========================================================================================+ +==================================+=========================+=========================================================================================+
| ``++r`` | ``X&`` | pre: ``r`` is dereferenceable; post: ``r`` is dereferenceable or ``r`` is past-the-end | | ``++r`` | ``X&`` | pre: ``r`` is dereferenceable; post: ``r`` is dereferenceable or ``r`` is past-the-end |
+----------------------------------+-------------------------+-----------------------------------------------------------------------------------------+ +----------------------------------+-------------------------+-----------------------------------------------------------------------------------------+
| ``a == b`` | convertible to ``bool`` | ``==`` is an equivalence relation over its domain |
+----------------------------------+-------------------------+-----------------------------------------------------------------------------------------+
| ``a != b`` | convertible to ``bool`` | ``!(a == b)`` | | ``a != b`` | convertible to ``bool`` | ``!(a == b)`` |
+----------------------------------+-------------------------+-----------------------------------------------------------------------------------------+ +----------------------------------+-------------------------+-----------------------------------------------------------------------------------------+
| ``traversal_category<X>::type`` | | Convertible to ``single_pass_iterator_tag`` | | ``traversal_category<X>::type`` | | Convertible to ``single_pass_iterator_tag`` |