boostorg/iterator
1
0
Fork 1
mirror of https://github.com/boostorg/iterator.git synced 2025-07-23 09:27:15 +02:00
Code Issues Packages Projects Releases Wiki Activity

Various updates and clarifications.

Browse Source 
[SVN r19106]
This commit is contained in:
Dave Abrahams
2003-07-13 22:47:15 +00:00
parent 9db269bb5b
commit a982c42303
4 changed files with 3264 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2042
doc/facade-and-adaptor.html Executable file
View File

File diff suppressed because it is too large Load Diff

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

@ -8,7 +8,7 @@
Lab`_, University of Hanover `Institute for Transport Lab`_, University of Hanover `Institute for Transport
Railway Operation and Construction`_ Railway Operation and Construction`_
:date: $Date$ :date: $Date$
:Number: N1476=03-0059 :Number: **This document is a revised version of the official** N1476=03-0059
:copyright: Copyright Dave Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved :copyright: Copyright Dave Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved
.. _`Boost Consulting`: http://www.boost-consulting.com .. _`Boost Consulting`: http://www.boost-consulting.com
@ -202,28 +202,40 @@ objects for several reasons:
iterators, and a separate ``iterator_adaptor`` layer would be iterators, and a separate ``iterator_adaptor`` layer would be
impossible. impossible.
Usage
-----
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`` which takes the derived iterator
implementing the core behaviors. The following table describes class as the first template parameter. The order of the other
template parameters to ``iterator_facade`` have been carefully chosen
to take advantage of useful defaults. For example, when defining a
constant lvalue iterator, the user can pass a const-qualified version
of the iterator's ``value_type`` as ``iterator_facade``\ 's ``Value``
parameter and omit the ``Reference`` parameter which follows.
The derived iterator class must define member functions implementing
the iterator's 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. These member functions are described of the derived iterator type. These member functions are described
briefly below and in more detail in the `iterator facade requirements`_. briefly below and in more detail in the `iterator facade
requirements`_.
+----------------------------------------+-------------------------------------------+ +------------------------+-------------------------------+
|Expression |Effects | |Expression |Effects |
+========================================+===========================================+ +========================+===============================+
|``i.dereference()`` |Access the value referred to | |``i.dereference()`` |Access the value referred to |
+----------------------------------------+-------------------------------------------+ +------------------------+-------------------------------+
|``i.equal(j)`` |Compare for equality with ``j``| |``i.equal(j)`` |Compare for equality with ``j``|
+----------------------------------------+-------------------------------------------+ +------------------------+-------------------------------+
|``i.increment()`` |Advance by one position | |``i.increment()`` |Advance by one position |
+----------------------------------------+-------------------------------------------+ +------------------------+-------------------------------+
|``i.decrement()`` |Retreat by one position | |``i.decrement()`` |Retreat by one position |
+----------------------------------------+-------------------------------------------+ +------------------------+-------------------------------+
|``i.advance(n)`` |Advance by ``n`` positions | |``i.advance(n)`` |Advance by ``n`` positions |
+----------------------------------------+-------------------------------------------+ +------------------------+-------------------------------+
|``i.distance_to(j)`` |Measure the distance to ``j`` | |``i.distance_to(j)`` |Measure the distance to ``j`` |
+----------------------------------------+-------------------------------------------+ +------------------------+-------------------------------+
.. 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?
@ -236,8 +248,9 @@ type ``X`` is meant to be automatically interoperate with another
iterator type ``Y`` (as with constant and mutable iterators) then iterator type ``Y`` (as with constant and mutable iterators) then
there must be an implicit conversion from ``X`` to ``Y`` or from ``Y`` there must be an implicit conversion from ``X`` to ``Y`` or from ``Y``
to ``X`` (but not both), typically implemented as a conversion to ``X`` (but not both), typically implemented as a conversion
constructor. Also, if the iterator is to model Forward Traversal constructor. Finally, if the iterator is to model Forward Traversal
Iterator, a default constructor is required. Iterator or a more-refined iterator concept, a default constructor is
required.
@ -306,6 +319,8 @@ from clients of her iterator.
.. _issue 299: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-active.html#299 .. _issue 299: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-active.html#299
.. _`operator arrow`:
``operator->`` ``operator->``
============== ==============
@ -355,7 +370,7 @@ implementation. Finally, ``use_default`` is not left unspecified
because specification helps to highlight that the ``Reference`` because specification helps to highlight that the ``Reference``
template parameter may not always be identical to the iterator's template parameter may not always be identical to the iterator's
``reference`` type, and will keep users making mistakes based on that ``reference`` type, and will keep users making mistakes based on that
assumtion. assumption.
Specialized Adaptors Specialized Adaptors
==================== ====================
@ -480,27 +495,27 @@ and associated types, to be supplied by a derived iterator class.
Class template ``iterator_facade`` Class template ``iterator_facade``
---------------------------------- ----------------------------------
:: .. parsed-literal::
template < template <
class Derived class Derived
, class Value , class Value
, class AccessCategory , class AccessCategory
, class TraversalCategory , class TraversalCategory
, class Reference = /* see below */ , class Reference = /* see below__ \*/
, class Difference = ptrdiff_t , class Difference = ptrdiff_t
> >
class iterator_facade { class iterator_facade {
public: public:
typedef remove_cv<Value>::type value_type; typedef remove_cv<Value>::type value_type;
typedef Reference reference; typedef Reference reference;
typedef /* see description of operator-> */ pointer; typedef /* see `description of operator->`__ \*/ pointer;
typedef Difference difference_type; typedef Difference difference_type;
typedef iterator_tag<AccessCategory, TraversalCategory> iterator_category; typedef iterator_tag<AccessCategory, TraversalCategory> iterator_category;
reference operator*() const; reference operator\*() const;
/* see below */ operator->() const; /* see below__ \*/ operator->() const;
/* impl defined */ operator[](difference_type n) const; /* see below__ \*/ operator[](difference_type n) const;
Derived& operator++(); Derived& operator++();
Derived operator++(int); Derived operator++(int);
Derived& operator--(); Derived& operator--();
@ -566,6 +581,14 @@ Class template ``iterator_facade``
typename Derived::difference_type n) typename Derived::difference_type n)
__ `iterator facade requirements`_
__ `operator arrow`_
__ `operator arrow`_
__ brackets_
[*Note:* The ``enable_if_interoperable`` template used above is for exposition [*Note:* The ``enable_if_interoperable`` template used above is for exposition
purposes. The member operators should be only be in an overload set purposes. The member operators should be only be in an overload set
provided the derived types ``Dr1`` and ``Dr2`` are interoperable, by provided the derived types ``Dr1`` and ``Dr2`` are interoperable, by
@ -602,30 +625,35 @@ object of a single pass iterator type interoperable with X, and ``z``
is a constant object of a random access traversal iterator type is a constant object of a random access traversal iterator type
interoperable with ``X``. interoperable with ``X``.
+----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+ +--------------------+-------------------+-------------------------------------+---------------------------+
| Expression | Return Type | Assertion/Note/Precondition/Postcondition | Required to implement Iterator Concept(s) | |Expression |Return Type |Assertion/Note |Required to implement |
| | | | | | | | |Iterator Concept(s) |
+========================================+========================================+=================================================+===========================================+ +====================+===================+=====================================+===========================+
| ``c.dereference()`` | ``X::reference`` | | Readable Iterator, Writable Iterator | |``c.dereference()`` |``X::reference`` | |Readable Iterator, Writable|
+----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+ | | | |Iterator |
| ``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 |Single Pass Iterator |
| ``c.equal(y)`` | convertible to bool |true iff ``c`` and ``y`` refer to the same | Single Pass Iterator | | | |equivalent. | |
| | |position. Implements ``c == y`` and ``c != y``. | | +--------------------+-------------------+-------------------------------------+---------------------------+
+----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+ |``c.equal(y)`` |convertible to bool|true iff ``c`` and ``y`` refer to the|Single Pass Iterator |
| ``a.advance(n)`` | unused | | Random Access Traversal Iterator | | | |same position. Implements ``c == y``| |
+----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+ | | |and ``c != y``. | |
+--------------------+-------------------+-------------------------------------+---------------------------+
|``a.advance(n)`` |unused | |Random Access Traversal |
| | | |Iterator |
+--------------------+-------------------+-------------------------------------+---------------------------+
|``a.increment()`` |unused | |Incrementable Iterator | |``a.increment()`` |unused | |Incrementable Iterator |
+----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+ +--------------------+-------------------+-------------------------------------+---------------------------+
| ``a.decrement()`` | unused | | Bidirectional Traversal 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(b)``|convertible to |equivalent to ``distance(c, b)`` |Random Access Traversal |
| ``c.distance_to(z)`` | convertible to X::difference_type |equivalent to ``distance(c, z)``. Implements ``c| Random Access Traversal Iterator | | |X::difference_type | |Iterator |
| | |- z``, ``c < z``, ``c <= z``, ``c > z``, and ``c | | +--------------------+-------------------+-------------------------------------+---------------------------+
| | |>= c``. | | |``c.distance_to(z)``|convertible to |equivalent to ``distance(c, z)``. |Random Access Traversal |
+----------------------------------------+----------------------------------------+-------------------------------------------------+-------------------------------------------+ | |X::difference_type |Implements ``c - z``, ``c < z``, ``c |Iterator |
| | |<= z``, ``c > z``, and ``c >= c``. | |
+--------------------+-------------------+-------------------------------------+---------------------------+
.. We should explain more about how the .. We should explain more about how the
functions in the interface of iterator_facade functions in the interface of iterator_facade
@ -644,7 +672,9 @@ through member functions of class ``iterator_core_access``.
:Returns: ``static_cast<Derived const*>(this)->dereference()`` :Returns: ``static_cast<Derived const*>(this)->dereference()``
*see below* ``operator->() const;`` ``operator->() const;`` (see below__)
__ `operator arrow`_
:Returns: If ``X::reference`` is a reference type, returns an object :Returns: If ``X::reference`` is a reference type, returns an object
of type ``X::pointer`` equal to:: of type ``X::pointer`` equal to::
@ -660,6 +690,8 @@ through member functions of class ``iterator_core_access``.
``Value const*`` otherwise. ``Value const*`` otherwise.
.. _brackets:
*unspecified* ``operator[](difference_type n) const;`` *unspecified* ``operator[](difference_type n) const;``
:Returns: an object convertible to ``X::reference`` and holding a copy :Returns: an object convertible to ``X::reference`` and holding a copy
@ -765,7 +797,7 @@ core interface functions of ``iterator_facade`` are redefined in the
Class template ``iterator_adaptor`` Class template ``iterator_adaptor``
----------------------------------- -----------------------------------
:: .. parsed-literal::
template < template <
class Derived class Derived
@ -776,7 +808,7 @@ Class template ``iterator_adaptor``
, class Difference = use_default , class Difference = use_default
> >
class iterator_adaptor class iterator_adaptor
: public iterator_facade<Derived, /* see details ...*/> : public iterator_facade<Derived, /* see details__ ...\*/>
{ {
friend class iterator_core_access; friend class iterator_core_access;
public: public:
@ -808,7 +840,7 @@ Class template ``iterator_adaptor``
Base m_iterator; Base m_iterator;
}; };
__ :
``iterator_adaptor`` requirements ``iterator_adaptor`` requirements
--------------------------------- ---------------------------------

1133
doc/new-iter-concepts.html Executable file
View File

File diff suppressed because it is too large Load Diff

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

@ -6,7 +6,7 @@
:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de :Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de
:organization: `Boost Consulting`_, Indiana University `Open Systems Lab`_, University of Hanover `Institute for Transport Railway Operation and Construction`_ :organization: `Boost Consulting`_, Indiana University `Open Systems Lab`_, University of Hanover `Institute for Transport Railway Operation and Construction`_
:date: $Date$ :date: $Date$
:Number: N1477=03-0060 :Number: **This document is a revised version of the official** N1477=03-0060
:copyright: Copyright Dave Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved :copyright: Copyright Dave Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved
.. _`Boost Consulting`: http://www.boost-consulting.com .. _`Boost Consulting`: http://www.boost-consulting.com