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

factoring the specialized iterator adaptors

Browse Source 
[SVN r19467]
This commit is contained in:
Jeremy Siek
2003-08-05 19:42:37 +00:00
parent 0f42b93c3b
commit 76af84c0e7
23 changed files with 826 additions and 570 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
doc/counting_iterator.rst Normal file
View File

@ -0,0 +1,23 @@
+++++++++++++++++++
Counting Iterator
+++++++++++++++++++
:Author: David Abrahams, Jeremy Siek, Thomas Witt
: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`_
:date: $Date$
:copyright: Copyright Dave Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved
.. _`Boost Consulting`: http://www.boost-consulting.com
.. _`Open Systems Lab`: http://www.osl.iu.edu
.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de
:abstract:
.. include:: counting_iterator_abstract.rst
.. contents:: Table of Contents
.. include:: counting_iterator_ref.rst

5
doc/counting_iterator_abstract.rst Normal file
View File

@ -0,0 +1,5 @@
The counting iterator adaptor implements dereference by returning a
reference to the base object. The other operations are implemented by
the base ``m_iterator``, as per the inheritance from
``iterator_adaptor``.

85
doc/counting_iterator_ref.rst Normal file
View File

@ -0,0 +1,85 @@
::
template <class Incrementable, class Category = use_default, class Difference = use_default>
class counting_iterator
: public iterator_adaptor<
counting_iterator<Incrementable, Category, Difference>
, Incrementable
, Incrementable
, /* see details for category */
, Incrementable const&
, Incrementable const*
, /* distance = Difference or a signed integral type */>
{
friend class iterator_core_access;
public:
counting_iterator();
counting_iterator(counting_iterator const& rhs);
counting_iterator(Incrementable x);
private:
typename counting_iterator::reference dereference() const
{
return this->base_reference();
}
};
[*Note:* implementers are encouraged to provide an implementation of
``distance_to`` and a ``difference_type`` that avoids overflows in
the cases when the ``Incrementable`` type is a numeric type.]
``counting_iterator`` requirements
----------------------------------
The ``Incrementable`` type must be Default Constructible, Copy
Constructible, and Assignable. The default distance is
an implementation defined signed integegral type.
The resulting ``counting_iterator`` models Readable Lvalue Iterator.
Furthermore, if you wish to create a counting iterator that is a Forward
Traversal Iterator, then the following expressions must be valid:
::
Incrementable i, j;
++i // pre-increment
i == j // operator equal
If you wish to create a counting iterator that is a
Bidirectional Traversal Iterator, then pre-decrement is also required:
::
--i
If you wish to create a counting iterator that is a Random Access
Traversal Iterator, then these additional expressions are also
required:
::
counting_iterator::difference_type n;
i += n
n = i - j
i < j
``counting_iterator`` operations
--------------------------------
``counting_iterator();``
:Returns: A default constructed instance of ``counting_iterator``.
``counting_iterator(counting_iterator const& rhs);``
:Returns: An instance of ``counting_iterator`` that is a copy of ``rhs``.
``counting_iterator(Incrementable x);``
:Returns: An instance of ``counting_iterator`` with its base
object copy constructed from ``x``.

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

@ -324,626 +324,68 @@ implicitly convertible.]
Indirect iterator
-----------------
The indirect iterator adapts an iterator by applying an *extra*
dereference inside of ``operator*()``. For example, this iterator
adaptor makes it possible to view a container of pointers
(e.g. ``list<foo*>``) as if it were a container of the pointed-to type
(e.g. ``list<foo>``) .
.. At some point we should add the capability to handle
iterators over smart pointers, which the impl handles. -JGS
.. include:: indirect_iterator_abstract.rst
Class template ``indirect_iterator``
....................................
::
template <
class Iterator
, class Value = use_default
, class Category = use_default
, class Reference = use_default
, class Difference = use_default
>
class indirect_iterator
: public iterator_adaptor</* see discussion */>
{
friend class iterator_core_access;
public:
indirect_iterator();
indirect_iterator(Iterator x);
template <
class Iterator2, class Value2, class Category2
, class Reference2, class Difference2
>
indirect_iterator(
indirect_iterator<
Iterator2, Value2, Category2, Reference2, Difference2
> const& y
, typename enable_if_convertible<Iterator2, Iterator>::type* = 0 // exposition
);
private: // as-if specification
typename indirect_iterator::reference dereference() const
{
return **this->base();
}
};
``indirect_iterator`` requirements
..................................
The ``value_type`` of the ``Iterator`` template parameter should
itself be dereferenceable. The return type of the ``operator*`` for
the ``value_type`` must be the same type as the ``Reference`` template
parameter. The ``Value`` template parameter will be the ``value_type``
for the ``indirect_iterator``, unless ``Value`` is const. If ``Value``
is ``const X``, then ``value_type`` will be *non-* ``const X``. The
default for ``Value`` is
::
iterator_traits< iterator_traits<Iterator>::value_type >::value_type
If the default is used for ``Value``, then there must be a valid
specialization of ``iterator_traits`` for the value type of the base
iterator.
The ``Reference`` parameter will be the ``reference`` type of the
``indirect_iterator``. The default is ``Value&``.
The ``Category`` parameter is the ``iterator_category`` type for the
``indirect_iterator``. The default is
``iterator_traits<Iterator>::iterator_category``.
The indirect iterator will model the most refined standard traversal
concept that is modeled by the ``Iterator`` type. The indirect
iterator will model the most refined standard access concept that is
modeled by the value type of ``Iterator``.
``indirect_iterator`` operations
................................
``indirect_iterator();``
:Requires: ``Iterator`` must be Default Constructible.
:Returns: An instance of ``indirect_iterator`` with
a default constructed base object.
``indirect_iterator(Iterator x);``
:Returns: An instance of ``indirect_iterator`` with
the ``iterator_adaptor`` subobject copy constructed from ``x``.
::
template <
class Iterator2, class Value2, class Category2
, class Reference2, class Difference2
>
indirect_iterator(
indirect_iterator<
Iterator2, Value2, Category2, Reference2, Difference2
> const& y
, typename enable_if_convertible<Iterator2, Iterator>::type* = 0 // exposition
);
:Requires: ``Iterator2`` is implicitly convertible to ``Iterator``.
:Returns: An instance of ``indirect_iterator`` that is a copy of ``y``.
.. include:: indirect_iterator_ref.rst
Reverse iterator
----------------
.. I think we'd better strike the old reverse_iterator text from the standard, eh?
The reverse iterator adaptor flips the direction of a base iterator's
motion. Invoking ``operator++()`` moves the base iterator backward and
invoking ``operator--()`` moves the base iterator forward.
.. include:: reverse_iterator_abstract.rst
Class template ``reverse_iterator``
...................................
::
template <class Iterator>
class reverse_iterator :
public iterator_adaptor< reverse_iterator<Iterator>, Iterator >
{
friend class iterator_core_access;
public:
reverse_iterator() {}
explicit reverse_iterator(Iterator x) ;
template<class OtherIterator>
reverse_iterator(
reverse_iterator<OtherIterator> const& r
, typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
);
private: // as-if specification
typename reverse_iterator::reference dereference() const { return *prior(this->base()); }
void increment() { --this->base_reference(); }
void decrement() { ++this->base_reference(); }
void advance(typename reverse_iterator::difference_type n)
{
this->base_reference() += -n;
}
template <class OtherIterator>
typename reverse_iterator::difference_type
distance_to(reverse_iterator<OtherIterator> const& y) const
{
return this->base_reference() - y.base();
}
};
``reverse_iterator`` requirements
.................................
The base ``Iterator`` must be a model of Bidirectional Traversal
Iterator. The resulting ``reverse_iterator`` will be a model of the
most refined standard traversal and access concepts that are modeled
by ``Iterator``.
``reverse_iterator();``
:Requires: ``Iterator`` must be Default Constructible.
:Returns: An instance of ``reverse_iterator`` with a
default constructed base object.
``explicit reverse_iterator(Iterator x);``
:Returns: An instance of ``reverse_iterator`` with a
base object copy constructed from ``x``.
::
template<class OtherIterator>
reverse_iterator(
reverse_iterator<OtherIterator> const& r
, typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
);
:Requires: ``OtherIterator`` is implicitly convertible to ``Iterator``.
:Returns: An instance of ``reverse_iterator`` that is a copy of ``r``.
.. include:: reverse_iterator_ref.rst
Transform iterator
------------------
The transform iterator adapts an iterator by applying some function
object to the result of dereferencing the iterator. In other words,
the ``operator*`` of the transform iterator first dereferences the
base iterator, passes the result of this to the function object, and
then returns the result.
.. include:: transform_iterator_abstract.rst
Class template ``transform_iterator``
.....................................
::
template <class AdaptableUnaryFunction,
class Iterator,
class Reference = use_default,
class Value = use_default>
class transform_iterator
: public iterator_adaptor</* see discussion */>
{
friend class iterator_core_access;
public:
transform_iterator();
transform_iterator(Iterator const& x, AdaptableUnaryFunction f);
template<class OtherIterator, class R2, class V2>
transform_iterator(
transform_iterator<AdaptableUnaryFunction, OtherIterator, R2, V2> const& t
, typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
);
AdaptableUnaryFunction functor() const;
private:
typename transform_iterator::value_type dereference() const;
AdaptableUnaryFunction m_f;
};
``transform_iterator`` requirements
...................................
The type ``AdaptableUnaryFunction`` must be Assignable, Copy
Constructible, and the expression ``f(x)`` must be valid where ``f``
is an object of type ``AdaptableUnaryFunction``, ``x`` is an object of
type ``AdaptableUnaryFunction::argument_type``, and where the type of
``f(x)`` must be ``AdaptableUnaryFunction::result_type``.
The type ``Iterator`` must at least model Readable Iterator. The
resulting ``transform_iterator`` models the most refined of the
following options that is also modeled by ``Iterator``.
* Writable Lvalue Iterator if the ``result_type`` of the
``AdaptableUnaryFunction`` is a non-const reference.
* Readable Lvalue Iterator if the ``result_type`` is a const
reference.
* Readable Iterator otherwise.
The ``transform_iterator`` models the most refined standard traversal
concept that is modeled by ``Iterator``.
The ``value_type`` of ``transform_iterator`` is
``remove_reference<result_type>::type``. The ``reference`` type is
``result_type``.
``transform_iterator`` public operations
........................................
``transform_iterator();``
:Returns: An instance of ``transform_iterator`` with ``m_f``
and ``m_iterator`` default constructed.
``transform_iterator(Iterator const& x, AdaptableUnaryFunction f);``
:Returns: An instance of ``transform_iterator`` with ``m_f``
initialized to ``f`` and ``m_iterator`` initialized to ``x``.
::
template<class OtherIterator, class R2, class V2>
transform_iterator(
transform_iterator<AdaptableUnaryFunction, OtherIterator, R2, V2> const& t
, typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
);
:Returns: An instance of ``transform_iterator`` that is a copy of ``t``.
:Requires: ``OtherIterator`` is implicitly convertible to ``Iterator``.
``AdaptableUnaryFunction functor() const;``
:Returns: ``m_f``
``transform_iterator`` private operations
.........................................
``typename transform_iterator::value_type dereference() const;``
:Returns: ``m_f(transform_iterator::dereference());``
.. include:: transform_iterator_ref.rst
Filter iterator
---------------
The filter iterator adaptor creates a view of an iterator range in
which some elements of the range are skipped over. A predicate
function object controls which elements are skipped. When the
predicate is applied to an element, if it returns ``true`` then the
element is retained and if it returns ``false`` then the element is
skipped over. When skipping over elements, it is necessary for the
filter adaptor to know when to stop so as to avoid going past the end
of the underlying range. Therefore the constructor of the filter
iterator takes two iterator parameters: the position for the filtered
iterator and the end of the range.
.. include:: filter_iterator_abstract.rst
Class template ``filter_iterator``
..................................
::
template <class Predicate, class Iterator>
class filter_iterator
: public iterator_adaptor<
filter_iterator<Predicate, Iterator>, Iterator
, use_default
, /* see details */
>
{
public:
filter_iterator();
filter_iterator(Predicate f, Iterator x, Iterator end = Iterator());
filter_iterator(Iterator x, Iterator end = Iterator());
template<class OtherIterator>
filter_iterator(
filter_iterator<Predicate, OtherIterator> const& t
, typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
);
Predicate predicate() const;
Iterator end() const;
private: // as-if specification
void increment()
{
++(this->base_reference());
satisfy_predicate();
}
void satisfy_predicate()
{
while (this->base() != this->m_end && !this->m_predicate(*this->base()))
++(this->base_reference());
}
Predicate m_predicate;
Iterator m_end;
};
``filter_iterator`` requirements
--------------------------------
The base ``Iterator`` parameter must be a model of Readable Iterator
and Single Pass Iterator. The resulting ``filter_iterator`` will be a
model of Forward Traversal Iterator if ``Iterator`` is, otherwise the
``filter_iterator`` will be a model of Single Pass Iterator. The
access category of the ``filter_iterator`` will be the most refined
standard access category that is modeled by ``Iterator``.
.. Thomas is going to try implementing filter_iterator so that
it will be bidirectional if the underlying iterator is. -JGS
The ``Predicate`` must be Assignable, Copy Constructible, and the
expression ``p(x)`` must be valid where ``p`` is an object of type
``Predicate``, ``x`` is an object of type
``iterator_traits<Iterator>::value_type``, and where the type of
``p(x)`` must be convertible to ``bool``.
``filter_iterator`` operations
------------------------------
``filter_iterator();``
:Requires: ``Predicate`` and ``Iterator`` must be Default Constructible.
:Returns: a ``filter_iterator`` whose
predicate is a default constructed ``Predicate`` and
whose ``end`` is a default constructed ``Iterator``.
``filter_iterator(Predicate f, Iterator x, Iterator end = Iterator());``
:Returns: A ``filter_iterator`` at position ``x`` that filters according
to predicate ``f`` and that will not increment past ``end``.
``filter_iterator(Iterator x, Iterator end = Iterator());``
:Requires: ``Predicate`` must be Default Constructible.
:Returns: A ``filter_iterator`` at position ``x`` that filters
according to a default constructed ``Predicate``
and that will not increment past ``end``.
::
template <class OtherIterator>
filter_iterator(
filter_iterator<Predicate, OtherIterator> const& t
, typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
);``
:Requires: ``OtherIterator`` is implicitly convertible to ``Iterator``.
:Returns: A copy of iterator ``t``.
``Predicate predicate() const;``
:Returns: A copy of the predicate object used to construct ``*this``.
``Iterator end() const;``
:Returns: The object ``end`` used to construct ``*this``.
.. include:: filter_iterator_ref.rst
Counting iterator
-----------------
The counting iterator adaptor implements dereference by returning a
reference to the base object. The other operations are implemented by
the base ``m_iterator``, as per the inheritance from
``iterator_adaptor``.
.. include:: counting_iterator_abstract.rst
Class template ``counting_iterator``
....................................
::
template <class Incrementable, class Category = use_default, class Difference = use_default>
class counting_iterator
: public iterator_adaptor<
counting_iterator<Incrementable, Category, Difference>
, Incrementable
, Incrementable
, /* see details for category */
, Incrementable const&
, Incrementable const*
, /* distance = Difference or a signed integral type */>
{
friend class iterator_core_access;
public:
counting_iterator();
counting_iterator(counting_iterator const& rhs);
counting_iterator(Incrementable x);
private:
typename counting_iterator::reference dereference() const
{
return this->base_reference();
}
};
[*Note:* implementers are encouraged to provide an implementation of
``distance_to`` and a ``difference_type`` that avoids overflows in
the cases when the ``Incrementable`` type is a numeric type.]
``counting_iterator`` requirements
----------------------------------
The ``Incrementable`` type must be Default Constructible, Copy
Constructible, and Assignable. The default distance is
an implementation defined signed integegral type.
The resulting ``counting_iterator`` models Readable Lvalue Iterator.
Furthermore, if you wish to create a counting iterator that is a Forward
Traversal Iterator, then the following expressions must be valid:
::
Incrementable i, j;
++i // pre-increment
i == j // operator equal
If you wish to create a counting iterator that is a
Bidirectional Traversal Iterator, then pre-decrement is also required:
::
--i
If you wish to create a counting iterator that is a Random Access
Traversal Iterator, then these additional expressions are also
required:
::
counting_iterator::difference_type n;
i += n
n = i - j
i < j
``counting_iterator`` operations
--------------------------------
``counting_iterator();``
:Returns: A default constructed instance of ``counting_iterator``.
``counting_iterator(counting_iterator const& rhs);``
:Returns: An instance of ``counting_iterator`` that is a copy of ``rhs``.
``counting_iterator(Incrementable x);``
:Returns: An instance of ``counting_iterator`` with its base
object copy constructed from ``x``.
.. include:: counting_iterator_ref.rst
Function output iterator
------------------------
The function output iterator adaptor makes it easier to create custom
output iterators. The adaptor takes a unary function and creates a
model of Output Iterator. Each item assigned to the output iterator is
passed as an argument to the unary function. The motivation for this
iterator is that creating a conforming output iterator is non-trivial,
particularly because the proper implementation usually requires a
proxy object.
.. include:: function_output_iterator_abstract.rst
Class template ``function_output_iterator``
...........................................
::
.. include:: function_output_iterator_ref.rst
template <class UnaryFunction>
class function_output_iterator {
public:
typedef iterator_tag<
writable_iterator_tag
, incrementable_traversal_tag
> iterator_category;
typedef void value_type;
typedef void difference_type;
typedef void pointer;
typedef void reference;
explicit function_output_iterator(const UnaryFunction& f = UnaryFunction());
struct output_proxy {
output_proxy(UnaryFunction& f);
template <class T> output_proxy& operator=(const T& value);
};
output_proxy operator*();
function_output_iterator& operator++();
function_output_iterator& operator++(int);
};
``function_output_iterator`` requirements
-----------------------------------------
The ``UnaryFunction`` must be Assignable, Copy Constructible, and the
expression ``f(x)`` must be valid, where ``f`` is an object of type
``UnaryFunction`` and ``x`` is an object of a type accepted by ``f``.
The resulting ``function_output_iterator`` is a model of the Writable
and Incrementable Iterator concepts.
``function_output_iterator`` operations
---------------------------------------
``explicit function_output_iterator(const UnaryFunction& f = UnaryFunction());``
:Returns: An instance of ``function_output_iterator`` with
``f`` stored as a data member.
``output_proxy operator*();``
:Returns: An instance of ``output_proxy`` constructed with
a copy of the unary function ``f``.
``function_output_iterator& operator++();``
:Returns: ``*this``
``function_output_iterator& operator++(int);``
:Returns: ``*this``
``function_output_iterator::output_proxy`` operations
-----------------------------------------------------
``output_proxy(UnaryFunction& f);``
:Returns: An instance of ``output_proxy`` with ``f`` stored as
a data member.
``template <class T> output_proxy& operator=(const T& value);``
:Effects:
::
m_f(value);
return *this;

23
doc/filter_iterator.rst Normal file
View File

@ -0,0 +1,23 @@
+++++++++++++++++
Filter Iterator
+++++++++++++++++
:Author: David Abrahams, Jeremy Siek, Thomas Witt
: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`_
:date: $Date$
:copyright: Copyright Dave Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved
.. _`Boost Consulting`: http://www.boost-consulting.com
.. _`Open Systems Lab`: http://www.osl.iu.edu
.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de
:abstract:
.. include:: filter_iterator_abstract.rst
.. contents:: Table of Contents
.. include:: filter_iterator_ref.rst

10
doc/filter_iterator_abstract.rst Normal file
View File

@ -0,0 +1,10 @@
The filter iterator adaptor creates a view of an iterator range in
which some elements of the range are skipped over. A predicate
function object controls which elements are skipped. When the
predicate is applied to an element, if it returns ``true`` then the
element is retained and if it returns ``false`` then the element is
skipped over. When skipping over elements, it is necessary for the
filter adaptor to know when to stop so as to avoid going past the end
of the underlying range. Therefore the constructor of the filter
iterator takes two iterator parameters: the position for the filtered
iterator and the end of the range.

108
doc/filter_iterator_ref.rst Normal file
View File

@ -0,0 +1,108 @@
::
template <class Predicate, class Iterator>
class filter_iterator
: public iterator_adaptor<
filter_iterator<Predicate, Iterator>, Iterator
, use_default
, /* see details */
>
{
public:
filter_iterator();
filter_iterator(Predicate f, Iterator x, Iterator end = Iterator());
filter_iterator(Iterator x, Iterator end = Iterator());
template<class OtherIterator>
filter_iterator(
filter_iterator<Predicate, OtherIterator> const& t
, typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
);
Predicate predicate() const;
Iterator end() const;
private: // as-if specification
void increment()
{
++(this->base_reference());
satisfy_predicate();
}
void satisfy_predicate()
{
while (this->base() != this->m_end && !this->m_predicate(*this->base()))
++(this->base_reference());
}
Predicate m_predicate;
Iterator m_end;
};
``filter_iterator`` requirements
--------------------------------
The base ``Iterator`` parameter must be a model of Readable Iterator
and Single Pass Iterator. The resulting ``filter_iterator`` will be a
model of Forward Traversal Iterator if ``Iterator`` is, otherwise the
``filter_iterator`` will be a model of Single Pass Iterator. The
access category of the ``filter_iterator`` will be the most refined
standard access category that is modeled by ``Iterator``.
.. Thomas is going to try implementing filter_iterator so that
it will be bidirectional if the underlying iterator is. -JGS
The ``Predicate`` must be Assignable, Copy Constructible, and the
expression ``p(x)`` must be valid where ``p`` is an object of type
``Predicate``, ``x`` is an object of type
``iterator_traits<Iterator>::value_type``, and where the type of
``p(x)`` must be convertible to ``bool``.
``filter_iterator`` operations
------------------------------
``filter_iterator();``
:Requires: ``Predicate`` and ``Iterator`` must be Default Constructible.
:Returns: a ``filter_iterator`` whose
predicate is a default constructed ``Predicate`` and
whose ``end`` is a default constructed ``Iterator``.
``filter_iterator(Predicate f, Iterator x, Iterator end = Iterator());``
:Returns: A ``filter_iterator`` at position ``x`` that filters according
to predicate ``f`` and that will not increment past ``end``.
``filter_iterator(Iterator x, Iterator end = Iterator());``
:Requires: ``Predicate`` must be Default Constructible.
:Returns: A ``filter_iterator`` at position ``x`` that filters
according to a default constructed ``Predicate``
and that will not increment past ``end``.
::
template <class OtherIterator>
filter_iterator(
filter_iterator<Predicate, OtherIterator> const& t
, typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
);``
:Requires: ``OtherIterator`` is implicitly convertible to ``Iterator``.
:Returns: A copy of iterator ``t``.
``Predicate predicate() const;``
:Returns: A copy of the predicate object used to construct ``*this``.
``Iterator end() const;``
:Returns: The object ``end`` used to construct ``*this``.

23
doc/function_output_iterator.rst Normal file
View File

@ -0,0 +1,23 @@
++++++++++++++++++++++++++
Function Output Iterator
++++++++++++++++++++++++++
:Author: David Abrahams, Jeremy Siek, Thomas Witt
: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`_
:date: $Date$
:copyright: Copyright Dave Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved
.. _`Boost Consulting`: http://www.boost-consulting.com
.. _`Open Systems Lab`: http://www.osl.iu.edu
.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de
:abstract:
.. include:: function_output_iterator_abstract.rst
.. contents:: Table of Contents
.. include:: function_output_iterator_ref.rst

8
doc/function_output_iterator_abstract.rst Normal file
View File

@ -0,0 +1,8 @@
The function output iterator adaptor makes it easier to create custom
output iterators. The adaptor takes a unary function and creates a
model of Output Iterator. Each item assigned to the output iterator is
passed as an argument to the unary function. The motivation for this
iterator is that creating a conforming output iterator is non-trivial,
particularly because the proper implementation usually requires a
proxy object.

77
doc/function_output_iterator_ref.rst Normal file
View File

@ -0,0 +1,77 @@
::
template <class UnaryFunction>
class function_output_iterator {
public:
typedef iterator_tag<
writable_iterator_tag
, incrementable_traversal_tag
> iterator_category;
typedef void value_type;
typedef void difference_type;
typedef void pointer;
typedef void reference;
explicit function_output_iterator(const UnaryFunction& f = UnaryFunction());
struct output_proxy {
output_proxy(UnaryFunction& f);
template <class T> output_proxy& operator=(const T& value);
};
output_proxy operator*();
function_output_iterator& operator++();
function_output_iterator& operator++(int);
};
``function_output_iterator`` requirements
-----------------------------------------
The ``UnaryFunction`` must be Assignable, Copy Constructible, and the
expression ``f(x)`` must be valid, where ``f`` is an object of type
``UnaryFunction`` and ``x`` is an object of a type accepted by ``f``.
The resulting ``function_output_iterator`` is a model of the Writable
and Incrementable Iterator concepts.
``function_output_iterator`` operations
---------------------------------------
``explicit function_output_iterator(const UnaryFunction& f = UnaryFunction());``
:Returns: An instance of ``function_output_iterator`` with
``f`` stored as a data member.
``output_proxy operator*();``
:Returns: An instance of ``output_proxy`` constructed with
a copy of the unary function ``f``.
``function_output_iterator& operator++();``
:Returns: ``*this``
``function_output_iterator& operator++(int);``
:Returns: ``*this``
``function_output_iterator::output_proxy`` operations
-----------------------------------------------------
``output_proxy(UnaryFunction& f);``
:Returns: An instance of ``output_proxy`` with ``f`` stored as
a data member.
``template <class T> output_proxy& operator=(const T& value);``
:Effects:
::
m_f(value);
return *this;

23
doc/indirect_iterator.rst Normal file
View File

@ -0,0 +1,23 @@
+++++++++++++++++++
Indirect Iterator
+++++++++++++++++++
:Author: David Abrahams, Jeremy Siek, Thomas Witt
: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`_
:date: $Date$
:copyright: Copyright Dave Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved
.. _`Boost Consulting`: http://www.boost-consulting.com
.. _`Open Systems Lab`: http://www.osl.iu.edu
.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de
:abstract:
.. include:: indirect_iterator_abstract.rst
.. contents:: Table of Contents
.. include:: indirect_iterator_ref.rst

8
doc/indirect_iterator_abstract.rst Normal file
View File

@ -0,0 +1,8 @@
The indirect iterator adapts an iterator by applying an *extra*
dereference inside of ``operator*()``. For example, this iterator
adaptor makes it possible to view a container of pointers
(e.g. ``list<foo*>``) as if it were a container of the pointed-to type
(e.g. ``list<foo>``) .
.. At some point we should add the capability to handle
iterators over smart pointers, which the impl handles. -JGS

96
doc/indirect_iterator_ref.rst Normal file
View File

@ -0,0 +1,96 @@
::
template <
class Iterator
, class Value = use_default
, class Category = use_default
, class Reference = use_default
, class Difference = use_default
>
class indirect_iterator
: public iterator_adaptor</* see discussion */>
{
friend class iterator_core_access;
public:
indirect_iterator();
indirect_iterator(Iterator x);
template <
class Iterator2, class Value2, class Category2
, class Reference2, class Difference2
>
indirect_iterator(
indirect_iterator<
Iterator2, Value2, Category2, Reference2, Difference2
> const& y
, typename enable_if_convertible<Iterator2, Iterator>::type* = 0 // exposition
);
private: // as-if specification
typename indirect_iterator::reference dereference() const
{
return **this->base();
}
};
``indirect_iterator`` requirements
..................................
The ``value_type`` of the ``Iterator`` template parameter should
itself be dereferenceable. The return type of the ``operator*`` for
the ``value_type`` must be the same type as the ``Reference`` template
parameter. The ``Value`` template parameter will be the ``value_type``
for the ``indirect_iterator``, unless ``Value`` is const. If ``Value``
is ``const X``, then ``value_type`` will be *non-* ``const X``. The
default for ``Value`` is
::
iterator_traits< iterator_traits<Iterator>::value_type >::value_type
If the default is used for ``Value``, then there must be a valid
specialization of ``iterator_traits`` for the value type of the base
iterator.
The ``Reference`` parameter will be the ``reference`` type of the
``indirect_iterator``. The default is ``Value&``.
The ``Category`` parameter is the ``iterator_category`` type for the
``indirect_iterator``. The default is
``iterator_traits<Iterator>::iterator_category``.
The indirect iterator will model the most refined standard traversal
concept that is modeled by the ``Iterator`` type. The indirect
iterator will model the most refined standard access concept that is
modeled by the value type of ``Iterator``.
``indirect_iterator`` operations
................................
``indirect_iterator();``
:Requires: ``Iterator`` must be Default Constructible.
:Returns: An instance of ``indirect_iterator`` with
a default constructed base object.
``indirect_iterator(Iterator x);``
:Returns: An instance of ``indirect_iterator`` with
the ``iterator_adaptor`` subobject copy constructed from ``x``.
::
template <
class Iterator2, class Value2, class Category2
, class Reference2, class Difference2
>
indirect_iterator(
indirect_iterator<
Iterator2, Value2, Category2, Reference2, Difference2
> const& y
, typename enable_if_convertible<Iterator2, Iterator>::type* = 0 // exposition
);
:Requires: ``Iterator2`` is implicitly convertible to ``Iterator``.
:Returns: An instance of ``indirect_iterator`` that is a copy of ``y``.

31
doc/permutation_iterator.rst Normal file
View File

@ -0,0 +1,31 @@
++++++++++++++++++++++
Permutation Iterator
++++++++++++++++++++++
:Author: Toon Knapen, David Abrahams, Roland Richter, Jeremy Siek
:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu
:organization: `Boost Consulting`_, Indiana University `Open Systems
Lab`_
:date: $Date$
:copyright: Copyright Toon Knapen, Dave Abrahams, Roland Richter, and Jeremy Siek 2003. All rights reserved
.. _`Boost Consulting`: http://www.boost-consulting.com
.. _`Open Systems Lab`: http://www.osl.iu.edu
:abstract:
.. include:: permutation_iterator_abstract.rst
.. contents:: Table of Contents
Introduction
============
.. include:: permutation_iterator_body.rst
Reference
=========
.. include:: permutation_iterator_ref.rst

4
doc/permutation_iterator_abstract.rst Normal file
View File

@ -0,0 +1,4 @@
The permutation iterator adaptor provides a permuted view of a given
range. That is, the view includes every element of the given range but
in a potentially different order.

15
doc/permutation_iterator_body.rst Normal file
View File

@ -0,0 +1,15 @@
The adaptor takes two arguments:
* an iterator to the range V on which the permutation
will be applied
* the reindexing scheme that defines how the
elements of V will be permuted.
Note that the permutation iterator is not limited to strict
permutations of the given range V. The distance between begin and end
of the reindexing iterators is allowed to be smaller compared to the
size of the range V, in which case the permutation iterator only
provides a permutation of a subrange of V. The indexes neither need
to be unique. In this same context, it must be noted that the past the
end permutation iterator is completely defined by means of the
past-the-end iterator to the indices.

54
doc/permutation_iterator_ref.rst Normal file
View File

@ -0,0 +1,54 @@
.. parsed-literal::
template< class ElementIterator
, class IndexIterator
, class ValueT = use_default
, class CategoryT = use_default
, class ReferenceT = use_default
, class DifferenceT = use_default >
class permutation_iterator
: public iterator_adaptor<...>
{
typedef iterator_adaptor<...>
friend class iterator_core_access;
public:
permutation_iterator();
explicit permutation_iterator(ElementIterator x, IndexIterator y);
template< class OEIter, class OIIter, class V, class C, class R, class D >
permutation_iterator(
permutation_iterator<OEIter, OIIter, V, C, R, D> const& r
, typename enable_if_convertible<OEIter, ElementIterator>::type* = 0
, typename enable_if_convertible<OIIter, IndexIterator>::type* = 0
);
};
``permutation_iterator`` requirements
-------------------------------------
``ElementIterator`` must be a model of RandomAccessIterator__.
``IndexIterator`` must at least be a model ForwardIterator__. The
value type of the ``IndexIterator`` must be convertible to the
difference type of ``ElementIterator``.
__ http://www.sgi.com/tech/stl/RandomAccessIterator.html
__ http://www.sgi.com/tech/stl/ForwardIterator.html
``permutation_iterator`` operations
-----------------------------------
The permutation iterator implements the member functions and operators
required for the `Random Access Iterator`__ concept. However, the
permutation iterator can only meet the complexity guarantees of the
same concept as the IndexIterator. Thus for instance, although the
permutation iterator provides ``operator+=(distance)``, this operation
will take linear time in case the IndexIterator is a model of
ForwardIterator instead of amortized constant time.
__ http://www.sgi.com/tech/stl/RandomAccessIterator.html

23
doc/reverse_iterator.rst Normal file
View File

@ -0,0 +1,23 @@
++++++++++++++++++
Reverse Iterator
++++++++++++++++++
:Author: David Abrahams, Jeremy Siek, Thomas Witt
: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`_
:date: $Date$
:copyright: Copyright Dave Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved
.. _`Boost Consulting`: http://www.boost-consulting.com
.. _`Open Systems Lab`: http://www.osl.iu.edu
.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de
:abstract:
.. include:: reverse_iterator_abstract.rst
.. contents:: Table of Contents
.. include:: reverse_iterator_ref.rst

6
doc/reverse_iterator_abstract.rst Normal file
View File

@ -0,0 +1,6 @@
.. I think we'd better strike the old reverse_iterator text from the standard, eh?
The reverse iterator adaptor flips the direction of a base iterator's
motion. Invoking ``operator++()`` moves the base iterator backward and
invoking ``operator--()`` moves the base iterator forward.

69
doc/reverse_iterator_ref.rst Normal file
View File

@ -0,0 +1,69 @@
::
template <class Iterator>
class reverse_iterator :
public iterator_adaptor< reverse_iterator<Iterator>, Iterator >
{
friend class iterator_core_access;
public:
reverse_iterator() {}
explicit reverse_iterator(Iterator x) ;
template<class OtherIterator>
reverse_iterator(
reverse_iterator<OtherIterator> const& r
, typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
);
private: // as-if specification
typename reverse_iterator::reference dereference() const { return *prior(this->base()); }
void increment() { --this->base_reference(); }
void decrement() { ++this->base_reference(); }
void advance(typename reverse_iterator::difference_type n)
{
this->base_reference() += -n;
}
template <class OtherIterator>
typename reverse_iterator::difference_type
distance_to(reverse_iterator<OtherIterator> const& y) const
{
return this->base_reference() - y.base();
}
};
``reverse_iterator`` requirements
.................................
The base ``Iterator`` must be a model of Bidirectional Traversal
Iterator. The resulting ``reverse_iterator`` will be a model of the
most refined standard traversal and access concepts that are modeled
by ``Iterator``.
``reverse_iterator();``
:Requires: ``Iterator`` must be Default Constructible.
:Returns: An instance of ``reverse_iterator`` with a
default constructed base object.
``explicit reverse_iterator(Iterator x);``
:Returns: An instance of ``reverse_iterator`` with a
base object copy constructed from ``x``.
::
template<class OtherIterator>
reverse_iterator(
reverse_iterator<OtherIterator> const& r
, typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
);
:Requires: ``OtherIterator`` is implicitly convertible to ``Iterator``.
:Returns: An instance of ``reverse_iterator`` that is a copy of ``r``.

23
doc/transform_iterator.rst Normal file
View File

@ -0,0 +1,23 @@
++++++++++++++++++++
Transform Iterator
++++++++++++++++++++
:Author: David Abrahams, Jeremy Siek, Thomas Witt
: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`_
:date: $Date$
:copyright: Copyright Dave Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved
.. _`Boost Consulting`: http://www.boost-consulting.com
.. _`Open Systems Lab`: http://www.osl.iu.edu
.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de
:abstract:
.. include:: transform_iterator_abstract.rst
.. contents:: Table of Contents
.. include:: transform_iterator_ref.rst

5
doc/transform_iterator_abstract.rst Normal file
View File

@ -0,0 +1,5 @@
The transform iterator adapts an iterator by applying some function
object to the result of dereferencing the iterator. In other words,
the ``operator*`` of the transform iterator first dereferences the
base iterator, passes the result of this to the function object, and
then returns the result.

95
doc/transform_iterator_ref.rst Normal file
View File

@ -0,0 +1,95 @@
::
template <class AdaptableUnaryFunction,
class Iterator,
class Reference = use_default,
class Value = use_default>
class transform_iterator
: public iterator_adaptor</* see discussion */>
{
friend class iterator_core_access;
public:
transform_iterator();
transform_iterator(Iterator const& x, AdaptableUnaryFunction f);
template<class OtherIterator, class R2, class V2>
transform_iterator(
transform_iterator<AdaptableUnaryFunction, OtherIterator, R2, V2> const& t
, typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
);
AdaptableUnaryFunction functor() const;
private:
typename transform_iterator::value_type dereference() const;
AdaptableUnaryFunction m_f;
};
``transform_iterator`` requirements
...................................
The type ``AdaptableUnaryFunction`` must be Assignable, Copy
Constructible, and the expression ``f(x)`` must be valid where ``f``
is an object of type ``AdaptableUnaryFunction``, ``x`` is an object of
type ``AdaptableUnaryFunction::argument_type``, and where the type of
``f(x)`` must be ``AdaptableUnaryFunction::result_type``.
The type ``Iterator`` must at least model Readable Iterator. The
resulting ``transform_iterator`` models the most refined of the
following options that is also modeled by ``Iterator``.
* Writable Lvalue Iterator if the ``result_type`` of the
``AdaptableUnaryFunction`` is a non-const reference.
* Readable Lvalue Iterator if the ``result_type`` is a const
reference.
* Readable Iterator otherwise.
The ``transform_iterator`` models the most refined standard traversal
concept that is modeled by ``Iterator``.
The ``value_type`` of ``transform_iterator`` is
``remove_reference<result_type>::type``. The ``reference`` type is
``result_type``.
``transform_iterator`` public operations
........................................
``transform_iterator();``
:Returns: An instance of ``transform_iterator`` with ``m_f``
and ``m_iterator`` default constructed.
``transform_iterator(Iterator const& x, AdaptableUnaryFunction f);``
:Returns: An instance of ``transform_iterator`` with ``m_f``
initialized to ``f`` and ``m_iterator`` initialized to ``x``.
::
template<class OtherIterator, class R2, class V2>
transform_iterator(
transform_iterator<AdaptableUnaryFunction, OtherIterator, R2, V2> const& t
, typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
);
:Returns: An instance of ``transform_iterator`` that is a copy of ``t``.
:Requires: ``OtherIterator`` is implicitly convertible to ``Iterator``.
``AdaptableUnaryFunction functor() const;``
:Returns: ``m_f``
``transform_iterator`` private operations
.........................................
``typename transform_iterator::value_type dereference() const;``
:Returns: ``m_f(transform_iterator::dereference());``