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

This commit was manufactured by cvs2svn to create branch 'RC_1_31_0'.

Browse Source 
[SVN r21989]
This commit is contained in:
nobody
2004-01-27 04:12:55 +00:00
parent be55d6db14
commit a4dbdcb00c
28 changed files with 12870 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
doc/counting_iterator.pdf Executable file
View File

Binary file not shown.

228
doc/facade-and-adaptor.diff Executable file
View File

@ -0,0 +1,228 @@
Index: facade-and-adaptor.rst
===================================================================
RCS file: /cvsroot/boost/boost/libs/iterator/doc/facade-and-adaptor.rst,v
retrieving revision 1.9
retrieving revision 1.14
diff -b -d -u -r1.9 -r1.14
--- facade-and-adaptor.rst 22 Sep 2003 19:55:00 -0000 1.9
+++ facade-and-adaptor.rst 18 Jan 2004 15:51:06 -0000 1.14
@@ -3,17 +3,25 @@ None
+++++++++++++++++++++++++++++
:Author: David Abrahams, Jeremy Siek, Thomas Witt
-:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@acm.org
+:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@styleadvisor.com
:organization: `Boost Consulting`_, Indiana University `Open Systems
- Lab`_, University of Hanover `Institute for Transport
- Railway Operation and Construction`_
-:date: $Date: 2004/01/18 19:56:39 $
-:Number: N1530=03-0113
+ Lab`_, `Zephyr Associates, Inc.`_
+:date: $Date: 2004/01/18 19:56:39 $
+
+:Number: This is a revised version of N1530_\ =03-0113, which was
+ accepted for Technical Report 1 by the C++ standard
+ committee's library working group.
+
+.. Version 1.9 of this ReStructuredText document corresponds to
+ n1530_, the paper accepted by the LWG.
+
+.. _n1530: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1530.html
+
:copyright: Copyright David 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
+.. _`Zephyr Associates, Inc.`: http://www.styleadvisor.com
:abstract: We propose a set of class templates that help programmers
build standard-conforming iterators, both from scratch and
@@ -124,15 +132,15 @@ None
=================
This proposal is formulated in terms of the new ``iterator concepts``
-as proposed in `n1477`_, since user-defined and especially adapted
+as proposed in n1550_, since user-defined and especially adapted
iterators suffer from the well known categorization problems that are
inherent to the current iterator categories.
-.. _`n1477`: http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/papers/2003/n1477.html
+.. _n1550: http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/papers/2003/n1550.html
-This proposal does not strictly depend on proposal `n1477`_, as there
+This proposal does not strictly depend on proposal n1550_, as there
is a direct mapping between new and old categories. This proposal
-could be reformulated using this mapping if `n1477`_ was not accepted.
+could be reformulated using this mapping if n1550_ was not accepted.
Interoperability
================
@@ -141,24 +149,24 @@ None
current standard. There are currently two defect reports that are
concerned with interoperability issues.
-Issue `179`_ concerns the fact that mutable container iterator types
+Issue 179_ concerns the fact that mutable container iterator types
are only required to be convertible to 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
+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`_ concerns the current lack of interoperability between
+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
+.. _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
Iterator Facade
@@ -195,7 +203,7 @@ None
* ``filter_iterator``, which provides a view of an iterator range in
which some elements of the underlying range are skipped.
-.. _counting_iterator:
+.. _counting:
* ``counting_iterator``, which adapts any incrementable type
(e.g. integers, iterators) so that incrementing/decrementing the
@@ -226,15 +234,13 @@ Issue 9.1 et al
::
struct use_default;
- const unsigned use_default_access = -1;
struct iterator_core_access { /* implementation detail */ };
template <
class Derived
, class Value
- , unsigned AccessCategory
- , class TraversalCategory
+ , class CategoryOrTraversal
, class Reference = Value&
, class Difference = ptrdiff_t
>
@@ -244,8 +250,7 @@ Issue 9.1 et al.
class Derived
, class Base
, class Value = use_default
- , unsigned Access = use_default_access
- , class Traversal = use_default
+ , class CategoryOrTraversal = use_default
, class Reference = use_default
, class Difference = use_default
>
@@ -254,10 +259,9 @@ Issue 9.1 et al.
template <
class Iterator
, class Value = use_default
- , unsigned Access = use_default_access
- , class Traversal = use_default
+ , class CategoryOrTraversal = use_default
, class Reference = use_default
, class Difference = use_default
>
class indirect_iterator;
Issue 9.44y
+ template <class Dereferenceable>
+ struct pointee;
+
+ template <class Dereferenceable>
+ struct indirect_reference;
+
template <class Iterator>
class reverse_iterator;
@@ -277,8 +287,7 @@ Issue 9.1 et al.
template <
class Incrementable
- , unsigned Access = use_default_access
- , class Traversal = use_default
+ , class CategoryOrTraversal = use_default
, class Difference = use_default
>
class counting_iterator
@@ -312,17 +321,35 @@ Issue 9.8
Specialized adaptors [lib.iterator.special.adaptors]
====================================================
-.. The requirements for all of these need to be written *much* more
- formally -DWA
-
-[*Note:* The ``enable_if_convertible<X,Y>::type`` expression used in
+The ``enable_if_convertible<X,Y>::type`` expression used in
this section is for exposition purposes. The converting constructors
for specialized adaptors should be only be in an overload set provided
that an object of type ``X`` is implicitly convertible to an object of
-type ``Y``. The ``enable_if_convertible`` approach uses SFINAE to
+type ``Y``.
+The signatures involving ``enable_if_convertible`` should behave
+*as-if* ``enable_if_convertible`` were defined to be::
+
+ template <bool> enable_if_convertible_impl
+ {};
+
+ template <> enable_if_convertible_impl<true>
+ { struct type; };
+
+ template<typename From, typename To>
+ struct enable_if_convertible
+ : enable_if_convertible_impl<is_convertible<From,To>::value>
+ {};
+
+If an expression other than the default argument is used to supply
+the value of a function parameter whose type is written in terms
+of ``enable_if_convertible``, the program is ill-formed, no
+diagnostic required.
+
+[*Note:* The ``enable_if_convertible`` approach uses SFINAE to
take the constructor out of the overload set when the types are not
-implicitly convertible.]
+implicitly convertible.
+]
Indirect iterator
@@ -330,6 +357,16 @@ Issue 9.44y
.. include:: indirect_iterator_abstract.rst
+Class template ``pointee``
+....................................
+
+.. include:: pointee_ref.rst
+
+Class template ``indirect_reference``
+.....................................
+
+.. include:: indirect_reference_ref.rst
+
Class template ``indirect_iterator``
....................................
@@ -393,8 +430,7 @@
-..
- LocalWords: Abrahams Siek Witt istream ostream iter MTL strided interoperate
+.. LocalWords: Abrahams Siek Witt istream ostream iter MTL strided interoperate
LocalWords: CRTP metafunctions inlining lvalue JGS incrementable BGL LEDA cv
LocalWords: GraphBase struct ptrdiff UnaryFunction const int typename bool pp
LocalWords: lhs rhs SFINAE markup iff tmp OtherDerived OtherIterator DWA foo

5108
doc/facade-and-adaptor.pdf Executable file
View File

File diff suppressed because one or more lines are too long

BIN
doc/filter_iterator.pdf Executable file
View File

Binary file not shown.

BIN
doc/function_output_iterator.pdf Executable file
View File

Binary file not shown.

BIN
doc/indirect_iterator.pdf Executable file
View File

Binary file not shown.

245
doc/indirect_iterator_ref.diff Normal file
View File

@ -0,0 +1,245 @@
Index: indirect_iterator_ref.rst
===================================================================
RCS file: /cvsroot/boost/boost/libs/iterator/doc/indirect_iterator_ref.rst,v
retrieving revision 1.2
retrieving revision 1.21
diff -w -d -u -b -r1.2 -r1.21
--- indirect_iterator_ref.rst 22 Sep 2003 19:55:00 -0000 1.2
+++ indirect_iterator_ref.rst 15 Jan 2004 00:01:33 -0000 1.21
@@ -3,82 +3,139 @@
template <
class Iterator
, class Value = use_default
Issue 9.15
- , unsigned Access = use_default_access
- , class Traversal = use_default
+ , class CategoryOrTraversal = use_default
, class Reference = use_default
, class Difference = use_default
>
class indirect_iterator
Issue 9.37x
- : public iterator_adaptor</* see discussion */>
{
- friend class iterator_core_access;
public:
+ typedef /* see below */ value_type;
+ typedef /* see below */ reference;
+ typedef /* see below */ pointer;
+ typedef /* see below */ difference_type;
+ typedef /* see below */ iterator_category;
+
indirect_iterator();
indirect_iterator(Iterator x);
+
Issue 9.15
template <
- class Iterator2, class Value2, unsigned Access2, class Traversal2
+ class Iterator2, class Value2, class Category2
, class Reference2, class Difference2
>
indirect_iterator(
indirect_iterator<
- Iterator2, Value2, Access2, Traversal2, Reference2, Difference2
+ Iterator2, Value2, Category2, Reference2, Difference2
> const& y
, typename enable_if_convertible<Iterator2, Iterator>::type* = 0 // exposition
);
Issue 9.37x
- private: // as-if specification
- typename indirect_iterator::reference dereference() const
- {
- return **this->base();
- }
+
+ Iterator const& base() const;
+ reference operator*() const;
+ indirect_iterator& operator++();
+ indirect_iterator& operator--();
+ private:
+ Iterator m_iterator; // exposition
};
+
+The member types of ``indirect_iterator`` are defined according to
+the following pseudo-code, where ``V`` is
+``iterator_traits<Iterator>::value_type``
+
+.. parsed-literal::
+
+ if (Value is use_default) then
+ typedef remove_const<pointee<V>::type>::type value_type;
+ else
+ typedef remove_const<Value>::type value_type;
+
+ if (Reference is use_default) then
+ if (Value is use_default) then
+ typedef indirect_reference<V>::type reference;
+ else
+ typedef Value& reference;
+ else
+ typedef Reference reference;
+
+ if (Value is use_default) then
+ typedef pointee<V>::type\* pointer;
+ else
+ typedef Value\* pointer;
+
+ if (Difference is use_default)
+ typedef iterator_traits<Iterator>::difference_type difference_type;
+ else
+ typedef Difference difference_type;
+
+ if (CategoryOrTraversal is use_default)
+ typedef |iterator-category|_\ (
+ iterator_traversal<Iterator>::type,``reference``,``value_type``
+ ) iterator_category;
+ else
+ typedef |iterator-category|_\ (
+ CategoryOrTraversal,``reference``,``value_type``
+ ) iterator_category;
+
+
``indirect_iterator`` requirements
..................................
Issue 9.40x
-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
+The expression ``*v``, where ``v`` is an object of
+``iterator_traits<Iterator>::value_type``, shall be valid
+expression and convertible to ``reference``. ``Iterator`` shall
+model the traversal concept indicated by ``iterator_category``.
+``Value``, ``Reference``, and ``Difference`` shall be chosen so
+that ``value_type``, ``reference``, and ``difference_type`` meet
+the requirements indicated by ``iterator_category``.
-::
+[Note: there are further requirements on the
+``iterator_traits<Iterator>::value_type`` if the ``Value``
+parameter is not ``use_default``, as implied by the algorithm for
+deducing the default for the ``value_type`` member.]
- iterator_traits< iterator_traits<Iterator>::value_type >::value_type
Issue 9.37x
+``indirect_iterator`` models
+............................
-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.
+In addition to the concepts indicated by ``iterator_category``
+and by ``iterator_traversal<indirect_iterator>::type``, a
+specialization of ``indirect_iterator`` models the following
+concepts, Where ``v`` is an object of
+``iterator_traits<Iterator>::value_type``:
-The ``Reference`` parameter will be the ``reference`` type of the
-``indirect_iterator``. The default is ``Value&``.
+ * Readable Iterator if ``reference(*v)`` is convertible to
+ ``value_type``.
-The ``Access`` and ``Traversal`` parameters are passed unchanged to
-the corresponding parameters of the ``iterator_adaptor`` base
-class, and the ``Iterator`` parameter is passed unchanged as the
-``Base`` parameter to the ``iterator_adaptor`` base class.
+ * Writable Iterator if ``reference(*v) = t`` is a valid
+ expression (where ``t`` is an object of type
+ ``indirect_iterator::value_type``)
-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``.
+ * Lvalue Iterator if ``reference`` is a reference type.
+
+``indirect_iterator<X,V1,C1,R1,D1>`` is interoperable with
+``indirect_iterator<Y,V2,C2,R2,D2>`` if and only if ``X`` is
+interoperable with ``Y``.
``indirect_iterator`` operations
................................
Issue 9.37x
+In addition to the operations required by the concepts described
+above, specializations of ``indirect_iterator`` provide the
+following operations.
+
+
Issue 9.28 and 9.37x
``indirect_iterator();``
:Requires: ``Iterator`` must be Default Constructible.
:Returns: An instance of ``indirect_iterator`` with
- a default constructed base object.
+ a default-constructed ``m_iterator``.
Issue 9.37x
``indirect_iterator(Iterator x);``
:Returns: An instance of ``indirect_iterator`` with
- the ``iterator_adaptor`` subobject copy constructed from ``x``.
+ ``m_iterator`` copy constructed from ``x``.
::
Issue 9.29
@@ -94,5 +151,27 @@
);
:Requires: ``Iterator2`` is implicitly convertible to ``Iterator``.
-:Returns: An instance of ``indirect_iterator`` that is a copy of ``y``.
+:Returns: An instance of ``indirect_iterator`` whose
+ ``m_iterator`` subobject is constructed from ``y.base()``.
+
Issue 9.37x
+``Iterator const& base() const;``
+:Returns: ``m_iterator``
+
+
+``reference operator*() const;``
+
+:Returns: ``**m_iterator``
+
+
+``indirect_iterator& operator++();``
+
+:Effects: ``++m_iterator``
+:Returns: ``*this``
+
+
+``indirect_iterator& operator--();``
+
+:Effects: ``--m_iterator``
+:Returns: ``*this``

BIN
doc/iterator_adaptor.pdf Executable file
View File

Binary file not shown.

22
doc/iterator_adaptor_abstract.diff Executable file
View File

@ -0,0 +1,22 @@
Index: iterator_adaptor_abstract.rst
===================================================================
RCS file: /cvsroot/boost/boost/libs/iterator/doc/iterator_adaptor_abstract.rst,v
retrieving revision 1.1
retrieving revision 1.2
diff -b -d -u -r1.1 -r1.2
--- iterator_adaptor_abstract.rst 5 Aug 2003 18:19:55 -0000 1.1
+++ iterator_adaptor_abstract.rst 24 Nov 2003 05:02:46 -0000 1.2
@@ -1,5 +1,11 @@ Issue 9.21
-The ``iterator_adaptor`` is a base class template derived from an
-instantiation of ``iterator_facade``. The core interface functions
+.. Version 1.1 of this ReStructuredText document corresponds to
+ n1530_, the paper accepted by the LWG.
+
+.. Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
+ rights reserved
+
+Each specialization of the ``iterator_adaptor`` class template is derived from
+a specialization of ``iterator_facade``. The core interface functions
expected by ``iterator_facade`` are implemented in terms of the
``iterator_adaptor``\ 's ``Base`` template parameter. A class derived
from ``iterator_adaptor`` typically redefines some of the core

35
doc/iterator_adaptor_body.diff Executable file
View File

@ -0,0 +1,35 @@
Index: iterator_adaptor_body.rst
===================================================================
RCS file: /cvsroot/boost/boost/libs/iterator/doc/iterator_adaptor_body.rst,v
retrieving revision 1.2
retrieving revision 1.3
diff -b -d -u -r1.2 -r1.3
--- iterator_adaptor_body.rst 22 Sep 2003 19:55:00 -0000 1.2
+++ iterator_adaptor_body.rst 24 Nov 2003 05:02:46 -0000 1.3
@@ -1,3 +1,9 @@
+.. Version 1.2 of this ReStructuredText document corresponds to
+ n1530_, the paper accepted by the LWG for TR1.
+
+.. Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
+ rights reserved
+
The ``iterator_adaptor`` class template adapts some ``Base`` [#base]_
type to create a new iterator. Instantiations of ``iterator_adaptor``
are derived from a corresponding instantiation of ``iterator_facade``
@@ -19,7 +25,7 @@ Issue 9.1 et al
redefined in the user's derived class.
Several of the template parameters of ``iterator_adaptor`` default
-to ``use_default`` (or ``use_default_access``). This allows the
+to ``use_default``. This allows the
user to make use of a default parameter even when she wants to
specify a parameter later in the parameter list. Also, the
defaults for the corresponding associated types are somewhat
@@ -28,6 +34,6 @@ Issue 9.45y
the identity of the ``use_default`` type is not left unspecified
because specification helps to highlight that the ``Reference``
template parameter may not always be identical to the iterator's
-``reference`` type, and will keep users making mistakes based on
+``reference`` type, and will keep users from making mistakes based on
that assumption.

216
doc/iterator_archetypes.html Executable file
View File

@ -0,0 +1,216 @@
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.3.1: http://docutils.sourceforge.net/" />
<title>Iterator Archetype</title>
<meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" />
<meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, Zephyr Associates, Inc." />
<meta name="date" content="2004-01-16" />
<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2004. All rights reserved" />
<link rel="stylesheet" href="default.css" type="text/css" />
</head>
<body>
<div class="document" id="iterator-archetype">
<h1 class="title">Iterator Archetype</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>David Abrahams, Jeremy Siek, Thomas Witt</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first reference" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="last reference" href="mailto:witt&#64;styleadvisor.com">witt&#64;styleadvisor.com</a></td></tr>
<tr><th class="docinfo-name">Organization:</th>
<td><a class="first reference" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference" href="http://www.osl.iu.edu">Open Systems
Lab</a>, <a class="last reference" href="http://www.styleadvisor.com">Zephyr Associates, Inc.</a></td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2004-01-16</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2004. All rights reserved</td></tr>
</tbody>
</table>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">abstract:</th><td class="field-body">iterator archetypes provide a means to check the compile time requirements of a generic component on its iterator arguments.</td>
</tr>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
<p class="topic-title"><a name="table-of-contents">Table of Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#reference" id="id1" name="id1">Reference</a><ul>
<li><a class="reference" href="#iterator-archetype-synopsis" id="id2" name="id2"><tt class="literal"><span class="pre">iterator_archetype</span></tt> Synopsis</a></li>
<li><a class="reference" href="#access-category-tags" id="id3" name="id3"><tt class="literal"><span class="pre">Access</span> <span class="pre">Category</span> <span class="pre">Tags</span></tt></a></li>
<li><a class="reference" href="#iterator-archetype-requirements" id="id4" name="id4"><tt class="literal"><span class="pre">iterator_archetype</span></tt> Requirements</a></li>
<li><a class="reference" href="#iterator-archetype-models" id="id5" name="id5"><tt class="literal"><span class="pre">iterator_archetype</span></tt> Models</a></li>
<li><a class="reference" href="#traits" id="id6" name="id6"><tt class="literal"><span class="pre">Traits</span></tt></a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="reference">
<h1><a class="toc-backref" href="#id1" name="reference">Reference</a></h1>
<div class="section" id="iterator-archetype-synopsis">
<h2><a class="toc-backref" href="#id2" name="iterator-archetype-synopsis"><tt class="literal"><span class="pre">iterator_archetype</span></tt> Synopsis</a></h2>
<pre class="literal-block">
namespace iterator_archetypes
{
// Access categories
typedef /*implementation defined*/ readable_iterator_t;
typedef /*implementation defined*/ writable_iterator_t;
typedef /*implementation defined*/ readable_writable_iterator_t;
typedef /*implementation defined*/ readable_lvalue_iterator_t;
typedef /*implementation defined*/ writable_lvalue_iterator_t;
}
template &lt;
class Value
, class AccessCategory
, class TraversalCategory
&gt;
class iterator_archetype
{
typedef /* see below */ value_type;
typedef /* see below */ reference;
typedef /* see below */ pointer;
typedef /* see below */ difference_type;
typedef /* see below */ iterator_category;
};
</pre>
</div>
<div class="section" id="access-category-tags">
<h2><a class="toc-backref" href="#id3" name="access-category-tags"><tt class="literal"><span class="pre">Access</span> <span class="pre">Category</span> <span class="pre">Tags</span></tt></a></h2>
<p>The access category types provided correspond to the following
standard iterator access concept combinations:</p>
<pre class="literal-block">
readable_iterator_t :=
Readable Iterator
writable_iterator_t :=
Writeable Iterator
readable_writable_iterator_t :=
Readable Iterator &amp; Writeable Iterator &amp; Swappable Iterator
readable_lvalue_iterator_t :=
Readable Iterator &amp; Lvalue Iterator
writeable_lvalue_iterator_t :=
Readable Iterator &amp; Writeable Iterator &amp; Swappable Iterator &amp; Lvalue Iterator
</pre>
</div>
<div class="section" id="iterator-archetype-requirements">
<h2><a class="toc-backref" href="#id4" name="iterator-archetype-requirements"><tt class="literal"><span class="pre">iterator_archetype</span></tt> Requirements</a></h2>
<p>The <tt class="literal"><span class="pre">AccessCategory</span></tt> argument must be one of the predefined access
category tags. The <tt class="literal"><span class="pre">TraversalCategory</span></tt> must be one of the standard
traversal tags. The <tt class="literal"><span class="pre">Value</span></tt> type must satisfy the requirements of
the iterator concept specified by <tt class="literal"><span class="pre">AccessCategory</span></tt> and
<tt class="literal"><span class="pre">TraversalCategory</span></tt> as implied by the nested traits types.</p>
</div>
<div class="section" id="iterator-archetype-models">
<h2><a class="toc-backref" href="#id5" name="iterator-archetype-models"><tt class="literal"><span class="pre">iterator_archetype</span></tt> Models</a></h2>
<p><tt class="literal"><span class="pre">iterator_archetype</span></tt> models the iterator concepts specified by the
<tt class="literal"><span class="pre">AccessCategory</span></tt> and <tt class="literal"><span class="pre">TraversalCategory</span></tt>
arguments. <tt class="literal"><span class="pre">iterator_archetype</span></tt> does not model any other access
concepts or any more derived traversal concepts.</p>
</div>
<div class="section" id="traits">
<h2><a class="toc-backref" href="#id6" name="traits"><tt class="literal"><span class="pre">Traits</span></tt></a></h2>
<p>The nested trait types are defined as follows:</p>
<pre class="literal-block">
if (AccessCategory == readable_iterator_t)
value_type = Value
reference = Value
pointer = Value*
else if (AccessCategory == writable_iterator_t)
value_type = void
reference = void
pointer = void
else if (AccessCategory == readable_writable_iterator_t)
value_type = Value
reference :=
A type X that is convertible to Value for which the following
expression is valid. Given an object x of type X and v of type
Value.
x = v
pointer = Value*
else if (AccessCategory == readable_lvalue_iterator_t)
value_type = Value
reference = Value const&amp;
pointer = Value const*
else if (AccessCategory == writable_lvalue_iterator_t)
value_type = Value
reference = Value&amp;
pointer = Value*
if ( TraversalCategory is convertible to forward_traversal_tag )
difference_type := ptrdiff_t
else
difference_type := unspecified type
iterator_category :=
A type X satisfying the following two constraints:
1. X is convertible to X1, and not to any more-derived
type, where X1 is defined by:
if (reference is a reference type
&amp;&amp; TraversalCategory is convertible to forward_traversal_tag)
{
if (TraversalCategory is convertible to random_access_traversal_tag)
X1 = random_access_iterator_tag
else if (TraversalCategory is convertible to bidirectional_traversal_tag)
X1 = bidirectional_iterator_tag
else
X1 = forward_iterator_tag
}
else
{
if (TraversalCategory is convertible to single_pass_traversal_tag
&amp;&amp; reference != void)
X1 = input_iterator_tag
else
X1 = output_iterator_tag
}
2. X is convertible to TraversalCategory
</pre>
</div>
</div>
</div>
<hr class="footer" />
<div class="footer">
<a class="reference" href="iterator_archetypes.rst">View document source</a>.
Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div>
</body>
</html>

BIN
doc/iterator_archetypes.pdf Executable file
View File

Binary file not shown.

181
doc/iterator_archetypes.rst Executable file
View File

@ -0,0 +1,181 @@
++++++++++++++++++++
Iterator Archetype
++++++++++++++++++++
:Author: David Abrahams, Jeremy Siek, Thomas Witt
:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@styleadvisor.com
:organization: `Boost Consulting`_, Indiana University `Open Systems
Lab`_, `Zephyr Associates, Inc.`_
:date: $Date$
:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2004. All rights reserved
.. _`Boost Consulting`: http://www.boost-consulting.com
.. _`Open Systems Lab`: http://www.osl.iu.edu
.. _`Zephyr Associates, Inc.`: http://www.styleadvisor.com
:abstract: iterator archetypes provide a means to check the compile time requirements of a generic component on its iterator arguments.
.. contents:: Table of Contents
Reference
=========
``iterator_archetype`` Synopsis
...............................
::
namespace iterator_archetypes
{
// Access categories
typedef /*implementation defined*/ readable_iterator_t;
typedef /*implementation defined*/ writable_iterator_t;
typedef /*implementation defined*/ readable_writable_iterator_t;
typedef /*implementation defined*/ readable_lvalue_iterator_t;
typedef /*implementation defined*/ writable_lvalue_iterator_t;
}
template <
class Value
, class AccessCategory
, class TraversalCategory
>
class iterator_archetype
{
typedef /* see below */ value_type;
typedef /* see below */ reference;
typedef /* see below */ pointer;
typedef /* see below */ difference_type;
typedef /* see below */ iterator_category;
};
``Access Category Tags``
........................
The access category types provided correspond to the following
standard iterator access concept combinations:
::
readable_iterator_t :=
Readable Iterator
writable_iterator_t :=
Writeable Iterator
readable_writable_iterator_t :=
Readable Iterator & Writeable Iterator & Swappable Iterator
readable_lvalue_iterator_t :=
Readable Iterator & Lvalue Iterator
writeable_lvalue_iterator_t :=
Readable Iterator & Writeable Iterator & Swappable Iterator & Lvalue Iterator
``iterator_archetype`` Requirements
...................................
The ``AccessCategory`` argument must be one of the predefined access
category tags. The ``TraversalCategory`` must be one of the standard
traversal tags. The ``Value`` type must satisfy the requirements of
the iterator concept specified by ``AccessCategory`` and
``TraversalCategory`` as implied by the nested traits types.
``iterator_archetype`` Models
.............................
``iterator_archetype`` models the iterator concepts specified by the
``AccessCategory`` and ``TraversalCategory``
arguments. ``iterator_archetype`` does not model any other access
concepts or any more derived traversal concepts.
``Traits``
..........
The nested trait types are defined as follows:
::
if (AccessCategory == readable_iterator_t)
value_type = Value
reference = Value
pointer = Value*
else if (AccessCategory == writable_iterator_t)
value_type = void
reference = void
pointer = void
else if (AccessCategory == readable_writable_iterator_t)
value_type = Value
reference :=
A type X that is convertible to Value for which the following
expression is valid. Given an object x of type X and v of type
Value.
x = v
pointer = Value*
else if (AccessCategory == readable_lvalue_iterator_t)
value_type = Value
reference = Value const&
pointer = Value const*
else if (AccessCategory == writable_lvalue_iterator_t)
value_type = Value
reference = Value&
pointer = Value*
if ( TraversalCategory is convertible to forward_traversal_tag )
difference_type := ptrdiff_t
else
difference_type := unspecified type
iterator_category :=
A type X satisfying the following two constraints:
1. X is convertible to X1, and not to any more-derived
type, where X1 is defined by:
if (reference is a reference type
&& TraversalCategory is convertible to forward_traversal_tag)
{
if (TraversalCategory is convertible to random_access_traversal_tag)
X1 = random_access_iterator_tag
else if (TraversalCategory is convertible to bidirectional_traversal_tag)
X1 = bidirectional_iterator_tag
else
X1 = forward_iterator_tag
}
else
{
if (TraversalCategory is convertible to single_pass_traversal_tag
&& reference != void)
X1 = input_iterator_tag
else
X1 = output_iterator_tag
}
2. X is convertible to TraversalCategory

3153
doc/iterator_facade.pdf Executable file
View File

File diff suppressed because it is too large Load Diff

8
doc/make_zip_iterator.rst Executable file
View File

@ -0,0 +1,8 @@
::
template<typename IteratorTuple>
zip_iterator<IteratorTuple>
make_zip_iterator(IteratorTuple t);
:Returns: An instance of ``zip_iterator<IteratorTuple>`` with ``m_iterator_tuple``
initialized to ``t``.

2761
doc/new-iter-concepts.pdf Executable file
View File

File diff suppressed because it is too large Load Diff

BIN
doc/permutation_iterator.pdf Executable file
View File

Binary file not shown.

BIN
doc/pointee.pdf Executable file
View File

Binary file not shown.

BIN
doc/reverse_iterator.pdf Executable file
View File

Binary file not shown.

BIN
doc/transform_iterator.pdf Executable file
View File

Binary file not shown.

202
doc/transform_iterator_ref.diff Normal file
View File

@ -0,0 +1,202 @@
Index: transform_iterator_ref.rst
===================================================================
RCS file: /cvsroot/boost/boost/libs/iterator/doc/transform_iterator_ref.rst,v
retrieving revision 1.3
retrieving revision 1.15
diff -w -d -u -b -r1.3 -r1.15
--- transform_iterator_ref.rst 21 Sep 2003 11:13:46 -0000 1.3
+++ transform_iterator_ref.rst 15 Jan 2004 00:06:57 -0000 1.15
@@ -1,3 +1,5 @@
+.. Version 1.3 of this document was accepted for TR1
+
::
template <class UnaryFunction,
@@ -5,26 +7,55 @@
class Reference = use_default,
class Value = use_default>
class transform_iterator
Issue 9.37x
- : public iterator_adaptor</* see discussion */>
{
- friend class iterator_core_access;
public:
+ typedef /* see below */ value_type;
+ typedef /* see below */ reference;
+ typedef /* see below */ pointer;
+ typedef iterator_traits<Iterator>::difference_type difference_type;
+ typedef /* see below */ iterator_category;
+
transform_iterator();
transform_iterator(Iterator const& x, UnaryFunction f);
Issue 9.43x
- template<class OtherIterator, class R2, class V2>
+ template<class F2, class I2, class R2, class V2>
transform_iterator(
- transform_iterator<UnaryFunction, OtherIterator, R2, V2> const& t
- , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
+ transform_iterator<F2, I2, R2, V2> const& t
+ , typename enable_if_convertible<I2, Iterator>::type* = 0 // exposition only
+ , typename enable_if_convertible<F2, UnaryFunction>::type* = 0 // exposition only
);
-
Issues 9.37x and 9.12
+ Iterator const& base() const;
+ reference operator*() const;
+ transform_iterator& operator++();
+ transform_iterator& operator--();
private:
- typename transform_iterator::value_type dereference() const;
- UnaryFunction m_f;
+ Iterator m_iterator; // exposition only
+ UnaryFunction m_f; // exposition only
};
Issue 9.41x
+If ``Reference`` is ``use_default`` then the ``reference`` member of
+``transform_iterator`` is
+``result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type``.
+Otherwise, ``reference`` is ``Reference``.
+
+If ``Value`` is ``use_default`` then the ``value_type`` member is
+``remove_cv<remove_reference<reference> >::type``. Otherwise,
+``value_type`` is ``Value``.
+
+
Issue 9.37x
+If ``Iterator`` models Readable Lvalue Iterator and if ``Iterator``
+models Random Access Traversal Iterator, then ``iterator_category`` is
+convertible to ``random_access_iterator_tag``. Otherwise, if
+``Iterator`` models Bidirectional Traversal Iterator, then
+``iterator_category`` is convertible to
+``bidirectional_iterator_tag``. Otherwise ``iterator_category`` is
+convertible to ``forward_iterator_tag``. If ``Iterator`` does not
+model Readable Lvalue Iterator then ``iterator_category`` is
+convertible to ``input_iterator_tag``.
+
+
``transform_iterator`` requirements
...................................
@@ -34,27 +65,55 @@
where the type of ``f(*i)`` must be
``result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type``.
Issue 9.37x
-The type ``Iterator`` must at least model Readable Iterator. The
-resulting ``transform_iterator`` models the most refined of the
+The argument ``Iterator`` shall model Readable Iterator.
+
+
+``transform_iterator`` models
+.............................
+
+The resulting ``transform_iterator`` models the most refined of the
following options that is also modeled by ``Iterator``.
- * Writable Lvalue Iterator if ``result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type`` is a non-const reference.
+ * Writable Lvalue Iterator if ``transform_iterator::reference`` is a non-const reference.
- * Readable Lvalue Iterator if ``result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type`` is a const
- reference.
+ * Readable Lvalue Iterator if ``transform_iterator::reference`` is a const reference.
* Readable Iterator otherwise.
-
The ``transform_iterator`` models the most refined standard traversal
-concept that is modeled by ``Iterator``.
+concept that is modeled by the ``Iterator`` argument.
Issue 9.41x
-The ``reference`` type of ``transform_iterator`` is
-``result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type``.
-The ``value_type`` is ``remove_cv<remove_reference<reference> >::type``.
Issue 9.37x.
+If ``transform_iterator`` is a model of Readable Lvalue Iterator then
+it models the following original iterator concepts depending on what
+the ``Iterator`` argument models.
-``transform_iterator`` public operations
-........................................
++-----------------------------------+---------------------------------+
+| If ``Iterator`` models | then ``filter_iterator`` models |
++===================================+=================================+
+| Single Pass Iterator | Input Iterator |
++-----------------------------------+---------------------------------+
+| Forward Traversal Iterator | Forward Iterator |
++-----------------------------------+---------------------------------+
+| Bidirectional Traversal Iterator | Bidirectional Iterator |
++-----------------------------------+---------------------------------+
+| Random Access Traversal Iterator | Random Access Iterator |
++-----------------------------------+---------------------------------+
+
+If ``transform_iterator`` models Writable Lvalue Iterator then it is a
+mutable iterator (as defined in the old iterator requirements).
+
+``transform_iterator<F1, X, R1, V1>`` is interoperable with
+``transform_iterator<F2, Y, R2, V2>`` if and only if ``X`` is
+interoperable with ``Y``.
+
+
+
+``transform_iterator`` operations
+.................................
+
+In addition to the operations required by the concepts modeled by
+``transform_iterator``, ``transform_iterator`` provides the following
+operations.
``transform_iterator();``
@@ -80,14 +139,30 @@
:Returns: An instance of ``transform_iterator`` that is a copy of ``t``.
:Requires: ``OtherIterator`` is implicitly convertible to ``Iterator``.
+
+``Iterator const& base() const;``
+
+:Returns: ``m_iterator``
+
+
``UnaryFunction functor() const;``
:Returns: ``m_f``
-``transform_iterator`` private operations
-.........................................
-``typename transform_iterator::value_type dereference() const;``
+``reference operator*() const;``
-:Returns: ``m_f(transform_iterator::dereference());``
+:Returns: ``m_f(*m_iterator)``
+
+
+``transform_iterator& operator++();``
+
+:Effects: ``++m_iterator``
+:Returns: ``*this``
+
+
+``transform_iterator& operator--();``
+
+:Effects: ``--m_iterator``
+:Returns: ``*this``

352
doc/zip_iterator.html Executable file
View File

@ -0,0 +1,352 @@
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.3.1: http://docutils.sourceforge.net/" />
<title>Zip Iterator</title>
<meta name="author" content="David Abrahams, Thomas Becker" />
<meta name="organization" content="Boost Consulting, Zephyr Associates, Inc." />
<meta name="date" content="2004-01-19" />
<meta name="copyright" content="Copyright David Abrahams and Thomas Becker 2003. All rights reserved" />
<link rel="stylesheet" href="default.css" type="text/css" />
</head>
<body>
<div class="document" id="zip-iterator">
<h1 class="title">Zip Iterator</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>David Abrahams, Thomas Becker</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first reference" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="last reference" href="mailto:thomas&#64;styleadvisor.com">thomas&#64;styleadvisor.com</a></td></tr>
<tr><th class="docinfo-name">Organization:</th>
<td><a class="first reference" href="http://www.boost-consulting.com">Boost Consulting</a>, <a class="last reference" href="http://www.styleadvisor.com">Zephyr Associates, Inc.</a></td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2004-01-19</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>Copyright David Abrahams and Thomas Becker 2003. All rights reserved</td></tr>
</tbody>
</table>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">abstract:</th><td class="field-body">The zip iterator provides the ability to parallel-iterate
over several controlled sequences simultaneously. A zip
iterator is constructed from a tuple of iterators. Moving
the zip iterator moves all the iterators in parallel.
Dereferencing the zip iterator returns a tuple that contains
the results of dereferencing the individual iterators.</td>
</tr>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
<p class="topic-title"><a name="table-of-contents">Table of Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#zip-iterator-synopsis" id="id2" name="id2"><tt class="literal"><span class="pre">zip_iterator</span></tt> synopsis</a></li>
<li><a class="reference" href="#zip-iterator-requirements" id="id3" name="id3"><tt class="literal"><span class="pre">zip_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#zip-iterator-models" id="id4" name="id4"><tt class="literal"><span class="pre">zip_iterator</span></tt> models</a></li>
<li><a class="reference" href="#zip-iterator-operations" id="id5" name="id5"><tt class="literal"><span class="pre">zip_iterator</span></tt> operations</a></li>
<li><a class="reference" href="#examples" id="id6" name="id6">Examples</a></li>
</ul>
</div>
<div class="section" id="zip-iterator-synopsis">
<h1><a class="toc-backref" href="#id2" name="zip-iterator-synopsis"><tt class="literal"><span class="pre">zip_iterator</span></tt> synopsis</a></h1>
<pre class="literal-block">
template&lt;typename IteratorTuple&gt;
class zip_iterator
{
public:
typedef /* see below */ reference;
typedef reference value_type;
typedef value_type* pointer;
typedef /* see below */ difference_type;
typedef /* see below */ iterator_category;
zip_iterator();
zip_iterator(IteratorTuple iterator_tuple);
template&lt;typename OtherIteratorTuple&gt;
zip_iterator(
const zip_iterator&lt;OtherIteratorTuple&gt;&amp; other
, typename enable_if_convertible&lt;
OtherIteratorTuple
, IteratorTuple&gt;::type* = 0 // exposition only
);
const IteratorTuple&amp; get_iterator_tuple() const;
private:
IteratorTuple m_iterator_tuple; // exposition only
};
template&lt;typename IteratorTuple&gt;
zip_iterator&lt;IteratorTuple&gt;
make_zip_iterator(IteratorTuple t);
</pre>
<p>The <tt class="literal"><span class="pre">reference</span></tt> member of <tt class="literal"><span class="pre">zip_iterator</span></tt> is the type of the tuple
made of the reference types of the iterator types in the <tt class="literal"><span class="pre">IteratorTuple</span></tt>
argument.</p>
<p>The <tt class="literal"><span class="pre">difference_type</span></tt> member of <tt class="literal"><span class="pre">zip_iterator</span></tt> is the <tt class="literal"><span class="pre">difference_type</span></tt>
of the first of the iterator types in the <tt class="literal"><span class="pre">IteratorTuple</span></tt> argument.</p>
<p>The <tt class="literal"><span class="pre">iterator_category</span></tt> member of <tt class="literal"><span class="pre">zip_iterator</span></tt> is convertible to the
minimum of the traversal categories of the iterator types in the <tt class="literal"><span class="pre">IteratorTuple</span></tt>
argument. For example, if the <tt class="literal"><span class="pre">zip_iterator</span></tt> holds only vector
iterators, then <tt class="literal"><span class="pre">iterator_category</span></tt> is convertible to
<tt class="literal"><span class="pre">boost::random_access_traversal_tag</span></tt>. If you add a list iterator, then
<tt class="literal"><span class="pre">iterator_category</span></tt> will be convertible to <tt class="literal"><span class="pre">boost::bidirectional_traversal_tag</span></tt>,
but no longer to <tt class="literal"><span class="pre">boost::random_access_traversal_tag</span></tt>.</p>
</div>
<div class="section" id="zip-iterator-requirements">
<h1><a class="toc-backref" href="#id3" name="zip-iterator-requirements"><tt class="literal"><span class="pre">zip_iterator</span></tt> requirements</a></h1>
<p>All iterator types in the argument <tt class="literal"><span class="pre">IteratorTuple</span></tt> shall model Readable Iterator.</p>
</div>
<div class="section" id="zip-iterator-models">
<h1><a class="toc-backref" href="#id4" name="zip-iterator-models"><tt class="literal"><span class="pre">zip_iterator</span></tt> models</a></h1>
<p>The resulting <tt class="literal"><span class="pre">zip_iterator</span></tt> models Readable Iterator.</p>
<p>The fact that the <tt class="literal"><span class="pre">zip_iterator</span></tt> models only Readable Iterator does not
prevent you from modifying the values that the individual iterators point
to. The tuple returned by the <tt class="literal"><span class="pre">zip_iterator</span></tt>'s <tt class="literal"><span class="pre">operator*</span></tt> is a tuple
constructed from the reference types of the individual iterators, not
their value types. For example, if <tt class="literal"><span class="pre">zip_it</span></tt> is a <tt class="literal"><span class="pre">zip_iterator</span></tt> whose
first member iterator is an <tt class="literal"><span class="pre">std::vector&lt;double&gt;::iterator</span></tt>, then the
following line will modify the value which the first member iterator of
<tt class="literal"><span class="pre">zip_it</span></tt> currently points to:</p>
<pre class="literal-block">
zip_it-&gt;get&lt;0&gt;() = 42.0;
</pre>
<p>Consider the set of standard traversal concepts obtained by taking
the most refined standard traversal concept modeled by each individual
iterator type in the <tt class="literal"><span class="pre">IteratorTuple</span></tt> argument.The <tt class="literal"><span class="pre">zip_iterator</span></tt>
models the least refined standard traversal concept in this set.</p>
<p><tt class="literal"><span class="pre">zip_iterator&lt;IteratorTuple1&gt;</span></tt> is interoperable with
<tt class="literal"><span class="pre">zip_iterator&lt;IteratorTuple2&gt;</span></tt> if and only if <tt class="literal"><span class="pre">IteratorTuple1</span></tt>
is interoperable with <tt class="literal"><span class="pre">IteratorTuple2</span></tt>.</p>
</div>
<div class="section" id="zip-iterator-operations">
<h1><a class="toc-backref" href="#id5" name="zip-iterator-operations"><tt class="literal"><span class="pre">zip_iterator</span></tt> operations</a></h1>
<p>In addition to the operations required by the concepts modeled by
<tt class="literal"><span class="pre">zip_iterator</span></tt>, <tt class="literal"><span class="pre">zip_iterator</span></tt> provides the following
operations.</p>
<p><tt class="literal"><span class="pre">zip_iterator();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">zip_iterator</span></tt> with <tt class="literal"><span class="pre">m_iterator_tuple</span></tt>
default constructed.</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">zip_iterator(IteratorTuple</span> <span class="pre">iterator_tuple);</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">zip_iterator</span></tt> with <tt class="literal"><span class="pre">m_iterator_tuple</span></tt>
initialized to <tt class="literal"><span class="pre">iterator_tuple</span></tt>.</td>
</tr>
</tbody>
</table>
<pre class="literal-block">
template&lt;typename OtherIteratorTuple&gt;
zip_iterator(
const zip_iterator&lt;OtherIteratorTuple&gt;&amp; other
, typename enable_if_convertible&lt;
OtherIteratorTuple
, IteratorTuple&gt;::type* = 0 // exposition only
);
</pre>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">zip_iterator</span></tt> that is a copy of <tt class="literal"><span class="pre">other</span></tt>.</td>
</tr>
<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="literal"><span class="pre">OtherIteratorTuple</span></tt> is implicitly convertible to <tt class="literal"><span class="pre">IteratorTuple</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">const</span> <span class="pre">IteratorTuple&amp;</span> <span class="pre">get_iterator_tuple()</span> <span class="pre">const;</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">m_iterator_tuple</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">reference</span> <span class="pre">operator*()</span> <span class="pre">const;</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">A tuple consisting of the results of dereferencing all iterators in
<tt class="literal"><span class="pre">m_iterator_tuple</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">zip_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Increments each iterator in <tt class="literal"><span class="pre">m_iterator_tuple</span></tt>.</td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">*this</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="literal"><span class="pre">zip_iterator&amp;</span> <span class="pre">operator--();</span></tt></p>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Decrements each iterator in <tt class="literal"><span class="pre">m_iterator_tuple</span></tt>.</td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">*this</span></tt></td>
</tr>
</tbody>
</table>
<pre class="literal-block">
template&lt;typename IteratorTuple&gt;
zip_iterator&lt;IteratorTuple&gt;
make_zip_iterator(IteratorTuple t);
</pre>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">zip_iterator&lt;IteratorTuple&gt;</span></tt> with <tt class="literal"><span class="pre">m_iterator_tuple</span></tt>
initialized to <tt class="literal"><span class="pre">t</span></tt>.</td>
</tr>
</tbody>
</table>
<pre class="literal-block">
template&lt;typename IteratorTuple&gt;
zip_iterator&lt;IteratorTuple&gt;
make_zip_iterator(IteratorTuple t);
</pre>
<table class="field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">zip_iterator&lt;IteratorTuple&gt;</span></tt> with <tt class="literal"><span class="pre">m_iterator_tuple</span></tt>
initialized to <tt class="literal"><span class="pre">t</span></tt>.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples">
<h1><a class="toc-backref" href="#id6" name="examples">Examples</a></h1>
<p>There are two main types of applications of the <tt class="literal"><span class="pre">zip_iterator</span></tt>. The first
one concerns runtime efficiency: If one has several controlled sequences
of the same length that must be somehow processed, e.g., with the
<tt class="literal"><span class="pre">for_each</span></tt> algorithm, then it is more efficient to perform just
one parallel-iteration rather than several individual iterations. For an
example, assume that <tt class="literal"><span class="pre">vect_of_doubles</span></tt> and <tt class="literal"><span class="pre">vect_of_ints</span></tt>
are two vectors of equal length containing doubles and ints, respectively,
and consider the following two iterations:</p>
<pre class="literal-block">
std::vector&lt;double&gt;::const_iterator beg1 = vect_of_doubles.begin();
std::vector&lt;double&gt;::const_iterator end1 = vect_of_doubles.end();
std::vector&lt;int&gt;::const_iterator beg2 = vect_of_ints.begin();
std::vector&lt;int&gt;::const_iterator end2 = vect_of_ints.end();
std::for_each(beg1, end1, func_0());
std::for_each(beg2, end2, func_1());
</pre>
<p>These two iterations can now be replaced with a single one as follows:</p>
<pre class="literal-block">
std::for_each(
boost::make_zip_iterator(
boost::make_tuple(beg1, beg2)
),
boost::make_zip_iterator(
boost::make_tuple(end1, end2)
),
zip_func()
);
</pre>
<p>A non-generic implementation of <tt class="literal"><span class="pre">zip_func</span></tt> could look as follows:</p>
<pre class="literal-block">
struct zip_func :
public std::unary_function&lt;const boost::tuple&lt;const double&amp;, const int&amp;&gt;&amp;, void&gt;
{
void operator()(const boost::tuple&lt;const double&amp;, const int&amp;&gt;&amp; t) const
{
m_f0(t.get&lt;0&gt;());
m_f1(t.get&lt;1&gt;());
}
private:
func_0 m_f0;
func_1 m_f1;
};
</pre>
<p>The second important application of the <tt class="literal"><span class="pre">zip_iterator</span></tt> is as a building block
to make combining iterators. A combining iterator is an iterator
that parallel-iterates over several controlled sequences and, upon
dereferencing, returns the result of applying a functor to the values of the
sequences at the respective positions. This can now be achieved by using the
<tt class="literal"><span class="pre">zip_iterator</span></tt> in conjunction with the <tt class="literal"><span class="pre">transform_iterator</span></tt>.</p>
<p>Suppose, for example, that you have two vectors of doubles, say
<tt class="literal"><span class="pre">vect_1</span></tt> and <tt class="literal"><span class="pre">vect_2</span></tt>, and you need to expose to a client
a controlled sequence containing the products of the elements of
<tt class="literal"><span class="pre">vect_1</span></tt> and <tt class="literal"><span class="pre">vect_2</span></tt>. Rather than placing these products
in a third vector, you can use a combining iterator that calculates the
products on the fly. Let us assume that <tt class="literal"><span class="pre">tuple_multiplies</span></tt> is a
functor that works like <tt class="literal"><span class="pre">std::multiplies</span></tt>, except that it takes
its two arguments packaged in a tuple. Then the two iterators
<tt class="literal"><span class="pre">it_begin</span></tt> and <tt class="literal"><span class="pre">it_end</span></tt> defined below delimit a controlled
sequence containing the products of the elements of <tt class="literal"><span class="pre">vect_1</span></tt> and
<tt class="literal"><span class="pre">vect_2</span></tt>:</p>
<pre class="literal-block">
typedef boost::tuple&lt;
std::vector&lt;double&gt;::const_iterator,
std::vector&lt;double&gt;::const_iterator
&gt; the_iterator_tuple;
typedef boost::zip_iterator&lt;
the_iterator_tuple
&gt; the_zip_iterator;
typedef boost::transform_iterator&lt;
tuple_multiplies&lt;double&gt;,
the_zip_iterator
&gt; the_transform_iterator;
the_transform_iterator it_begin(
the_zip_iterator(
the_iterator_tuple(
vect_1.begin(),
vect_2.begin()
)
),
tuple_multiplies&lt;double&gt;()
);
the_transform_iterator it_end(
the_zip_iterator(
the_iterator_tuple(
vect_1.end(),
vect_2.end()
)
),
tuple_multiplies&lt;double&gt;()
);
</pre>
<p>The source code for these examples can be found <a class="reference" href="../example/zip_iterator_examples.cpp">here</a>.</p>
</div>
</div>
<hr class="footer" />
<div class="footer">
<a class="reference" href="zip_iterator.rst">View document source</a>.
Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div>
</body>
</html>

BIN
doc/zip_iterator.pdf Executable file
View File

Binary file not shown.

25
doc/zip_iterator.rst Executable file
View File

@ -0,0 +1,25 @@
+++++++++++++
Zip Iterator
+++++++++++++
:Author: David Abrahams, Thomas Becker
:Contact: dave@boost-consulting.com, thomas@styleadvisor.com
:organization: `Boost Consulting`_, `Zephyr Associates, Inc.`_
:date: $Date$
:copyright: Copyright David Abrahams and Thomas Becker 2003. All rights reserved
.. _`Boost Consulting`: http://www.boost-consulting.com
.. _`Zephyr Associates, Inc.`: http://www.styleadvisor.com
:abstract:
.. include:: zip_iterator_abstract.rst
.. contents:: Table of Contents
``zip_iterator`` synopsis
...............................
.. include:: zip_iterator_ref.rst
.. include:: make_zip_iterator.rst
.. include:: zip_iterator_eg.rst

6
doc/zip_iterator_abstract.rst Executable file
View File

@ -0,0 +1,6 @@
The zip iterator provides the ability to parallel-iterate
over several controlled sequences simultaneously. A zip
iterator is constructed from a tuple of iterators. Moving
the zip iterator moves all the iterators in parallel.
Dereferencing the zip iterator returns a tuple that contains
the results of dereferencing the individual iterators.

117
doc/zip_iterator_eg.rst Executable file
View File

@ -0,0 +1,117 @@
Examples
........
There are two main types of applications of the ``zip_iterator``. The first
one concerns runtime efficiency: If one has several controlled sequences
of the same length that must be somehow processed, e.g., with the
``for_each`` algorithm, then it is more efficient to perform just
one parallel-iteration rather than several individual iterations. For an
example, assume that ``vect_of_doubles`` and ``vect_of_ints``
are two vectors of equal length containing doubles and ints, respectively,
and consider the following two iterations:
::
std::vector<double>::const_iterator beg1 = vect_of_doubles.begin();
std::vector<double>::const_iterator end1 = vect_of_doubles.end();
std::vector<int>::const_iterator beg2 = vect_of_ints.begin();
std::vector<int>::const_iterator end2 = vect_of_ints.end();
std::for_each(beg1, end1, func_0());
std::for_each(beg2, end2, func_1());
These two iterations can now be replaced with a single one as follows:
::
std::for_each(
boost::make_zip_iterator(
boost::make_tuple(beg1, beg2)
),
boost::make_zip_iterator(
boost::make_tuple(end1, end2)
),
zip_func()
);
A non-generic implementation of ``zip_func`` could look as follows:
::
struct zip_func :
public std::unary_function<const boost::tuple<const double&, const int&>&, void>
{
void operator()(const boost::tuple<const double&, const int&>& t) const
{
m_f0(t.get<0>());
m_f1(t.get<1>());
}
private:
func_0 m_f0;
func_1 m_f1;
};
The second important application of the ``zip_iterator`` is as a building block
to make combining iterators. A combining iterator is an iterator
that parallel-iterates over several controlled sequences and, upon
dereferencing, returns the result of applying a functor to the values of the
sequences at the respective positions. This can now be achieved by using the
``zip_iterator`` in conjunction with the ``transform_iterator``.
Suppose, for example, that you have two vectors of doubles, say
``vect_1`` and ``vect_2``, and you need to expose to a client
a controlled sequence containing the products of the elements of
``vect_1`` and ``vect_2``. Rather than placing these products
in a third vector, you can use a combining iterator that calculates the
products on the fly. Let us assume that ``tuple_multiplies`` is a
functor that works like ``std::multiplies``, except that it takes
its two arguments packaged in a tuple. Then the two iterators
``it_begin`` and ``it_end`` defined below delimit a controlled
sequence containing the products of the elements of ``vect_1`` and
``vect_2``:
::
typedef boost::tuple<
std::vector<double>::const_iterator,
std::vector<double>::const_iterator
> the_iterator_tuple;
typedef boost::zip_iterator<
the_iterator_tuple
> the_zip_iterator;
typedef boost::transform_iterator<
tuple_multiplies<double>,
the_zip_iterator
> the_transform_iterator;
the_transform_iterator it_begin(
the_zip_iterator(
the_iterator_tuple(
vect_1.begin(),
vect_2.begin()
)
),
tuple_multiplies<double>()
);
the_transform_iterator it_end(
the_zip_iterator(
the_iterator_tuple(
vect_1.end(),
vect_2.end()
)
),
tuple_multiplies<double>()
);
The source code for these examples can be found `here`__.
__ ../example/zip_iterator_examples.cpp

152
doc/zip_iterator_ref.rst Executable file
View File

@ -0,0 +1,152 @@
::
template<typename IteratorTuple>
class zip_iterator
{
public:
typedef /* see below */ reference;
typedef reference value_type;
typedef value_type* pointer;
typedef /* see below */ difference_type;
typedef /* see below */ iterator_category;
zip_iterator();
zip_iterator(IteratorTuple iterator_tuple);
template<typename OtherIteratorTuple>
zip_iterator(
const zip_iterator<OtherIteratorTuple>& other
, typename enable_if_convertible<
OtherIteratorTuple
, IteratorTuple>::type* = 0 // exposition only
);
const IteratorTuple& get_iterator_tuple() const;
private:
IteratorTuple m_iterator_tuple; // exposition only
};
template<typename IteratorTuple>
zip_iterator<IteratorTuple>
make_zip_iterator(IteratorTuple t);
The ``reference`` member of ``zip_iterator`` is the type of the tuple
made of the reference types of the iterator types in the ``IteratorTuple``
argument.
The ``difference_type`` member of ``zip_iterator`` is the ``difference_type``
of the first of the iterator types in the ``IteratorTuple`` argument.
The ``iterator_category`` member of ``zip_iterator`` is convertible to the
minimum of the traversal categories of the iterator types in the ``IteratorTuple``
argument. For example, if the ``zip_iterator`` holds only vector
iterators, then ``iterator_category`` is convertible to
``boost::random_access_traversal_tag``. If you add a list iterator, then
``iterator_category`` will be convertible to ``boost::bidirectional_traversal_tag``,
but no longer to ``boost::random_access_traversal_tag``.
``zip_iterator`` requirements
...................................
All iterator types in the argument ``IteratorTuple`` shall model Readable Iterator.
``zip_iterator`` models
.............................
The resulting ``zip_iterator`` models Readable Iterator.
The fact that the ``zip_iterator`` models only Readable Iterator does not
prevent you from modifying the values that the individual iterators point
to. The tuple returned by the ``zip_iterator``'s ``operator*`` is a tuple
constructed from the reference types of the individual iterators, not
their value types. For example, if ``zip_it`` is a ``zip_iterator`` whose
first member iterator is an ``std::vector<double>::iterator``, then the
following line will modify the value which the first member iterator of
``zip_it`` currently points to:
::
zip_it->get<0>() = 42.0;
Consider the set of standard traversal concepts obtained by taking
the most refined standard traversal concept modeled by each individual
iterator type in the ``IteratorTuple`` argument.The ``zip_iterator``
models the least refined standard traversal concept in this set.
``zip_iterator<IteratorTuple1>`` is interoperable with
``zip_iterator<IteratorTuple2>`` if and only if ``IteratorTuple1``
is interoperable with ``IteratorTuple2``.
``zip_iterator`` operations
.................................
In addition to the operations required by the concepts modeled by
``zip_iterator``, ``zip_iterator`` provides the following
operations.
``zip_iterator();``
:Returns: An instance of ``zip_iterator`` with ``m_iterator_tuple``
default constructed.
``zip_iterator(IteratorTuple iterator_tuple);``
:Returns: An instance of ``zip_iterator`` with ``m_iterator_tuple``
initialized to ``iterator_tuple``.
::
template<typename OtherIteratorTuple>
zip_iterator(
const zip_iterator<OtherIteratorTuple>& other
, typename enable_if_convertible<
OtherIteratorTuple
, IteratorTuple>::type* = 0 // exposition only
);
:Returns: An instance of ``zip_iterator`` that is a copy of ``other``.
:Requires: ``OtherIteratorTuple`` is implicitly convertible to ``IteratorTuple``.
``const IteratorTuple& get_iterator_tuple() const;``
:Returns: ``m_iterator_tuple``
``reference operator*() const;``
:Returns: A tuple consisting of the results of dereferencing all iterators in
``m_iterator_tuple``.
``zip_iterator& operator++();``
:Effects: Increments each iterator in ``m_iterator_tuple``.
:Returns: ``*this``
``zip_iterator& operator--();``
:Effects: Decrements each iterator in ``m_iterator_tuple``.
:Returns: ``*this``
::
template<typename IteratorTuple>
zip_iterator<IteratorTuple>
make_zip_iterator(IteratorTuple t);
:Returns: An instance of ``zip_iterator<IteratorTuple>`` with ``m_iterator_tuple``
initialized to ``t``.

59
test/interoperable.cpp Executable file
View File

@ -0,0 +1,59 @@
// Copyright David Abrahams 2004. Use, modification and distribution is
// subject to the Boost Software License, Version 1.0. (See accompanying
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
#include <boost/iterator/iterator_adaptor.hpp>
#include <boost/pending/iterator_tests.hpp>
#include <cassert>
struct mutable_it : boost::iterator_adaptor<mutable_it,int*>
{
typedef boost::iterator_adaptor<mutable_it,int*> super_t;
mutable_it();
explicit mutable_it(int* p) : super_t(p) {}
bool equal(mutable_it const& rhs) const
{
return this->base() == rhs.base();
}
};
struct constant_it : boost::iterator_adaptor<constant_it,int const*>
{
typedef boost::iterator_adaptor<constant_it,int const*> super_t;
constant_it();
explicit constant_it(int* p) : super_t(p) {}
constant_it(mutable_it const& x) : super_t(x.base()) {}
bool equal(constant_it const& rhs) const
{
return this->base() == rhs.base();
}
};
int main()
{
int data[] = { 49, 77 };
mutable_it i(data);
constant_it j(data + 1);
assert(i < j);
assert(j > i);
assert(i <= j);
assert(j >= i);
assert(j - i == 1);
assert(i - j == -1);
constant_it k = i;
assert(!(i < k));
assert(!(k > i));
assert(i <= k);
assert(k >= i);
assert(k - i == 0);
assert(i - k == 0);
return 0;
}