w4kek/WSJT-X
1
0
Fork 0
mirror of https://github.com/saitohirga/WSJT-X.git synced 2026-06-02 14:04:55 -04:00
Code Issues Packages Projects Releases Wiki Activity

Squashed 'boost/' content from commit b4feb19f2

Browse Source 
git-subtree-dir: boost
git-subtree-split: b4feb19f287ee92d87a9624b5d36b7cf46aeadeb
This commit is contained in:
Bill Somerville
2018-06-09 21:48:32 +01:00
commit 4ebe6417a5
12444 changed files with 2327021 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
libs/iterator/doc/BidirectionalTraversal.html
+76
View File
@@ -0,0 +1,76 @@
<?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.5: http://docutils.sourceforge.net/" />
<title>Bidirectional Traversal Concept</title>
<link rel="stylesheet" href="../../../rst.css" type="text/css" />
</head>
<body>
<div class="document" id="bidirectional-traversal-concept">
<h1 class="title">Bidirectional Traversal Concept</h1>
<!-- Copyright David Abrahams 2006. Distributed under 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) -->
<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> models the <em>Bidirectional Traversal</em>
concept if, in addition to <tt class="docutils literal"><span class="pre">X</span></tt> meeting the requirements of Forward
Traversal Iterator, the following expressions are valid and respect
the stated semantics.</p>
<table border="1" class="docutils">
<colgroup>
<col width="38%" />
<col width="37%" />
<col width="25%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head" colspan="3">Bidirectional Traversal Iterator Requirements (in addition to Forward Traversal
Iterator)</th>
</tr>
<tr><th class="head">Expression</th>
<th class="head">Return Type</th>
<th class="head">Assertion/Semantics /
Pre-/Post-condition</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">--r</span></tt></td>
<td><tt class="docutils literal"><span class="pre">X&amp;</span></tt></td>
<td>pre: there exists
<tt class="docutils literal"><span class="pre">s</span></tt> such that <tt class="docutils literal"><span class="pre">r</span>
<span class="pre">==</span> <span class="pre">++s</span></tt>. post:
<tt class="docutils literal"><span class="pre">s</span></tt> is
dereferenceable.
<tt class="docutils literal"><span class="pre">--(++r)</span> <span class="pre">==</span> <span class="pre">r</span></tt>.
<tt class="docutils literal"><span class="pre">--r</span> <span class="pre">==</span> <span class="pre">--s</span></tt>
implies <tt class="docutils literal"><span class="pre">r</span> <span class="pre">==</span>
<span class="pre">s</span></tt>. <tt class="docutils literal"><span class="pre">&amp;r</span> <span class="pre">==</span> <span class="pre">&amp;--r</span></tt>.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">r--</span></tt></td>
<td>convertible to <tt class="docutils literal"><span class="pre">const</span> <span class="pre">X&amp;</span></tt></td>
<td><pre class="first last literal-block">
{
X tmp = r;
--r;
return tmp;
}
</pre>
</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt></td>
<td>Convertible to
<tt class="docutils literal"><span class="pre">bidirectional_traversal_tag</span></tt></td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</div>
<div class="footer">
<hr class="footer" />
<a class="reference external" href="BidirectionalTraversal.rst">View document source</a>.
Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div>
</body>
</html>
libs/iterator/doc/BidirectionalTraversal.rst
+41
View File
@@ -0,0 +1,41 @@
.. Copyright David Abrahams 2006. Distributed under 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)
Bidirectional Traversal Concept
...............................
A class or built-in type ``X`` models the *Bidirectional Traversal*
concept if, in addition to ``X`` meeting the requirements of Forward
Traversal Iterator, the following expressions are valid and respect
the stated semantics.
+--------------------------------------------------------------------------------------+
|Bidirectional Traversal Iterator Requirements (in addition to Forward Traversal |
|Iterator) |
+--------------------------------+-------------------------------+---------------------+
|Expression |Return Type |Assertion/Semantics /|
| | |Pre-/Post-condition |
+================================+===============================+=====================+
|``--r`` |``X&`` |pre: there exists |
| | |``s`` such that ``r |
| | |== ++s``. post: |
| | |``s`` is |
| | |dereferenceable. |
| | |``--(++r) == r``. |
| | |``--r == --s`` |
| | |implies ``r == |
| | |s``. ``&r == &--r``. |
+--------------------------------+-------------------------------+---------------------+
|``r--`` |convertible to ``const X&`` |:: |
| | | |
| | | { |
| | | X tmp = r; |
| | | --r; |
| | | return tmp; |
| | | } |
+--------------------------------+-------------------------------+---------------------+
|``iterator_traversal<X>::type`` |Convertible to | |
| |``bidirectional_traversal_tag``| |
| | | |
+--------------------------------+-------------------------------+---------------------+
libs/iterator/doc/ForwardTraversal.html
+67
View File
@@ -0,0 +1,67 @@
<?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.5: http://docutils.sourceforge.net/" />
<title>Forward Traversal Concept</title>
<link rel="stylesheet" href="../../../rst.css" type="text/css" />
</head>
<body>
<div class="document" id="forward-traversal-concept">
<h1 class="title">Forward Traversal Concept</h1>
<!-- Copyright David Abrahams 2006. Distributed under 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) -->
<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> models the <em>Forward Traversal</em>
concept if, in addition to <tt class="docutils literal"><span class="pre">X</span></tt> meeting the requirements of Default
Constructible and Single Pass Iterator, the following expressions are
valid and respect the stated semantics.</p>
<table border="1" class="docutils">
<colgroup>
<col width="38%" />
<col width="34%" />
<col width="27%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head" colspan="3">Forward Traversal Iterator Requirements (in addition to Default Constructible and Single Pass Iterator)</th>
</tr>
<tr><th class="head">Expression</th>
<th class="head">Return Type</th>
<th class="head">Assertion/Note</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">X</span> <span class="pre">u;</span></tt></td>
<td><tt class="docutils literal"><span class="pre">X&amp;</span></tt></td>
<td>note: <tt class="docutils literal"><span class="pre">u</span></tt> may have a
singular value.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">++r</span></tt></td>
<td><tt class="docutils literal"><span class="pre">X&amp;</span></tt></td>
<td><tt class="docutils literal"><span class="pre">r</span> <span class="pre">==</span> <span class="pre">s</span></tt> and <tt class="docutils literal"><span class="pre">r</span></tt> is
dereferenceable implies
<tt class="docutils literal"><span class="pre">++r</span> <span class="pre">==</span> <span class="pre">++s.</span></tt></td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">iterator_traits&lt;X&gt;::difference_type</span></tt></td>
<td>A signed integral type representing
the distance between iterators</td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt></td>
<td>Convertible to
<tt class="docutils literal"><span class="pre">forward_traversal_tag</span></tt></td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</div>
<div class="footer">
<hr class="footer" />
<a class="reference external" href="ForwardTraversal.rst">View document source</a>.
Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div>
</body>
</html>
libs/iterator/doc/ForwardTraversal.rst
+31
View File
@@ -0,0 +1,31 @@
.. Copyright David Abrahams 2006. Distributed under 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)
Forward Traversal Concept
.........................
A class or built-in type ``X`` models the *Forward Traversal*
concept if, in addition to ``X`` meeting the requirements of Default
Constructible and Single Pass Iterator, the following expressions are
valid and respect the stated semantics.
+--------------------------------------------------------------------------------------------------------+
|Forward Traversal Iterator Requirements (in addition to Default Constructible and Single Pass Iterator) |
+---------------------------------------+-----------------------------------+----------------------------+
|Expression |Return Type |Assertion/Note |
+=======================================+===================================+============================+
|``X u;`` |``X&`` |note: ``u`` may have a |
| | |singular value. |
+---------------------------------------+-----------------------------------+----------------------------+
|``++r`` |``X&`` |``r == s`` and ``r`` is |
| | |dereferenceable implies |
| | |``++r == ++s.`` |
+---------------------------------------+-----------------------------------+----------------------------+
|``iterator_traits<X>::difference_type``|A signed integral type representing| |
| |the distance between iterators | |
| | | |
+---------------------------------------+-----------------------------------+----------------------------+
|``iterator_traversal<X>::type`` |Convertible to | |
| |``forward_traversal_tag`` | |
+---------------------------------------+-----------------------------------+----------------------------+
libs/iterator/doc/GNUmakefile
+15
View File
@@ -0,0 +1,15 @@
# Copyright David Abrahams 2004. Distributed under 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)
ECHO = /bin/echo
all:
@${ECHO} "<boost-root>/libs/iterator/doc/GNUmakefile should be replaced by"
@${ECHO}
@${ECHO} " http://www.boost-consulting.com/writing/GNUmakefile,"
@${ECHO}
@${ECHO} "before proceeding. That file is not included in the Boost"
@${ECHO} "distribution because it is licensed under the GPL, which violates"
@${ECHO} "Boost license requirements."
libs/iterator/doc/IncrementableIterator.html
+66
View File
@@ -0,0 +1,66 @@
<?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.5: http://docutils.sourceforge.net/" />
<title>Incrementable Iterator Concept</title>
<link rel="stylesheet" href="../../../rst.css" type="text/css" />
</head>
<body>
<div class="document" id="incrementable-iterator-concept">
<h1 class="title">Incrementable Iterator Concept</h1>
<!-- Copyright David Abrahams 2006. Distributed under 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) -->
<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> models the <em>Incrementable Iterator</em>
concept if, in addition to <tt class="docutils literal"><span class="pre">X</span></tt> being Assignable and Copy
Constructible, the following expressions are valid and respect the
stated semantics.</p>
<table border="1" class="docutils">
<colgroup>
<col width="39%" />
<col width="37%" />
<col width="24%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head" colspan="3">Incrementable Iterator Requirements (in addition to Assignable, Copy Constructible)</th>
</tr>
<tr><th class="head">Expression</th>
<th class="head">Return Type</th>
<th class="head">Assertion/Semantics</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">++r</span></tt></td>
<td><tt class="docutils literal"><span class="pre">X&amp;</span></tt></td>
<td><tt class="docutils literal"><span class="pre">&amp;r</span> <span class="pre">==</span> <span class="pre">&amp;++r</span></tt></td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">r++</span></tt></td>
<td><tt class="docutils literal"><span class="pre">X</span></tt></td>
<td><pre class="first last literal-block">
{
X tmp = r;
++r;
return tmp;
}
</pre>
</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt></td>
<td>Convertible to
<tt class="docutils literal"><span class="pre">incrementable_traversal_tag</span></tt></td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</div>
<div class="footer">
<hr class="footer" />
<a class="reference external" href="IncrementableIterator.rst">View document source</a>.
Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div>
</body>
</html>
libs/iterator/doc/IncrementableIterator.rst
+32
View File
@@ -0,0 +1,32 @@
.. Copyright David Abrahams 2006. Distributed under 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)
Incrementable Iterator Concept
..............................
A class or built-in type ``X`` models the *Incrementable Iterator*
concept if, in addition to ``X`` being Assignable and Copy
Constructible, the following expressions are valid and respect the
stated semantics.
+-------------------------------------------------------------------------------------+
|Incrementable Iterator Requirements (in addition to Assignable, Copy Constructible) |
| |
+--------------------------------+-------------------------------+--------------------+
|Expression |Return Type |Assertion/Semantics |
+================================+===============================+====================+
|``++r`` |``X&`` |``&r == &++r`` |
+--------------------------------+-------------------------------+--------------------+
|``r++`` |``X`` |:: |
| | | |
| | | { |
| | | X tmp = r; |
| | | ++r; |
| | | return tmp; |
| | | } |
+--------------------------------+-------------------------------+--------------------+
|``iterator_traversal<X>::type`` |Convertible to | |
| |``incrementable_traversal_tag``| |
+--------------------------------+-------------------------------+--------------------+
libs/iterator/doc/InteroperableIterator.rst
+61
View File
@@ -0,0 +1,61 @@
.. Copyright David Abrahams 2006. Distributed under 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)
Interoperable Iterator Concept
..............................
A class or built-in type ``X`` that models Single Pass Iterator is
*interoperable with* a class or built-in type ``Y`` that also models
Single Pass Iterator if the following expressions are valid and
respect the stated semantics. In the tables below, ``x`` is an object
of type ``X``, ``y`` is an object of type ``Y``, ``Distance`` is
``iterator_traits<Y>::difference_type``, and ``n`` represents a
constant object of type ``Distance``.
+-----------+-----------------------+---------------------------------------------------+
|Expression |Return Type |Assertion/Precondition/Postcondition |
+===========+=======================+===================================================+
|``y = x`` |``Y`` |post: ``y == x`` |
+-----------+-----------------------+---------------------------------------------------+
|``Y(x)`` |``Y`` |post: ``Y(x) == x`` |
+-----------+-----------------------+---------------------------------------------------+
|``x == y`` |convertible to ``bool``|``==`` is an equivalence relation over its domain. |
+-----------+-----------------------+---------------------------------------------------+
|``y == x`` |convertible to ``bool``|``==`` is an equivalence relation over its domain. |
+-----------+-----------------------+---------------------------------------------------+
|``x != y`` |convertible to ``bool``|``bool(a==b) != bool(a!=b)`` over its domain. |
+-----------+-----------------------+---------------------------------------------------+
|``y != x`` |convertible to ``bool``|``bool(a==b) != bool(a!=b)`` over its domain. |
+-----------+-----------------------+---------------------------------------------------+
If ``X`` and ``Y`` both model Random Access Traversal Iterator then
the following additional requirements must be met.
+-----------+-----------------------+---------------------+--------------------------------------+
|Expression |Return Type |Operational Semantics|Assertion/ Precondition |
+===========+=======================+=====================+======================================+
|``x < y`` |convertible to ``bool``|``y - x > 0`` |``<`` is a total ordering relation |
+-----------+-----------------------+---------------------+--------------------------------------+
|``y < x`` |convertible to ``bool``|``x - y > 0`` |``<`` is a total ordering relation |
+-----------+-----------------------+---------------------+--------------------------------------+
|``x > y`` |convertible to ``bool``|``y < x`` |``>`` is a total ordering relation |
+-----------+-----------------------+---------------------+--------------------------------------+
|``y > x`` |convertible to ``bool``|``x < y`` |``>`` is a total ordering relation |
+-----------+-----------------------+---------------------+--------------------------------------+
|``x >= y`` |convertible to ``bool``|``!(x < y)`` | |
+-----------+-----------------------+---------------------+--------------------------------------+
|``y >= x`` |convertible to ``bool``|``!(y < x)`` | |
+-----------+-----------------------+---------------------+--------------------------------------+
|``x <= y`` |convertible to ``bool``|``!(x > y)`` | |
+-----------+-----------------------+---------------------+--------------------------------------+
|``y <= x`` |convertible to ``bool``|``!(y > x)`` | |
+-----------+-----------------------+---------------------+--------------------------------------+
|``y - x`` |``Distance`` |``distance(Y(x),y)`` |pre: there exists a value ``n`` of |
| | | |``Distance`` such that ``x + n == y``.|
| | | |``y == x + (y - x)``. |
+-----------+-----------------------+---------------------+--------------------------------------+
|``x - y`` |``Distance`` |``distance(y,Y(x))`` |pre: there exists a value ``n`` of |
| | | |``Distance`` such that ``y + n == x``.|
| | | |``x == y + (x - y)``. |
+-----------+-----------------------+---------------------+--------------------------------------+
libs/iterator/doc/Jamfile.v2
+27
View File
@@ -0,0 +1,27 @@
# Copyright Thomas Witt 2005. Use, modification, and distribution are
# 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)
using quickbook ;
xml iterator
:
quickbook/iterator.qbk
;
boostbook standalone
:
iterator
:
<xsl:param>boost.root=../../../..
<xsl:param>toc.max.depth=3
<xsl:param>toc.section.depth=3
<xsl:param>chunk.section.depth=4
<format>pdf:<xsl:param>boost.url.prefix=http://www.boost.org/doc/libs/release/libs/iterator/doc
;
###############################################################################
alias boostdoc ;
explicit boostdoc ;
alias boostrelease : standalone ;
explicit boostrelease ;
libs/iterator/doc/LvalueIterator.html
+56
View File
@@ -0,0 +1,56 @@
<?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.5: http://docutils.sourceforge.net/" />
<title>Lvalue Iterator Concept</title>
<link rel="stylesheet" href="../../../rst.css" type="text/css" />
</head>
<body>
<div class="document" id="lvalue-iterator-concept">
<h1 class="title">Lvalue Iterator Concept</h1>
<!-- Copyright David Abrahams 2006. Distributed under 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) -->
<p>The <em>Lvalue Iterator</em> concept adds the requirement that the return
type of <tt class="docutils literal"><span class="pre">operator*</span></tt> type be a reference to the value type of the
iterator.</p>
<table border="1" class="docutils">
<colgroup>
<col width="22%" />
<col width="19%" />
<col width="59%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head" colspan="3">Lvalue Iterator Requirements</th>
</tr>
<tr><th class="head">Expression</th>
<th class="head">Return Type</th>
<th class="head">Note/Assertion</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">*a</span></tt></td>
<td><tt class="docutils literal"><span class="pre">T&amp;</span></tt></td>
<td><tt class="docutils literal"><span class="pre">T</span></tt> is <em>cv</em>
<tt class="docutils literal"><span class="pre">iterator_traits&lt;X&gt;::value_type</span></tt>
where <em>cv</em> is an optional
cv-qualification.
pre: <tt class="docutils literal"><span class="pre">a</span></tt> is
dereferenceable. If <tt class="docutils literal"><span class="pre">a</span>
<span class="pre">==</span> <span class="pre">b</span></tt> then <tt class="docutils literal"><span class="pre">*a</span></tt> is
equivalent to <tt class="docutils literal"><span class="pre">*b</span></tt>.</td>
</tr>
</tbody>
</table>
</div>
<div class="footer">
<hr class="footer" />
<a class="reference external" href="LvalueIterator.rst">View document source</a>.
Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div>
</body>
</html>
libs/iterator/doc/LvalueIterator.rst
+25
View File
@@ -0,0 +1,25 @@
.. Copyright David Abrahams 2006. Distributed under 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)
Lvalue Iterator Concept
.......................
The *Lvalue Iterator* concept adds the requirement that the return
type of ``operator*`` type be a reference to the value type of the
iterator.
+-------------------------------------------------------------+
| Lvalue Iterator Requirements |
+-------------+-----------+-----------------------------------+
|Expression |Return Type|Note/Assertion |
+=============+===========+===================================+
|``*a`` | ``T&`` |``T`` is *cv* |
| | |``iterator_traits<X>::value_type`` |
| | |where *cv* is an optional |
| | |cv-qualification. |
| | |pre: ``a`` is |
| | |dereferenceable. If ``a |
| | |== b`` then ``*a`` is |
| | |equivalent to ``*b``. |
+-------------+-----------+-----------------------------------+
libs/iterator/doc/RandomAccessTraversal.html
+134
View File
@@ -0,0 +1,134 @@
<?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.5: http://docutils.sourceforge.net/" />
<title>Random Access Traversal Concept</title>
<link rel="stylesheet" href="../../../rst.css" type="text/css" />
</head>
<body>
<div class="document" id="random-access-traversal-concept">
<h1 class="title">Random Access Traversal Concept</h1>
<!-- Copyright David Abrahams 2006. Distributed under 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) -->
<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> models the <em>Random Access Traversal</em>
concept if the following expressions are valid and respect the stated
semantics. In the table below, <tt class="docutils literal"><span class="pre">Distance</span></tt> is
<tt class="docutils literal"><span class="pre">iterator_traits&lt;X&gt;::difference_type</span></tt> and <tt class="docutils literal"><span class="pre">n</span></tt> represents a
constant object of type <tt class="docutils literal"><span class="pre">Distance</span></tt>.</p>
<table border="1" class="docutils">
<colgroup>
<col width="28%" />
<col width="30%" />
<col width="23%" />
<col width="20%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head" colspan="4">Random Access Traversal Iterator Requirements (in addition to Bidirectional Traversal)</th>
</tr>
<tr><th class="head">Expression</th>
<th class="head">Return Type</th>
<th class="head">Operational Semantics</th>
<th class="head">Assertion/
Precondition</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">r</span> <span class="pre">+=</span> <span class="pre">n</span></tt></td>
<td><tt class="docutils literal"><span class="pre">X&amp;</span></tt></td>
<td><pre class="first last literal-block">
{
Distance m = n;
if (m &gt;= 0)
while (m--)
++r;
else
while (m++)
--r;
return r;
}
</pre>
</td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">a</span> <span class="pre">+</span> <span class="pre">n</span></tt>, <tt class="docutils literal"><span class="pre">n</span> <span class="pre">+</span> <span class="pre">a</span></tt></td>
<td><tt class="docutils literal"><span class="pre">X</span></tt></td>
<td><tt class="docutils literal"><span class="pre">{</span> <span class="pre">X</span> <span class="pre">tmp</span> <span class="pre">=</span> <span class="pre">a;</span> <span class="pre">return</span> <span class="pre">tmp</span>
<span class="pre">+=</span> <span class="pre">n;</span> <span class="pre">}</span></tt></td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">r</span> <span class="pre">-=</span> <span class="pre">n</span></tt></td>
<td><tt class="docutils literal"><span class="pre">X&amp;</span></tt></td>
<td><tt class="docutils literal"><span class="pre">return</span> <span class="pre">r</span> <span class="pre">+=</span> <span class="pre">-n</span></tt></td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">a</span> <span class="pre">-</span> <span class="pre">n</span></tt></td>
<td><tt class="docutils literal"><span class="pre">X</span></tt></td>
<td><tt class="docutils literal"><span class="pre">{</span> <span class="pre">X</span> <span class="pre">tmp</span> <span class="pre">=</span> <span class="pre">a;</span> <span class="pre">return</span> <span class="pre">tmp</span>
<span class="pre">-=</span> <span class="pre">n;</span> <span class="pre">}</span></tt></td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">b</span> <span class="pre">-</span> <span class="pre">a</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Distance</span></tt></td>
<td><tt class="docutils literal"><span class="pre">a</span> <span class="pre">&lt;</span> <span class="pre">b</span> <span class="pre">?</span>&nbsp; <span class="pre">distance(a,b)</span>
<span class="pre">:</span> <span class="pre">-distance(b,a)</span></tt></td>
<td>pre: there exists a
value <tt class="docutils literal"><span class="pre">n</span></tt> of
<tt class="docutils literal"><span class="pre">Distance</span></tt> such that
<tt class="docutils literal"><span class="pre">a</span> <span class="pre">+</span> <span class="pre">n</span> <span class="pre">==</span> <span class="pre">b</span></tt>. <tt class="docutils literal"><span class="pre">b</span>
<span class="pre">==</span> <span class="pre">a</span> <span class="pre">+</span> <span class="pre">(b</span> <span class="pre">-</span> <span class="pre">a)</span></tt>.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">a[n]</span></tt></td>
<td>convertible to T</td>
<td><tt class="docutils literal"><span class="pre">*(a</span> <span class="pre">+</span> <span class="pre">n)</span></tt></td>
<td>pre: a is a <em>Readable
Iterator</em></td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">a[n]</span> <span class="pre">=</span> <span class="pre">v</span></tt></td>
<td>convertible to T</td>
<td><tt class="docutils literal"><span class="pre">*(a</span> <span class="pre">+</span> <span class="pre">n)</span> <span class="pre">=</span> <span class="pre">v</span></tt></td>
<td>pre: a is a <em>Writable
iterator</em></td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">a</span> <span class="pre">&lt;</span> <span class="pre">b</span></tt></td>
<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
<td><tt class="docutils literal"><span class="pre">b</span> <span class="pre">-</span> <span class="pre">a</span> <span class="pre">&gt;</span> <span class="pre">0</span></tt></td>
<td><tt class="docutils literal"><span class="pre">&lt;</span></tt> is a total
ordering relation</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">a</span> <span class="pre">&gt;</span> <span class="pre">b</span></tt></td>
<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
<td><tt class="docutils literal"><span class="pre">b</span> <span class="pre">&lt;</span> <span class="pre">a</span></tt></td>
<td><tt class="docutils literal"><span class="pre">&gt;</span></tt> is a total
ordering relation</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">a</span> <span class="pre">&gt;=</span> <span class="pre">b</span></tt></td>
<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
<td><tt class="docutils literal"><span class="pre">!(a</span> <span class="pre">&lt;</span> <span class="pre">b)</span></tt></td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">a</span> <span class="pre">&lt;=</span> <span class="pre">b</span></tt></td>
<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
<td><tt class="docutils literal"><span class="pre">!(a</span> <span class="pre">&gt;</span> <span class="pre">b)</span></tt></td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt></td>
<td>Convertible to
<tt class="docutils literal"><span class="pre">random_access_traversal_tag</span></tt></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</div>
<div class="footer">
<hr class="footer" />
<a class="reference external" href="RandomAccessTraversal.rst">View document source</a>.
Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div>
</body>
</html>
libs/iterator/doc/RandomAccessTraversal.rst
+67
View File
@@ -0,0 +1,67 @@
.. Copyright David Abrahams 2006. Distributed under 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)
Random Access Traversal Concept
...............................
A class or built-in type ``X`` models the *Random Access Traversal*
concept if the following expressions are valid and respect the stated
semantics. In the table below, ``Distance`` is
``iterator_traits<X>::difference_type`` and ``n`` represents a
constant object of type ``Distance``.
+------------------------------------------------------------------------------------------------------------------+
|Random Access Traversal Iterator Requirements (in addition to Bidirectional Traversal) |
+-------------------------------+---------------------------------+-------------------------+----------------------+
|Expression |Return Type |Operational Semantics |Assertion/ |
| | | |Precondition |
+===============================+=================================+=========================+======================+
|``r += n`` |``X&`` |:: | |
| | | | |
| | | { | |
| | | Distance m = n; | |
| | | if (m >= 0) | |
| | | while (m--) | |
| | | ++r; | |
| | | else | |
| | | while (m++) | |
| | | --r; | |
| | | return r; | |
| | | } | |
+-------------------------------+---------------------------------+-------------------------+----------------------+
|``a + n``, ``n + a`` |``X`` |``{ X tmp = a; return tmp| |
| | |+= n; }`` | |
| | | | |
+-------------------------------+---------------------------------+-------------------------+----------------------+
|``r -= n`` |``X&`` |``return r += -n`` | |
+-------------------------------+---------------------------------+-------------------------+----------------------+
|``a - n`` |``X`` |``{ X tmp = a; return tmp| |
| | |-= n; }`` | |
| | | | |
+-------------------------------+---------------------------------+-------------------------+----------------------+
|``b - a`` |``Distance`` |``a < b ? distance(a,b) |pre: there exists a |
| | |: -distance(b,a)`` |value ``n`` of |
| | | |``Distance`` such that|
| | | |``a + n == b``. ``b |
| | | |== a + (b - a)``. |
+-------------------------------+---------------------------------+-------------------------+----------------------+
|``a[n]`` |convertible to T |``*(a + n)`` |pre: a is a *Readable |
| | | |Iterator* |
+-------------------------------+---------------------------------+-------------------------+----------------------+
|``a[n] = v`` |convertible to T |``*(a + n) = v`` |pre: a is a *Writable |
| | | |iterator* |
+-------------------------------+---------------------------------+-------------------------+----------------------+
|``a < b`` |convertible to ``bool`` |``b - a > 0`` |``<`` is a total |
| | | |ordering relation |
+-------------------------------+---------------------------------+-------------------------+----------------------+
|``a > b`` |convertible to ``bool`` |``b < a`` |``>`` is a total |
| | | |ordering relation |
+-------------------------------+---------------------------------+-------------------------+----------------------+
|``a >= b`` |convertible to ``bool`` |``!(a < b)`` | |
+-------------------------------+---------------------------------+-------------------------+----------------------+
|``a <= b`` |convertible to ``bool`` |``!(a > b)`` | |
+-------------------------------+---------------------------------+-------------------------+----------------------+
|``iterator_traversal<X>::type``|Convertible to | | |
| |``random_access_traversal_tag`` | | |
+-------------------------------+---------------------------------+-------------------------+----------------------+
libs/iterator/doc/ReadableIterator.html
+64
View File
@@ -0,0 +1,64 @@
<?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.5: http://docutils.sourceforge.net/" />
<title>Readable Iterator Concept</title>
<link rel="stylesheet" href="../../../rst.css" type="text/css" />
</head>
<body>
<div class="document" id="readable-iterator-concept">
<h1 class="title">Readable Iterator Concept</h1>
<!-- Copyright David Abrahams 2006. Distributed under 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) -->
<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> models the <em>Readable Iterator</em> concept
for value type <tt class="docutils literal"><span class="pre">T</span></tt> if, in addition to <tt class="docutils literal"><span class="pre">X</span></tt> being Assignable and
Copy Constructible, the following expressions are valid and respect
the stated semantics. <tt class="docutils literal"><span class="pre">U</span></tt> is the type of any specified member of
type <tt class="docutils literal"><span class="pre">T</span></tt>.</p>
<table border="1" class="docutils">
<colgroup>
<col width="28%" />
<col width="20%" />
<col width="52%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head" colspan="3">Readable Iterator Requirements (in addition to Assignable and Copy Constructible)</th>
</tr>
<tr><th class="head">Expression</th>
<th class="head">Return Type</th>
<th class="head">Note/Precondition</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">iterator_traits&lt;X&gt;::value_type</span></tt></td>
<td><tt class="docutils literal"><span class="pre">T</span></tt></td>
<td>Any non-reference,
non-cv-qualified type</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">*a</span></tt></td>
<td>Convertible to <tt class="docutils literal"><span class="pre">T</span></tt></td>
<td><dl class="first last docutils">
<dt>pre: <tt class="docutils literal"><span class="pre">a</span></tt> is dereferenceable. If <tt class="docutils literal"><span class="pre">a</span> <span class="pre">==</span> <span class="pre">b</span></tt> then <tt class="docutils literal"><span class="pre">*a</span></tt></dt>
<dd>is equivalent to <tt class="docutils literal"><span class="pre">*b</span></tt>.</dd>
</dl>
</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">a-&gt;m</span></tt></td>
<td><tt class="docutils literal"><span class="pre">U&amp;</span></tt></td>
<td>pre: <tt class="docutils literal"><span class="pre">pre:</span> <span class="pre">(*a).m</span></tt> is well-defined. Equivalent to <tt class="docutils literal"><span class="pre">(*a).m</span></tt>.</td>
</tr>
</tbody>
</table>
</div>
<div class="footer">
<hr class="footer" />
<a class="reference external" href="ReadableIterator.rst">View document source</a>.
Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div>
</body>
</html>
libs/iterator/doc/ReadableIterator.rst
+26
View File
@@ -0,0 +1,26 @@
.. Copyright David Abrahams 2006. Distributed under 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)
Readable Iterator Concept
.........................
A class or built-in type ``X`` models the *Readable Iterator* concept
for value type ``T`` if, in addition to ``X`` being Assignable and
Copy Constructible, the following expressions are valid and respect
the stated semantics. ``U`` is the type of any specified member of
type ``T``.
+-----------------------------------------------------------------------------------------------------------------------------+
|Readable Iterator Requirements (in addition to Assignable and Copy Constructible) |
+-----------------------------------+------------------------+----------------------------------------------------------------+
|Expression |Return Type |Note/Precondition |
+===================================+========================+================================================================+
|``iterator_traits<X>::value_type`` |``T`` |Any non-reference, |
| | |non-cv-qualified type |
+-----------------------------------+------------------------+----------------------------------------------------------------+
|``*a`` | Convertible to ``T`` |pre: ``a`` is dereferenceable. If ``a == b`` then ``*a`` |
| | | is equivalent to ``*b``. |
+-----------------------------------+------------------------+----------------------------------------------------------------+
|``a->m`` |``U&`` |pre: ``pre: (*a).m`` is well-defined. Equivalent to ``(*a).m``. |
+-----------------------------------+------------------------+----------------------------------------------------------------+
libs/iterator/doc/SinglePassIterator.html
+68
View File
@@ -0,0 +1,68 @@
<?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.5: http://docutils.sourceforge.net/" />
<title>Single Pass Iterator Concept</title>
<link rel="stylesheet" href="../../../rst.css" type="text/css" />
</head>
<body>
<div class="document" id="single-pass-iterator-concept">
<h1 class="title">Single Pass Iterator Concept</h1>
<!-- Copyright David Abrahams 2006. Distributed under 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) -->
<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> models the <em>Single Pass Iterator</em>
concept if the following expressions are valid and respect the stated
semantics.</p>
<table border="1" class="docutils">
<colgroup>
<col width="36%" />
<col width="33%" />
<col width="31%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head" colspan="3">Single Pass Iterator Requirements (in addition to Incrementable Iterator and Equality
Comparable)</th>
</tr>
<tr><th class="head">Expression</th>
<th class="head">Return Type</th>
<th class="head">Assertion/Semantics /
Pre-/Post-condition</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">++r</span></tt></td>
<td><tt class="docutils literal"><span class="pre">X&amp;</span></tt></td>
<td>pre: <tt class="docutils literal"><span class="pre">r</span></tt> is
dereferenceable; post:
<tt class="docutils literal"><span class="pre">r</span></tt> is dereferenceable or
<tt class="docutils literal"><span class="pre">r</span></tt> is past-the-end</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">a</span> <span class="pre">==</span> <span class="pre">b</span></tt></td>
<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
<td><tt class="docutils literal"><span class="pre">==</span></tt> is an equivalence
relation over its domain</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">a</span> <span class="pre">!=</span> <span class="pre">b</span></tt></td>
<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
<td><tt class="docutils literal"><span class="pre">!(a</span> <span class="pre">==</span> <span class="pre">b)</span></tt></td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt></td>
<td>Convertible to
<tt class="docutils literal"><span class="pre">single_pass_traversal_tag</span></tt></td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</div>
<div class="footer">
<hr class="footer" />
<a class="reference external" href="SinglePassIterator.rst">View document source</a>.
Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div>
</body>
</html>
libs/iterator/doc/SinglePassIterator.rst
+32
View File
@@ -0,0 +1,32 @@
.. Copyright David Abrahams 2006. Distributed under 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)
Single Pass Iterator Concept
............................
A class or built-in type ``X`` models the *Single Pass Iterator*
concept if the following expressions are valid and respect the stated
semantics.
+------------------------------------------------------------------------------------------+
|Single Pass Iterator Requirements (in addition to Incrementable Iterator and Equality |
|Comparable) |
+--------------------------------+-----------------------------+---------------------------+
|Expression |Return Type |Assertion/Semantics / |
| | |Pre-/Post-condition |
+================================+=============================+===========================+
|``++r`` |``X&`` |pre: ``r`` is |
| | |dereferenceable; post: |
| | |``r`` is dereferenceable or|
| | |``r`` is past-the-end |
+--------------------------------+-----------------------------+---------------------------+
|``a == b`` |convertible to ``bool`` |``==`` is an equivalence |
| | |relation over its domain |
+--------------------------------+-----------------------------+---------------------------+
|``a != b`` |convertible to ``bool`` |``!(a == b)`` |
+--------------------------------+-----------------------------+---------------------------+
|``iterator_traversal<X>::type`` |Convertible to | |
| |``single_pass_traversal_tag``| |
+--------------------------------+-----------------------------+---------------------------+
libs/iterator/doc/SwappableIterator.html
+54
View File
@@ -0,0 +1,54 @@
<?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.5: http://docutils.sourceforge.net/" />
<title>Swappable Iterator Concept</title>
<link rel="stylesheet" href="../../../rst.css" type="text/css" />
</head>
<body>
<div class="document" id="swappable-iterator-concept">
<h1 class="title">Swappable Iterator Concept</h1>
<!-- Copyright David Abrahams 2006. Distributed under 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) -->
<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> models the <em>Swappable Iterator</em> concept
if, in addition to <tt class="docutils literal"><span class="pre">X</span></tt> being Copy Constructible, the following
expressions are valid and respect the stated semantics.</p>
<table border="1" class="docutils">
<colgroup>
<col width="37%" />
<col width="19%" />
<col width="43%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head" colspan="3">Swappable Iterator Requirements (in addition to Copy Constructible)</th>
</tr>
<tr><th class="head">Expression</th>
<th class="head">Return Type</th>
<th class="head">Postcondition</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">iter_swap(a,</span> <span class="pre">b)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">void</span></tt></td>
<td>the pointed to values are
exchanged</td>
</tr>
</tbody>
</table>
<dl class="docutils">
<dt>[<em>Note:</em> An iterator that is a model of the <em>Readable</em> and <em>Writable Iterator</em> concepts</dt>
<dd>is also a model of <em>Swappable Iterator</em>. <em>--end note</em>]</dd>
</dl>
</div>
<div class="footer">
<hr class="footer" />
<a class="reference external" href="SwappableIterator.rst">View document source</a>.
Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div>
</body>
</html>
libs/iterator/doc/SwappableIterator.rst
+23
View File
@@ -0,0 +1,23 @@
.. Copyright David Abrahams 2006. Distributed under 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)
Swappable Iterator Concept
..........................
A class or built-in type ``X`` models the *Swappable Iterator* concept
if, in addition to ``X`` being Copy Constructible, the following
expressions are valid and respect the stated semantics.
+---------------------------------------------------------------------+
|Swappable Iterator Requirements (in addition to Copy Constructible) |
+-------------------------+-------------+-----------------------------+
|Expression |Return Type |Postcondition |
+=========================+=============+=============================+
|``iter_swap(a, b)`` |``void`` |the pointed to values are |
| | |exchanged |
+-------------------------+-------------+-----------------------------+
[*Note:* An iterator that is a model of the *Readable* and *Writable Iterator* concepts
is also a model of *Swappable Iterator*. *--end note*]
libs/iterator/doc/WritableIterator.html
+52
View File
@@ -0,0 +1,52 @@
<?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.5: http://docutils.sourceforge.net/" />
<title>Writable Iterator Concept</title>
<link rel="stylesheet" href="../../../rst.css" type="text/css" />
</head>
<body>
<div class="document" id="writable-iterator-concept">
<h1 class="title">Writable Iterator Concept</h1>
<!-- Copyright David Abrahams 2006. Distributed under 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) -->
<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> models the <em>Writable Iterator</em> concept
if, in addition to <tt class="docutils literal"><span class="pre">X</span></tt> being Copy Constructible, the following
expressions are valid and respect the stated semantics. Writable
Iterators have an associated <em>set of value types</em>.</p>
<table border="1" class="docutils">
<colgroup>
<col width="37%" />
<col width="21%" />
<col width="42%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head" colspan="3">Writable Iterator Requirements (in addition to Copy Constructible)</th>
</tr>
<tr><th class="head">Expression</th>
<th class="head">Return Type</th>
<th class="head">Precondition</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">*a</span> <span class="pre">=</span> <span class="pre">o</span></tt></td>
<td>&nbsp;</td>
<td>pre: The type of <tt class="docutils literal"><span class="pre">o</span></tt>
is in the set of
value types of <tt class="docutils literal"><span class="pre">X</span></tt></td>
</tr>
</tbody>
</table>
</div>
<div class="footer">
<hr class="footer" />
<a class="reference external" href="WritableIterator.rst">View document source</a>.
Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div>
</body>
</html>
libs/iterator/doc/WritableIterator.rst
+21
View File
@@ -0,0 +1,21 @@
.. Copyright David Abrahams 2006. Distributed under 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)
Writable Iterator Concept
.........................
A class or built-in type ``X`` models the *Writable Iterator* concept
if, in addition to ``X`` being Copy Constructible, the following
expressions are valid and respect the stated semantics. Writable
Iterators have an associated *set of value types*.
+---------------------------------------------------------------------+
|Writable Iterator Requirements (in addition to Copy Constructible) |
+-------------------------+--------------+----------------------------+
|Expression |Return Type |Precondition |
+=========================+==============+============================+
|``*a = o`` | | pre: The type of ``o`` |
| | | is in the set of |
| | | value types of ``X`` |
+-------------------------+--------------+----------------------------+
libs/iterator/doc/access.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 11 KiB

libs/iterator/doc/access2old.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 41 KiB

libs/iterator/doc/counting_iterator.html
+301
View File
@@ -0,0 +1,301 @@
<?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.5: http://docutils.sourceforge.net/" />
<title>Counting Iterator</title>
<meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" />
<meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, University of Hanover Institute for Transport Railway Operation and Construction" />
<meta name="date" content="2006-09-11" />
<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003." />
<link rel="stylesheet" href="../../../rst.css" type="text/css" />
</head>
<body>
<div class="document" id="counting-iterator">
<h1 class="title">Counting 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, Jeremy Siek, Thomas Witt</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first reference external" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference external" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="last reference external" href="mailto:witt&#64;ive.uni-hannover.de">witt&#64;ive.uni-hannover.de</a></td></tr>
<tr><th class="docinfo-name">Organization:</th>
<td><a class="first reference external" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference external" href="http://www.osl.iu.edu">Open Systems
Lab</a>, University of Hanover <a class="last reference external" href="http://www.ive.uni-hannover.de">Institute for Transport
Railway Operation and Construction</a></td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2006-09-11</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003.</td></tr>
</tbody>
</table>
<!-- Distributed under 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) -->
<table class="docutils 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"><p class="first">How would you fill up a vector with the numbers zero
through one hundred using <tt class="docutils literal"><span class="pre">std::copy()</span></tt>? The only iterator
operation missing from builtin integer types is an
<tt class="docutils literal"><span class="pre">operator*()</span></tt> that returns the current value of the integer.
The counting iterator adaptor adds this crucial piece of
functionality to whatever type it wraps. One can use the
counting iterator adaptor not only with integer types, but with
any incrementable type.</p>
<!-- Copyright David Abrahams 2006. Distributed under 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) -->
<p class="last"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> adapts an object by adding an <tt class="docutils literal"><span class="pre">operator*</span></tt> that
returns the current value of the object. All other iterator operations
are forwarded to the adapted object.</p>
</td>
</tr>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#counting-iterator-synopsis" id="id2"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> synopsis</a></li>
<li><a class="reference internal" href="#counting-iterator-requirements" id="id3"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> requirements</a></li>
<li><a class="reference internal" href="#counting-iterator-models" id="id4"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models</a></li>
<li><a class="reference internal" href="#counting-iterator-operations" id="id5"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> operations</a></li>
<li><a class="reference internal" href="#example" id="id6">Example</a></li>
</ul>
</div>
<div class="section" id="counting-iterator-synopsis">
<h1><a class="toc-backref" href="#id2"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> synopsis</a></h1>
<!-- Copyright David Abrahams 2006. Distributed under 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) -->
<pre class="literal-block">
template &lt;
class Incrementable
, class CategoryOrTraversal = use_default
, class Difference = use_default
&gt;
class counting_iterator
{
public:
typedef Incrementable value_type;
typedef const Incrementable&amp; reference;
typedef const Incrementable* pointer;
typedef /* see below */ difference_type;
typedef /* see below */ iterator_category;
counting_iterator();
counting_iterator(counting_iterator const&amp; rhs);
explicit counting_iterator(Incrementable x);
Incrementable const&amp; base() const;
reference operator*() const;
counting_iterator&amp; operator++();
counting_iterator&amp; operator--();
private:
Incrementable m_inc; // exposition
};
</pre>
<p>If the <tt class="docutils literal"><span class="pre">Difference</span></tt> argument is <tt class="docutils literal"><span class="pre">use_default</span></tt> then
<tt class="docutils literal"><span class="pre">difference_type</span></tt> is an unspecified signed integral
type. Otherwise <tt class="docutils literal"><span class="pre">difference_type</span></tt> is <tt class="docutils literal"><span class="pre">Difference</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">iterator_category</span></tt> is determined according to the following
algorithm:</p>
<pre class="literal-block">
if (CategoryOrTraversal is not use_default)
return CategoryOrTraversal
else if (numeric_limits&lt;Incrementable&gt;::is_specialized)
return <a class="reference external" href="iterator_facade.html#iterator-category"><em>iterator-category</em></a>(
random_access_traversal_tag, Incrementable, const Incrementable&amp;)
else
return <a class="reference external" href="iterator_facade.html#iterator-category"><em>iterator-category</em></a>(
iterator_traversal&lt;Incrementable&gt;::type,
Incrementable, const Incrementable&amp;)
</pre>
<dl class="docutils">
<dt>[<em>Note:</em> implementers are encouraged to provide an implementation of</dt>
<dd><tt class="docutils literal"><span class="pre">operator-</span></tt> and a <tt class="docutils literal"><span class="pre">difference_type</span></tt> that avoids overflows in
the cases where <tt class="docutils literal"><span class="pre">std::numeric_limits&lt;Incrementable&gt;::is_specialized</span></tt>
is true.]</dd>
</dl>
</div>
<div class="section" id="counting-iterator-requirements">
<h1><a class="toc-backref" href="#id3"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> requirements</a></h1>
<p>The <tt class="docutils literal"><span class="pre">Incrementable</span></tt> argument shall be Copy Constructible and Assignable.</p>
<p>If <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible to <tt class="docutils literal"><span class="pre">forward_iterator_tag</span></tt>
or <tt class="docutils literal"><span class="pre">forward_traversal_tag</span></tt>, the following must be well-formed:</p>
<pre class="literal-block">
Incrementable i, j;
++i; // pre-increment
i == j; // operator equal
</pre>
<p>If <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible to
<tt class="docutils literal"><span class="pre">bidirectional_iterator_tag</span></tt> or <tt class="docutils literal"><span class="pre">bidirectional_traversal_tag</span></tt>,
the following expression must also be well-formed:</p>
<pre class="literal-block">
--i
</pre>
<p>If <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible to
<tt class="docutils literal"><span class="pre">random_access_iterator_tag</span></tt> or <tt class="docutils literal"><span class="pre">random_access_traversal_tag</span></tt>,
the following must must also be valid:</p>
<pre class="literal-block">
counting_iterator::difference_type n;
i += n;
n = i - j;
i &lt; j;
</pre>
</div>
<div class="section" id="counting-iterator-models">
<h1><a class="toc-backref" href="#id4"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models</a></h1>
<p>Specializations of <tt class="docutils literal"><span class="pre">counting_iterator</span></tt> model Readable Lvalue
Iterator. In addition, they model the concepts corresponding to the
iterator tags to which their <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible.
Also, if <tt class="docutils literal"><span class="pre">CategoryOrTraversal</span></tt> is not <tt class="docutils literal"><span class="pre">use_default</span></tt> then
<tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models the concept corresponding to the iterator
tag <tt class="docutils literal"><span class="pre">CategoryOrTraversal</span></tt>. Otherwise, if
<tt class="docutils literal"><span class="pre">numeric_limits&lt;Incrementable&gt;::is_specialized</span></tt>, then
<tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models Random Access Traversal Iterator.
Otherwise, <tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models the same iterator traversal
concepts modeled by <tt class="docutils literal"><span class="pre">Incrementable</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">counting_iterator&lt;X,C1,D1&gt;</span></tt> is interoperable with
<tt class="docutils literal"><span class="pre">counting_iterator&lt;Y,C2,D2&gt;</span></tt> if and only if <tt class="docutils literal"><span class="pre">X</span></tt> is
interoperable with <tt class="docutils literal"><span class="pre">Y</span></tt>.</p>
</div>
<div class="section" id="counting-iterator-operations">
<h1><a class="toc-backref" href="#id5"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> operations</a></h1>
<p>In addition to the operations required by the concepts modeled by
<tt class="docutils literal"><span class="pre">counting_iterator</span></tt>, <tt class="docutils literal"><span class="pre">counting_iterator</span></tt> provides the following
operations.</p>
<p><tt class="docutils literal"><span class="pre">counting_iterator();</span></tt></p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="docutils literal"><span class="pre">Incrementable</span></tt> is Default Constructible.</td>
</tr>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Default construct the member <tt class="docutils literal"><span class="pre">m_inc</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">counting_iterator(counting_iterator</span> <span class="pre">const&amp;</span> <span class="pre">rhs);</span></tt></p>
<table class="docutils 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">Construct member <tt class="docutils literal"><span class="pre">m_inc</span></tt> from <tt class="docutils literal"><span class="pre">rhs.m_inc</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">explicit</span> <span class="pre">counting_iterator(Incrementable</span> <span class="pre">x);</span></tt></p>
<table class="docutils 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">Construct member <tt class="docutils literal"><span class="pre">m_inc</span></tt> from <tt class="docutils literal"><span class="pre">x</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">reference</span> <span class="pre">operator*()</span> <span class="pre">const;</span></tt></p>
<table class="docutils 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="docutils literal"><span class="pre">m_inc</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">counting_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
<table class="docutils 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"><tt class="docutils literal"><span class="pre">++m_inc</span></tt></td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">counting_iterator&amp;</span> <span class="pre">operator--();</span></tt></p>
<table class="docutils 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"><tt class="docutils literal"><span class="pre">--m_inc</span></tt></td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">Incrementable</span> <span class="pre">const&amp;</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
<table class="docutils 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="docutils literal"><span class="pre">m_inc</span></tt></td>
</tr>
</tbody>
</table>
<!-- Copyright David Abrahams 2006. Distributed under 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) -->
<pre class="literal-block">
template &lt;class Incrementable&gt;
counting_iterator&lt;Incrementable&gt; make_counting_iterator(Incrementable x);
</pre>
<table class="docutils 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="docutils literal"><span class="pre">counting_iterator&lt;Incrementable&gt;</span></tt>
with <tt class="docutils literal"><span class="pre">current</span></tt> constructed from <tt class="docutils literal"><span class="pre">x</span></tt>.</td>
</tr>
</tbody>
</table>
<!-- Copyright David Abrahams 2006. Distributed under 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) -->
</div>
<div class="section" id="example">
<h1><a class="toc-backref" href="#id6">Example</a></h1>
<p>This example fills an array with numbers and a second array with
pointers into the first array, using <tt class="docutils literal"><span class="pre">counting_iterator</span></tt> for both
tasks. Finally <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> is used to print out the numbers
into the first array via indirection through the second array.</p>
<pre class="literal-block">
int N = 7;
std::vector&lt;int&gt; numbers;
typedef std::vector&lt;int&gt;::iterator n_iter;
std::copy(boost::counting_iterator&lt;int&gt;(0),
boost::counting_iterator&lt;int&gt;(N),
std::back_inserter(numbers));
std::vector&lt;std::vector&lt;int&gt;::iterator&gt; pointers;
std::copy(boost::make_counting_iterator(numbers.begin()),
boost::make_counting_iterator(numbers.end()),
std::back_inserter(pointers));
std::cout &lt;&lt; &quot;indirectly printing out the numbers from 0 to &quot;
&lt;&lt; N &lt;&lt; std::endl;
std::copy(boost::make_indirect_iterator(pointers.begin()),
boost::make_indirect_iterator(pointers.end()),
std::ostream_iterator&lt;int&gt;(std::cout, &quot; &quot;));
std::cout &lt;&lt; std::endl;
</pre>
<p>The output is:</p>
<pre class="literal-block">
indirectly printing out the numbers from 0 to 7
0 1 2 3 4 5 6
</pre>
<p>The source code for this example can be found <a class="reference external" href="../example/counting_iterator_example.cpp">here</a>.</p>
</div>
</div>
<div class="footer">
<hr class="footer" />
<a class="reference external" href="counting_iterator.rst">View document source</a>.
Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div>
</body>
</html>
libs/iterator/doc/counting_iterator.pdf
BIN
View File
Binary file not shown.
libs/iterator/doc/counting_iterator.rst
+43
View File
@@ -0,0 +1,43 @@
.. Distributed under 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)
+++++++++++++++++++
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 David Abrahams, Jeremy Siek, and Thomas Witt 2003.
.. _`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: How would you fill up a vector with the numbers zero
through one hundred using ``std::copy()``? The only iterator
operation missing from builtin integer types is an
``operator*()`` that returns the current value of the integer.
The counting iterator adaptor adds this crucial piece of
functionality to whatever type it wraps. One can use the
counting iterator adaptor not only with integer types, but with
any incrementable type.
.. include:: counting_iterator_abstract.rst
.. contents:: Table of Contents
``counting_iterator`` synopsis
..............................
.. include:: counting_iterator_ref.rst
.. include:: make_counting_iterator.rst
.. include:: counting_iterator_eg.rst
.. _iterator-category: iterator_facade.html#iterator-category
.. |iterator-category| replace:: *iterator-category*
libs/iterator/doc/counting_iterator_abstract.rst
+8
View File
@@ -0,0 +1,8 @@
.. Copyright David Abrahams 2006. Distributed under 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)
``counting_iterator`` adapts an object by adding an ``operator*`` that
returns the current value of the object. All other iterator operations
are forwarded to the adapted object.
libs/iterator/doc/counting_iterator_eg.rst
+43
View File
@@ -0,0 +1,43 @@
.. Copyright David Abrahams 2006. Distributed under 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)
Example
.......
This example fills an array with numbers and a second array with
pointers into the first array, using ``counting_iterator`` for both
tasks. Finally ``indirect_iterator`` is used to print out the numbers
into the first array via indirection through the second array.
::
int N = 7;
std::vector<int> numbers;
typedef std::vector<int>::iterator n_iter;
std::copy(boost::counting_iterator<int>(0),
boost::counting_iterator<int>(N),
std::back_inserter(numbers));
std::vector<std::vector<int>::iterator> pointers;
std::copy(boost::make_counting_iterator(numbers.begin()),
boost::make_counting_iterator(numbers.end()),
std::back_inserter(pointers));
std::cout << "indirectly printing out the numbers from 0 to "
<< N << std::endl;
std::copy(boost::make_indirect_iterator(pointers.begin()),
boost::make_indirect_iterator(pointers.end()),
std::ostream_iterator<int>(std::cout, " "));
std::cout << std::endl;
The output is::
indirectly printing out the numbers from 0 to 7
0 1 2 3 4 5 6
The source code for this example can be found `here`__.
__ ../example/counting_iterator_example.cpp
libs/iterator/doc/counting_iterator_ref.rst
+149
View File
@@ -0,0 +1,149 @@
.. Copyright David Abrahams 2006. Distributed under 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)
::
template <
class Incrementable
, class CategoryOrTraversal = use_default
, class Difference = use_default
>
class counting_iterator
{
public:
typedef Incrementable value_type;
typedef const Incrementable& reference;
typedef const Incrementable* pointer;
typedef /* see below */ difference_type;
typedef /* see below */ iterator_category;
counting_iterator();
counting_iterator(counting_iterator const& rhs);
explicit counting_iterator(Incrementable x);
Incrementable const& base() const;
reference operator*() const;
counting_iterator& operator++();
counting_iterator& operator--();
private:
Incrementable m_inc; // exposition
};
If the ``Difference`` argument is ``use_default`` then
``difference_type`` is an unspecified signed integral
type. Otherwise ``difference_type`` is ``Difference``.
``iterator_category`` is determined according to the following
algorithm:
.. parsed-literal::
if (CategoryOrTraversal is not use_default)
return CategoryOrTraversal
else if (numeric_limits<Incrementable>::is_specialized)
return |iterator-category|_\ (
random_access_traversal_tag, Incrementable, const Incrementable&)
else
return |iterator-category|_\ (
iterator_traversal<Incrementable>::type,
Incrementable, const Incrementable&)
[*Note:* implementers are encouraged to provide an implementation of
``operator-`` and a ``difference_type`` that avoids overflows in
the cases where ``std::numeric_limits<Incrementable>::is_specialized``
is true.]
``counting_iterator`` requirements
..................................
The ``Incrementable`` argument shall be Copy Constructible and Assignable.
If ``iterator_category`` is convertible to ``forward_iterator_tag``
or ``forward_traversal_tag``, the following must be well-formed::
Incrementable i, j;
++i; // pre-increment
i == j; // operator equal
If ``iterator_category`` is convertible to
``bidirectional_iterator_tag`` or ``bidirectional_traversal_tag``,
the following expression must also be well-formed::
--i
If ``iterator_category`` is convertible to
``random_access_iterator_tag`` or ``random_access_traversal_tag``,
the following must must also be valid::
counting_iterator::difference_type n;
i += n;
n = i - j;
i < j;
``counting_iterator`` models
............................
Specializations of ``counting_iterator`` model Readable Lvalue
Iterator. In addition, they model the concepts corresponding to the
iterator tags to which their ``iterator_category`` is convertible.
Also, if ``CategoryOrTraversal`` is not ``use_default`` then
``counting_iterator`` models the concept corresponding to the iterator
tag ``CategoryOrTraversal``. Otherwise, if
``numeric_limits<Incrementable>::is_specialized``, then
``counting_iterator`` models Random Access Traversal Iterator.
Otherwise, ``counting_iterator`` models the same iterator traversal
concepts modeled by ``Incrementable``.
``counting_iterator<X,C1,D1>`` is interoperable with
``counting_iterator<Y,C2,D2>`` if and only if ``X`` is
interoperable with ``Y``.
``counting_iterator`` operations
................................
In addition to the operations required by the concepts modeled by
``counting_iterator``, ``counting_iterator`` provides the following
operations.
``counting_iterator();``
:Requires: ``Incrementable`` is Default Constructible.
:Effects: Default construct the member ``m_inc``.
``counting_iterator(counting_iterator const& rhs);``
:Effects: Construct member ``m_inc`` from ``rhs.m_inc``.
``explicit counting_iterator(Incrementable x);``
:Effects: Construct member ``m_inc`` from ``x``.
``reference operator*() const;``
:Returns: ``m_inc``
``counting_iterator& operator++();``
:Effects: ``++m_inc``
:Returns: ``*this``
``counting_iterator& operator--();``
:Effects: ``--m_inc``
:Returns: ``*this``
``Incrementable const& base() const;``
:Returns: ``m_inc``
libs/iterator/doc/default.css
+226
View File
@@ -0,0 +1,226 @@
/*
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:date: $Date$
:version: $Revision$
:copyright: This stylesheet has been placed in the public domain.
boostinspect:nolicense
Default cascading style sheet for the HTML output of Docutils.
*/
.first {
margin-top: 0 }
.last {
margin-bottom: 0 }
a.toc-backref {
text-decoration: none ;
color: black }
dd {
margin-bottom: 0.5em }
div.abstract {
margin: 2em 5em }
div.abstract p.topic-title {
font-weight: bold ;
text-align: center }
div.attention, div.caution, div.danger, div.error, div.hint,
div.important, div.note, div.tip, div.warning, div.admonition {
margin: 2em ;
border: medium outset ;
padding: 1em }
div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
color: red ;
font-weight: bold ;
font-family: sans-serif }
div.hint p.admonition-title, div.important p.admonition-title,
div.note p.admonition-title, div.tip p.admonition-title,
div.admonition p.admonition-title {
font-weight: bold ;
font-family: sans-serif }
div.dedication {
margin: 2em 5em ;
text-align: center ;
font-style: italic }
div.dedication p.topic-title {
font-weight: bold ;
font-style: normal }
div.figure {
margin-left: 2em }
div.footer, div.header {
font-size: smaller }
div.sidebar {
margin-left: 1em ;
border: medium outset ;
padding: 0em 1em ;
background-color: #ffffee ;
width: 40% ;
float: right ;
clear: right }
div.sidebar p.rubric {
font-family: sans-serif ;
font-size: medium }
div.system-messages {
margin: 5em }
div.system-messages h1 {
color: red }
div.system-message {
border: medium outset ;
padding: 1em }
div.system-message p.system-message-title {
color: red ;
font-weight: bold }
div.topic {
margin: 2em }
h1.title {
text-align: center }
h2.subtitle {
text-align: center }
hr {
width: 75% }
ol.simple, ul.simple {
margin-bottom: 1em }
ol.arabic {
list-style: decimal }
ol.loweralpha {
list-style: lower-alpha }
ol.upperalpha {
list-style: upper-alpha }
ol.lowerroman {
list-style: lower-roman }
ol.upperroman {
list-style: upper-roman }
p.attribution {
text-align: right ;
margin-left: 50% }
p.caption {
font-style: italic }
p.credits {
font-style: italic ;
font-size: smaller }
p.label {
white-space: nowrap }
p.rubric {
font-weight: bold ;
font-size: larger ;
color: maroon ;
text-align: center }
p.sidebar-title {
font-family: sans-serif ;
font-weight: bold ;
font-size: larger }
p.sidebar-subtitle {
font-family: sans-serif ;
font-weight: bold }
p.topic-title {
font-weight: bold }
pre.address {
margin-bottom: 0 ;
margin-top: 0 ;
font-family: serif ;
font-size: 100% }
pre.line-block {
font-family: serif ;
font-size: 100% }
pre.literal-block, pre.doctest-block {
margin-left: 2em ;
margin-right: 2em ;
background-color: #eeeeee }
span.classifier {
font-family: sans-serif ;
font-style: oblique }
span.classifier-delimiter {
font-family: sans-serif ;
font-weight: bold }
span.interpreted {
font-family: sans-serif }
span.option {
white-space: nowrap }
span.option-argument {
font-style: italic }
span.pre {
white-space: pre }
span.problematic {
color: red }
table {
margin-top: 0.5em ;
margin-bottom: 0.5em }
table.citation {
border-left: solid thin gray ;
padding-left: 0.5ex }
table.docinfo {
margin: 2em 4em }
table.footnote {
border-left: solid thin black ;
padding-left: 0.5ex }
td, th {
padding-left: 0.5em ;
padding-right: 0.5em ;
vertical-align: top }
th.docinfo-name, th.field-name {
font-weight: bold ;
text-align: left ;
white-space: nowrap }
h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
font-size: 100% }
tt {
background-color: #eeeeee }
ul.auto-toc {
list-style-type: none }
libs/iterator/doc/docutils.sty
+54
View File
@@ -0,0 +1,54 @@
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%% docutils.sty: A style for docutils latex output %%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% o author: Alexander Schmolck (a.schmolck@gmx.net)
%% o created: 2002-07-07 10:50:31+00:40
%% o last modified: $Date: 2004/01/29 05:55:26 $
%% o keywords:
%% o license:
%XXX titlesec
%% XXX geometry
\usepackage{graphicx}
\usepackage{latexsym} % extra symbols
\usepackage{url} % !!!: pay attention when using in other commands!!!
\usepackage{verbatim} % normal verbatim has lenght-limit
\usepackage{enumerate} % easy style choice with e.g: ``\begin{enumerate}[Ex i.]``
\usepackage{hyperref} %href, htarget and hlink XXX: pdfauthor, pdfcreator etc.
\usepackage{xr} %XXX do we need this?
% need this to have ``fboxes`` in ``enviroments``, as well as ``verbatim``s
\usepackage{fancybox}
\usepackage{mdwtab} % better tables and arrays (fixes spacing and adds
% vertical align and multirows (m))
\usepackage{ltxtable} % long and autoscaling tables (use X for autoscaled
% columns)
\newcommand{\transition}{\vspace{2em}\par\hrule{}\par\vspace{2em}}
\newcommand{\classifier}[1]{(\textit{#1})}
\newenvironment{topic}[1]%
{\begin{Sbox}%
\begin{minipage}{.8\textwidth}%
\protect{\large{\textbf{#1}}}\par\vspace{.5em}}%
{\end{minipage}\end{Sbox}\fbox{\TheSbox}\par\vspace{.5em}}
%XXX shadow box for warnings?
\newenvironment{admonition}[1]%
{\begin{center}%
\begin{Sbox}%
\begin{minipage}{.9\textwidth}%
\protect{\textsc{#1}}\par\vspace{.2em}}%
{\end{minipage}\end{Sbox}\fbox{\TheSbox}\par\vspace{.5em}\end{center}}
\newenvironment{doctest}%
{\VerbatimEnvironment
\begin{Verbatim}}%
{\end{Verbatim}}
% {%
% \begin{Sbox}%
% \begin{minipage}{.8\textwidth}%
% \protect{\large{\textsc{#1}}\par\vspace{.5em}}}%
% {\end{minipage}\end{Sbox}\fbox{\TheSbox}\par\vspace{.5em}}
%{\end{minipage}\end{Sbox}\fbox{\TheSbox}}
%% just a piece of example code
% \newcommand{\vitem}%
% {\SaveVerb[{\item[\UseVerb{\MyTemp}]}]{\MyTemp}}
libs/iterator/doc/facade-and-adaptor.html
+2716
View File
File diff suppressed because it is too large Load Diff
libs/iterator/doc/facade-and-adaptor.pdf
BIN
View File
Binary file not shown.
libs/iterator/doc/facade-and-adaptor.rst
+438
View File
@@ -0,0 +1,438 @@
.. Distributed under 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)
+++++++++++++++++++++++++++++
Iterator Facade and Adaptor
+++++++++++++++++++++++++++++
: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$
: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://www.open-std.org/jtc1/sc22/wg21/docs/papers/2003/n1530.html
:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003.
.. _`Boost Consulting`: http://www.boost-consulting.com
.. _`Open Systems Lab`: http://www.osl.iu.edu
.. _`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
by adapting other iterators.
.. contents:: Table of Contents
============
Motivation
============
Iterators play an important role in modern C++ programming. The
iterator is the central abstraction of the algorithms of the Standard
Library, allowing algorithms to be re-used in in a wide variety of
contexts. The C++ Standard Library contains a wide variety of useful
iterators. Every one of the standard containers comes with constant
and mutable iterators [#mutable]_, and also reverse versions of those
same iterators which traverse the container in the opposite direction.
The Standard also supplies ``istream_iterator`` and
``ostream_iterator`` for reading from and writing to streams,
``insert_iterator``, ``front_insert_iterator`` and
``back_insert_iterator`` for inserting elements into containers, and
``raw_storage_iterator`` for initializing raw memory [7].
Despite the many iterators supplied by the Standard Library, obvious
and useful iterators are missing, and creating new iterator types is
still a common task for C++ programmers. The literature documents
several of these, for example line_iterator [3] and Constant_iterator
[9]. The iterator abstraction is so powerful that we expect
programmers will always need to invent new iterator types.
Although it is easy to create iterators that *almost* conform to the
standard, the iterator requirements contain subtleties which can make
creating an iterator which *actually* conforms quite difficult.
Further, the iterator interface is rich, containing many operators
that are technically redundant and tedious to implement. To automate
the repetitive work of constructing iterators, we propose
``iterator_facade``, an iterator base class template which provides
the rich interface of standard iterators and delegates its
implementation to member functions of the derived class. In addition
to reducing the amount of code necessary to create an iterator, the
``iterator_facade`` also provides compile-time error detection.
Iterator implementation mistakes that often go unnoticed are turned
into compile-time errors because the derived class implementation must
match the expectations of the ``iterator_facade``.
A common pattern of iterator construction is the adaptation of one
iterator to form a new one. The functionality of an iterator is
composed of four orthogonal aspects: traversal, indirection, equality
comparison and distance measurement. Adapting an old iterator to
create a new one often saves work because one can reuse one aspect of
functionality while redefining the other. For example, the Standard
provides ``reverse_iterator``, which adapts any Bidirectional Iterator
by inverting its direction of traversal. As with plain iterators,
iterator adaptors defined outside the Standard have become commonplace
in the literature:
* Checked iter[13] adds bounds-checking to an existing iterator.
* The iterators of the View Template Library[14], which adapts
containers, are themselves adaptors over the underlying iterators.
* Smart iterators [5] adapt an iterator's dereferencing behavior by
applying a function object to the object being referenced and
returning the result.
* Custom iterators [4], in which a variety of adaptor types are enumerated.
* Compound iterators [1], which access a slice out of a container of containers.
* Several iterator adaptors from the MTL [12]. The MTL contains a
strided iterator, where each call to ``operator++()`` moves the
iterator ahead by some constant factor, and a scaled iterator, which
multiplies the dereferenced value by some constant.
.. [#concept] We use the term concept to mean a set of requirements
that a type must satisfy to be used with a particular template
parameter.
.. [#mutable] The term mutable iterator refers to iterators over objects that
can be changed by assigning to the dereferenced iterator, while
constant iterator refers to iterators over objects that cannot be
modified.
To fulfill the need for constructing adaptors, we propose the
``iterator_adaptor`` class template. Instantiations of
``iterator_adaptor`` serve as a base classes for new iterators,
providing the default behavior of forwarding all operations to the
underlying iterator. The user can selectively replace these features
in the derived iterator class. This proposal also includes a number
of more specialized adaptors, such as the ``transform_iterator`` that
applies some user-specified function during the dereference of the
iterator.
========================
Impact on the Standard
========================
This proposal is purely an addition to the C++ standard library.
However, note that this proposal relies on the proposal for New
Iterator Concepts.
========
Design
========
Iterator Concepts
=================
This proposal is formulated in terms of the new ``iterator concepts``
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.
.. _n1550: http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2003/n1550.htm
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 n1550_ was not accepted.
Interoperability
================
The question of iterator interoperability is poorly addressed in the
current standard. There are currently two defect reports that are
concerned with interoperability issues.
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
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
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://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#179
.. _280: http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#280
Iterator Facade
===============
.. include:: iterator_facade_body.rst
Iterator Adaptor
================
.. include:: iterator_adaptor_body.rst
Specialized Adaptors
====================
This proposal also contains several examples of specialized adaptors
which were easily implemented using ``iterator_adaptor``:
* ``indirect_iterator``, which iterates over iterators, pointers,
or smart pointers and applies an extra level of dereferencing.
* A new ``reverse_iterator``, which inverts the direction of a Base
iterator's motion, while allowing adapted constant and mutable
iterators to interact in the expected ways (unlike those in most
implementations of C++98).
* ``transform_iterator``, which applies a user-defined function object
to the underlying values when dereferenced.
* ``filter_iterator``, which provides a view of an iterator range in
which some elements of the underlying range are skipped.
.. _counting:
* ``counting_iterator``, which adapts any incrementable type
(e.g. integers, iterators) so that incrementing/decrementing the
adapted iterator and dereferencing it produces successive values of
the Base type.
* ``function_output_iterator``, which makes it easier to create custom
output iterators.
Based on examples in the Boost library, users have generated many new
adaptors, among them a permutation adaptor which applies some
permutation to a random access iterator, and a strided adaptor, which
adapts a random access iterator by multiplying its unit of motion by a
constant factor. In addition, the Boost Graph Library (BGL) uses
iterator adaptors to adapt other graph libraries, such as LEDA [10]
and Stanford GraphBase [8], to the BGL interface (which requires C++
Standard compliant iterators).
===============
Proposed Text
===============
Header ``<iterator_helper>`` synopsis [lib.iterator.helper.synopsis]
=======================================================================
::
struct use_default;
struct iterator_core_access { /* implementation detail */ };
template <
class Derived
, class Value
, class CategoryOrTraversal
, class Reference = Value&
, class Difference = ptrdiff_t
>
class iterator_facade;
template <
class Derived
, class Base
, class Value = use_default
, class CategoryOrTraversal = use_default
, class Reference = use_default
, class Difference = use_default
>
class iterator_adaptor;
template <
class Iterator
, class Value = use_default
, class CategoryOrTraversal = use_default
, class Reference = use_default
, class Difference = use_default
>
class indirect_iterator;
template <class Dereferenceable>
struct pointee;
template <class Dereferenceable>
struct indirect_reference;
template <class Iterator>
class reverse_iterator;
template <
class UnaryFunction
, class Iterator
, class Reference = use_default
, class Value = use_default
>
class transform_iterator;
template <class Predicate, class Iterator>
class filter_iterator;
template <
class Incrementable
, class CategoryOrTraversal = use_default
, class Difference = use_default
>
class counting_iterator;
template <class UnaryFunction>
class function_output_iterator;
Iterator facade [lib.iterator.facade]
=====================================
.. include:: iterator_facade_abstract.rst
Class template ``iterator_facade``
----------------------------------
.. include:: iterator_facade_ref.rst
Iterator adaptor [lib.iterator.adaptor]
=======================================
.. include:: iterator_adaptor_abstract.rst
Class template ``iterator_adaptor``
-----------------------------------
.. include:: iterator_adaptor_ref.rst
Specialized adaptors [lib.iterator.special.adaptors]
====================================================
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 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.
]
Indirect iterator
-----------------
.. 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``
....................................
.. include:: indirect_iterator_ref.rst
Reverse iterator
----------------
.. include:: reverse_iterator_abstract.rst
Class template ``reverse_iterator``
...................................
.. include:: reverse_iterator_ref.rst
Transform iterator
------------------
.. include:: transform_iterator_abstract.rst
Class template ``transform_iterator``
.....................................
.. include:: transform_iterator_ref.rst
Filter iterator
---------------
.. include:: filter_iterator_abstract.rst
Class template ``filter_iterator``
..................................
.. include:: filter_iterator_ref.rst
Counting iterator
-----------------
.. include:: counting_iterator_abstract.rst
Class template ``counting_iterator``
....................................
.. include:: counting_iterator_ref.rst
Function output iterator
------------------------
.. include:: func_output_iter_abstract.rst
Class template ``function_output_iterator``
...........................................
.. include:: func_output_iter_ref.rst
.. 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
LocalWords: dereferenceable subobject AdaptableUnaryFunction impl pre ifdef'd
LocalWords: OtherIncrementable Coplien
libs/iterator/doc/facade_iterator_category.rst
+53
View File
@@ -0,0 +1,53 @@
.. |iterator-category| replace:: *iterator-category*
.. _iterator-category:
.. parsed-literal::
*iterator-category*\ (C,R,V) :=
if (C is convertible to std::input_iterator_tag
|| C is convertible to std::output_iterator_tag
)
return C
else if (C is not convertible to incrementable_traversal_tag)
*the program is ill-formed*
else return 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 (R is a reference type
&& C is convertible to forward_traversal_tag)
{
if (C is convertible to random_access_traversal_tag)
X1 = random_access_iterator_tag
else if (C is convertible to bidirectional_traversal_tag)
X1 = bidirectional_iterator_tag
else
X1 = forward_iterator_tag
}
else
{
if (C is convertible to single_pass_traversal_tag
&& R is convertible to V)
X1 = input_iterator_tag
else
X1 = C
}
2. |category-to-traversal|_\ (X) is convertible to the most
derived traversal tag type to which X is also
convertible, and not to any more-derived traversal tag
type.
.. |category-to-traversal| replace:: *category-to-traversal*
.. _`category-to-traversal`: new-iter-concepts.html#category-to-traversal
[Note: the intention is to allow ``iterator_category`` to be one of
the five original category tags when convertibility to one of the
traversal tags would add no information]
.. 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)
libs/iterator/doc/filter_iterator.html
+413
View File
@@ -0,0 +1,413 @@
<?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.5: http://docutils.sourceforge.net/" />
<title>Filter Iterator</title>
<meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" />
<meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, University of Hanover Institute for Transport Railway Operation and Construction" />
<meta name="date" content="2006-09-11" />
<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003." />
<link rel="stylesheet" href="../../../rst.css" type="text/css" />
</head>
<body>
<div class="document" id="filter-iterator">
<h1 class="title">Filter 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, Jeremy Siek, Thomas Witt</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first reference external" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference external" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="last reference external" href="mailto:witt&#64;ive.uni-hannover.de">witt&#64;ive.uni-hannover.de</a></td></tr>
<tr><th class="docinfo-name">Organization:</th>
<td><a class="first reference external" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference external" href="http://www.osl.iu.edu">Open Systems
Lab</a>, University of Hanover <a class="last reference external" href="http://www.ive.uni-hannover.de">Institute for Transport
Railway Operation and Construction</a></td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2006-09-11</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003.</td></tr>
</tbody>
</table>
<!-- Distributed under 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) -->
<table class="docutils 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"><!-- Copyright David Abrahams 2006. Distributed under 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) -->
The filter iterator adaptor creates a view of an iterator range in
which some elements of the range are skipped. A predicate function
object controls which elements are skipped. When the predicate is
applied to an element, if it returns <tt class="docutils literal"><span class="pre">true</span></tt> then the element is
retained and if it returns <tt class="docutils literal"><span class="pre">false</span></tt> 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. A filter iterator is therefore constructed with pair
of iterators indicating the range of elements in the unfiltered
sequence to be traversed.</td>
</tr>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#filter-iterator-synopsis" id="id2"><tt class="docutils literal"><span class="pre">filter_iterator</span></tt> synopsis</a></li>
<li><a class="reference internal" href="#filter-iterator-requirements" id="id3"><tt class="docutils literal"><span class="pre">filter_iterator</span></tt> requirements</a></li>
<li><a class="reference internal" href="#filter-iterator-models" id="id4"><tt class="docutils literal"><span class="pre">filter_iterator</span></tt> models</a></li>
<li><a class="reference internal" href="#filter-iterator-operations" id="id5"><tt class="docutils literal"><span class="pre">filter_iterator</span></tt> operations</a></li>
<li><a class="reference internal" href="#example" id="id6">Example</a></li>
</ul>
</div>
<div class="section" id="filter-iterator-synopsis">
<h1><a class="toc-backref" href="#id2"><tt class="docutils literal"><span class="pre">filter_iterator</span></tt> synopsis</a></h1>
<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt -->
<!-- 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) -->
<pre class="literal-block">
template &lt;class Predicate, class Iterator&gt;
class filter_iterator
{
public:
typedef iterator_traits&lt;Iterator&gt;::value_type value_type;
typedef iterator_traits&lt;Iterator&gt;::reference reference;
typedef iterator_traits&lt;Iterator&gt;::pointer pointer;
typedef iterator_traits&lt;Iterator&gt;::difference_type difference_type;
typedef /* see below */ iterator_category;
filter_iterator();
filter_iterator(Predicate f, Iterator x, Iterator end = Iterator());
filter_iterator(Iterator x, Iterator end = Iterator());
template&lt;class OtherIterator&gt;
filter_iterator(
filter_iterator&lt;Predicate, OtherIterator&gt; const&amp; t
, typename enable_if_convertible&lt;OtherIterator, Iterator&gt;::type* = 0 // exposition
);
Predicate predicate() const;
Iterator end() const;
Iterator const&amp; base() const;
reference operator*() const;
filter_iterator&amp; operator++();
private:
Predicate m_pred; // exposition only
Iterator m_iter; // exposition only
Iterator m_end; // exposition only
};
</pre>
<p>If <tt class="docutils literal"><span class="pre">Iterator</span></tt> models Readable Lvalue Iterator and Bidirectional Traversal
Iterator then <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible to
<tt class="docutils literal"><span class="pre">std::bidirectional_iterator_tag</span></tt>.
Otherwise, if <tt class="docutils literal"><span class="pre">Iterator</span></tt> models Readable Lvalue Iterator and Forward Traversal
Iterator then <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible to
<tt class="docutils literal"><span class="pre">std::forward_iterator_tag</span></tt>.
Otherwise <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is
convertible to <tt class="docutils literal"><span class="pre">std::input_iterator_tag</span></tt>.</p>
</div>
<div class="section" id="filter-iterator-requirements">
<h1><a class="toc-backref" href="#id3"><tt class="docutils literal"><span class="pre">filter_iterator</span></tt> requirements</a></h1>
<p>The <tt class="docutils literal"><span class="pre">Iterator</span></tt> argument shall meet the requirements of Readable
Iterator and Single Pass Iterator or it shall meet the requirements of
Input Iterator.</p>
<p>The <tt class="docutils literal"><span class="pre">Predicate</span></tt> argument must be Assignable, Copy Constructible, and
the expression <tt class="docutils literal"><span class="pre">p(x)</span></tt> must be valid where <tt class="docutils literal"><span class="pre">p</span></tt> is an object of type
<tt class="docutils literal"><span class="pre">Predicate</span></tt>, <tt class="docutils literal"><span class="pre">x</span></tt> is an object of type
<tt class="docutils literal"><span class="pre">iterator_traits&lt;Iterator&gt;::value_type</span></tt>, and where the type of
<tt class="docutils literal"><span class="pre">p(x)</span></tt> must be convertible to <tt class="docutils literal"><span class="pre">bool</span></tt>.</p>
</div>
<div class="section" id="filter-iterator-models">
<h1><a class="toc-backref" href="#id4"><tt class="docutils literal"><span class="pre">filter_iterator</span></tt> models</a></h1>
<p>The concepts that <tt class="docutils literal"><span class="pre">filter_iterator</span></tt> models are dependent on which
concepts the <tt class="docutils literal"><span class="pre">Iterator</span></tt> argument models, as specified in the
following tables.</p>
<table border="1" class="docutils">
<colgroup>
<col width="44%" />
<col width="56%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">If <tt class="docutils literal"><span class="pre">Iterator</span></tt> models</th>
<th class="head">then <tt class="docutils literal"><span class="pre">filter_iterator</span></tt> models</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Single Pass Iterator</td>
<td>Single Pass Iterator</td>
</tr>
<tr><td>Forward Traversal Iterator</td>
<td>Forward Traversal Iterator</td>
</tr>
<tr><td>Bidirectional Traversal Iterator</td>
<td>Bidirectional Traversal Iterator</td>
</tr>
</tbody>
</table>
<table border="1" class="docutils">
<colgroup>
<col width="41%" />
<col width="59%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">If <tt class="docutils literal"><span class="pre">Iterator</span></tt> models</th>
<th class="head">then <tt class="docutils literal"><span class="pre">filter_iterator</span></tt> models</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Readable Iterator</td>
<td>Readable Iterator</td>
</tr>
<tr><td>Writable Iterator</td>
<td>Writable Iterator</td>
</tr>
<tr><td>Lvalue Iterator</td>
<td>Lvalue Iterator</td>
</tr>
</tbody>
</table>
<table border="1" class="docutils">
<colgroup>
<col width="63%" />
<col width="38%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">If <tt class="docutils literal"><span class="pre">Iterator</span></tt> models</th>
<th class="head">then <tt class="docutils literal"><span class="pre">filter_iterator</span></tt> models</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Readable Iterator, Single Pass Iterator</td>
<td>Input Iterator</td>
</tr>
<tr><td>Readable Lvalue Iterator, Forward Traversal Iterator</td>
<td>Forward Iterator</td>
</tr>
<tr><td>Writable Lvalue Iterator, Forward Traversal Iterator</td>
<td>Mutable Forward Iterator</td>
</tr>
<tr><td>Writable Lvalue Iterator, Bidirectional Iterator</td>
<td>Mutable Bidirectional Iterator</td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">filter_iterator&lt;P1,</span> <span class="pre">X&gt;</span></tt> is interoperable with <tt class="docutils literal"><span class="pre">filter_iterator&lt;P2,</span> <span class="pre">Y&gt;</span></tt>
if and only if <tt class="docutils literal"><span class="pre">X</span></tt> is interoperable with <tt class="docutils literal"><span class="pre">Y</span></tt>.</p>
</div>
<div class="section" id="filter-iterator-operations">
<h1><a class="toc-backref" href="#id5"><tt class="docutils literal"><span class="pre">filter_iterator</span></tt> operations</a></h1>
<p>In addition to those operations required by the concepts that
<tt class="docutils literal"><span class="pre">filter_iterator</span></tt> models, <tt class="docutils literal"><span class="pre">filter_iterator</span></tt> provides the following
operations.</p>
<p><tt class="docutils literal"><span class="pre">filter_iterator();</span></tt></p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="docutils literal"><span class="pre">Predicate</span></tt> and <tt class="docutils literal"><span class="pre">Iterator</span></tt> must be Default Constructible.</td>
</tr>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Constructs a <tt class="docutils literal"><span class="pre">filter_iterator</span></tt> whose``m_pred``, <tt class="docutils literal"><span class="pre">m_iter</span></tt>, and <tt class="docutils literal"><span class="pre">m_end</span></tt>
members are a default constructed.</td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">filter_iterator(Predicate</span> <span class="pre">f,</span> <span class="pre">Iterator</span> <span class="pre">x,</span> <span class="pre">Iterator</span> <span class="pre">end</span> <span class="pre">=</span> <span class="pre">Iterator());</span></tt></p>
<table class="docutils 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">Constructs a <tt class="docutils literal"><span class="pre">filter_iterator</span></tt> where <tt class="docutils literal"><span class="pre">m_iter</span></tt> is either
the first position in the range <tt class="docutils literal"><span class="pre">[x,end)</span></tt> such that <tt class="docutils literal"><span class="pre">f(*m_iter)</span> <span class="pre">==</span> <span class="pre">true</span></tt>
or else``m_iter == end``. The member <tt class="docutils literal"><span class="pre">m_pred</span></tt> is constructed from
<tt class="docutils literal"><span class="pre">f</span></tt> and <tt class="docutils literal"><span class="pre">m_end</span></tt> from <tt class="docutils literal"><span class="pre">end</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">filter_iterator(Iterator</span> <span class="pre">x,</span> <span class="pre">Iterator</span> <span class="pre">end</span> <span class="pre">=</span> <span class="pre">Iterator());</span></tt></p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="docutils literal"><span class="pre">Predicate</span></tt> must be Default Constructible and
<tt class="docutils literal"><span class="pre">Predicate</span></tt> is a class type (not a function pointer).</td>
</tr>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Constructs a <tt class="docutils literal"><span class="pre">filter_iterator</span></tt> where <tt class="docutils literal"><span class="pre">m_iter</span></tt> is either
the first position in the range <tt class="docutils literal"><span class="pre">[x,end)</span></tt> such that <tt class="docutils literal"><span class="pre">m_pred(*m_iter)</span> <span class="pre">==</span> <span class="pre">true</span></tt>
or else``m_iter == end``. The member <tt class="docutils literal"><span class="pre">m_pred</span></tt> is default constructed.</td>
</tr>
</tbody>
</table>
<pre class="literal-block">
template &lt;class OtherIterator&gt;
filter_iterator(
filter_iterator&lt;Predicate, OtherIterator&gt; const&amp; t
, typename enable_if_convertible&lt;OtherIterator, Iterator&gt;::type* = 0 // exposition
);``
</pre>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="docutils literal"><span class="pre">OtherIterator</span></tt> is implicitly convertible to <tt class="docutils literal"><span class="pre">Iterator</span></tt>.</td>
</tr>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Constructs a filter iterator whose members are copied from <tt class="docutils literal"><span class="pre">t</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">Predicate</span> <span class="pre">predicate()</span> <span class="pre">const;</span></tt></p>
<table class="docutils 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="docutils literal"><span class="pre">m_pred</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">Iterator</span> <span class="pre">end()</span> <span class="pre">const;</span></tt></p>
<table class="docutils 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="docutils literal"><span class="pre">m_end</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">Iterator</span> <span class="pre">const&amp;</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
<table class="docutils 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="docutils literal"><span class="pre">m_iterator</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">reference</span> <span class="pre">operator*()</span> <span class="pre">const;</span></tt></p>
<table class="docutils 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="docutils literal"><span class="pre">*m_iter</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">filter_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
<table class="docutils 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 <tt class="docutils literal"><span class="pre">m_iter</span></tt> and then continues to
increment <tt class="docutils literal"><span class="pre">m_iter</span></tt> until either <tt class="docutils literal"><span class="pre">m_iter</span> <span class="pre">==</span> <span class="pre">m_end</span></tt>
or <tt class="docutils literal"><span class="pre">m_pred(*m_iter)</span> <span class="pre">==</span> <span class="pre">true</span></tt>.</td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
</tr>
</tbody>
</table>
<!-- Copyright David Abrahams 2006. Distributed under 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) -->
<pre class="literal-block">
template &lt;class Predicate, class Iterator&gt;
filter_iterator&lt;Predicate,Iterator&gt;
make_filter_iterator(Predicate f, Iterator x, Iterator end = Iterator());
</pre>
<table class="docutils 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">filter_iterator&lt;Predicate,Iterator&gt;(f, x, end)</td>
</tr>
</tbody>
</table>
<pre class="literal-block">
template &lt;class Predicate, class Iterator&gt;
filter_iterator&lt;Predicate,Iterator&gt;
make_filter_iterator(Iterator x, Iterator end = Iterator());
</pre>
<table class="docutils 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">filter_iterator&lt;Predicate,Iterator&gt;(x, end)</td>
</tr>
</tbody>
</table>
<!-- Copyright David Abrahams 2006. Distributed under 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) -->
</div>
<div class="section" id="example">
<h1><a class="toc-backref" href="#id6">Example</a></h1>
<p>This example uses <tt class="docutils literal"><span class="pre">filter_iterator</span></tt> and then
<tt class="docutils literal"><span class="pre">make_filter_iterator</span></tt> to output only the positive integers from an
array of integers. Then <tt class="docutils literal"><span class="pre">make_filter_iterator</span></tt> is is used to output
the integers greater than <tt class="docutils literal"><span class="pre">-2</span></tt>.</p>
<pre class="literal-block">
struct is_positive_number {
bool operator()(int x) { return 0 &lt; x; }
};
int main()
{
int numbers_[] = { 0, -1, 4, -3, 5, 8, -2 };
const int N = sizeof(numbers_)/sizeof(int);
typedef int* base_iterator;
base_iterator numbers(numbers_);
// Example using filter_iterator
typedef boost::filter_iterator&lt;is_positive_number, base_iterator&gt;
FilterIter;
is_positive_number predicate;
FilterIter filter_iter_first(predicate, numbers, numbers + N);
FilterIter filter_iter_last(predicate, numbers + N, numbers + N);
std::copy(filter_iter_first, filter_iter_last, std::ostream_iterator&lt;int&gt;(std::cout, &quot; &quot;));
std::cout &lt;&lt; std::endl;
// Example using make_filter_iterator()
std::copy(boost::make_filter_iterator&lt;is_positive_number&gt;(numbers, numbers + N),
boost::make_filter_iterator&lt;is_positive_number&gt;(numbers + N, numbers + N),
std::ostream_iterator&lt;int&gt;(std::cout, &quot; &quot;));
std::cout &lt;&lt; std::endl;
// Another example using make_filter_iterator()
std::copy(
boost::make_filter_iterator(
std::bind2nd(std::greater&lt;int&gt;(), -2)
, numbers, numbers + N)
, boost::make_filter_iterator(
std::bind2nd(std::greater&lt;int&gt;(), -2)
, numbers + N, numbers + N)
, std::ostream_iterator&lt;int&gt;(std::cout, &quot; &quot;)
);
std::cout &lt;&lt; std::endl;
return boost::exit_success;
}
</pre>
<p>The output is:</p>
<pre class="literal-block">
4 5 8
4 5 8
0 -1 4 5 8
</pre>
<p>The source code for this example can be found <a class="reference external" href="../example/filter_iterator_example.cpp">here</a>.</p>
</div>
</div>
<div class="footer">
<hr class="footer" />
<a class="reference external" href="filter_iterator.rst">View document source</a>.
Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div>
</body>
</html>
libs/iterator/doc/filter_iterator.pdf
BIN
View File
Binary file not shown.
libs/iterator/doc/filter_iterator.rst
+33
View File
@@ -0,0 +1,33 @@
.. Distributed under 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)
+++++++++++++++++
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 David Abrahams, Jeremy Siek, and Thomas Witt 2003.
.. _`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
``filter_iterator`` synopsis
............................
.. include:: filter_iterator_ref.rst
.. include:: make_filter_iterator.rst
.. include:: filter_iterator_eg.rst
libs/iterator/doc/filter_iterator_abstract.rst
+15
View File
@@ -0,0 +1,15 @@
.. Copyright David Abrahams 2006. Distributed under 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)
The filter iterator adaptor creates a view of an iterator range in
which some elements of the range are skipped. 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. A filter iterator is therefore constructed with pair
of iterators indicating the range of elements in the unfiltered
sequence to be traversed.
libs/iterator/doc/filter_iterator_eg.rst
+72
View File
@@ -0,0 +1,72 @@
.. Copyright David Abrahams 2006. Distributed under 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)
Example
.......
This example uses ``filter_iterator`` and then
``make_filter_iterator`` to output only the positive integers from an
array of integers. Then ``make_filter_iterator`` is is used to output
the integers greater than ``-2``.
::
struct is_positive_number {
bool operator()(int x) { return 0 < x; }
};
int main()
{
int numbers_[] = { 0, -1, 4, -3, 5, 8, -2 };
const int N = sizeof(numbers_)/sizeof(int);
typedef int* base_iterator;
base_iterator numbers(numbers_);
// Example using filter_iterator
typedef boost::filter_iterator<is_positive_number, base_iterator>
FilterIter;
is_positive_number predicate;
FilterIter filter_iter_first(predicate, numbers, numbers + N);
FilterIter filter_iter_last(predicate, numbers + N, numbers + N);
std::copy(filter_iter_first, filter_iter_last, std::ostream_iterator<int>(std::cout, " "));
std::cout << std::endl;
// Example using make_filter_iterator()
std::copy(boost::make_filter_iterator<is_positive_number>(numbers, numbers + N),
boost::make_filter_iterator<is_positive_number>(numbers + N, numbers + N),
std::ostream_iterator<int>(std::cout, " "));
std::cout << std::endl;
// Another example using make_filter_iterator()
std::copy(
boost::make_filter_iterator(
std::bind2nd(std::greater<int>(), -2)
, numbers, numbers + N)
, boost::make_filter_iterator(
std::bind2nd(std::greater<int>(), -2)
, numbers + N, numbers + N)
, std::ostream_iterator<int>(std::cout, " ")
);
std::cout << std::endl;
return boost::exit_success;
}
The output is::
4 5 8
4 5 8
0 -1 4 5 8
The source code for this example can be found `here`__.
__ ../example/filter_iterator_example.cpp
libs/iterator/doc/filter_iterator_ref.rst
+177
View File
@@ -0,0 +1,177 @@
.. Copyright David Abrahams, Jeremy Siek, and Thomas Witt
.. 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)
::
template <class Predicate, class Iterator>
class filter_iterator
{
public:
typedef iterator_traits<Iterator>::value_type value_type;
typedef iterator_traits<Iterator>::reference reference;
typedef iterator_traits<Iterator>::pointer pointer;
typedef iterator_traits<Iterator>::difference_type difference_type;
typedef /* see below */ iterator_category;
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;
Iterator const& base() const;
reference operator*() const;
filter_iterator& operator++();
private:
Predicate m_pred; // exposition only
Iterator m_iter; // exposition only
Iterator m_end; // exposition only
};
If ``Iterator`` models Readable Lvalue Iterator and Bidirectional Traversal
Iterator then ``iterator_category`` is convertible to
``std::bidirectional_iterator_tag``.
Otherwise, if ``Iterator`` models Readable Lvalue Iterator and Forward Traversal
Iterator then ``iterator_category`` is convertible to
``std::forward_iterator_tag``.
Otherwise ``iterator_category`` is
convertible to ``std::input_iterator_tag``.
``filter_iterator`` requirements
................................
The ``Iterator`` argument shall meet the requirements of Readable
Iterator and Single Pass Iterator or it shall meet the requirements of
Input Iterator.
The ``Predicate`` argument 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`` models
..........................
The concepts that ``filter_iterator`` models are dependent on which
concepts the ``Iterator`` argument models, as specified in the
following tables.
+---------------------------------+------------------------------------------+
|If ``Iterator`` models |then ``filter_iterator`` models |
+=================================+==========================================+
|Single Pass Iterator |Single Pass Iterator |
+---------------------------------+------------------------------------------+
|Forward Traversal Iterator |Forward Traversal Iterator |
+---------------------------------+------------------------------------------+
|Bidirectional Traversal Iterator |Bidirectional Traversal Iterator |
+---------------------------------+------------------------------------------+
+--------------------------------+----------------------------------------------+
| If ``Iterator`` models | then ``filter_iterator`` models |
+================================+==============================================+
| Readable Iterator | Readable Iterator |
+--------------------------------+----------------------------------------------+
| Writable Iterator | Writable Iterator |
+--------------------------------+----------------------------------------------+
| Lvalue Iterator | Lvalue Iterator |
+--------------------------------+----------------------------------------------+
+-------------------------------------------------------+---------------------------------+
|If ``Iterator`` models | then ``filter_iterator`` models |
+=======================================================+=================================+
|Readable Iterator, Single Pass Iterator | Input Iterator |
+-------------------------------------------------------+---------------------------------+
|Readable Lvalue Iterator, Forward Traversal Iterator | Forward Iterator |
+-------------------------------------------------------+---------------------------------+
|Writable Lvalue Iterator, Forward Traversal Iterator | Mutable Forward Iterator |
+-------------------------------------------------------+---------------------------------+
|Writable Lvalue Iterator, Bidirectional Iterator | Mutable Bidirectional Iterator |
+-------------------------------------------------------+---------------------------------+
``filter_iterator<P1, X>`` is interoperable with ``filter_iterator<P2, Y>``
if and only if ``X`` is interoperable with ``Y``.
``filter_iterator`` operations
..............................
In addition to those operations required by the concepts that
``filter_iterator`` models, ``filter_iterator`` provides the following
operations.
``filter_iterator();``
:Requires: ``Predicate`` and ``Iterator`` must be Default Constructible.
:Effects: Constructs a ``filter_iterator`` whose``m_pred``, ``m_iter``, and ``m_end``
members are a default constructed.
``filter_iterator(Predicate f, Iterator x, Iterator end = Iterator());``
:Effects: Constructs a ``filter_iterator`` where ``m_iter`` is either
the first position in the range ``[x,end)`` such that ``f(*m_iter) == true``
or else``m_iter == end``. The member ``m_pred`` is constructed from
``f`` and ``m_end`` from ``end``.
``filter_iterator(Iterator x, Iterator end = Iterator());``
:Requires: ``Predicate`` must be Default Constructible and
``Predicate`` is a class type (not a function pointer).
:Effects: Constructs a ``filter_iterator`` where ``m_iter`` is either
the first position in the range ``[x,end)`` such that ``m_pred(*m_iter) == true``
or else``m_iter == end``. The member ``m_pred`` is default constructed.
::
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``.
:Effects: Constructs a filter iterator whose members are copied from ``t``.
``Predicate predicate() const;``
:Returns: ``m_pred``
``Iterator end() const;``
:Returns: ``m_end``
``Iterator const& base() const;``
:Returns: ``m_iterator``
``reference operator*() const;``
:Returns: ``*m_iter``
``filter_iterator& operator++();``
:Effects: Increments ``m_iter`` and then continues to
increment ``m_iter`` until either ``m_iter == m_end``
or ``m_pred(*m_iter) == true``.
:Returns: ``*this``
libs/iterator/doc/func_output_iter_abstract.rst
+12
View File
@@ -0,0 +1,12 @@
.. Copyright David Abrahams 2006. Distributed under 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)
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.
libs/iterator/doc/func_output_iter_ref.rst
+73
View File
@@ -0,0 +1,73 @@
.. Copyright David Abrahams 2006. Distributed under 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)
Header
......
::
#include <boost/function_output_iterator.hpp>
::
template <class UnaryFunction>
class function_output_iterator {
public:
typedef std::output_iterator_tag iterator_category;
typedef void value_type;
typedef void difference_type;
typedef void pointer;
typedef void reference;
explicit function_output_iterator();
explicit function_output_iterator(const UnaryFunction& f);
/* see below */ operator*();
function_output_iterator& operator++();
function_output_iterator& operator++(int);
private:
UnaryFunction m_f; // exposition only
};
``function_output_iterator`` requirements
.........................................
``UnaryFunction`` must be Assignable and Copy Constructible.
``function_output_iterator`` models
...................................
``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());``
:Effects: Constructs an instance of ``function_output_iterator``
with ``m_f`` constructed from ``f``.
``operator*();``
:Returns: An object ``r`` of unspecified type such that ``r = t``
is equivalent to ``m_f(t)`` for all ``t``.
``function_output_iterator& operator++();``
:Returns: ``*this``
``function_output_iterator& operator++(int);``
:Returns: ``*this``
libs/iterator/doc/function_input_iterator.html
+142
View File
@@ -0,0 +1,142 @@
<?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.6: http://docutils.sourceforge.net/" />
<title></title>
<meta name="author" content="Dean Michael Berris" />
<link rel="stylesheet" href="../../../rst.css" type="text/css" />
</head>
<body>
<div class="document">
<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><a class="first reference external" href="mailto:mikhailberis&#64;gmail.com">Dean Michael Berris</a></td></tr>
<tr class="field"><th class="docinfo-name">License:</th><td class="field-body">Distributed under the Boost Software License, Version 1.0
(See accompanying file LICENSE_1_0.txt or copy at <a class="reference external" href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</td>
</tr>
</tbody>
</table>
<div class="section" id="function-input-iterator">
<h1>Function Input Iterator</h1>
<p>The Function Input Iterator allows for creating iterators that encapsulate
a nullary function object and a state object which tracks the number of times
the iterator has been incremented. A Function Input Iterator models the
<a class="reference external" href="http://www.sgi.com/tech/stl/InputIterator.html">InputIterator</a> concept and is useful for creating bounded input iterators.</p>
<p>Like the Generator Iterator, the Function Input Iterator takes a function
that models the <a class="reference external" href="http://www.sgi.com/tech/stl/Generator.html">Generator</a> concept (which is basically a nullary or 0-arity
function object). Each increment of the function Function Input Iterator
invokes the generator function and stores the value in the iterator. When
the iterator is dereferenced the stored value is returned.</p>
<p>The Function Input Iterator encapsulates a state object which models the
<a class="reference internal" href="#incrementable-concept">Incrementable Concept</a> and the <a class="reference external" href="http://www.sgi.com/tech/stl/EqualityComparable.html">EqualityComparable</a> Concept. These concepts are
described below as:</p>
<div class="section" id="incrementable-concept">
<h2>Incrementable Concept</h2>
<p>A type models the Incrementable Concept when it supports the pre- and post-
increment operators. For a given object <tt class="docutils literal"><span class="pre">i</span></tt> with type <tt class="docutils literal"><span class="pre">I</span></tt>, the following
constructs should be valid:</p>
<table border="1" class="docutils">
<colgroup>
<col width="24%" />
<col width="46%" />
<col width="30%" />
</colgroup>
<tbody valign="top">
<tr><td colspan="3">Construct Description Return Type</td>
</tr>
<tr><td>i++</td>
<td>Post-increment i.</td>
<td>I</td>
</tr>
<tr><td>++i</td>
<td>Pre-increment i.</td>
<td>I&amp;</td>
</tr>
</tbody>
</table>
<p>NOTE: An Incrementable type should also be <a class="reference external" href="http://www.sgi.com/tech/stl/DefaultConstructible.html">DefaultConstructible</a>.</p>
</div>
<div class="section" id="synopsis">
<h2>Synopsis</h2>
<pre class="literal-block">
namespace {
template &lt;class Function, class State&gt;
class function_input_iterator;
template &lt;class Function, class State&gt;
typename function_input_iterator&lt;Function, State&gt;
make_function_input_iterator(Function &amp; f);
struct infinite;
}
</pre>
</div>
<div class="section" id="function-input-iterator-class">
<h2>Function Input Iterator Class</h2>
<p>The class Function Input Iterator class takes two template parameters
<tt class="docutils literal"><span class="pre">Function</span></tt> and <tt class="docutils literal"><span class="pre">State</span></tt>. These two template parameters tell the
Function Input Iterator the type of the function to encapsulate and
the type of the internal state value to hold.</p>
<p>The <tt class="docutils literal"><span class="pre">State</span></tt> parameter is important in cases where you want to
control the type of the counter which determines whether two iterators
are at the same state. This allows for creating a pair of iterators which
bound the range of the invocations of the encapsulated functions.</p>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<p>The following example shows how we use the function input iterator class
in cases where we want to create bounded (lazy) generated ranges.</p>
<pre class="literal-block">
struct generator {
typedef int result_type;
generator() { srand(time(0)); }
result_type operator() () const {
return rand();
}
};
int main(int argc, char * argv[]) {
generator f;
copy(
make_function_input_iterator(f, 0),
make_function_input_iterator(f, 10),
ostream_iterator&lt;int&gt;(cout, &quot; &quot;)
);
return 0;
}
</pre>
<p>Here we can see that we've bounded the number of invocations using an <tt class="docutils literal"><span class="pre">int</span></tt>
that counts from <tt class="docutils literal"><span class="pre">0</span></tt> to <tt class="docutils literal"><span class="pre">10</span></tt>. Say we want to create an endless stream
of random numbers and encapsulate that in a pair of integers, we can do
it with the <tt class="docutils literal"><span class="pre">boost::infinite</span></tt> helper class.</p>
<pre class="literal-block">
copy(
make_function_input_iterator(f,infinite()),
make_function_input_iterator(f,infinite()),
ostream_iterator&lt;int&gt;(count, &quot; &quot;)
);
</pre>
<p>Above, instead of creating a huge vector we rely on the STL copy algorithm
to traverse the function input iterator and call the function object f
as it increments the iterator. The special property of <tt class="docutils literal"><span class="pre">boost::infinite</span></tt>
is that equating two instances always yield false -- and that incrementing
an instance of <tt class="docutils literal"><span class="pre">boost::infinite</span></tt> doesn't do anything. This is an efficient
way of stating that the iterator range provided by two iterators with an
encapsulated infinite state will definitely be infinite.</p>
</div>
</div>
</div>
<div class="footer">
<hr class="footer" />
<a class="reference external" href="function_input_iterator.rst">View document source</a>.
Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div>
</body>
</html>
libs/iterator/doc/function_input_iterator.rst
+132
View File
@@ -0,0 +1,132 @@
:Author:
`Dean Michael Berris <mailto:me@deanberris.com>`_
:License:
Distributed under 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)
:Copyright:
Copyright 2012 Google, Inc.
Function Input Iterator
=======================
The Function Input Iterator allows for creating iterators that encapsulate
a nullary function object and a state object which tracks the number of times
the iterator has been incremented. A Function Input Iterator models the
`InputIterator`_ concept and is useful for creating bounded input iterators.
.. _InputIterator: http://www.sgi.com/tech/stl/InputIterator.html
The Function Input Iterator takes a function that models the Generator_ concept
(which is basically a nullary or 0-arity function object). The first dereference
of the iterator at a given position invokes the generator function and stores
and returns the result; subsequent dereferences at the same position simply
return the same stored result. Incrementing the iterator places it at a new
position, hence a subsequent dereference will generate a new value via another
invokation of the generator function. This ensures the generator function is
invoked precisely when the iterator is requested to return a (new) value.
.. _Generator: http://www.sgi.com/tech/stl/Generator.html
The Function Input Iterator encapsulates a state object which models the
`Incrementable Concept`_ and the EqualityComparable_ Concept. These concepts are
described below as:
.. _EqualityComparable: http://www.sgi.com/tech/stl/EqualityComparable.html
Incrementable Concept
---------------------
A type models the Incrementable Concept when it supports the pre- and post-
increment operators. For a given object ``i`` with type ``I``, the following
constructs should be valid:
========= ================= ===========
Construct Description Return Type
-----------------------------------------
i++ Post-increment i. I
++i Pre-increment i. I&
========= ================= ===========
NOTE: An Incrementable type should also be DefaultConstructible_.
.. _DefaultConstructible: http://www.sgi.com/tech/stl/DefaultConstructible.html
Synopsis
--------
::
namespace {
template <class Function, class State>
class function_input_iterator;
template <class Function, class State>
typename function_input_iterator<Function, State>
make_function_input_iterator(Function & f, State s);
struct infinite;
}
Function Input Iterator Class
-----------------------------
The class Function Input Iterator class takes two template parameters
``Function`` and ``State``. These two template parameters tell the
Function Input Iterator the type of the function to encapsulate and
the type of the internal state value to hold.
The ``State`` parameter is important in cases where you want to
control the type of the counter which determines whether two iterators
are at the same state. This allows for creating a pair of iterators which
bound the range of the invocations of the encapsulated functions.
Examples
--------
The following example shows how we use the function input iterator class
in cases where we want to create bounded (lazy) generated ranges.
::
struct generator {
typedef int result_type;
generator() { srand(time(0)); }
result_type operator() () const {
return rand();
}
};
int main(int argc, char * argv[]) {
generator f;
copy(
make_function_input_iterator(f, 0),
make_function_input_iterator(f, 10),
ostream_iterator<int>(cout, " ")
);
return 0;
}
Here we can see that we've bounded the number of invocations using an ``int``
that counts from ``0`` to ``10``. Say we want to create an endless stream
of random numbers and encapsulate that in a pair of integers, we can do
it with the ``boost::infinite`` helper class.
::
copy(
make_function_input_iterator(f,infinite()),
make_function_input_iterator(f,infinite()),
ostream_iterator<int>(cout, " ")
);
Above, instead of creating a huge vector we rely on the STL copy algorithm
to traverse the function input iterator and call the function object f
as it increments the iterator. The special property of ``boost::infinite``
is that equating two instances always yield false -- and that incrementing
an instance of ``boost::infinite`` doesn't do anything. This is an efficient
way of stating that the iterator range provided by two iterators with an
encapsulated infinite state will definitely be infinite.
libs/iterator/doc/function_output_iterator.html
+191
View File
@@ -0,0 +1,191 @@
<?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.5: http://docutils.sourceforge.net/" />
<title>Function Output Iterator</title>
<meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" />
<meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, University of Hanover Institute for Transport Railway Operation and Construction" />
<meta name="date" content="2006-09-11" />
<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003." />
<link rel="stylesheet" href="../../../rst.css" type="text/css" />
</head>
<body>
<div class="document" id="function-output-iterator">
<h1 class="title">Function Output 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, Jeremy Siek, Thomas Witt</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first reference external" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference external" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="last reference external" href="mailto:witt&#64;ive.uni-hannover.de">witt&#64;ive.uni-hannover.de</a></td></tr>
<tr><th class="docinfo-name">Organization:</th>
<td><a class="first reference external" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference external" href="http://www.osl.iu.edu">Open Systems
Lab</a>, University of Hanover <a class="last reference external" href="http://www.ive.uni-hannover.de">Institute for Transport
Railway Operation and Construction</a></td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2006-09-11</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003.</td></tr>
</tbody>
</table>
<!-- Distributed under 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) -->
<table class="docutils 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"><!-- Copyright David Abrahams 2006. Distributed under 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) -->
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.</td>
</tr>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#header" id="id1">Header</a></li>
<li><a class="reference internal" href="#function-output-iterator-requirements" id="id2"><tt class="docutils literal"><span class="pre">function_output_iterator</span></tt> requirements</a></li>
<li><a class="reference internal" href="#function-output-iterator-models" id="id3"><tt class="docutils literal"><span class="pre">function_output_iterator</span></tt> models</a></li>
<li><a class="reference internal" href="#function-output-iterator-operations" id="id4"><tt class="docutils literal"><span class="pre">function_output_iterator</span></tt> operations</a></li>
<li><a class="reference internal" href="#example" id="id5">Example</a></li>
</ul>
</div>
<!-- Copyright David Abrahams 2006. Distributed under 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) -->
<div class="section" id="header">
<h1><a class="toc-backref" href="#id1">Header</a></h1>
<pre class="literal-block">
#include &lt;boost/function_output_iterator.hpp&gt;
</pre>
<pre class="literal-block">
template &lt;class UnaryFunction&gt;
class function_output_iterator {
public:
typedef std::output_iterator_tag iterator_category;
typedef void value_type;
typedef void difference_type;
typedef void pointer;
typedef void reference;
explicit function_output_iterator();
explicit function_output_iterator(const UnaryFunction&amp; f);
/* see below */ operator*();
function_output_iterator&amp; operator++();
function_output_iterator&amp; operator++(int);
private:
UnaryFunction m_f; // exposition only
};
</pre>
</div>
<div class="section" id="function-output-iterator-requirements">
<h1><a class="toc-backref" href="#id2"><tt class="docutils literal"><span class="pre">function_output_iterator</span></tt> requirements</a></h1>
<p><tt class="docutils literal"><span class="pre">UnaryFunction</span></tt> must be Assignable and Copy Constructible.</p>
</div>
<div class="section" id="function-output-iterator-models">
<h1><a class="toc-backref" href="#id3"><tt class="docutils literal"><span class="pre">function_output_iterator</span></tt> models</a></h1>
<p><tt class="docutils literal"><span class="pre">function_output_iterator</span></tt> is a model of the Writable and
Incrementable Iterator concepts.</p>
</div>
<div class="section" id="function-output-iterator-operations">
<h1><a class="toc-backref" href="#id4"><tt class="docutils literal"><span class="pre">function_output_iterator</span></tt> operations</a></h1>
<p><tt class="docutils literal"><span class="pre">explicit</span> <span class="pre">function_output_iterator(const</span> <span class="pre">UnaryFunction&amp;</span> <span class="pre">f</span> <span class="pre">=</span> <span class="pre">UnaryFunction());</span></tt></p>
<table class="docutils 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">Constructs an instance of <tt class="docutils literal"><span class="pre">function_output_iterator</span></tt>
with <tt class="docutils literal"><span class="pre">m_f</span></tt> constructed from <tt class="docutils literal"><span class="pre">f</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">operator*();</span></tt></p>
<table class="docutils 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 object <tt class="docutils literal"><span class="pre">r</span></tt> of unspecified type such that <tt class="docutils literal"><span class="pre">r</span> <span class="pre">=</span> <span class="pre">t</span></tt>
is equivalent to <tt class="docutils literal"><span class="pre">m_f(t)</span></tt> for all <tt class="docutils literal"><span class="pre">t</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">function_output_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
<table class="docutils 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="docutils literal"><span class="pre">*this</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">function_output_iterator&amp;</span> <span class="pre">operator++(int);</span></tt></p>
<table class="docutils 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="docutils literal"><span class="pre">*this</span></tt></td>
</tr>
</tbody>
</table>
<!-- Copyright David Abrahams 2006. Distributed under 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) -->
</div>
<div class="section" id="example">
<h1><a class="toc-backref" href="#id5">Example</a></h1>
<pre class="literal-block">
struct string_appender
{
string_appender(std::string&amp; s)
: m_str(&amp;s)
{}
void operator()(const std::string&amp; x) const
{
*m_str += x;
}
std::string* m_str;
};
int main(int, char*[])
{
std::vector&lt;std::string&gt; x;
x.push_back(&quot;hello&quot;);
x.push_back(&quot; &quot;);
x.push_back(&quot;world&quot;);
x.push_back(&quot;!&quot;);
std::string s = &quot;&quot;;
std::copy(x.begin(), x.end(),
boost::make_function_output_iterator(string_appender(s)));
std::cout &lt;&lt; s &lt;&lt; std::endl;
return 0;
}
</pre>
</div>
</div>
<div class="footer">
<hr class="footer" />
<a class="reference external" href="function_output_iterator.rst">View document source</a>.
Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div>
</body>
</html>
libs/iterator/doc/function_output_iterator.pdf
BIN
View File
Binary file not shown.
libs/iterator/doc/function_output_iterator.rst
+28
View File
@@ -0,0 +1,28 @@
.. Distributed under 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)
++++++++++++++++++++++++++
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 David Abrahams, Jeremy Siek, and Thomas Witt 2003.
.. _`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:: func_output_iter_abstract.rst
.. contents:: Table of Contents
.. include:: func_output_iter_ref.rst
.. include:: function_output_iterator_eg.rst
libs/iterator/doc/function_output_iterator_eg.rst
+39
View File
@@ -0,0 +1,39 @@
.. Copyright David Abrahams 2006. Distributed under 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)
Example
.......
::
struct string_appender
{
string_appender(std::string& s)
: m_str(&s)
{}
void operator()(const std::string& x) const
{
*m_str += x;
}
std::string* m_str;
};
int main(int, char*[])
{
std::vector<std::string> x;
x.push_back("hello");
x.push_back(" ");
x.push_back("world");
x.push_back("!");
std::string s = "";
std::copy(x.begin(), x.end(),
boost::make_function_output_iterator(string_appender(s)));
std::cout << s << std::endl;
return 0;
}
libs/iterator/doc/generate.py
+32
View File
@@ -0,0 +1,32 @@
#!/usr/bin/python
# 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)
#
# Generate html, TeX, and PDF versions of all the source files
#
import os
import sys
from syscmd import syscmd
from sources import sources
if 0:
for s in sources:
syscmd('boosthtml %s' % s)
else:
extensions = ('html', 'pdf')
if len(sys.argv) > 1:
extensions = sys.argv[1:]
all = [ '%s.%s' % (os.path.splitext(s)[0],ext)
for ext in extensions
for s in sources
]
print 'make %s' % ' '.join(all)
syscmd('make %s' % ' '.join(all))
libs/iterator/doc/generator_iterator.htm
+163
View File
@@ -0,0 +1,163 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<title>Generator Iterator Adaptor Documentation</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<img src="../../boost.png" alt="boost.png (6897 bytes)" align="middle"
width="277" height="86">
<h1>Generator Iterator Adaptor</h1>
<p>Defined in header <a href=
"../../boost/generator_iterator.hpp">boost/generator_iterator.hpp</a></p>
<p>The generator iterator adaptor makes it easier to create custom input
iterators from 0-ary functions and function objects. The adaptor takes a
<a href="http://www.sgi.com/tech/stl/Generator.html">Generator</a> and
creates a model of <a href=
"http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a>. Each
increment retrieves an item from the generator and makes it available to be
retrieved by dereferencing. The motivation for this iterator is that some
concepts can be more naturally expressed as a generator, while most STL
algorithms expect an iterator. An example is the <a href=
"../random/index.html">Random Number</a> library.</p>
<h2>Synopsis</h2>
<blockquote>
<pre>
namespace boost {
template &lt;class Generator&gt;
class generator_iterator_policies;
template &lt;class Generator&gt;
class generator_iterator_generator;
template &lt;class Generator&gt;
typename generator_iterator_generator&lt;Generator&gt;::type
make_generator_iterator(Generator &amp; gen);
}
</pre>
</blockquote>
<hr>
<h2>The Generator Iterator Generator Class</h2>
<p>The class generator_iterator_generator is a helper class whose purpose
is to construct a generator iterator type. The template parameter for this
class is the Generator function object type that is being wrapped. The
generator iterator adaptor only holds a reference (or pointer) to the
function object, therefore the function object must outlive the generator
iterator adaptor constructed from it.</p>
<pre>
template &lt;class Generator&gt;
class generator_iterator_generator
{
public:
typedef <i>unspecified</i> type; // the resulting generator iterator type
}
</pre>
<h3>Template Parameters</h3>
<table border summary="">
<tr>
<th>Parameter</th>
<th>Description</th>
</tr>
<tr>
<td><tt><a href=
"http://www.sgi.com/tech/stl/Generator.html">Generator</a></tt></td>
<td>The generator (0-ary function object) type being wrapped. The
return type of the function must be defined as
<tt>Generator::result_type</tt>. The function object must be a model of
<a href=
"http://www.sgi.com/tech/stl/Generator.html">Generator</a>.</td>
</tr>
</table>
<h3>Concept Model</h3>
<p>The generator iterator class is a model of <a href=
"http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a>.</p>
<h3>Members</h3>
<p>The generator iterator implements the member functions and operators
required of the <a href=
"http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a>
concept.<br></p>
<hr>
<h2><a name="make_generator_iterator" id="make_generator_iterator">The
Generator Iterator Object Generator</a></h2>
<p>The <tt>make_generator_iterator()</tt> function provides a convenient
way to create generator iterator objects. The function saves the user the
trouble of explicitly writing out the iterator types.</p>
<blockquote>
<pre>
template &lt;class Generator&gt;
typename generator_iterator_generator&lt;Generator&gt;::type
make_generator_iterator(Generator &amp; gen);
</pre>
</blockquote>
<hr>
<h3>Example</h3>
<p>The following program shows how <code>generator_iterator</code>
transforms a generator into an input iterator.</p>
<blockquote>
<pre>
#include &lt;iostream&gt;
#include &lt;boost/generator_iterator.hpp&gt;
class my_generator
{
public:
typedef int result_type;
my_generator() : state(0) { }
int operator()() { return ++state; }
private:
int state;
};
int main()
{
my_generator gen;
boost::generator_iterator_generator&lt;my_generator&gt;::type it = boost::make_generator_iterator(gen);
for(int i = 0; i &lt; 10; ++i, ++it)
std::cout &lt;&lt; *it &lt;&lt; std::endl;
}
</pre>
</blockquote>
<hr>
<p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
"../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
height="31" width="88"></a></p>
<p>Revised
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->05 December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38516" --></p>
<p><i>Copyright &copy; 2001 <a href=
"http://www.boost.org/people/jens_maurer.htm">Jens Maurer</a></i></p>
<p><i>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
copy at <a href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>
libs/iterator/doc/html/index.html
+296
View File
@@ -0,0 +1,296 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Chapter&#160;1.&#160;Boost.Iterator</title>
<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="next" href="iterator/concepts.html" title="Iterator Concepts">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td>
<td align="center"><a href="../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav"><a accesskey="n" href="iterator/concepts.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a></div>
<div class="chapter">
<div class="titlepage"><div>
<div><h2 class="title">
<a name="iterator"></a>Chapter&#160;1.&#160;Boost.Iterator</h2></div>
<div><div class="author"><h3 class="author">
<span class="firstname">David</span> <span class="surname">Abrahams</span>
</h3></div></div>
<div><div class="author"><h3 class="author">
<span class="firstname">Jeremy</span> <span class="surname">Siek</span>
</h3></div></div>
<div><div class="author"><h3 class="author">
<span class="firstname">Thomas</span> <span class="surname">Witt</span>
</h3></div></div>
<div><p class="copyright">Copyright &#169; 2003, 2005 David Abrahams Jeremy Siek Thomas
Witt</p></div>
<div><div class="legalnotice">
<a name="iterator.legal"></a><p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at &lt;ulink url="http://www.boost.org/LICENSE_1_0.txt"&gt;
http://www.boost.org/LICENSE_1_0.txt &lt;/ulink&gt;)
</p>
</div></div>
</div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
<dl class="toc">
<dt><span class="section"><a href="index.html#iterator.intro">Introduction</a></span></dt>
<dt><span class="section"><a href="iterator/concepts.html">Iterator Concepts</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="iterator/concepts.html#iterator.concepts.concepts_access">Access</a></span></dt>
<dt><span class="section"><a href="iterator/concepts/concepts_traversal.html">Traversal</a></span></dt>
</dl></dd>
<dt><span class="section"><a href="iterator/generic.html">Generic Iterators</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="iterator/generic.html#iterator.generic.facade">Iterator Facade</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="iterator/generic.html#iterator.generic.facade.facade_reference">Reference</a></span></dt>
<dt><span class="section"><a href="iterator/generic.html#iterator.generic.facade.facade_tutorial">Tutorial</a></span></dt>
</dl></dd>
<dt><span class="section"><a href="iterator/generic/adaptor.html">Iterator Adaptor</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="iterator/generic/adaptor.html#iterator.generic.adaptor.adaptor_reference">Reference</a></span></dt>
<dt><span class="section"><a href="iterator/generic/adaptor/adaptor_tutorial.html">Tutorial</a></span></dt>
</dl></dd>
</dl></dd>
<dt><span class="section"><a href="iterator/specialized.html">Specialized Adaptors</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="iterator/specialized.html#iterator.specialized.counting">Counting Iterator</a></span></dt>
<dt><span class="section"><a href="iterator/specialized/filter.html">Filter Iterator</a></span></dt>
<dt><span class="section"><a href="iterator/specialized/function_output.html">Function Output
Iterator</a></span></dt>
<dt><span class="section"><a href="iterator/specialized/indirect.html">Indirect Iterator</a></span></dt>
<dt><span class="section"><a href="iterator/specialized/permutation.html">Permutation Iterator</a></span></dt>
<dt><span class="section"><a href="iterator/specialized/reverse.html">Reverse Iterator</a></span></dt>
<dt><span class="section"><a href="iterator/specialized/shared_container.html">Shared Container
Iterator</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="iterator/specialized/shared_container.html#iterator.specialized.shared_container.shared_container_type">The
Shared Container Iterator Type</a></span></dt>
<dt><span class="section"><a href="iterator/specialized/shared_container/shared_container_object_generator.html">The
Shared Container Iterator Object Generator</a></span></dt>
<dt><span class="section"><a href="iterator/specialized/shared_container/shared_container_generator.html">The
Shared Container Iterator Range Generator</a></span></dt>
</dl></dd>
<dt><span class="section"><a href="iterator/specialized/transform.html">Transform Iterator</a></span></dt>
<dt><span class="section"><a href="iterator/specialized/zip.html">Zip Iterator</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="iterator/specialized/zip.html#iterator.specialized.zip.zip_example">Example</a></span></dt>
<dt><span class="section"><a href="iterator/specialized/zip/zip_reference.html">Reference</a></span></dt>
</dl></dd>
</dl></dd>
<dt><span class="section"><a href="iterator/utilities.html">Utilities</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="iterator/utilities.html#iterator.utilities.archetypes">Iterator Archetypes</a></span></dt>
<dt><span class="section"><a href="iterator/utilities/concept_checking.html">Concept Checking</a></span></dt>
<dt><span class="section"><a href="iterator/utilities/traits.html">Iterator Traits</a></span></dt>
<dt><span class="section"><a href="iterator/utilities/utilities.html">Iterator Utilities</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="iterator/utilities/utilities.html#iterator.utilities.utilities.utilities_traits">Traits</a></span></dt>
<dt><span class="section"><a href="iterator/utilities/utilities/utilities_testing.html">Testing
and Concept Checking</a></span></dt>
</dl></dd>
</dl></dd>
<dt><span class="section"><a href="iterator/upgrading.html">Upgrading from the old Boost Iterator
Adaptor Library</a></span></dt>
<dt><span class="section"><a href="iterator/history.html">History</a></span></dt>
</dl>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="iterator.intro"></a><a class="link" href="index.html#iterator.intro" title="Introduction">Introduction</a>
</h2></div></div></div>
<p>
The Boost Iterator Library contains two parts. The first is a system of <a href="http://www.boost.org/more/generic_programming.html#concept" target="_top">concepts</a>
which extend the C++ standard iterator requirements. The second is a framework
of components for building iterators based on these extended concepts and includes
several useful iterator adaptors. The extended iterator concepts have been
carefully designed so that old-style iterators can fit in the new concepts
and so that new-style iterators will be compatible with old-style algorithms,
though algorithms may need to be updated if they want to take full advantage
of the new-style iterator capabilities. Several components of this library
have been accepted into the C++ standard technical report. The components of
the Boost Iterator Library replace the older Boost Iterator Adaptor Library.
</p>
<h3>
<a name="iterator.intro.h0"></a>
<span class="phrase"><a name="iterator.intro.new_style_iterators"></a></span><a class="link" href="index.html#iterator.intro.new_style_iterators">New-Style
Iterators</a>
</h3>
<p>
The iterator categories defined in C++98 are extremely limiting because they
bind together two orthogonal concepts: traversal and element access. For example,
because a random access iterator is required to return a reference (and not
a proxy) when dereferenced, it is impossible to capture the capabilities of
<code class="computeroutput"><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">bool</span><span class="special">&gt;::</span><span class="identifier">iterator</span></code>
using the C++98 categories. This is the infamous "<code class="computeroutput"><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">bool</span><span class="special">&gt;</span></code>
is not a container, and its iterators aren't random access iterators",
debacle about which Herb Sutter wrote two papers for the standards comittee
(<a href="http://www.gotw.ca/publications/N1185.pdf" target="_top">N1185</a> and
<a href="http://www.gotw.ca/publications/N1211.pdf" target="_top">N1211</a>), and
a <a href="http://www.gotw.ca/gotw/050.htm" target="_top">Guru of the Week</a>. New-style
iterators go well beyond patching up <code class="computeroutput"><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">bool</span><span class="special">&gt;</span></code>,
though: there are lots of other iterators already in use which can't be adequately
represented by the existing concepts. For details about the new iterator concepts,
see our <a href="./new-iter-concepts.html" target="_top">Standard Proposal for New-Style
Iterators</a>.
</p>
<h3>
<a name="iterator.intro.h1"></a>
<span class="phrase"><a name="iterator.intro.iterator_facade_and_adaptor"></a></span><a class="link" href="index.html#iterator.intro.iterator_facade_and_adaptor">Iterator
Facade and Adaptor</a>
</h3>
<p>
Writing standard-conforming iterators is tricky, but the need comes up often.
In order to ease the implementation of new iterators, the Boost.Iterator library
provides the <a href="./iterator_facade.html" target="_top">facade</a> class template,
which implements many useful defaults and compile-time checks designed to help
the iterator author ensure that his iterator is correct.
</p>
<p>
It is also common to define a new iterator that is similar to some underlying
iterator or iterator-like type, but that modifies some aspect of the underlying
type's behavior. For that purpose, the library supplies the <a href="./iterator_adaptor.html" target="_top">adaptor</a>
class template, which is specially designed to take advantage of as much of
the underlying type's behavior as possible.
</p>
<p>
Both <a href="./iterator_facade.html" target="_top">facade</a> and <a href="./iterator_adaptor.html" target="_top">adaptor</a>
as well as many of the <code class="computeroutput"><span class="identifier">specialized</span>
<span class="identifier">adaptors</span></code>_ mentioned below have been
proposed for standardization (<a href="./facade-and-adaptor.html" target="_top">Standard
Proposal For Iterator Facade and Adaptor</a>).
</p>
<h3>
<a name="iterator.intro.h2"></a>
<span class="phrase"><a name="iterator.intro.specialized_adaptors"></a></span><a class="link" href="index.html#iterator.intro.specialized_adaptors">Specialized
Adaptors</a>
</h3>
<p>
The iterator library supplies a useful suite of standard-conforming iterator
templates based on the Boost <a class="link" href="index.html#iterator.intro.iterator_facade_and_adaptor">iterator
facade and adaptor</a> templates.
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<a href="./counting_iterator.html" target="_top"><code class="computeroutput"><span class="identifier">counting_iterator</span></code></a>:
an iterator over a sequence of consecutive values. Implements a "lazy
sequence"
</li>
<li class="listitem">
<a href="./filter_iterator.html" target="_top"><code class="computeroutput"><span class="identifier">filter_iterator</span></code></a>:
an iterator over the subset of elements of some sequence which satisfy
a given predicate
</li>
<li class="listitem">
<a href="./function_output_iterator.html" target="_top"><code class="computeroutput"><span class="identifier">function_output_iterator</span></code></a>:
an output iterator wrapping a unary function object; each time an element
is written into the dereferenced iterator, it is passed as a parameter
to the function object.
</li>
<li class="listitem">
<a href="./indirect_iterator.html" target="_top"><code class="computeroutput"><span class="identifier">indirect_iterator</span></code></a>:
an iterator over the objects <span class="bold"><strong>pointed-to</strong></span>
by the elements of some sequence.
</li>
<li class="listitem">
<a href="./permutation_iterator.html" target="_top"><code class="computeroutput"><span class="identifier">permutation_iterator</span></code></a>:
an iterator over the elements of some random-access sequence, rearranged
according to some sequence of integer indices.
</li>
<li class="listitem">
<p class="simpara">
<a href="./reverse_iterator.html" target="_top"><code class="computeroutput"><span class="identifier">reverse_iterator</span></code></a>:
an iterator which traverses the elements of some bidirectional sequence
in reverse. Corrects many of the shortcomings of C++98's
</p>
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">reverse_iterator</span></pre>
<p class="simpara">
.
</p>
</li>
<li class="listitem">
<a href="./shared_container_iterator.html" target="_top"><code class="computeroutput"><span class="identifier">shared_container_iterator</span></code></a>:
an iterator over elements of a container whose lifetime is maintained by
a <a href="../../smart_ptr/shared_ptr.htm" target="_top"><code class="computeroutput"><span class="identifier">shared_ptr</span></code></a>
stored in the iterator.
</li>
<li class="listitem">
<p class="simpara">
<a href="./transform_iterator.html" target="_top"><code class="computeroutput"><span class="identifier">transform_iterator</span></code></a>:
an iterator over elements which are the result of applying some functional
transformation to the elements of an underlying sequence. This component
also replaces the old
</p>
<pre class="programlisting"><span class="identifier">projection_iterator_adaptor</span></pre>
<p class="simpara">
.
</p>
</li>
<li class="listitem">
<a href="./zip_iterator.html" target="_top"><code class="computeroutput"><span class="identifier">zip_iterator</span></code></a>:
an iterator over tuples of the elements at corresponding positions of heterogeneous
underlying iterators.
</li>
</ul></div>
<h3>
<a name="iterator.intro.h3"></a>
<span class="phrase"><a name="iterator.intro.iterator_utilities"></a></span><a class="link" href="index.html#iterator.intro.iterator_utilities">Iterator
Utilities</a>
</h3>
<h4>
<a name="iterator.intro.h4"></a>
<span class="phrase"><a name="iterator.intro.traits"></a></span><a class="link" href="index.html#iterator.intro.traits">Traits</a>
</h4>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<a href="./pointee.html" target="_top"><code class="computeroutput"><span class="identifier">pointee</span><span class="special">.</span><span class="identifier">hpp</span></code></a>:
Provides the capability to deduce the referent types of pointers, smart
pointers and iterators in generic code. Used in <a href="./indirect_iterator.html" target="_top"><code class="computeroutput"><span class="identifier">indirect_iterator</span></code></a>.
</li>
<li class="listitem">
<a href="./iterator_traits.html" target="_top"><code class="computeroutput"><span class="identifier">iterator_traits</span><span class="special">.</span><span class="identifier">hpp</span></code></a>:
Provides <a href="../../mpl/doc/index.html" target="_top"><span class="bold"><strong>MPL</strong></span></a>
compatible metafunctions which retrieve an iterator's traits. Also corrects
for the deficiencies of broken implementations of <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">iterator_traits</span></code>.
</li>
</ul></div>
<p>
[* |interoperable|_ (PDF__): Provides an <a href="../../mpl/doc/index.html" target="_top"><span class="bold"><strong>MPL</strong></span></a> compatible metafunction for testing iterator
interoperability ]
</p>
<h4>
<a name="iterator.intro.h5"></a>
<span class="phrase"><a name="iterator.intro.testing_and_concept_checking"></a></span><a class="link" href="index.html#iterator.intro.testing_and_concept_checking">Testing
and Concept Checking</a>
</h4>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<a href="./iterator_concepts.html" target="_top"><code class="computeroutput"><span class="identifier">iterator_concepts</span><span class="special">.</span><span class="identifier">hpp</span></code></a>:
Concept checking classes for the new iterator concepts.
</li>
<li class="listitem">
<a href="./iterator_archetypes.html" target="_top"><code class="computeroutput"><span class="identifier">iterator_archetypes</span><span class="special">.</span><span class="identifier">hpp</span></code></a>:
Concept archetype classes for the new iterators concepts.
</li>
</ul></div>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"><p><small>Last revised: December 22, 2016 at 12:43:11 GMT</small></p></td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>
<div class="spirit-nav"><a accesskey="n" href="iterator/concepts.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a></div>
</body>
</html>
libs/iterator/doc/html/iterator/concepts.html
+336
View File
@@ -0,0 +1,336 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Iterator Concepts</title>
<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="up" href="../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="prev" href="../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="next" href="concepts/concepts_traversal.html" title="Traversal">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
<td align="center"><a href="../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../index.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="concepts/concepts_traversal.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="iterator.concepts"></a><a class="link" href="concepts.html" title="Iterator Concepts">Iterator Concepts</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="concepts.html#iterator.concepts.concepts_access">Access</a></span></dt>
<dt><span class="section"><a href="concepts/concepts_traversal.html">Traversal</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="iterator.concepts.concepts_access"></a><a class="link" href="concepts.html#iterator.concepts.concepts_access" title="Access">Access</a>
</h3></div></div></div>
<h3>
<a name="iterator.concepts.concepts_access.h0"></a>
<span class="phrase"><a name="iterator.concepts.concepts_access.readable_iterator_concept"></a></span><a class="link" href="concepts.html#iterator.concepts.concepts_access.readable_iterator_concept">Readable
Iterator Concept</a>
</h3>
<p>
A class or built-in type <code class="computeroutput"><span class="identifier">X</span></code>
models the <span class="bold"><strong>Readable Iterator</strong></span> concept for
value type <code class="computeroutput"><span class="identifier">T</span></code> if, in addition
to <code class="computeroutput"><span class="identifier">X</span></code> being Assignable and
Copy Constructible, the following expressions are valid and respect the stated
semantics. <code class="computeroutput"><span class="identifier">U</span></code> is the type
of any specified member of type <code class="computeroutput"><span class="identifier">T</span></code>.
</p>
<div class="table">
<a name="iterator.concepts.concepts_access.readable_iterator_requirements_i"></a><p class="title"><b>Table&#160;1.1.&#160;Readable Iterator Requirements (in addition to Assignable and Copy
Constructible)</b></p>
<div class="table-contents"><table class="table" summary="Readable Iterator Requirements (in addition to Assignable and Copy
Constructible)">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Expression
</p>
</th>
<th>
<p>
Return Type
</p>
</th>
<th>
<p>
Note/Precondition
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">&gt;::</span><span class="identifier">value_type</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">T</span></code>
</p>
</td>
<td>
<p>
Any non-reference, non cv-qualified type
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="special">*</span><span class="identifier">a</span></code>
</p>
</td>
<td>
<p>
Convertible to <code class="computeroutput"><span class="identifier">T</span></code>
</p>
</td>
<td>
<p>
pre: <code class="computeroutput"><span class="identifier">a</span></code> is dereferenceable.
If <code class="computeroutput"><span class="identifier">a</span> <span class="special">==</span>
<span class="identifier">b</span></code> then <code class="computeroutput"><span class="special">*</span><span class="identifier">a</span></code>
is equivalent to <code class="computeroutput"><span class="special">*</span><span class="identifier">b</span></code>.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">a</span><span class="special">-&gt;</span><span class="identifier">m</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">U</span><span class="special">&amp;</span></code>
</p>
</td>
<td>
<p>
pre: <code class="computeroutput"><span class="special">(*</span><span class="identifier">a</span><span class="special">).</span><span class="identifier">m</span></code>
is well-defined. Equivalent to <code class="computeroutput"><span class="special">(*</span><span class="identifier">a</span><span class="special">).</span><span class="identifier">m</span></code>.
</p>
</td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><h3>
<a name="iterator.concepts.concepts_access.h1"></a>
<span class="phrase"><a name="iterator.concepts.concepts_access.writable_iterator_concept"></a></span><a class="link" href="concepts.html#iterator.concepts.concepts_access.writable_iterator_concept">Writable
Iterator Concept </a>
</h3>
<p>
A class or built-in type <code class="computeroutput"><span class="identifier">X</span></code>
models the <span class="bold"><strong>Writable Iterator</strong></span> concept if,
in addition to <code class="computeroutput"><span class="identifier">X</span></code> being Copy
Constructible, the following expressions are valid and respect the stated
semantics. Writable Iterators have an associated <span class="bold"><strong>set
of value types</strong></span>.
</p>
<div class="table">
<a name="iterator.concepts.concepts_access.writable_iterator_requirements_i"></a><p class="title"><b>Table&#160;1.2.&#160;Writable Iterator Requirements (in addition to Copy Constructible)</b></p>
<div class="table-contents"><table class="table" summary="Writable Iterator Requirements (in addition to Copy Constructible)">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Expression
</p>
</th>
<th>
<p>
Return Type
</p>
</th>
<th>
<p>
Precondition
</p>
</th>
</tr></thead>
<tbody><tr>
<td>
<p>
<code class="computeroutput"><span class="special">*</span><span class="identifier">a</span>
<span class="special">=</span> <span class="identifier">o</span></code>
</p>
</td>
<td>
</td>
<td>
<p>
pre: The type of <code class="computeroutput"><span class="identifier">o</span></code>
is in the set of value types of <code class="computeroutput"><span class="identifier">X</span></code>
</p>
</td>
</tr></tbody>
</table></div>
</div>
<br class="table-break"><h3>
<a name="iterator.concepts.concepts_access.h2"></a>
<span class="phrase"><a name="iterator.concepts.concepts_access.swappable_iterator_concept"></a></span><a class="link" href="concepts.html#iterator.concepts.concepts_access.swappable_iterator_concept">Swappable
Iterator Concept</a>
</h3>
<p>
A class or built-in type <code class="computeroutput"><span class="identifier">X</span></code>
models the <span class="bold"><strong>Swappable Iterator</strong></span> concept if,
in addition to <code class="computeroutput"><span class="identifier">X</span></code> being Copy
Constructible, the following expressions are valid and respect the stated
semantics.
</p>
<div class="table">
<a name="iterator.concepts.concepts_access.swappable_iterator_requirements_"></a><p class="title"><b>Table&#160;1.3.&#160;Swappable Iterator Requirements (in addition to Copy Constructible)</b></p>
<div class="table-contents"><table class="table" summary="Swappable Iterator Requirements (in addition to Copy Constructible)">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Expression
</p>
</th>
<th>
<p>
Return Type
</p>
</th>
<th>
<p>
Postcondition
</p>
</th>
</tr></thead>
<tbody><tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">iter_swap</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span>
<span class="identifier">b</span><span class="special">)</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="keyword">void</span></code>
</p>
</td>
<td>
<p>
the pointed to values are exchanged
</p>
</td>
</tr></tbody>
</table></div>
</div>
<br class="table-break"><div class="sidebar">
<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div>
<p>
<span class="bold"><strong>Note:</strong></span> An iterator that is a model of the
<span class="bold"><strong>Readable</strong></span> and <span class="bold"><strong>Writable
Iterator</strong></span> concepts is also a model of <span class="bold"><strong>Swappable
Iterator</strong></span>. <span class="bold"><strong>--end note</strong></span>
</p>
</div>
<h3>
<a name="iterator.concepts.concepts_access.h3"></a>
<span class="phrase"><a name="iterator.concepts.concepts_access.lvalue_iterator_concept"></a></span><a class="link" href="concepts.html#iterator.concepts.concepts_access.lvalue_iterator_concept">Lvalue
Iterator Concept</a>
</h3>
<p>
The <span class="bold"><strong>Lvalue Iterator</strong></span> concept adds the requirement
that the return type of <code class="computeroutput"><span class="keyword">operator</span><span class="special">*</span></code> type be a reference to the value type of
the iterator.
</p>
<div class="table">
<a name="iterator.concepts.concepts_access.lvalue_iterator_requirements"></a><p class="title"><b>Table&#160;1.4.&#160;Lvalue Iterator Requirements</b></p>
<div class="table-contents"><table class="table" summary="Lvalue Iterator Requirements">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Expression
</p>
</th>
<th>
<p>
Return Type
</p>
</th>
<th>
<p>
Note/Assertion
</p>
</th>
</tr></thead>
<tbody><tr>
<td>
<p>
<code class="computeroutput"><span class="special">*</span><span class="identifier">a</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">T</span><span class="special">&amp;</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">T</span></code> is <span class="bold"><strong>cv</strong></span> <code class="computeroutput"><span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">&gt;::</span><span class="identifier">value_type</span></code>
where <span class="bold"><strong>cv</strong></span> is an optional cv-qualification.
pre: <code class="computeroutput"><span class="identifier">a</span></code> is dereferenceable.
If <code class="computeroutput"><span class="identifier">a</span> <span class="special">==</span>
<span class="identifier">b</span></code> then <code class="computeroutput"><span class="special">*</span><span class="identifier">a</span></code>
is equivalent to <code class="computeroutput"><span class="special">*</span><span class="identifier">b</span></code>.
</p>
</td>
</tr></tbody>
</table></div>
</div>
<br class="table-break">
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003, 2005 David Abrahams Jeremy Siek Thomas
Witt<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at &lt;ulink url="http://www.boost.org/LICENSE_1_0.txt"&gt;
http://www.boost.org/LICENSE_1_0.txt &lt;/ulink&gt;)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../index.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="concepts/concepts_traversal.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
libs/iterator/doc/html/iterator/concepts/concepts_traversal.html
+798
View File
@@ -0,0 +1,798 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Traversal</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="up" href="../concepts.html" title="Iterator Concepts">
<link rel="prev" href="../concepts.html" title="Iterator Concepts">
<link rel="next" href="../generic.html" title="Generic Iterators">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../concepts.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../concepts.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../generic.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="iterator.concepts.concepts_traversal"></a><a class="link" href="concepts_traversal.html" title="Traversal">Traversal</a>
</h3></div></div></div>
<h3>
<a name="iterator.concepts.concepts_traversal.h0"></a>
<span class="phrase"><a name="iterator.concepts.concepts_traversal.incrementable_iterator_concept"></a></span><a class="link" href="concepts_traversal.html#iterator.concepts.concepts_traversal.incrementable_iterator_concept">Incrementable
Iterator Concept</a>
</h3>
<p>
A class or built-in type <code class="computeroutput"><span class="identifier">X</span></code>
models the <span class="bold"><strong>Incrementable Iterator</strong></span> concept
if, in addition to <code class="computeroutput"><span class="identifier">X</span></code> being
Assignable and Copy Constructible, the following expressions are valid and
respect the stated semantics.
</p>
<div class="table">
<a name="iterator.concepts.concepts_traversal.incrementable_iterator_requireme"></a><p class="title"><b>Table&#160;1.5.&#160;Incrementable Iterator Requirements (in addition to Assignable, Copy
Constructible)</b></p>
<div class="table-contents"><table class="table" summary="Incrementable Iterator Requirements (in addition to Assignable, Copy
Constructible)">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Expression
</p>
</th>
<th>
<p>
Return Type
</p>
</th>
<th>
<p>
Assertion/Semantics
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
<code class="computeroutput"><span class="special">++</span><span class="identifier">r</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">X</span><span class="special">&amp;</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="special">&amp;</span><span class="identifier">r</span>
<span class="special">==</span> <span class="special">&amp;++</span><span class="identifier">r</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">r</span><span class="special">++</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">X</span></code>
</p>
</td>
<td>
<pre class="programlisting"><span class="special">{</span>
<span class="identifier">X</span> <span class="identifier">tmp</span> <span class="special">=</span> <span class="identifier">r</span><span class="special">;</span>
<span class="special">++</span><span class="identifier">r</span><span class="special">;</span>
<span class="keyword">return</span> <span class="identifier">tmp</span><span class="special">;</span>
<span class="special">}</span>
</pre>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">iterator_traversal</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">&gt;::</span><span class="identifier">type</span></code>
</p>
</td>
<td>
<p>
Convertible to <code class="computeroutput"><span class="identifier">incrementable_traversal_tag</span></code>
</p>
</td>
<td>
</td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><h3>
<a name="iterator.concepts.concepts_traversal.h1"></a>
<span class="phrase"><a name="iterator.concepts.concepts_traversal.single_pass_iterator_concept"></a></span><a class="link" href="concepts_traversal.html#iterator.concepts.concepts_traversal.single_pass_iterator_concept">Single
Pass Iterator Concept</a>
</h3>
<p>
A class or built-in type <code class="computeroutput"><span class="identifier">X</span></code>
models the <span class="bold"><strong>Single Pass Iterator</strong></span> concept
if the following expressions are valid and respect the stated semantics.
</p>
<div class="table">
<a name="iterator.concepts.concepts_traversal.single_pass_iterator_requirement"></a><p class="title"><b>Table&#160;1.6.&#160;Single Pass Iterator Requirements (in addition to Incrementable Iterator
and Equality Comparable)</b></p>
<div class="table-contents"><table class="table" summary="Single Pass Iterator Requirements (in addition to Incrementable Iterator
and Equality Comparable)">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Expression
</p>
</th>
<th>
<p>
Return Type
</p>
</th>
<th>
<p>
Assertion/Semantics / Pre-/Post-condition
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
<code class="computeroutput"><span class="special">++</span><span class="identifier">r</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">X</span><span class="special">&amp;</span></code>
</p>
</td>
<td>
<p>
pre:<br> <code class="computeroutput"><span class="identifier">r</span></code> is
dereferenceable;<br> post:<br> <code class="computeroutput"><span class="identifier">r</span></code>
is dereferenceable or<br> <code class="computeroutput"><span class="identifier">r</span></code>
is past-the-end
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">a</span> <span class="special">==</span>
<span class="identifier">b</span></code>
</p>
</td>
<td>
<p>
convertible to <code class="computeroutput"><span class="keyword">bool</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="special">==</span></code> is an equivalence
relation over its domain
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">a</span> <span class="special">!=</span>
<span class="identifier">b</span></code>
</p>
</td>
<td>
<p>
convertible to <code class="computeroutput"><span class="keyword">bool</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="special">!(</span><span class="identifier">a</span>
<span class="special">==</span> <span class="identifier">b</span><span class="special">)</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">iterator_traversal</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">&gt;::</span><span class="identifier">type</span></code>
</p>
</td>
<td>
<p>
Convertible to<code class="computeroutput"><span class="identifier">single_pass_traversal_tag</span></code>
</p>
</td>
<td>
</td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><h3>
<a name="iterator.concepts.concepts_traversal.h2"></a>
<span class="phrase"><a name="iterator.concepts.concepts_traversal.forward_traversal_concept"></a></span><a class="link" href="concepts_traversal.html#iterator.concepts.concepts_traversal.forward_traversal_concept">Forward
Traversal Concept</a>
</h3>
<p>
A class or built-in type <code class="computeroutput"><span class="identifier">X</span></code>
models the <span class="bold"><strong>Forward Traversal</strong></span> concept if,
in addition to <code class="computeroutput"><span class="identifier">X</span></code> meeting
the requirements of Default Constructible and Single Pass Iterator, the following
expressions are valid and respect the stated semantics.
</p>
<div class="table">
<a name="iterator.concepts.concepts_traversal.forward_traversal_iterator_requi"></a><p class="title"><b>Table&#160;1.7.&#160;Forward Traversal Iterator Requirements (in addition to Default Constructible
and Single Pass Iterator)</b></p>
<div class="table-contents"><table class="table" summary="Forward Traversal Iterator Requirements (in addition to Default Constructible
and Single Pass Iterator)">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Expression
</p>
</th>
<th>
<p>
Return Type
</p>
</th>
<th>
<p>
Assertion/Note
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">X</span> <span class="identifier">u</span><span class="special">;</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">X</span><span class="special">&amp;</span></code>
</p>
</td>
<td>
<p>
note: <code class="computeroutput"><span class="identifier">u</span></code> may have
a singular value.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="special">++</span><span class="identifier">r</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">X</span><span class="special">&amp;</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">r</span> <span class="special">==</span>
<span class="identifier">s</span></code> and <code class="computeroutput"><span class="identifier">r</span></code>
is dereferenceable implies <code class="computeroutput"><span class="special">++</span><span class="identifier">r</span> <span class="special">==</span>
<span class="special">++</span><span class="identifier">s</span><span class="special">.</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">&gt;::</span><span class="identifier">difference_type</span></code>
</p>
</td>
<td>
<p>
A signed integral type representing the distance between iterators
</p>
</td>
<td>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">iterator_traversal</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">&gt;::</span><span class="identifier">type</span></code>
</p>
</td>
<td>
<p>
Convertible to <code class="computeroutput"><span class="identifier">forward_traversal_tag</span></code>
</p>
</td>
<td>
</td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><h3>
<a name="iterator.concepts.concepts_traversal.h3"></a>
<span class="phrase"><a name="iterator.concepts.concepts_traversal.bidirectional_traversal_concept"></a></span><a class="link" href="concepts_traversal.html#iterator.concepts.concepts_traversal.bidirectional_traversal_concept">Bidirectional
Traversal Concept</a>
</h3>
<p>
A class or built-in type <code class="computeroutput"><span class="identifier">X</span></code>
models the <span class="bold"><strong>Bidirectional Traversal</strong></span> concept
if, in addition to <code class="computeroutput"><span class="identifier">X</span></code> meeting
the requirements of Forward Traversal Iterator, the following expressions
are valid and respect the stated semantics.
</p>
<div class="table">
<a name="iterator.concepts.concepts_traversal.bidirectional_traversal_iterator"></a><p class="title"><b>Table&#160;1.8.&#160;Bidirectional Traversal Iterator Requirements (in addition to Forward
Traversal Iterator)</b></p>
<div class="table-contents"><table class="table" summary="Bidirectional Traversal Iterator Requirements (in addition to Forward
Traversal Iterator)">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Expression
</p>
</th>
<th>
<p>
Return Type
</p>
</th>
<th>
<p>
Assertion/Semantics/Pre-/Post-condition
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
<code class="computeroutput"><span class="special">--</span><span class="identifier">r</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">X</span><span class="special">&amp;</span></code>
</p>
</td>
<td>
<p>
pre: there exists <code class="computeroutput"><span class="identifier">s</span></code>
such that <code class="computeroutput"><span class="identifier">r</span> <span class="special">==</span>
<span class="special">++</span><span class="identifier">s</span></code>.<br>
post: <code class="computeroutput"><span class="identifier">s</span></code> is dereferenceable.
<code class="computeroutput"><span class="special">--(++</span><span class="identifier">r</span><span class="special">)</span> <span class="special">==</span> <span class="identifier">r</span></code>. <code class="computeroutput"><span class="special">--</span><span class="identifier">r</span> <span class="special">==</span>
<span class="special">--</span><span class="identifier">s</span></code>
implies <code class="computeroutput"><span class="identifier">r</span> <span class="special">==</span>
<span class="identifier">s</span></code>. <code class="computeroutput"><span class="special">&amp;</span><span class="identifier">r</span> <span class="special">==</span>
<span class="special">&amp;--</span><span class="identifier">r</span></code>.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">r</span><span class="special">--</span></code>
</p>
</td>
<td>
<p>
convertible to <code class="computeroutput"><span class="keyword">const</span> <span class="identifier">X</span><span class="special">&amp;</span></code>
</p>
</td>
<td>
<pre class="programlisting"><span class="special">{</span>
<span class="identifier">X</span> <span class="identifier">tmp</span> <span class="special">=</span> <span class="identifier">r</span><span class="special">;</span>
<span class="special">--</span><span class="identifier">r</span><span class="special">;</span>
<span class="keyword">return</span> <span class="identifier">tmp</span><span class="special">;</span>
<span class="special">}</span>
</pre>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">iterator_traversal</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">&gt;::</span><span class="identifier">type</span></code>
</p>
</td>
<td>
<p>
Convertible to <code class="computeroutput"><span class="identifier">bidirectional_traversal_tag</span></code>
</p>
</td>
<td>
</td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><h3>
<a name="iterator.concepts.concepts_traversal.h4"></a>
<span class="phrase"><a name="iterator.concepts.concepts_traversal.random_access_traversal_concept"></a></span><a class="link" href="concepts_traversal.html#iterator.concepts.concepts_traversal.random_access_traversal_concept">Random
Access Traversal Concept</a>
</h3>
<p>
A class or built-in type <code class="computeroutput"><span class="identifier">X</span></code>
models the <span class="bold"><strong>Random Access Traversal</strong></span> concept
if the following expressions are valid and respect the stated semantics.
In the table below, <code class="computeroutput"><span class="identifier">Distance</span></code>
is <code class="computeroutput"><span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">&gt;::</span><span class="identifier">difference_type</span></code> and <code class="computeroutput"><span class="identifier">n</span></code>
represents a constant object of type <code class="computeroutput"><span class="identifier">Distance</span></code>.
</p>
<div class="table">
<a name="iterator.concepts.concepts_traversal.random_access_traversal_iterator"></a><p class="title"><b>Table&#160;1.9.&#160;Random Access Traversal Iterator Requirements (in addition to Bidirectional
Traversal)</b></p>
<div class="table-contents"><table class="table" summary="Random Access Traversal Iterator Requirements (in addition to Bidirectional
Traversal)">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Expression
</p>
</th>
<th>
<p>
Return Type
</p>
</th>
<th>
<p>
Operational Semantics
</p>
</th>
<th>
<p>
Assertion/Precondition
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">r</span> <span class="special">+=</span>
<span class="identifier">n</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">X</span><span class="special">&amp;</span></code>
</p>
</td>
<td>
<pre class="programlisting"><span class="special">{</span>
<span class="identifier">Distance</span> <span class="identifier">m</span> <span class="special">=</span> <span class="identifier">n</span><span class="special">;</span>
<span class="keyword">if</span> <span class="special">(</span><span class="identifier">m</span> <span class="special">&gt;=</span> <span class="number">0</span><span class="special">)</span>
<span class="keyword">while</span> <span class="special">(</span><span class="identifier">m</span><span class="special">--)</span>
<span class="special">++</span><span class="identifier">r</span><span class="special">;</span>
<span class="keyword">else</span>
<span class="keyword">while</span> <span class="special">(</span><span class="identifier">m</span><span class="special">++)</span>
<span class="special">--</span><span class="identifier">r</span><span class="special">;</span>
<span class="keyword">return</span> <span class="identifier">r</span><span class="special">;</span>
<span class="special">}</span>
</pre>
</td>
<td>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">a</span> <span class="special">+</span>
<span class="identifier">n</span></code>, <code class="computeroutput"><span class="identifier">n</span>
<span class="special">+</span> <span class="identifier">a</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">X</span></code>
</p>
</td>
<td>
<pre class="programlisting"><span class="special">{</span>
<span class="identifier">X</span> <span class="identifier">tmp</span> <span class="special">=</span> <span class="identifier">a</span><span class="special">;</span>
<span class="keyword">return</span> <span class="identifier">tmp</span><span class="special">+=</span> <span class="identifier">n</span><span class="special">;</span>
<span class="special">}</span>
</pre>
</td>
<td>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">r</span> <span class="special">-=</span>
<span class="identifier">n</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">X</span><span class="special">&amp;</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="keyword">return</span> <span class="identifier">r</span>
<span class="special">+=</span> <span class="special">-</span><span class="identifier">n</span></code>
</p>
</td>
<td>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">a</span> <span class="special">-</span>
<span class="identifier">n</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">X</span></code>
</p>
</td>
<td>
<pre class="programlisting"><span class="special">{</span>
<span class="identifier">X</span> <span class="identifier">tmp</span> <span class="special">=</span> <span class="identifier">a</span><span class="special">;</span>
<span class="keyword">return</span> <span class="identifier">tmp</span><span class="special">-=</span> <span class="identifier">n</span><span class="special">;</span>
<span class="special">}</span>
</pre>
</td>
<td>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">b</span> <span class="special">-</span>
<span class="identifier">a</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">Distance</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">a</span> <span class="special">&lt;</span>
<span class="identifier">b</span> <span class="special">?</span>
<span class="identifier">distance</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span><span class="identifier">b</span><span class="special">)</span>
<span class="special">:</span> <span class="special">-</span><span class="identifier">distance</span><span class="special">(</span><span class="identifier">b</span><span class="special">,</span><span class="identifier">a</span><span class="special">)</span></code>
</p>
</td>
<td>
<p>
pre: there exists a value <code class="computeroutput"><span class="identifier">n</span></code>
of <code class="computeroutput"><span class="identifier">Distance</span></code> such
that <code class="computeroutput"><span class="identifier">a</span> <span class="special">+</span>
<span class="identifier">n</span> <span class="special">==</span>
<span class="identifier">b</span></code>. <code class="computeroutput"><span class="identifier">b</span>
<span class="special">==</span> <span class="identifier">a</span>
<span class="special">+</span> <span class="special">(</span><span class="identifier">b</span> <span class="special">-</span>
<span class="identifier">a</span><span class="special">)</span></code>.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">a</span><span class="special">\[</span><span class="identifier">n</span><span class="special">\]</span></code>
</p>
</td>
<td>
<p>
convertible to T
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="special">*(</span><span class="identifier">a</span>
<span class="special">+</span> <span class="identifier">n</span><span class="special">)</span></code>
</p>
</td>
<td>
<p>
pre: a is a <span class="bold"><strong>Readable Iterator</strong></span>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">a</span><span class="special">\[</span><span class="identifier">n</span><span class="special">\]</span>
<span class="special">=</span> <span class="identifier">v</span></code>
</p>
</td>
<td>
<p>
convertible to T
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="special">*(</span><span class="identifier">a</span>
<span class="special">+</span> <span class="identifier">n</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">v</span></code>
</p>
</td>
<td>
<p>
pre: a is a <span class="bold"><strong>Writable iterator</strong></span>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">a</span> <span class="special">&lt;</span>
<span class="identifier">b</span></code>
</p>
</td>
<td>
<p>
convertible to <code class="computeroutput"><span class="keyword">bool</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">b</span> <span class="special">-</span>
<span class="identifier">a</span> <span class="special">&gt;</span>
<span class="number">0</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="special">&lt;</span></code> is a total ordering
relation
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">a</span> <span class="special">&gt;</span>
<span class="identifier">b</span></code>
</p>
</td>
<td>
<p>
convertible to <code class="computeroutput"><span class="keyword">bool</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">b</span> <span class="special">&lt;</span>
<span class="identifier">a</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="special">&gt;</span></code> is a total ordering
relation
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">a</span> <span class="special">&gt;=</span>
<span class="identifier">b</span></code>
</p>
</td>
<td>
<p>
convertible to <code class="computeroutput"><span class="keyword">bool</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="special">!(</span><span class="identifier">a</span>
<span class="special">&lt;</span> <span class="identifier">b</span><span class="special">)</span></code>
</p>
</td>
<td>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">a</span> <span class="special">&lt;=</span>
<span class="identifier">b</span></code>
</p>
</td>
<td>
<p>
convertible to <code class="computeroutput"><span class="keyword">bool</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="special">!(</span><span class="identifier">a</span>
<span class="special">&gt;</span> <span class="identifier">b</span><span class="special">)</span></code>
</p>
</td>
<td>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">iterator_traversal</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">&gt;::</span><span class="identifier">type</span></code>
</p>
</td>
<td>
<p>
convertible to <code class="computeroutput"><span class="identifier">random_access_traversal_tag</span></code>
</p>
</td>
<td>
</td>
<td>
</td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break">
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003, 2005 David Abrahams Jeremy Siek Thomas
Witt<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at &lt;ulink url="http://www.boost.org/LICENSE_1_0.txt"&gt;
http://www.boost.org/LICENSE_1_0.txt &lt;/ulink&gt;)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../concepts.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../concepts.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../generic.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
libs/iterator/doc/html/iterator/generic.html
+1546
View File
File diff suppressed because it is too large Load Diff
libs/iterator/doc/html/iterator/generic/adaptor.html
+278
View File
@@ -0,0 +1,278 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Iterator Adaptor</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="up" href="../generic.html" title="Generic Iterators">
<link rel="prev" href="../generic.html" title="Generic Iterators">
<link rel="next" href="adaptor/adaptor_tutorial.html" title="Tutorial">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../generic.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../generic.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="adaptor/adaptor_tutorial.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="iterator.generic.adaptor"></a><a class="link" href="adaptor.html" title="Iterator Adaptor">Iterator Adaptor</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="adaptor.html#iterator.generic.adaptor.adaptor_reference">Reference</a></span></dt>
<dt><span class="section"><a href="adaptor/adaptor_tutorial.html">Tutorial</a></span></dt>
</dl></div>
<p>
The <code class="computeroutput"><span class="identifier">iterator_adaptor</span></code> class
template adapts some <code class="computeroutput"><span class="identifier">Base</span></code>
<a name="base"></a>_ type to create a new iterator. Instantiations of <code class="computeroutput"><span class="identifier">iterator_adaptor</span></code> are derived from a corresponding
instantiation of <code class="computeroutput"><span class="identifier">iterator_facade</span></code>
and implement the core behaviors in terms of the <code class="computeroutput"><span class="identifier">Base</span></code>
type. In essence, <code class="computeroutput"><span class="identifier">iterator_adaptor</span></code>
merely forwards all operations to an instance of the <code class="computeroutput"><span class="identifier">Base</span></code>
type, which it stores as a member.
</p>
<p>
.. <a name="base0"></a>The term "Base" here does not refer to a
base class and is not meant to imply the use of derivation. We have followed
the lead of the standard library, which provides a base() function to access
the underlying iterator object of a <code class="computeroutput"><span class="identifier">reverse_iterator</span></code>
adaptor.
</p>
<p>
The user of <code class="computeroutput"><span class="identifier">iterator_adaptor</span></code>
creates a class derived from an instantiation of <code class="computeroutput"><span class="identifier">iterator_adaptor</span></code>
and then selectively redefines some of the core member functions described
in the <code class="computeroutput"><span class="identifier">iterator_facade</span></code> core
requirements table. The <code class="computeroutput"><span class="identifier">Base</span></code>
type need not meet the full requirements for an iterator; it need only support
the operations used by the core interface functions of <code class="computeroutput"><span class="identifier">iterator_adaptor</span></code>
that have not been redefined in the user's derived class.
</p>
<p>
Several of the template parameters of <code class="computeroutput"><span class="identifier">iterator_adaptor</span></code>
default to <code class="computeroutput"><span class="identifier">use_default</span></code>. 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 complicated, so metaprogramming
is required to compute them, and <code class="computeroutput"><span class="identifier">use_default</span></code>
can help to simplify the implementation. Finally, the identity of the <code class="computeroutput"><span class="identifier">use_default</span></code> type is not left unspecified
because specification helps to highlight that the <code class="computeroutput"><span class="identifier">Reference</span></code>
template parameter may not always be identical to the iterator's <code class="computeroutput"><span class="identifier">reference</span></code> type, and will keep users from
making mistakes based on that assumption.
</p>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="iterator.generic.adaptor.adaptor_reference"></a><a class="link" href="adaptor.html#iterator.generic.adaptor.adaptor_reference" title="Reference">Reference</a>
</h4></div></div></div>
<h3>
<a name="iterator.generic.adaptor.adaptor_reference.h0"></a>
<span class="phrase"><a name="iterator.generic.adaptor.adaptor_reference.synopsis"></a></span><a class="link" href="adaptor.html#iterator.generic.adaptor.adaptor_reference.synopsis">Synopsis</a>
</h3>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span>
<span class="keyword">class</span> <span class="identifier">Derived</span>
<span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Base</span>
<span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Value</span> <span class="special">=</span> <span class="identifier">use_default</span>
<span class="special">,</span> <span class="keyword">class</span> <span class="identifier">CategoryOrTraversal</span> <span class="special">=</span> <span class="identifier">use_default</span>
<span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Reference</span> <span class="special">=</span> <span class="identifier">use_default</span>
<span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Difference</span> <span class="special">=</span> <span class="identifier">use_default</span>
<span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">iterator_adaptor</span>
<span class="special">:</span> <span class="keyword">public</span> <span class="identifier">iterator_facade</span><span class="special">&lt;</span><span class="identifier">Derived</span><span class="special">,</span> <span class="special">*</span><span class="identifier">V</span><span class="char">'*, *C'</span><span class="special">*,</span> <span class="special">*</span><span class="identifier">R</span><span class="char">'*, *D'</span><span class="special">*&gt;</span> <span class="comment">// see details</span>
<span class="special">{</span>
<span class="keyword">friend</span> <span class="keyword">class</span> <span class="identifier">iterator_core_access</span><span class="special">;</span>
<span class="keyword">public</span><span class="special">:</span>
<span class="identifier">iterator_adaptor</span><span class="special">();</span>
<span class="keyword">explicit</span> <span class="identifier">iterator_adaptor</span><span class="special">(</span><span class="identifier">Base</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">iter</span><span class="special">);</span>
<span class="keyword">typedef</span> <span class="identifier">Base</span> <span class="identifier">base_type</span><span class="special">;</span>
<span class="identifier">Base</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">base</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="keyword">protected</span><span class="special">:</span>
<span class="keyword">typedef</span> <span class="identifier">iterator_adaptor</span> <span class="identifier">iterator_adaptor</span><span class="special">\</span><span class="identifier">_</span><span class="special">;</span>
<span class="identifier">Base</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">base_reference</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="identifier">Base</span><span class="special">&amp;</span> <span class="identifier">base_reference</span><span class="special">();</span>
<span class="keyword">private</span><span class="special">:</span> <span class="comment">// Core iterator interface for iterator_facade. </span>
<span class="keyword">typename</span> <span class="identifier">iterator_adaptor</span><span class="special">::</span><span class="identifier">reference</span> <span class="identifier">dereference</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="keyword">template</span> <span class="special">&lt;</span>
<span class="keyword">class</span> <span class="identifier">OtherDerived</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">OtherIterator</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">C</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">D</span>
<span class="special">&gt;</span>
<span class="keyword">bool</span> <span class="identifier">equal</span><span class="special">(</span><span class="identifier">iterator_adaptor</span><span class="special">&lt;</span><span class="identifier">OtherDerived</span><span class="special">,</span> <span class="identifier">OtherIterator</span><span class="special">,</span> <span class="identifier">V</span><span class="special">,</span> <span class="identifier">C</span><span class="special">,</span> <span class="identifier">R</span><span class="special">,</span> <span class="identifier">D</span><span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">x</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
<span class="keyword">void</span> <span class="identifier">advance</span><span class="special">(</span><span class="keyword">typename</span> <span class="identifier">iterator_adaptor</span><span class="special">::</span><span class="identifier">difference_type</span> <span class="identifier">n</span><span class="special">);</span>
<span class="keyword">void</span> <span class="identifier">increment</span><span class="special">();</span>
<span class="keyword">void</span> <span class="identifier">decrement</span><span class="special">();</span>
<span class="keyword">template</span> <span class="special">&lt;</span>
<span class="keyword">class</span> <span class="identifier">OtherDerived</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">OtherIterator</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">C</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">D</span>
<span class="special">&gt;</span>
<span class="keyword">typename</span> <span class="identifier">iterator_adaptor</span><span class="special">::</span><span class="identifier">difference_type</span> <span class="identifier">distance_to</span><span class="special">(</span>
<span class="identifier">iterator_adaptor</span><span class="special">&lt;</span><span class="identifier">OtherDerived</span><span class="special">,</span> <span class="identifier">OtherIterator</span><span class="special">,</span> <span class="identifier">V</span><span class="special">,</span> <span class="identifier">C</span><span class="special">,</span> <span class="identifier">R</span><span class="special">,</span> <span class="identifier">D</span><span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">y</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
<span class="keyword">private</span><span class="special">:</span>
<span class="identifier">Base</span> <span class="identifier">m_iterator</span><span class="special">;</span> <span class="comment">// exposition only</span>
<span class="special">};</span>
</pre>
<p>
__ base_parameters_
</p>
<p>
.. _requirements:
</p>
<h3>
<a name="iterator.generic.adaptor.adaptor_reference.h1"></a>
<span class="phrase"><a name="iterator.generic.adaptor.adaptor_reference.requirements"></a></span><a class="link" href="adaptor.html#iterator.generic.adaptor.adaptor_reference.requirements">Requirements</a>
</h3>
<p>
<code class="computeroutput"><span class="keyword">static_cast</span><span class="special">&lt;</span><span class="identifier">Derived</span><span class="special">*&gt;(</span><span class="identifier">iterator_adaptor</span><span class="special">*)</span></code>
shall be well-formed. The <code class="computeroutput"><span class="identifier">Base</span></code>
argument shall be Assignable and Copy Constructible.
</p>
<p>
.. _base_parameters:
</p>
<h3>
<a name="iterator.generic.adaptor.adaptor_reference.h2"></a>
<span class="phrase"><a name="iterator.generic.adaptor.adaptor_reference.base_class_parameters"></a></span><a class="link" href="adaptor.html#iterator.generic.adaptor.adaptor_reference.base_class_parameters">Base
Class Parameters</a>
</h3>
<p>
The <span class="bold"><strong>V'</strong></span>, <span class="bold"><strong>C'</strong></span>,
<span class="bold"><strong>R'</strong></span>, and <span class="bold"><strong>D'</strong></span>
parameters of the <code class="computeroutput"><span class="identifier">iterator_facade</span></code>
used as a base class in the summary of <code class="computeroutput"><span class="identifier">iterator_adaptor</span></code>
above are defined as follows:
</p>
<pre class="programlisting"> <span class="bold"><strong>V'</strong></span> = if (Value is use_default)
return iterator_traits&lt;Base&gt;::value_type
else
return Value
<span class="bold"><strong>C'</strong></span> = if (CategoryOrTraversal is use_default)
return iterator_traversal&lt;Base&gt;::type
else
return CategoryOrTraversal
<span class="bold"><strong>R'</strong></span> = if (Reference is use_default)
if (Value is use_default)
return iterator_traits&lt;Base&gt;::reference
else
return Value&amp;
else
return Reference
<span class="bold"><strong>D'</strong></span> = if (Difference is use_default)
return iterator_traits&lt;Base&gt;::difference_type
else
return Difference
</pre>
<h3>
<a name="iterator.generic.adaptor.adaptor_reference.h3"></a>
<span class="phrase"><a name="iterator.generic.adaptor.adaptor_reference.operations"></a></span><a class="link" href="adaptor.html#iterator.generic.adaptor.adaptor_reference.operations">Operations</a>
</h3>
<h4>
<a name="iterator.generic.adaptor.adaptor_reference.h4"></a>
<span class="phrase"><a name="iterator.generic.adaptor.adaptor_reference.public"></a></span><a class="link" href="adaptor.html#iterator.generic.adaptor.adaptor_reference.public">Public</a>
</h4>
<pre class="programlisting"><span class="identifier">iterator_adaptor</span><span class="special">();</span>
</pre>
<p>
<span class="bold"><strong>Requires:</strong></span> The <code class="computeroutput"><span class="identifier">Base</span></code>
type must be Default Constructible.<br> <span class="bold"><strong>Returns:</strong></span>
An instance of <code class="computeroutput"><span class="identifier">iterator_adaptor</span></code>
with <code class="computeroutput"><span class="identifier">m_iterator</span></code> default
constructed.
</p>
<pre class="programlisting"><span class="keyword">explicit</span> <span class="identifier">iterator_adaptor</span><span class="special">(</span><span class="identifier">Base</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">iter</span><span class="special">);</span>
</pre>
<p>
<span class="bold"><strong>Returns:</strong></span> An instance of <code class="computeroutput"><span class="identifier">iterator_adaptor</span></code> with <code class="computeroutput"><span class="identifier">m_iterator</span></code>
copy constructed from <code class="computeroutput"><span class="identifier">iter</span></code>.
</p>
<pre class="programlisting"><span class="identifier">Base</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">base</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
</pre>
<p>
<span class="bold"><strong>Returns:</strong></span> <code class="computeroutput"><span class="identifier">m_iterator</span></code>
</p>
<h4>
<a name="iterator.generic.adaptor.adaptor_reference.h5"></a>
<span class="phrase"><a name="iterator.generic.adaptor.adaptor_reference.protected"></a></span><a class="link" href="adaptor.html#iterator.generic.adaptor.adaptor_reference.protected">Protected</a>
</h4>
<pre class="programlisting"><span class="identifier">Base</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">base_reference</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
</pre>
<p>
<span class="bold"><strong>Returns:</strong></span> A const reference to <code class="computeroutput"><span class="identifier">m_iterator</span></code>.
</p>
<pre class="programlisting"><span class="identifier">Base</span><span class="special">&amp;</span> <span class="identifier">base_reference</span><span class="special">();</span>
</pre>
<p>
<span class="bold"><strong>Returns:</strong></span> A non-const reference to <code class="computeroutput"><span class="identifier">m_iterator</span></code>.
</p>
<h4>
<a name="iterator.generic.adaptor.adaptor_reference.h6"></a>
<span class="phrase"><a name="iterator.generic.adaptor.adaptor_reference.private"></a></span><a class="link" href="adaptor.html#iterator.generic.adaptor.adaptor_reference.private">Private</a>
</h4>
<pre class="programlisting"><span class="keyword">typename</span> <span class="identifier">iterator_adaptor</span><span class="special">::</span><span class="identifier">reference</span> <span class="identifier">dereference</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
</pre>
<p>
<span class="bold"><strong>Returns:</strong></span> <code class="computeroutput"><span class="special">*</span><span class="identifier">m_iterator</span></code>
</p>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span>
<span class="keyword">class</span> <span class="identifier">OtherDerived</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">OtherIterator</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">C</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">D</span>
<span class="special">&gt;</span>
<span class="keyword">bool</span> <span class="identifier">equal</span><span class="special">(</span><span class="identifier">iterator_adaptor</span><span class="special">&lt;</span><span class="identifier">OtherDerived</span><span class="special">,</span> <span class="identifier">OtherIterator</span><span class="special">,</span> <span class="identifier">V</span><span class="special">,</span> <span class="identifier">C</span><span class="special">,</span> <span class="identifier">R</span><span class="special">,</span> <span class="identifier">D</span><span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">x</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
</pre>
<p>
<span class="bold"><strong>Returns:</strong></span> <code class="computeroutput"><span class="identifier">m_iterator</span>
<span class="special">==</span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">base</span><span class="special">()</span></code>
</p>
<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">advance</span><span class="special">(</span><span class="keyword">typename</span> <span class="identifier">iterator_adaptor</span><span class="special">::</span><span class="identifier">difference_type</span> <span class="identifier">n</span><span class="special">);</span>
</pre>
<p>
<span class="bold"><strong>Effects:</strong></span> <code class="computeroutput"><span class="identifier">m_iterator</span>
<span class="special">+=</span> <span class="identifier">n</span><span class="special">;</span></code>
</p>
<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">increment</span><span class="special">();</span>
</pre>
<p>
<span class="bold"><strong>Effects:</strong></span> <code class="computeroutput"><span class="special">++</span><span class="identifier">m_iterator</span><span class="special">;</span></code>
</p>
<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">decrement</span><span class="special">();</span>
</pre>
<p>
<span class="bold"><strong>Effects:</strong></span> <code class="computeroutput"><span class="special">--</span><span class="identifier">m_iterator</span><span class="special">;</span></code>
</p>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span>
<span class="keyword">class</span> <span class="identifier">OtherDerived</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">OtherIterator</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">C</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">D</span>
<span class="special">&gt;</span>
<span class="keyword">typename</span> <span class="identifier">iterator_adaptor</span><span class="special">::</span><span class="identifier">difference_type</span> <span class="identifier">distance_to</span><span class="special">(</span>
<span class="identifier">iterator_adaptor</span><span class="special">&lt;</span><span class="identifier">OtherDerived</span><span class="special">,</span> <span class="identifier">OtherIterator</span><span class="special">,</span> <span class="identifier">V</span><span class="special">,</span> <span class="identifier">C</span><span class="special">,</span> <span class="identifier">R</span><span class="special">,</span> <span class="identifier">D</span><span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">y</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
</pre>
<p>
<span class="bold"><strong>Returns:</strong></span> <code class="computeroutput"><span class="identifier">y</span><span class="special">.</span><span class="identifier">base</span><span class="special">()</span> <span class="special">-</span> <span class="identifier">m_iterator</span></code>
</p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003, 2005 David Abrahams Jeremy Siek Thomas
Witt<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at &lt;ulink url="http://www.boost.org/LICENSE_1_0.txt"&gt;
http://www.boost.org/LICENSE_1_0.txt &lt;/ulink&gt;)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../generic.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../generic.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="adaptor/adaptor_tutorial.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
libs/iterator/doc/html/iterator/generic/adaptor/adaptor_tutorial.html
+198
View File
@@ -0,0 +1,198 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Tutorial</title>
<link rel="stylesheet" href="../../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="up" href="../adaptor.html" title="Iterator Adaptor">
<link rel="prev" href="../adaptor.html" title="Iterator Adaptor">
<link rel="next" href="../../specialized.html" title="Specialized Adaptors">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../adaptor.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../adaptor.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../../specialized.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="iterator.generic.adaptor.adaptor_tutorial"></a><a class="link" href="adaptor_tutorial.html" title="Tutorial">Tutorial</a>
</h4></div></div></div>
<p>
In this section we'll further refine the <code class="computeroutput"><span class="identifier">node_iter</span></code>
class template we developed in the |fac_tut|_. If you haven't already read
that material, you should go back now and check it out because we're going
to pick up right where it left off.
</p>
<p>
.. |fac_tut| replace:: <code class="computeroutput"><span class="identifier">iterator_facade</span></code>
tutorial .. _fac_tut: iterator_facade.html#tutorial-example
</p>
<div class="sidebar">
<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div>
<p>
<span class="bold"><strong><code class="computeroutput"><span class="identifier">node_base</span><span class="special">*</span></code> really <span class="bold"><strong>is</strong></span>
an iterator</strong></span><br> <br> It's not really a very interesting
iterator, since <code class="computeroutput"><span class="identifier">node_base</span></code>
is an abstract class: a pointer to a <code class="computeroutput"><span class="identifier">node_base</span></code>
just points at some base subobject of an instance of some other class,
and incrementing a <code class="computeroutput"><span class="identifier">node_base</span><span class="special">*</span></code> moves it past this base subobject to who-knows-where?
The most we can do with that incremented position is to compare another
<code class="computeroutput"><span class="identifier">node_base</span><span class="special">*</span></code>
to it. In other words, the original iterator traverses a one-element array.
</p>
</div>
<p>
You probably didn't think of it this way, but the <code class="computeroutput"><span class="identifier">node_base</span><span class="special">*</span></code> object that underlies <code class="computeroutput"><span class="identifier">node_iterator</span></code>
is itself an iterator, just like all other pointers. If we examine that
pointer closely from an iterator perspective, we can see that it has much
in common with the <code class="computeroutput"><span class="identifier">node_iterator</span></code>
we're building. First, they share most of the same associated types (<code class="computeroutput"><span class="identifier">value_type</span></code>, <code class="computeroutput"><span class="identifier">reference</span></code>,
<code class="computeroutput"><span class="identifier">pointer</span></code>, and <code class="computeroutput"><span class="identifier">difference_type</span></code>). Second, even some of
the core functionality is the same: <code class="computeroutput"><span class="keyword">operator</span><span class="special">*</span></code> and <code class="computeroutput"><span class="keyword">operator</span><span class="special">==</span></code> on the <code class="computeroutput"><span class="identifier">node_iterator</span></code>
return the result of invoking the same operations on the underlying pointer,
via the <code class="computeroutput"><span class="identifier">node_iterator</span></code>'s
|dereference_and_equal|_). The only real behavioral difference between
<code class="computeroutput"><span class="identifier">node_base</span><span class="special">*</span></code>
and <code class="computeroutput"><span class="identifier">node_iterator</span></code> can be
observed when they are incremented: <code class="computeroutput"><span class="identifier">node_iterator</span></code>
follows the <code class="computeroutput"><span class="identifier">m_next</span></code> pointer,
while <code class="computeroutput"><span class="identifier">node_base</span><span class="special">*</span></code>
just applies an address offset.
</p>
<p>
.. |dereference_and_equal| replace:: <code class="computeroutput"><span class="identifier">dereference</span></code>
and <code class="computeroutput"><span class="identifier">equal</span></code> member functions
.. _dereference_and_equal: iterator_facade.html#implementing-the-core-operations
</p>
<p>
It turns out that the pattern of building an iterator on another iterator-like
type (the <code class="computeroutput"><span class="identifier">Base</span></code> <a name="base1"></a>_ type) while modifying just a few aspects of the underlying
type's behavior is an extremely common one, and it's the pattern addressed
by <code class="computeroutput"><span class="identifier">iterator_adaptor</span></code>. Using
<code class="computeroutput"><span class="identifier">iterator_adaptor</span></code> is very
much like using <code class="computeroutput"><span class="identifier">iterator_facade</span></code>,
but because iterator_adaptor tries to mimic as much of the <code class="computeroutput"><span class="identifier">Base</span></code> type's behavior as possible, we
neither have to supply a <code class="computeroutput"><span class="identifier">Value</span></code>
argument, nor implement any core behaviors other than <code class="computeroutput"><span class="identifier">increment</span></code>.
The implementation of <code class="computeroutput"><span class="identifier">node_iter</span></code>
is thus reduced to:
</p>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Value</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">node_iter</span>
<span class="special">:</span> <span class="keyword">public</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">iterator_adaptor</span><span class="special">&lt;</span>
<span class="identifier">node_iter</span><span class="special">&lt;</span><span class="identifier">Value</span><span class="special">&gt;</span> <span class="comment">// Derived</span>
<span class="special">,</span> <span class="identifier">Value</span><span class="special">*</span> <span class="comment">// Base</span>
<span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">use_default</span> <span class="comment">// Value</span>
<span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">forward_traversal_tag</span> <span class="comment">// CategoryOrTraversal</span>
<span class="special">&gt;</span>
<span class="special">{</span>
<span class="keyword">private</span><span class="special">:</span>
<span class="keyword">struct</span> <span class="identifier">enabler</span> <span class="special">{};</span> <span class="comment">// a private type avoids misuse</span>
<span class="keyword">public</span><span class="special">:</span>
<span class="identifier">node_iter</span><span class="special">()</span>
<span class="special">:</span> <span class="identifier">node_iter</span><span class="special">::</span><span class="identifier">iterator_adaptor_</span><span class="special">(</span><span class="number">0</span><span class="special">)</span> <span class="special">{}</span>
<span class="keyword">explicit</span> <span class="identifier">node_iter</span><span class="special">(</span><span class="identifier">Value</span><span class="special">*</span> <span class="identifier">p</span><span class="special">)</span>
<span class="special">:</span> <span class="identifier">node_iter</span><span class="special">::</span><span class="identifier">iterator_adaptor_</span><span class="special">(</span><span class="identifier">p</span><span class="special">)</span> <span class="special">{}</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">OtherValue</span><span class="special">&gt;</span>
<span class="identifier">node_iter</span><span class="special">(</span>
<span class="identifier">node_iter</span><span class="special">&lt;</span><span class="identifier">OtherValue</span><span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">other</span>
<span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">enable_if</span><span class="special">&lt;</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">is_convertible</span><span class="special">&lt;</span><span class="identifier">OtherValue</span><span class="special">*,</span><span class="identifier">Value</span><span class="special">*&gt;</span>
<span class="special">,</span> <span class="identifier">enabler</span>
<span class="special">&gt;::</span><span class="identifier">type</span> <span class="special">=</span> <span class="identifier">enabler</span><span class="special">()</span>
<span class="special">)</span>
<span class="special">:</span> <span class="identifier">node_iter</span><span class="special">::</span><span class="identifier">iterator_adaptor_</span><span class="special">(</span><span class="identifier">other</span><span class="special">.</span><span class="identifier">base</span><span class="special">())</span> <span class="special">{}</span>
<span class="keyword">private</span><span class="special">:</span>
<span class="keyword">friend</span> <span class="keyword">class</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">iterator_core_access</span><span class="special">;</span>
<span class="keyword">void</span> <span class="identifier">increment</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">this</span><span class="special">-&gt;</span><span class="identifier">base_reference</span><span class="special">()</span> <span class="special">=</span> <span class="keyword">this</span><span class="special">-&gt;</span><span class="identifier">base</span><span class="special">()-&gt;</span><span class="identifier">next</span><span class="special">();</span> <span class="special">}</span>
<span class="special">};</span>
</pre>
<p>
Note the use of <code class="computeroutput"><span class="identifier">node_iter</span><span class="special">::</span><span class="identifier">iterator_adaptor_</span></code>
here: because <code class="computeroutput"><span class="identifier">iterator_adaptor</span></code>
defines a nested <code class="computeroutput"><span class="identifier">iterator_adaptor_</span></code>
type that refers to itself, that gives us a convenient way to refer to
the complicated base class type of <code class="computeroutput"><span class="identifier">node_iter</span><span class="special">&lt;</span><span class="identifier">Value</span><span class="special">&gt;</span></code>. [Note: this technique is known not
to work with Borland C++ 5.6.4 and Metrowerks CodeWarrior versions prior
to 9.0]
</p>
<p>
You can see an example program that exercises this version of the node
iterators <a href="../../../../example/node_iterator3.cpp" target="_top"><code class="computeroutput"><span class="identifier">here</span></code></a>.
</p>
<p>
In the case of <code class="computeroutput"><span class="identifier">node_iter</span></code>,
it's not very compelling to pass <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">use_default</span></code>
as <code class="computeroutput"><span class="identifier">iterator_adaptor</span></code> 's
<code class="computeroutput"><span class="identifier">Value</span></code> argument; we could
have just passed <code class="computeroutput"><span class="identifier">node_iter</span></code>
's <code class="computeroutput"><span class="identifier">Value</span></code> along to <code class="computeroutput"><span class="identifier">iterator_adaptor</span></code>, and that'd even be
shorter! Most iterator class templates built with <code class="computeroutput"><span class="identifier">iterator_adaptor</span></code>
are parameterized on another iterator type, rather than on its <code class="computeroutput"><span class="identifier">value_type</span></code>. For example, <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">reverse_iterator</span></code> takes an iterator type
argument and reverses its direction of traversal, since the original iterator
and the reversed one have all the same associated types, <code class="computeroutput"><span class="identifier">iterator_adaptor</span></code> 's delegation of default
types to its <code class="computeroutput"><span class="identifier">Base</span></code> saves
the implementor of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">reverse_iterator</span></code>
from writing:
</p>
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::*</span><span class="identifier">some</span><span class="special">-</span><span class="identifier">associated</span><span class="special">-</span><span class="identifier">type</span><span class="special">*</span>
</pre>
<p>
at least four times.
</p>
<p>
We urge you to review the documentation and implementations of |reverse_iterator|_
and the other Boost <code class="computeroutput"><span class="identifier">specialized</span>
<span class="identifier">iterator</span> <span class="identifier">adaptors</span></code>__
to get an idea of the sorts of things you can do with <code class="computeroutput"><span class="identifier">iterator_adaptor</span></code>.
In particular, have a look at |transform_iterator|<span class="underline">,
which is perhaps the most straightforward adaptor, and also |counting_iterator|</span>,
which demonstrates that <code class="computeroutput"><span class="identifier">iterator_adaptor</span></code>'s
<code class="computeroutput"><span class="identifier">Base</span></code> type needn't be an
iterator.
</p>
<p>
.. |reverse_iterator| replace:: <code class="computeroutput"><span class="identifier">reverse_iterator</span></code>
.. _reverse_iterator: reverse_iterator.html
</p>
<p>
.. |counting_iterator| replace:: <code class="computeroutput"><span class="identifier">counting_iterator</span></code>
.. _counting_iterator: counting_iterator.html
</p>
<p>
.. |transform_iterator| replace:: <code class="computeroutput"><span class="identifier">transform_iterator</span></code>
.. _transform_iterator: transform_iterator.html
</p>
<p>
__ index.html#specialized-adaptors
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003, 2005 David Abrahams Jeremy Siek Thomas
Witt<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at &lt;ulink url="http://www.boost.org/LICENSE_1_0.txt"&gt;
http://www.boost.org/LICENSE_1_0.txt &lt;/ulink&gt;)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../adaptor.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../adaptor.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../../specialized.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
libs/iterator/doc/html/iterator/history.html
+74
View File
@@ -0,0 +1,74 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>History</title>
<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="up" href="../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="prev" href="upgrading.html" title="Upgrading from the old Boost Iterator Adaptor Library">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
<td align="center"><a href="../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="upgrading.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="iterator.history"></a><a class="link" href="history.html" title="History">History</a>
</h2></div></div></div>
<p>
In 2000 Dave Abrahams was writing an iterator for a container of pointers,
which would access the pointed-to elements when dereferenced. Naturally, being
a library writer, he decided to generalize the idea and the Boost Iterator
Adaptor library was born. Dave was inspired by some writings of Andrei Alexandrescu
and chose a policy based design (though he probably didn't capture Andrei's
idea very well - there was only one policy class for all the iterator's orthogonal
properties). Soon Jeremy Siek realized he would need the library and they worked
together to produce a "Boostified" version, which was reviewed and
accepted into the library. They wrote a paper and made several important revisions
of the code.
</p>
<p>
Eventually, several shortcomings of the older library began to make the need
for a rewrite apparent. Dave and Jeremy started working at the Santa Cruz C++
committee meeting in 2002, and had quickly generated a working prototype. At
the urging of Mat Marcus, they decided to use the GenVoca/CRTP pattern approach,
and moved the policies into the iterator class itself. Thomas Witt expressed
interest and became the voice of strict compile-time checking for the project,
adding uses of the SFINAE technique to eliminate false converting constructors
and operators from the overload set. He also recognized the need for a separate
<code class="computeroutput"><span class="identifier">iterator_facade</span></code>, and factored
it out of <code class="computeroutput"><span class="identifier">iterator_adaptor</span></code>.
Finally, after a near-complete rewrite of the prototype, they came up with
the library you see today.
</p>
<div class="blockquote"><blockquote class="blockquote"><p>
[Coplien, 1995] Coplien, J., Curiously Recurring Template Patterns, C++ Report,
February 1995, pp. 24-27.
</p></blockquote></div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003, 2005 David Abrahams Jeremy Siek Thomas
Witt<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at &lt;ulink url="http://www.boost.org/LICENSE_1_0.txt"&gt;
http://www.boost.org/LICENSE_1_0.txt &lt;/ulink&gt;)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="upgrading.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a>
</div>
</body>
</html>
libs/iterator/doc/html/iterator/specialized.html
+287
View File
@@ -0,0 +1,287 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Specialized Adaptors</title>
<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="up" href="../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="prev" href="generic/adaptor/adaptor_tutorial.html" title="Tutorial">
<link rel="next" href="specialized/filter.html" title="Filter Iterator">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
<td align="center"><a href="../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="generic/adaptor/adaptor_tutorial.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="specialized/filter.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="iterator.specialized"></a><a class="link" href="specialized.html" title="Specialized Adaptors">Specialized Adaptors</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="specialized.html#iterator.specialized.counting">Counting Iterator</a></span></dt>
<dt><span class="section"><a href="specialized/filter.html">Filter Iterator</a></span></dt>
<dt><span class="section"><a href="specialized/function_output.html">Function Output
Iterator</a></span></dt>
<dt><span class="section"><a href="specialized/indirect.html">Indirect Iterator</a></span></dt>
<dt><span class="section"><a href="specialized/permutation.html">Permutation Iterator</a></span></dt>
<dt><span class="section"><a href="specialized/reverse.html">Reverse Iterator</a></span></dt>
<dt><span class="section"><a href="specialized/shared_container.html">Shared Container
Iterator</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="specialized/shared_container.html#iterator.specialized.shared_container.shared_container_type">The
Shared Container Iterator Type</a></span></dt>
<dt><span class="section"><a href="specialized/shared_container/shared_container_object_generator.html">The
Shared Container Iterator Object Generator</a></span></dt>
<dt><span class="section"><a href="specialized/shared_container/shared_container_generator.html">The
Shared Container Iterator Range Generator</a></span></dt>
</dl></dd>
<dt><span class="section"><a href="specialized/transform.html">Transform Iterator</a></span></dt>
<dt><span class="section"><a href="specialized/zip.html">Zip Iterator</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="specialized/zip.html#iterator.specialized.zip.zip_example">Example</a></span></dt>
<dt><span class="section"><a href="specialized/zip/zip_reference.html">Reference</a></span></dt>
</dl></dd>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="iterator.specialized.counting"></a><a class="link" href="specialized.html#iterator.specialized.counting" title="Counting Iterator">Counting Iterator</a>
</h3></div></div></div>
<p>
A <code class="computeroutput"><span class="identifier">counting_iterator</span></code> adapts
an object by adding an <code class="computeroutput"><span class="keyword">operator</span><span class="special">*</span></code> that returns the current value of the object.
All other iterator operations are forwarded to the adapted object.
</p>
<h3>
<a name="iterator.specialized.counting.h0"></a>
<span class="phrase"><a name="iterator.specialized.counting.example"></a></span><a class="link" href="specialized.html#iterator.specialized.counting.example">Example</a>
</h3>
<p>
This example fills an array with numbers and a second array with pointers
into the first array, using <code class="computeroutput"><span class="identifier">counting_iterator</span></code>
for both tasks. Finally <code class="computeroutput"><span class="identifier">indirect_iterator</span></code>
is used to print out the numbers into the first array via indirection through
the second array.
</p>
<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">N</span> <span class="special">=</span> <span class="number">7</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">numbers</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;::</span><span class="identifier">iterator</span> <span class="identifier">n_iter</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">copy</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">counting_iterator</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="number">0</span><span class="special">),</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">counting_iterator</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="identifier">N</span><span class="special">),</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">back_inserter</span><span class="special">(</span><span class="identifier">numbers</span><span class="special">));</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;::</span><span class="identifier">iterator</span><span class="special">&gt;</span> <span class="identifier">pointers</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">copy</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_counting_iterator</span><span class="special">(</span><span class="identifier">numbers</span><span class="special">.</span><span class="identifier">begin</span><span class="special">()),</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_counting_iterator</span><span class="special">(</span><span class="identifier">numbers</span><span class="special">.</span><span class="identifier">end</span><span class="special">()),</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">back_inserter</span><span class="special">(</span><span class="identifier">pointers</span><span class="special">));</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"indirectly printing out the numbers from 0 to "</span>
<span class="special">&lt;&lt;</span> <span class="identifier">N</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">copy</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_indirect_iterator</span><span class="special">(</span><span class="identifier">pointers</span><span class="special">.</span><span class="identifier">begin</span><span class="special">()),</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_indirect_iterator</span><span class="special">(</span><span class="identifier">pointers</span><span class="special">.</span><span class="identifier">end</span><span class="special">()),</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream_iterator</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">,</span> <span class="string">" "</span><span class="special">));</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
</pre>
<p>
The output is:
</p>
<pre class="programlisting"><span class="identifier">indirectly</span> <span class="identifier">printing</span> <span class="identifier">out</span> <span class="identifier">the</span> <span class="identifier">numbers</span> <span class="identifier">from</span> <span class="number">0</span> <span class="identifier">to</span> <span class="number">7</span>
<span class="number">0</span> <span class="number">1</span> <span class="number">2</span> <span class="number">3</span> <span class="number">4</span> <span class="number">5</span> <span class="number">6</span>
</pre>
<p>
The source code for this example can be found <a href="../../example/counting_iterator_example.cpp" target="_top">here</a>.
</p>
<h3>
<a name="iterator.specialized.counting.h1"></a>
<span class="phrase"><a name="iterator.specialized.counting.reference"></a></span><a class="link" href="specialized.html#iterator.specialized.counting.reference">Reference</a>
</h3>
<h4>
<a name="iterator.specialized.counting.h2"></a>
<span class="phrase"><a name="iterator.specialized.counting.synopsis"></a></span><a class="link" href="specialized.html#iterator.specialized.counting.synopsis">Synopsis</a>
</h4>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span>
<span class="keyword">class</span> <span class="identifier">Incrementable</span>
<span class="special">,</span> <span class="keyword">class</span> <span class="identifier">CategoryOrTraversal</span> <span class="special">=</span> <span class="identifier">use_default</span>
<span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Difference</span> <span class="special">=</span> <span class="identifier">use_default</span>
<span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">counting_iterator</span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>
<span class="keyword">typedef</span> <span class="identifier">Incrementable</span> <span class="identifier">value_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="keyword">const</span> <span class="identifier">Incrementable</span><span class="special">&amp;</span> <span class="identifier">reference</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="keyword">const</span> <span class="identifier">Incrementable</span><span class="special">*</span> <span class="identifier">pointer</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="comment">/* see below */</span> <span class="identifier">difference_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="comment">/* see below */</span> <span class="identifier">iterator_category</span><span class="special">;</span>
<span class="identifier">counting_iterator</span><span class="special">();</span>
<span class="identifier">counting_iterator</span><span class="special">(</span><span class="identifier">counting_iterator</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">rhs</span><span class="special">);</span>
<span class="keyword">explicit</span> <span class="identifier">counting_iterator</span><span class="special">(</span><span class="identifier">Incrementable</span> <span class="identifier">x</span><span class="special">);</span>
<span class="identifier">Incrementable</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">base</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="identifier">reference</span> <span class="keyword">operator</span><span class="special">*()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="identifier">counting_iterator</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">++();</span>
<span class="identifier">counting_iterator</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">--();</span>
<span class="keyword">private</span><span class="special">:</span>
<span class="identifier">Incrementable</span> <span class="identifier">m_inc</span><span class="special">;</span> <span class="comment">// exposition</span>
<span class="special">};</span>
</pre>
<p>
If the <code class="computeroutput"><span class="identifier">Difference</span></code> argument
is <code class="computeroutput"><span class="identifier">use_default</span></code> then <code class="computeroutput"><span class="identifier">difference_type</span></code> is an unspecified signed
integral type. Otherwise <code class="computeroutput"><span class="identifier">difference_type</span></code>
is <code class="computeroutput"><span class="identifier">Difference</span></code>.
</p>
<p>
<code class="computeroutput"><span class="identifier">iterator_category</span></code> is determined
according to the following algorithm:
</p>
<pre class="programlisting"><span class="keyword">if</span> <span class="special">(</span><span class="identifier">CategoryOrTraversal</span> <span class="identifier">is</span> <span class="keyword">not</span> <span class="identifier">use_default</span><span class="special">)</span>
<span class="keyword">return</span> <span class="identifier">CategoryOrTraversal</span>
<span class="keyword">else</span> <span class="keyword">if</span> <span class="special">(</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">Incrementable</span><span class="special">&gt;::</span><span class="identifier">is_specialized</span><span class="special">)</span>
<span class="keyword">return</span> <span class="special">|</span><span class="identifier">iterator</span><span class="special">-</span><span class="identifier">category</span><span class="special">|</span><span class="identifier">_</span><span class="special">\</span> <span class="special">(</span>
<span class="identifier">random_access_traversal_tag</span><span class="special">,</span> <span class="identifier">Incrementable</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Incrementable</span><span class="special">&amp;)</span>
<span class="keyword">else</span>
<span class="keyword">return</span> <span class="special">|</span><span class="identifier">iterator</span><span class="special">-</span><span class="identifier">category</span><span class="special">|</span><span class="identifier">_</span><span class="special">\</span> <span class="special">(</span>
<span class="identifier">iterator_traversal</span><span class="special">&lt;</span><span class="identifier">Incrementable</span><span class="special">&gt;::</span><span class="identifier">type</span><span class="special">,</span>
<span class="identifier">Incrementable</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Incrementable</span><span class="special">&amp;)</span>
</pre>
<div class="sidebar">
<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div>
<p>
<span class="bold"><strong>Note:</strong></span> implementers are encouraged to provide
an implementation of <code class="computeroutput"><span class="keyword">operator</span><span class="special">-</span></code> and a <code class="computeroutput"><span class="identifier">difference_type</span></code>
that avoids overflows in the cases where <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">Incrementable</span><span class="special">&gt;::</span><span class="identifier">is_specialized</span></code>
is true.
</p>
</div>
<h4>
<a name="iterator.specialized.counting.h3"></a>
<span class="phrase"><a name="iterator.specialized.counting.requirements"></a></span><a class="link" href="specialized.html#iterator.specialized.counting.requirements">Requirements</a>
</h4>
<p>
The <code class="computeroutput"><span class="identifier">Incrementable</span></code> argument
shall be Copy Constructible and Assignable.
</p>
<p>
If <code class="computeroutput"><span class="identifier">iterator_category</span></code> is convertible
to <code class="computeroutput"><span class="identifier">forward_iterator_tag</span></code> or
<code class="computeroutput"><span class="identifier">forward_traversal_tag</span></code>, the
following must be well-formed:
</p>
<pre class="programlisting"><span class="identifier">Incrementable</span> <span class="identifier">i</span><span class="special">,</span> <span class="identifier">j</span><span class="special">;</span>
<span class="special">++</span><span class="identifier">i</span><span class="special">;</span> <span class="comment">// pre-increment</span>
<span class="identifier">i</span> <span class="special">==</span> <span class="identifier">j</span><span class="special">;</span> <span class="comment">// operator equal</span>
</pre>
<p>
If <code class="computeroutput"><span class="identifier">iterator_category</span></code> is convertible
to <code class="computeroutput"><span class="identifier">bidirectional_iterator_tag</span></code>
or <code class="computeroutput"><span class="identifier">bidirectional_traversal_tag</span></code>,
the following expression must also be well-formed:
</p>
<pre class="programlisting"><span class="special">--</span><span class="identifier">i</span>
</pre>
<p>
If <code class="computeroutput"><span class="identifier">iterator_category</span></code> is convertible
to <code class="computeroutput"><span class="identifier">random_access_iterator_tag</span></code>
or <code class="computeroutput"><span class="identifier">random_access_traversal_tag</span></code>,
the following must must also be valid:
</p>
<pre class="programlisting"><span class="identifier">counting_iterator</span><span class="special">::</span><span class="identifier">difference_type</span> <span class="identifier">n</span><span class="special">;</span>
<span class="identifier">i</span> <span class="special">+=</span> <span class="identifier">n</span><span class="special">;</span>
<span class="identifier">n</span> <span class="special">=</span> <span class="identifier">i</span> <span class="special">-</span> <span class="identifier">j</span><span class="special">;</span>
<span class="identifier">i</span> <span class="special">&lt;</span> <span class="identifier">j</span><span class="special">;</span>
</pre>
<h4>
<a name="iterator.specialized.counting.h4"></a>
<span class="phrase"><a name="iterator.specialized.counting.concepts"></a></span><a class="link" href="specialized.html#iterator.specialized.counting.concepts">Concepts</a>
</h4>
<p>
Specializations of <code class="computeroutput"><span class="identifier">counting_iterator</span></code>
model Readable Lvalue Iterator. In addition, they model the concepts corresponding
to the iterator tags to which their <code class="computeroutput"><span class="identifier">iterator_category</span></code>
is convertible. Also, if <code class="computeroutput"><span class="identifier">CategoryOrTraversal</span></code>
is not <code class="computeroutput"><span class="identifier">use_default</span></code> then
<code class="computeroutput"><span class="identifier">counting_iterator</span></code> models
the concept corresponding to the iterator tag <code class="computeroutput"><span class="identifier">CategoryOrTraversal</span></code>.
Otherwise, if <code class="computeroutput"><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">Incrementable</span><span class="special">&gt;::</span><span class="identifier">is_specialized</span></code>,
then <code class="computeroutput"><span class="identifier">counting_iterator</span></code> models
Random Access Traversal Iterator. Otherwise, <code class="computeroutput"><span class="identifier">counting_iterator</span></code>
models the same iterator traversal concepts modeled by <code class="computeroutput"><span class="identifier">Incrementable</span></code>.
</p>
<p>
<code class="computeroutput"><span class="identifier">counting_iterator</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">,</span><span class="identifier">C1</span><span class="special">,</span><span class="identifier">D1</span><span class="special">&gt;</span></code>
is interoperable with <code class="computeroutput"><span class="identifier">counting_iterator</span><span class="special">&lt;</span><span class="identifier">Y</span><span class="special">,</span><span class="identifier">C2</span><span class="special">,</span><span class="identifier">D2</span><span class="special">&gt;</span></code> if and only if <code class="computeroutput"><span class="identifier">X</span></code>
is interoperable with <code class="computeroutput"><span class="identifier">Y</span></code>.
</p>
<h4>
<a name="iterator.specialized.counting.h5"></a>
<span class="phrase"><a name="iterator.specialized.counting.operations"></a></span><a class="link" href="specialized.html#iterator.specialized.counting.operations">Operations</a>
</h4>
<p>
In addition to the operations required by the concepts modeled by <code class="computeroutput"><span class="identifier">counting_iterator</span></code>, <code class="computeroutput"><span class="identifier">counting_iterator</span></code>
provides the following operations.
</p>
<pre class="programlisting"><span class="identifier">counting_iterator</span><span class="special">();</span>
</pre>
<p>
<span class="bold"><strong>Requires: </strong></span> <code class="computeroutput"><span class="identifier">Incrementable</span></code>
is Default Constructible.<br> <span class="bold"><strong>Effects: </strong></span>
Default construct the member <code class="computeroutput"><span class="identifier">m_inc</span></code>.
</p>
<pre class="programlisting"><span class="identifier">counting_iterator</span><span class="special">(</span><span class="identifier">counting_iterator</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">rhs</span><span class="special">);</span>
</pre>
<p>
<span class="bold"><strong>Effects: </strong></span> Construct member <code class="computeroutput"><span class="identifier">m_inc</span></code> from <code class="computeroutput"><span class="identifier">rhs</span><span class="special">.</span><span class="identifier">m_inc</span></code>.
</p>
<pre class="programlisting"><span class="keyword">explicit</span> <span class="identifier">counting_iterator</span><span class="special">(</span><span class="identifier">Incrementable</span> <span class="identifier">x</span><span class="special">);</span>
</pre>
<p>
<span class="bold"><strong>Effects: </strong></span> Construct member <code class="computeroutput"><span class="identifier">m_inc</span></code> from <code class="computeroutput"><span class="identifier">x</span></code>.
</p>
<pre class="programlisting"><span class="identifier">reference</span> <span class="keyword">operator</span><span class="special">*()</span> <span class="keyword">const</span><span class="special">;</span>
</pre>
<p>
<span class="bold"><strong>Returns: </strong></span> <code class="computeroutput"><span class="identifier">m_inc</span></code>
</p>
<pre class="programlisting"><span class="identifier">counting_iterator</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">++();</span>
</pre>
<p>
<span class="bold"><strong>Effects: </strong></span> <code class="computeroutput"><span class="special">++</span><span class="identifier">m_inc</span></code><br> <span class="bold"><strong>Returns:
</strong></span> <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>
</p>
<pre class="programlisting"><span class="identifier">counting_iterator</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">--();</span>
</pre>
<p>
<span class="bold"><strong>Effects: </strong></span> <code class="computeroutput"><span class="special">--</span><span class="identifier">m_inc</span></code><br> <span class="bold"><strong>Returns:
</strong></span> <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>
</p>
<pre class="programlisting"><span class="identifier">Incrementable</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">base</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
</pre>
<p>
<span class="bold"><strong>Returns: </strong></span> <code class="computeroutput"><span class="identifier">m_inc</span></code>
</p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003, 2005 David Abrahams Jeremy Siek Thomas
Witt<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at &lt;ulink url="http://www.boost.org/LICENSE_1_0.txt"&gt;
http://www.boost.org/LICENSE_1_0.txt &lt;/ulink&gt;)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="generic/adaptor/adaptor_tutorial.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="specialized/filter.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
libs/iterator/doc/html/iterator/specialized/filter.html
+474
View File
@@ -0,0 +1,474 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Filter Iterator</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="up" href="../specialized.html" title="Specialized Adaptors">
<link rel="prev" href="../specialized.html" title="Specialized Adaptors">
<link rel="next" href="function_output.html" title="Function Output Iterator">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../specialized.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../specialized.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="function_output.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="iterator.specialized.filter"></a><a class="link" href="filter.html" title="Filter Iterator">Filter Iterator</a>
</h3></div></div></div>
<p>
The filter iterator adaptor creates a view of an iterator range in which
some elements of the range are skipped. A predicate function object controls
which elements are skipped. When the predicate is applied to an element,
if it returns <code class="computeroutput"><span class="keyword">true</span></code> then the
element is retained and if it returns <code class="computeroutput"><span class="keyword">false</span></code>
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. A filter iterator is therefore constructed with
pair of iterators indicating the range of elements in the unfiltered sequence
to be traversed.
</p>
<h3>
<a name="iterator.specialized.filter.h0"></a>
<span class="phrase"><a name="iterator.specialized.filter.example"></a></span><a class="link" href="filter.html#iterator.specialized.filter.example">Example</a>
</h3>
<p>
This example uses <code class="computeroutput"><span class="identifier">filter_iterator</span></code>
and then <code class="computeroutput"><span class="identifier">make_filter_iterator</span></code>
to output only the positive integers from an array of integers. Then <code class="computeroutput"><span class="identifier">make_filter_iterator</span></code> is is used to output
the integers greater than <code class="computeroutput"><span class="special">-</span><span class="number">2</span></code>.
</p>
<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">is_positive_number</span> <span class="special">{</span>
<span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">()(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="number">0</span> <span class="special">&lt;</span> <span class="identifier">x</span><span class="special">;</span> <span class="special">}</span>
<span class="special">};</span>
<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
<span class="special">{</span>
<span class="keyword">int</span> <span class="identifier">numbers_</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span> <span class="number">0</span><span class="special">,</span> <span class="special">-</span><span class="number">1</span><span class="special">,</span> <span class="number">4</span><span class="special">,</span> <span class="special">-</span><span class="number">3</span><span class="special">,</span> <span class="number">5</span><span class="special">,</span> <span class="number">8</span><span class="special">,</span> <span class="special">-</span><span class="number">2</span> <span class="special">};</span>
<span class="keyword">const</span> <span class="keyword">int</span> <span class="identifier">N</span> <span class="special">=</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">numbers_</span><span class="special">)/</span><span class="keyword">sizeof</span><span class="special">(</span><span class="keyword">int</span><span class="special">);</span>
<span class="keyword">typedef</span> <span class="keyword">int</span><span class="special">*</span> <span class="identifier">base_iterator</span><span class="special">;</span>
<span class="identifier">base_iterator</span> <span class="identifier">numbers</span><span class="special">(</span><span class="identifier">numbers_</span><span class="special">);</span>
<span class="comment">// Example using filter_iterator</span>
<span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">filter_iterator</span><span class="special">&lt;</span><span class="identifier">is_positive_number</span><span class="special">,</span> <span class="identifier">base_iterator</span><span class="special">&gt;</span>
<span class="identifier">FilterIter</span><span class="special">;</span>
<span class="identifier">is_positive_number</span> <span class="identifier">predicate</span><span class="special">;</span>
<span class="identifier">FilterIter</span> <span class="identifier">filter_iter_first</span><span class="special">(</span><span class="identifier">predicate</span><span class="special">,</span> <span class="identifier">numbers</span><span class="special">,</span> <span class="identifier">numbers</span> <span class="special">+</span> <span class="identifier">N</span><span class="special">);</span>
<span class="identifier">FilterIter</span> <span class="identifier">filter_iter_last</span><span class="special">(</span><span class="identifier">predicate</span><span class="special">,</span> <span class="identifier">numbers</span> <span class="special">+</span> <span class="identifier">N</span><span class="special">,</span> <span class="identifier">numbers</span> <span class="special">+</span> <span class="identifier">N</span><span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">copy</span><span class="special">(</span><span class="identifier">filter_iter_first</span><span class="special">,</span> <span class="identifier">filter_iter_last</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream_iterator</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">,</span> <span class="string">" "</span><span class="special">));</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="comment">// Example using make_filter_iterator()</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">copy</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_filter_iterator</span><span class="special">&lt;</span><span class="identifier">is_positive_number</span><span class="special">&gt;(</span><span class="identifier">numbers</span><span class="special">,</span> <span class="identifier">numbers</span> <span class="special">+</span> <span class="identifier">N</span><span class="special">),</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_filter_iterator</span><span class="special">&lt;</span><span class="identifier">is_positive_number</span><span class="special">&gt;(</span><span class="identifier">numbers</span> <span class="special">+</span> <span class="identifier">N</span><span class="special">,</span> <span class="identifier">numbers</span> <span class="special">+</span> <span class="identifier">N</span><span class="special">),</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream_iterator</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">,</span> <span class="string">" "</span><span class="special">));</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="comment">// Another example using make_filter_iterator()</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">copy</span><span class="special">(</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_filter_iterator</span><span class="special">(</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">bind2nd</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">greater</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(),</span> <span class="special">-</span><span class="number">2</span><span class="special">)</span>
<span class="special">,</span> <span class="identifier">numbers</span><span class="special">,</span> <span class="identifier">numbers</span> <span class="special">+</span> <span class="identifier">N</span><span class="special">)</span>
<span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_filter_iterator</span><span class="special">(</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">bind2nd</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">greater</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(),</span> <span class="special">-</span><span class="number">2</span><span class="special">)</span>
<span class="special">,</span> <span class="identifier">numbers</span> <span class="special">+</span> <span class="identifier">N</span><span class="special">,</span> <span class="identifier">numbers</span> <span class="special">+</span> <span class="identifier">N</span><span class="special">)</span>
<span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream_iterator</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">,</span> <span class="string">" "</span><span class="special">)</span>
<span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">exit_success</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
The output is:
</p>
<pre class="programlisting"><span class="number">4</span> <span class="number">5</span> <span class="number">8</span>
<span class="number">4</span> <span class="number">5</span> <span class="number">8</span>
<span class="number">0</span> <span class="special">-</span><span class="number">1</span> <span class="number">4</span> <span class="number">5</span> <span class="number">8</span>
</pre>
<p>
The source code for this example can be found <a href="../../../example/filter_iterator_example.cpp" target="_top">here</a>.
</p>
<h3>
<a name="iterator.specialized.filter.h1"></a>
<span class="phrase"><a name="iterator.specialized.filter.reference"></a></span><a class="link" href="filter.html#iterator.specialized.filter.reference">Reference</a>
</h3>
<h4>
<a name="iterator.specialized.filter.h2"></a>
<span class="phrase"><a name="iterator.specialized.filter.synopsis"></a></span><a class="link" href="filter.html#iterator.specialized.filter.synopsis">Synopsis</a>
</h4>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Predicate</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">filter_iterator</span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>
<span class="keyword">typedef</span> <span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">value_type</span> <span class="identifier">value_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">reference</span> <span class="identifier">reference</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">pointer</span> <span class="identifier">pointer</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">difference_type</span> <span class="identifier">difference_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="comment">/* see below */</span> <span class="identifier">iterator_category</span><span class="special">;</span>
<span class="identifier">filter_iterator</span><span class="special">();</span>
<span class="identifier">filter_iterator</span><span class="special">(</span><span class="identifier">Predicate</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">Iterator</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">Iterator</span> <span class="identifier">end</span> <span class="special">=</span> <span class="identifier">Iterator</span><span class="special">());</span>
<span class="identifier">filter_iterator</span><span class="special">(</span><span class="identifier">Iterator</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">Iterator</span> <span class="identifier">end</span> <span class="special">=</span> <span class="identifier">Iterator</span><span class="special">());</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">OtherIterator</span><span class="special">&gt;</span>
<span class="identifier">filter_iterator</span><span class="special">(</span>
<span class="identifier">filter_iterator</span><span class="special">&lt;</span><span class="identifier">Predicate</span><span class="special">,</span> <span class="identifier">OtherIterator</span><span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">t</span>
<span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">enable_if_convertible</span><span class="special">&lt;</span><span class="identifier">OtherIterator</span><span class="special">,</span> <span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">type</span><span class="special">*</span> <span class="special">=</span> <span class="number">0</span> <span class="comment">// exposition</span>
<span class="special">);</span>
<span class="identifier">Predicate</span> <span class="identifier">predicate</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="identifier">Iterator</span> <span class="identifier">end</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="identifier">Iterator</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">base</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="identifier">reference</span> <span class="keyword">operator</span><span class="special">*()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="identifier">filter_iterator</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">++();</span>
<span class="keyword">private</span><span class="special">:</span>
<span class="identifier">Predicate</span> <span class="identifier">m_pred</span><span class="special">;</span> <span class="comment">// exposition only</span>
<span class="identifier">Iterator</span> <span class="identifier">m_iter</span><span class="special">;</span> <span class="comment">// exposition only</span>
<span class="identifier">Iterator</span> <span class="identifier">m_end</span><span class="special">;</span> <span class="comment">// exposition only</span>
<span class="special">};</span>
</pre>
<p>
If <code class="computeroutput"><span class="identifier">Iterator</span></code> models Readable
Lvalue Iterator and Bidirectional Traversal Iterator then <code class="computeroutput"><span class="identifier">iterator_category</span></code>
is convertible to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bidirectional_iterator_tag</span></code>. Otherwise,
if <code class="computeroutput"><span class="identifier">Iterator</span></code> models Readable
Lvalue Iterator and Forward Traversal Iterator then <code class="computeroutput"><span class="identifier">iterator_category</span></code>
is convertible to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">forward_iterator_tag</span></code>. Otherwise <code class="computeroutput"><span class="identifier">iterator_category</span></code> is convertible to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">input_iterator_tag</span></code>.
</p>
<h4>
<a name="iterator.specialized.filter.h3"></a>
<span class="phrase"><a name="iterator.specialized.filter.requirements"></a></span><a class="link" href="filter.html#iterator.specialized.filter.requirements">Requirements</a>
</h4>
<p>
The <code class="computeroutput"><span class="identifier">Iterator</span></code> argument shall
meet the requirements of Readable Iterator and Single Pass Iterator or it
shall meet the requirements of Input Iterator.
</p>
<p>
The <code class="computeroutput"><span class="identifier">Predicate</span></code> argument must
be Assignable, Copy Constructible, and the expression <code class="computeroutput"><span class="identifier">p</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span></code>
must be valid where <code class="computeroutput"><span class="identifier">p</span></code> is
an object of type <code class="computeroutput"><span class="identifier">Predicate</span></code>,
<code class="computeroutput"><span class="identifier">x</span></code> is an object of type <code class="computeroutput"><span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">value_type</span></code>, and where the type of <code class="computeroutput"><span class="identifier">p</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span></code> must be convertible to <code class="computeroutput"><span class="keyword">bool</span></code>.
</p>
<h4>
<a name="iterator.specialized.filter.h4"></a>
<span class="phrase"><a name="iterator.specialized.filter.concepts"></a></span><a class="link" href="filter.html#iterator.specialized.filter.concepts">Concepts</a>
</h4>
<p>
The concepts that <code class="computeroutput"><span class="identifier">filter_iterator</span></code>
models are dependent on which concepts the <code class="computeroutput"><span class="identifier">Iterator</span></code>
argument models, as specified in the following tables.
</p>
<div class="table">
<a name="iterator.specialized.filter.traversal"></a><p class="title"><b>Table&#160;1.12.&#160;Traversal</b></p>
<div class="table-contents"><table class="table" summary="Traversal">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
If <code class="computeroutput"><span class="identifier">Iterator</span></code> models
</p>
</th>
<th>
<p>
then <code class="computeroutput"><span class="identifier">filter_iterator</span></code>
models
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
Single Pass Iterator
</p>
</td>
<td>
<p>
Single Pass Iterator
</p>
</td>
</tr>
<tr>
<td>
<p>
Forward Traversal Iterator
</p>
</td>
<td>
<p>
Forward Traversal Iterator
</p>
</td>
</tr>
<tr>
<td>
<p>
Bidirectional Traversal Iterator
</p>
</td>
<td>
<p>
Bidirectional Traversal Iterator
</p>
</td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><div class="table">
<a name="iterator.specialized.filter.access"></a><p class="title"><b>Table&#160;1.13.&#160;Access</b></p>
<div class="table-contents"><table class="table" summary="Access">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
If <code class="computeroutput"><span class="identifier">Iterator</span></code> models
</p>
</th>
<th>
<p>
then <code class="computeroutput"><span class="identifier">filter_iterator</span></code>
models
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
Readable Iterator
</p>
</td>
<td>
<p>
Readable Iterator
</p>
</td>
</tr>
<tr>
<td>
<p>
Writable Iterator
</p>
</td>
<td>
<p>
Writable Iterator
</p>
</td>
</tr>
<tr>
<td>
<p>
Lvalue Iterator
</p>
</td>
<td>
<p>
Lvalue Iterator
</p>
</td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><div class="table">
<a name="iterator.specialized.filter.c_03"></a><p class="title"><b>Table&#160;1.14.&#160;C++03</b></p>
<div class="table-contents"><table class="table" summary="C++03">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
If <code class="computeroutput"><span class="identifier">Iterator</span></code> models
</p>
</th>
<th>
<p>
then <code class="computeroutput"><span class="identifier">filter_iterator</span></code>
models
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
Readable Iterator, Single Pass Iterator
</p>
</td>
<td>
<p>
Input Iterator
</p>
</td>
</tr>
<tr>
<td>
<p>
Readable Lvalue Iterator, Forward Traversal Iterator
</p>
</td>
<td>
<p>
Forward Iterator
</p>
</td>
</tr>
<tr>
<td>
<p>
Writable Lvalue Iterator, Forward Traversal Iterator
</p>
</td>
<td>
<p>
Mutable Forward Iterator
</p>
</td>
</tr>
<tr>
<td>
<p>
Writable Lvalue Iterator, Bidirectional Iterator
</p>
</td>
<td>
<p>
Mutable Bidirectional Iterator
</p>
</td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
<code class="computeroutput"><span class="identifier">filter_iterator</span><span class="special">&lt;</span><span class="identifier">P1</span><span class="special">,</span> <span class="identifier">X</span><span class="special">&gt;</span></code> is interoperable with <code class="computeroutput"><span class="identifier">filter_iterator</span><span class="special">&lt;</span><span class="identifier">P2</span><span class="special">,</span> <span class="identifier">Y</span><span class="special">&gt;</span></code>
if and only if <code class="computeroutput"><span class="identifier">X</span></code> is interoperable
with <code class="computeroutput"><span class="identifier">Y</span></code>.
</p>
<h4>
<a name="iterator.specialized.filter.h5"></a>
<span class="phrase"><a name="iterator.specialized.filter.operations"></a></span><a class="link" href="filter.html#iterator.specialized.filter.operations">Operations</a>
</h4>
<p>
In addition to those operations required by the concepts that <code class="computeroutput"><span class="identifier">filter_iterator</span></code> models, <code class="computeroutput"><span class="identifier">filter_iterator</span></code>
provides the following operations.
</p>
<pre class="programlisting"><span class="identifier">filter_iterator</span><span class="special">();</span>
</pre>
<p>
<span class="bold"><strong>Requires: </strong></span><code class="computeroutput"><span class="identifier">Predicate</span></code>
and <code class="computeroutput"><span class="identifier">Iterator</span></code> must be Default
Constructible.<br> <span class="bold"><strong>Effects: </strong></span> Constructs
a <code class="computeroutput"><span class="identifier">filter_iterator</span></code> whose<code class="computeroutput"><span class="identifier">m_pred</span></code>, <code class="computeroutput"><span class="identifier">m_iter</span></code>,
and <code class="computeroutput"><span class="identifier">m_end</span></code> members are a default
constructed.
</p>
<pre class="programlisting"><span class="identifier">filter_iterator</span><span class="special">(</span><span class="identifier">Predicate</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">Iterator</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">Iterator</span> <span class="identifier">end</span> <span class="special">=</span> <span class="identifier">Iterator</span><span class="special">());</span>
</pre>
<p>
<span class="bold"><strong>Effects: </strong></span> Constructs a <code class="computeroutput"><span class="identifier">filter_iterator</span></code>
where <code class="computeroutput"><span class="identifier">m_iter</span></code> is either the
first position in the range <code class="computeroutput"><span class="special">[</span><span class="identifier">x</span><span class="special">,</span><span class="identifier">end</span><span class="special">)</span></code> such that <code class="computeroutput"><span class="identifier">f</span><span class="special">(*</span><span class="identifier">m_iter</span><span class="special">)</span> <span class="special">==</span> <span class="keyword">true</span></code>
or else<code class="computeroutput"><span class="identifier">m_iter</span> <span class="special">==</span>
<span class="identifier">end</span></code>. The member <code class="computeroutput"><span class="identifier">m_pred</span></code>
is constructed from <code class="computeroutput"><span class="identifier">f</span></code> and
<code class="computeroutput"><span class="identifier">m_end</span></code> from <code class="computeroutput"><span class="identifier">end</span></code>.
</p>
<pre class="programlisting"><span class="identifier">filter_iterator</span><span class="special">(</span><span class="identifier">Iterator</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">Iterator</span> <span class="identifier">end</span> <span class="special">=</span> <span class="identifier">Iterator</span><span class="special">());</span>
</pre>
<p>
<span class="bold"><strong>Requires: </strong></span> <code class="computeroutput"><span class="identifier">Predicate</span></code>
must be Default Constructible and <code class="computeroutput"><span class="identifier">Predicate</span></code>
is a class type (not a function pointer).<br> <span class="bold"><strong>Effects:
</strong></span> Constructs a <code class="computeroutput"><span class="identifier">filter_iterator</span></code>
where <code class="computeroutput"><span class="identifier">m_iter</span></code> is either the
first position in the range <code class="computeroutput"><span class="special">[</span><span class="identifier">x</span><span class="special">,</span><span class="identifier">end</span><span class="special">)</span></code> such that <code class="computeroutput"><span class="identifier">m_pred</span><span class="special">(*</span><span class="identifier">m_iter</span><span class="special">)</span> <span class="special">==</span> <span class="keyword">true</span></code>
or else<code class="computeroutput"><span class="identifier">m_iter</span> <span class="special">==</span>
<span class="identifier">end</span></code>. The member <code class="computeroutput"><span class="identifier">m_pred</span></code>
is default constructed.
</p>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">OtherIterator</span><span class="special">&gt;</span>
<span class="identifier">filter_iterator</span><span class="special">(</span>
<span class="identifier">filter_iterator</span><span class="special">&lt;</span><span class="identifier">Predicate</span><span class="special">,</span> <span class="identifier">OtherIterator</span><span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">t</span>
<span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">enable_if_convertible</span><span class="special">&lt;</span><span class="identifier">OtherIterator</span><span class="special">,</span> <span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">type</span><span class="special">*</span> <span class="special">=</span> <span class="number">0</span> <span class="comment">// exposition</span>
<span class="special">);</span>
</pre>
<p>
<span class="bold"><strong>Requires: </strong></span> <code class="computeroutput"><span class="identifier">OtherIterator</span></code>
is implicitly convertible to <code class="computeroutput"><span class="identifier">Iterator</span></code>.<br>
<span class="bold"><strong>Effects: </strong></span> Constructs a filter iterator whose
members are copied from <code class="computeroutput"><span class="identifier">t</span></code>.
</p>
<pre class="programlisting"><span class="identifier">Predicate</span> <span class="identifier">predicate</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
</pre>
<p>
<span class="bold"><strong>Returns: </strong></span> <code class="computeroutput"><span class="identifier">m_pred</span></code>
</p>
<pre class="programlisting"><span class="identifier">Ierator</span> <span class="identifier">end</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
</pre>
<p>
<span class="bold"><strong>Returns: </strong></span> <code class="computeroutput"><span class="identifier">m_end</span></code>
</p>
<pre class="programlisting"><span class="identifier">Iterator</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">base</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
</pre>
<p>
<span class="bold"><strong>Returns: </strong></span> <code class="computeroutput"><span class="identifier">m_iterator</span></code>
</p>
<pre class="programlisting"><span class="identifier">reference</span> <span class="keyword">operator</span><span class="special">*()</span> <span class="keyword">const</span><span class="special">;</span>
</pre>
<p>
<span class="bold"><strong>Returns: </strong></span> <code class="computeroutput"><span class="special">*</span><span class="identifier">m_iter</span></code>
</p>
<pre class="programlisting"><span class="identifier">filter_iterator</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">++();</span>
</pre>
<p>
<span class="bold"><strong>Effects: </strong></span> Increments <code class="computeroutput"><span class="identifier">m_iter</span></code>
and then continues to increment <code class="computeroutput"><span class="identifier">m_iter</span></code>
until either <code class="computeroutput"><span class="identifier">m_iter</span> <span class="special">==</span>
<span class="identifier">m_end</span></code> or <code class="computeroutput"><span class="identifier">m_pred</span><span class="special">(*</span><span class="identifier">m_iter</span><span class="special">)</span> <span class="special">==</span> <span class="keyword">true</span></code>.<br>
<span class="bold"><strong>Returns: </strong></span> <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003, 2005 David Abrahams Jeremy Siek Thomas
Witt<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at &lt;ulink url="http://www.boost.org/LICENSE_1_0.txt"&gt;
http://www.boost.org/LICENSE_1_0.txt &lt;/ulink&gt;)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../specialized.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../specialized.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="function_output.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
libs/iterator/doc/html/iterator/specialized/function_output.html
+161
View File
@@ -0,0 +1,161 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Function Output Iterator</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="up" href="../specialized.html" title="Specialized Adaptors">
<link rel="prev" href="filter.html" title="Filter Iterator">
<link rel="next" href="indirect.html" title="Indirect Iterator">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="filter.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../specialized.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="indirect.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="iterator.specialized.function_output"></a><a class="link" href="function_output.html" title="Function Output Iterator">Function Output
Iterator</a>
</h3></div></div></div>
<p>
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.
</p>
<h3>
<a name="iterator.specialized.function_output.h0"></a>
<span class="phrase"><a name="iterator.specialized.function_output.example"></a></span><a class="link" href="function_output.html#iterator.specialized.function_output.example">Example</a>
</h3>
<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">string_appender</span>
<span class="special">{</span>
<span class="identifier">string_appender</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&amp;</span> <span class="identifier">s</span><span class="special">)</span>
<span class="special">:</span> <span class="identifier">m_str</span><span class="special">(&amp;</span><span class="identifier">s</span><span class="special">)</span>
<span class="special">{}</span>
<span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&amp;</span> <span class="identifier">x</span><span class="special">)</span> <span class="keyword">const</span>
<span class="special">{</span>
<span class="special">*</span><span class="identifier">m_str</span> <span class="special">+=</span> <span class="identifier">x</span><span class="special">;</span>
<span class="special">}</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">*</span> <span class="identifier">m_str</span><span class="special">;</span>
<span class="special">};</span>
<span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*[])</span>
<span class="special">{</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;</span> <span class="identifier">x</span><span class="special">;</span>
<span class="identifier">x</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="string">"hello"</span><span class="special">);</span>
<span class="identifier">x</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="string">" "</span><span class="special">);</span>
<span class="identifier">x</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="string">"world"</span><span class="special">);</span>
<span class="identifier">x</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="string">"!"</span><span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">s</span> <span class="special">=</span> <span class="string">""</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">copy</span><span class="special">(</span><span class="identifier">x</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_function_output_iterator</span><span class="special">(</span><span class="identifier">string_appender</span><span class="special">(</span><span class="identifier">s</span><span class="special">)));</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">s</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<h3>
<a name="iterator.specialized.function_output.h1"></a>
<span class="phrase"><a name="iterator.specialized.function_output.reference"></a></span><a class="link" href="function_output.html#iterator.specialized.function_output.reference">Reference</a>
</h3>
<h4>
<a name="iterator.specialized.function_output.h2"></a>
<span class="phrase"><a name="iterator.specialized.function_output.synopsis"></a></span><a class="link" href="function_output.html#iterator.specialized.function_output.synopsis">Synopsis</a>
</h4>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">UnaryFunction</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">function_output_iterator</span> <span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>
<span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">output_iterator_tag</span> <span class="identifier">iterator_category</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="keyword">void</span> <span class="identifier">value_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="keyword">void</span> <span class="identifier">difference_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="keyword">void</span> <span class="identifier">pointer</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="keyword">void</span> <span class="identifier">reference</span><span class="special">;</span>
<span class="keyword">explicit</span> <span class="identifier">function_output_iterator</span><span class="special">();</span>
<span class="keyword">explicit</span> <span class="identifier">function_output_iterator</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">UnaryFunction</span><span class="special">&amp;</span> <span class="identifier">f</span><span class="special">);</span>
<span class="comment">/* see below */</span> <span class="keyword">operator</span><span class="special">*();</span>
<span class="identifier">function_output_iterator</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">++();</span>
<span class="identifier">function_output_iterator</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">++(</span><span class="keyword">int</span><span class="special">);</span>
<span class="keyword">private</span><span class="special">:</span>
<span class="identifier">UnaryFunction</span> <span class="identifier">m_f</span><span class="special">;</span> <span class="comment">// exposition only</span>
<span class="special">};</span>
</pre>
<h4>
<a name="iterator.specialized.function_output.h3"></a>
<span class="phrase"><a name="iterator.specialized.function_output.requirements"></a></span><a class="link" href="function_output.html#iterator.specialized.function_output.requirements">Requirements</a>
</h4>
<p>
<code class="computeroutput"><span class="identifier">UnaryFunction</span></code> must be Assignable
and Copy Constructible.
</p>
<h4>
<a name="iterator.specialized.function_output.h4"></a>
<span class="phrase"><a name="iterator.specialized.function_output.concepts"></a></span><a class="link" href="function_output.html#iterator.specialized.function_output.concepts">Concepts</a>
</h4>
<p>
<code class="computeroutput"><span class="identifier">function_output_iterator</span></code>
is a model of the Writable and Incrementable Iterator concepts.
</p>
<h4>
<a name="iterator.specialized.function_output.h5"></a>
<span class="phrase"><a name="iterator.specialized.function_output.operations"></a></span><a class="link" href="function_output.html#iterator.specialized.function_output.operations">Operations</a>
</h4>
<pre class="programlisting"><span class="keyword">explicit</span> <span class="identifier">function_output_iterator</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">UnaryFunction</span><span class="special">&amp;</span> <span class="identifier">f</span> <span class="special">=</span> <span class="identifier">UnaryFunction</span><span class="special">());</span>
</pre>
<p>
<span class="bold"><strong>Effects: </strong></span> Constructs an instance of <code class="computeroutput"><span class="identifier">function_output_iterator</span></code> with <code class="computeroutput"><span class="identifier">m_f</span></code> constructed from <code class="computeroutput"><span class="identifier">f</span></code>.
</p>
<pre class="programlisting"><span class="identifier">unspecified_type</span> <span class="keyword">operator</span><span class="special">*();</span>
</pre>
<p>
<span class="bold"><strong>Returns: </strong></span> An object <code class="computeroutput"><span class="identifier">r</span></code>
of unspecified type such that <code class="computeroutput"><span class="identifier">r</span>
<span class="special">=</span> <span class="identifier">t</span></code>
is equivalent to <code class="computeroutput"><span class="identifier">m_f</span><span class="special">(</span><span class="identifier">t</span><span class="special">)</span></code> for
all <code class="computeroutput"><span class="identifier">t</span></code>.
</p>
<pre class="programlisting"><span class="identifier">function_output_iterator</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">++();</span>
</pre>
<p>
<span class="bold"><strong>Returns: </strong></span> <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>.
</p>
<pre class="programlisting"><span class="identifier">function_output_iterator</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">++(</span><span class="keyword">int</span><span class="special">);</span>
</pre>
<p>
<span class="bold"><strong>Returns: </strong></span> <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>.
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003, 2005 David Abrahams Jeremy Siek Thomas
Witt<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at &lt;ulink url="http://www.boost.org/LICENSE_1_0.txt"&gt;
http://www.boost.org/LICENSE_1_0.txt &lt;/ulink&gt;)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="filter.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../specialized.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="indirect.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
libs/iterator/doc/html/iterator/specialized/indirect.html
+323
View File
@@ -0,0 +1,323 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Indirect Iterator</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="up" href="../specialized.html" title="Specialized Adaptors">
<link rel="prev" href="function_output.html" title="Function Output Iterator">
<link rel="next" href="permutation.html" title="Permutation Iterator">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="function_output.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../specialized.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="permutation.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="iterator.specialized.indirect"></a><a class="link" href="indirect.html" title="Indirect Iterator">Indirect Iterator</a>
</h3></div></div></div>
<p>
<code class="computeroutput"><span class="identifier">indirect_iterator</span></code> adapts
an iterator by applying an <span class="bold"><strong>extra</strong></span> dereference
inside of <code class="computeroutput"><span class="keyword">operator</span><span class="special">*()</span></code>.
For example, this iterator adaptor makes it possible to view a container
of pointers (e.g. <code class="computeroutput"><span class="identifier">list</span><span class="special">&lt;</span><span class="identifier">foo</span><span class="special">*&gt;</span></code>)
as if it were a container of the pointed-to type (e.g. <code class="computeroutput"><span class="identifier">list</span><span class="special">&lt;</span><span class="identifier">foo</span><span class="special">&gt;</span></code>). <code class="computeroutput"><span class="identifier">indirect_iterator</span></code>
depends on two auxiliary traits, <code class="computeroutput"><span class="identifier">pointee</span></code>
and <code class="computeroutput"><span class="identifier">indirect_reference</span></code>, to
provide support for underlying iterators whose <code class="computeroutput"><span class="identifier">value_type</span></code>
is not an iterator.
</p>
<h3>
<a name="iterator.specialized.indirect.h0"></a>
<span class="phrase"><a name="iterator.specialized.indirect.example"></a></span><a class="link" href="indirect.html#iterator.specialized.indirect.example">Example</a>
</h3>
<p>
This example prints an array of characters, using <code class="computeroutput"><span class="identifier">indirect_iterator</span></code>
to access the array of characters through an array of pointers. Next <code class="computeroutput"><span class="identifier">indirect_iterator</span></code> is used with the <code class="computeroutput"><span class="identifier">transform</span></code> algorithm to copy the characters
(incremented by one) to another array. A constant indirect iterator is used
for the source and a mutable indirect iterator is used for the destination.
The last part of the example prints the original array of characters, but
this time using the <code class="computeroutput"><span class="identifier">make_indirect_iterator</span></code>
helper function.
</p>
<pre class="programlisting"><span class="keyword">char</span> <span class="identifier">characters</span><span class="special">[]</span> <span class="special">=</span> <span class="string">"abcdefg"</span><span class="special">;</span>
<span class="keyword">const</span> <span class="keyword">int</span> <span class="identifier">N</span> <span class="special">=</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">characters</span><span class="special">)/</span><span class="keyword">sizeof</span><span class="special">(</span><span class="keyword">char</span><span class="special">)</span> <span class="special">-</span> <span class="number">1</span><span class="special">;</span> <span class="comment">// -1 since characters has a null char</span>
<span class="keyword">char</span><span class="special">*</span> <span class="identifier">pointers_to_chars</span><span class="special">[</span><span class="identifier">N</span><span class="special">];</span> <span class="comment">// at the end.</span>
<span class="keyword">for</span> <span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="identifier">N</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">)</span>
<span class="identifier">pointers_to_chars</span><span class="special">[</span><span class="identifier">i</span><span class="special">]</span> <span class="special">=</span> <span class="special">&amp;</span><span class="identifier">characters</span><span class="special">[</span><span class="identifier">i</span><span class="special">];</span>
<span class="comment">// Example of using indirect_iterator</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">indirect_iterator</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">**,</span> <span class="keyword">char</span><span class="special">&gt;</span>
<span class="identifier">indirect_first</span><span class="special">(</span><span class="identifier">pointers_to_chars</span><span class="special">),</span> <span class="identifier">indirect_last</span><span class="special">(</span><span class="identifier">pointers_to_chars</span> <span class="special">+</span> <span class="identifier">N</span><span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">copy</span><span class="special">(</span><span class="identifier">indirect_first</span><span class="special">,</span> <span class="identifier">indirect_last</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream_iterator</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">,</span> <span class="string">","</span><span class="special">));</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="comment">// Example of making mutable and constant indirect iterators</span>
<span class="keyword">char</span> <span class="identifier">mutable_characters</span><span class="special">[</span><span class="identifier">N</span><span class="special">];</span>
<span class="keyword">char</span><span class="special">*</span> <span class="identifier">pointers_to_mutable_chars</span><span class="special">[</span><span class="identifier">N</span><span class="special">];</span>
<span class="keyword">for</span> <span class="special">(</span><span class="keyword">int</span> <span class="identifier">j</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">j</span> <span class="special">&lt;</span> <span class="identifier">N</span><span class="special">;</span> <span class="special">++</span><span class="identifier">j</span><span class="special">)</span>
<span class="identifier">pointers_to_mutable_chars</span><span class="special">[</span><span class="identifier">j</span><span class="special">]</span> <span class="special">=</span> <span class="special">&amp;</span><span class="identifier">mutable_characters</span><span class="special">[</span><span class="identifier">j</span><span class="special">];</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">indirect_iterator</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">*</span> <span class="keyword">const</span><span class="special">*&gt;</span> <span class="identifier">mutable_indirect_first</span><span class="special">(</span><span class="identifier">pointers_to_mutable_chars</span><span class="special">),</span>
<span class="identifier">mutable_indirect_last</span><span class="special">(</span><span class="identifier">pointers_to_mutable_chars</span> <span class="special">+</span> <span class="identifier">N</span><span class="special">);</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">indirect_iterator</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">*</span> <span class="keyword">const</span><span class="special">*,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">&gt;</span> <span class="identifier">const_indirect_first</span><span class="special">(</span><span class="identifier">pointers_to_chars</span><span class="special">),</span>
<span class="identifier">const_indirect_last</span><span class="special">(</span><span class="identifier">pointers_to_chars</span> <span class="special">+</span> <span class="identifier">N</span><span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">transform</span><span class="special">(</span><span class="identifier">const_indirect_first</span><span class="special">,</span> <span class="identifier">const_indirect_last</span><span class="special">,</span>
<span class="identifier">mutable_indirect_first</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">bind1st</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">plus</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;(),</span> <span class="number">1</span><span class="special">));</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">copy</span><span class="special">(</span><span class="identifier">mutable_indirect_first</span><span class="special">,</span> <span class="identifier">mutable_indirect_last</span><span class="special">,</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream_iterator</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">,</span> <span class="string">","</span><span class="special">));</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="comment">// Example of using make_indirect_iterator()</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">copy</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_indirect_iterator</span><span class="special">(</span><span class="identifier">pointers_to_chars</span><span class="special">),</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_indirect_iterator</span><span class="special">(</span><span class="identifier">pointers_to_chars</span> <span class="special">+</span> <span class="identifier">N</span><span class="special">),</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream_iterator</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">,</span> <span class="string">","</span><span class="special">));</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
</pre>
<p>
The output is:
</p>
<pre class="programlisting"><span class="identifier">a</span><span class="special">,</span><span class="identifier">b</span><span class="special">,</span><span class="identifier">c</span><span class="special">,</span><span class="identifier">d</span><span class="special">,</span><span class="identifier">e</span><span class="special">,</span><span class="identifier">f</span><span class="special">,</span><span class="identifier">g</span><span class="special">,</span>
<span class="identifier">b</span><span class="special">,</span><span class="identifier">c</span><span class="special">,</span><span class="identifier">d</span><span class="special">,</span><span class="identifier">e</span><span class="special">,</span><span class="identifier">f</span><span class="special">,</span><span class="identifier">g</span><span class="special">,</span><span class="identifier">h</span><span class="special">,</span>
<span class="identifier">a</span><span class="special">,</span><span class="identifier">b</span><span class="special">,</span><span class="identifier">c</span><span class="special">,</span><span class="identifier">d</span><span class="special">,</span><span class="identifier">e</span><span class="special">,</span><span class="identifier">f</span><span class="special">,</span><span class="identifier">g</span><span class="special">,</span>
</pre>
<p>
The source code for this example can be found <a href="../../../example/indirect_iterator_example.cpp" target="_top">here</a>.
</p>
<h3>
<a name="iterator.specialized.indirect.h1"></a>
<span class="phrase"><a name="iterator.specialized.indirect.reference"></a></span><a class="link" href="indirect.html#iterator.specialized.indirect.reference">Reference</a>
</h3>
<h4>
<a name="iterator.specialized.indirect.h2"></a>
<span class="phrase"><a name="iterator.specialized.indirect.synopsis"></a></span><a class="link" href="indirect.html#iterator.specialized.indirect.synopsis">Synopsis</a>
</h4>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span>
<span class="keyword">class</span> <span class="identifier">Iterator</span>
<span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Value</span> <span class="special">=</span> <span class="identifier">use_default</span>
<span class="special">,</span> <span class="keyword">class</span> <span class="identifier">CategoryOrTraversal</span> <span class="special">=</span> <span class="identifier">use_default</span>
<span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Reference</span> <span class="special">=</span> <span class="identifier">use_default</span>
<span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Difference</span> <span class="special">=</span> <span class="identifier">use_default</span>
<span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">indirect_iterator</span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>
<span class="keyword">typedef</span> <span class="comment">/* see below */</span> <span class="identifier">value_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="comment">/* see below */</span> <span class="identifier">reference</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="comment">/* see below */</span> <span class="identifier">pointer</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="comment">/* see below */</span> <span class="identifier">difference_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="comment">/* see below */</span> <span class="identifier">iterator_category</span><span class="special">;</span>
<span class="identifier">indirect_iterator</span><span class="special">();</span>
<span class="identifier">indirect_iterator</span><span class="special">(</span><span class="identifier">Iterator</span> <span class="identifier">x</span><span class="special">);</span>
<span class="keyword">template</span> <span class="special">&lt;</span>
<span class="keyword">class</span> <span class="identifier">Iterator2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Value2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Category2</span>
<span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Reference2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Difference2</span>
<span class="special">&gt;</span>
<span class="identifier">indirect_iterator</span><span class="special">(</span>
<span class="identifier">indirect_iterator</span><span class="special">&lt;</span>
<span class="identifier">Iterator2</span><span class="special">,</span> <span class="identifier">Value2</span><span class="special">,</span> <span class="identifier">Category2</span><span class="special">,</span> <span class="identifier">Reference2</span><span class="special">,</span> <span class="identifier">Difference2</span>
<span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">y</span>
<span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">enable_if_convertible</span><span class="special">&lt;</span><span class="identifier">Iterator2</span><span class="special">,</span> <span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">type</span><span class="special">*</span> <span class="special">=</span> <span class="number">0</span> <span class="comment">// exposition</span>
<span class="special">);</span>
<span class="identifier">Iterator</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">base</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="identifier">reference</span> <span class="keyword">operator</span><span class="special">*()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="identifier">indirect_iterator</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">++();</span>
<span class="identifier">indirect_iterator</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">--();</span>
<span class="keyword">private</span><span class="special">:</span>
<span class="identifier">Iterator</span> <span class="identifier">m_iterator</span><span class="special">;</span> <span class="comment">// exposition</span>
<span class="special">};</span>
</pre>
<p>
The member types of <code class="computeroutput"><span class="identifier">indirect_iterator</span></code>
are defined according to the following pseudo-code, where <code class="computeroutput"><span class="identifier">V</span></code>
is <code class="computeroutput"><span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">value_type</span></code>
</p>
<pre class="programlisting"> if (Value is use_default) then
typedef remove_const&lt;pointee&lt;V&gt;::type&gt;::type value_type;
else
typedef remove_const&lt;Value&gt;::type value_type;
if (Reference is use_default) then
if (Value is use_default) then
typedef indirect_reference&lt;V&gt;::type reference;
else
typedef Value&amp; reference;
else
typedef Reference reference;
if (Value is use_default) then
typedef pointee&lt;V&gt;::type* pointer;
else
typedef Value* pointer;
if (Difference is use_default)
typedef iterator_traits&lt;Iterator&gt;::difference_type difference_type;
else
typedef Difference difference_type;
if (CategoryOrTraversal is use_default)
typedef <span class="bold"><strong>iterator-category</strong></span> (
iterator_traversal&lt;Iterator&gt;::type,<code class="computeroutput"><span class="identifier">reference</span></code>,<code class="computeroutput"><span class="identifier">value_type</span></code>
) iterator_category;
else
typedef <span class="bold"><strong>iterator-category</strong></span> (
CategoryOrTraversal,<code class="computeroutput"><span class="identifier">reference</span></code>,<code class="computeroutput"><span class="identifier">value_type</span></code>
) iterator_category;
</pre>
<h4>
<a name="iterator.specialized.indirect.h3"></a>
<span class="phrase"><a name="iterator.specialized.indirect.requirements"></a></span><a class="link" href="indirect.html#iterator.specialized.indirect.requirements">Requirements</a>
</h4>
<p>
The expression <code class="computeroutput"><span class="special">*</span><span class="identifier">v</span></code>,
where <code class="computeroutput"><span class="identifier">v</span></code> is an object of
<code class="computeroutput"><span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">value_type</span></code>, shall be valid expression and
convertible to <code class="computeroutput"><span class="identifier">reference</span></code>.
<code class="computeroutput"><span class="identifier">Iterator</span></code> shall model the
traversal concept indicated by <code class="computeroutput"><span class="identifier">iterator_category</span></code>.
<code class="computeroutput"><span class="identifier">Value</span></code>, <code class="computeroutput"><span class="identifier">Reference</span></code>,
and <code class="computeroutput"><span class="identifier">Difference</span></code> shall be chosen
so that <code class="computeroutput"><span class="identifier">value_type</span></code>, <code class="computeroutput"><span class="identifier">reference</span></code>, and <code class="computeroutput"><span class="identifier">difference_type</span></code>
meet the requirements indicated by <code class="computeroutput"><span class="identifier">iterator_category</span></code>.
</p>
<div class="sidebar">
<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div>
<p>
Note: there are further requirements on the <code class="computeroutput"><span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">value_type</span></code>
if the <code class="computeroutput"><span class="identifier">Value</span></code> parameter is
not <code class="computeroutput"><span class="identifier">use_default</span></code>, as implied
by the algorithm for deducing the default for the <code class="computeroutput"><span class="identifier">value_type</span></code>
member.
</p>
</div>
<h4>
<a name="iterator.specialized.indirect.h4"></a>
<span class="phrase"><a name="iterator.specialized.indirect.concepts"></a></span><a class="link" href="indirect.html#iterator.specialized.indirect.concepts">Concepts</a>
</h4>
<p>
In addition to the concepts indicated by <code class="computeroutput"><span class="identifier">iterator_category</span></code>
and by <code class="computeroutput"><span class="identifier">iterator_traversal</span><span class="special">&lt;</span><span class="identifier">indirect_iterator</span><span class="special">&gt;::</span><span class="identifier">type</span></code>,
a specialization of <code class="computeroutput"><span class="identifier">indirect_iterator</span></code>
models the following concepts, Where <code class="computeroutput"><span class="identifier">v</span></code>
is an object of <code class="computeroutput"><span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">value_type</span></code>:
</p>
<p>
Readable Iterator if <code class="computeroutput"><span class="identifier">reference</span><span class="special">(*</span><span class="identifier">v</span><span class="special">)</span></code>
is convertible to <code class="computeroutput"><span class="identifier">value_type</span></code>.
</p>
<p>
Writable Iterator if <code class="computeroutput"><span class="identifier">reference</span><span class="special">(*</span><span class="identifier">v</span><span class="special">)</span>
<span class="special">=</span> <span class="identifier">t</span></code>
is a valid expression (where <code class="computeroutput"><span class="identifier">t</span></code>
is an object of type <code class="computeroutput"><span class="identifier">indirect_iterator</span><span class="special">::</span><span class="identifier">value_type</span></code>)
</p>
<p>
Lvalue Iterator if <code class="computeroutput"><span class="identifier">reference</span></code>
is a reference type.
</p>
<p>
<code class="computeroutput"><span class="identifier">indirect_iterator</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">,</span><span class="identifier">V1</span><span class="special">,</span><span class="identifier">C1</span><span class="special">,</span><span class="identifier">R1</span><span class="special">,</span><span class="identifier">D1</span><span class="special">&gt;</span></code> is interoperable with <code class="computeroutput"><span class="identifier">indirect_iterator</span><span class="special">&lt;</span><span class="identifier">Y</span><span class="special">,</span><span class="identifier">V2</span><span class="special">,</span><span class="identifier">C2</span><span class="special">,</span><span class="identifier">R2</span><span class="special">,</span><span class="identifier">D2</span><span class="special">&gt;</span></code>
if and only if <code class="computeroutput"><span class="identifier">X</span></code> is interoperable
with <code class="computeroutput"><span class="identifier">Y</span></code>.
</p>
<h4>
<a name="iterator.specialized.indirect.h5"></a>
<span class="phrase"><a name="iterator.specialized.indirect.operations"></a></span><a class="link" href="indirect.html#iterator.specialized.indirect.operations">Operations</a>
</h4>
<p>
In addition to the operations required by the concepts described above, specializations
of <code class="computeroutput"><span class="identifier">indirect_iterator</span></code> provide
the following operations:
</p>
<pre class="programlisting"><span class="identifier">indirect_iterator</span><span class="special">();</span>
</pre>
<p>
<span class="bold"><strong>Requires: </strong></span> <code class="computeroutput"><span class="identifier">Iterator</span></code>
must be Default Constructible.<br> <span class="bold"><strong>Effects: </strong></span>
Constructs an instance of <code class="computeroutput"><span class="identifier">indirect_iterator</span></code>
with a default-constructed <code class="computeroutput"><span class="identifier">m_iterator</span></code>.
</p>
<pre class="programlisting"><span class="identifier">indirect_iterator</span><span class="special">(</span><span class="identifier">Iterator</span> <span class="identifier">x</span><span class="special">);</span>
</pre>
<p>
<span class="bold"><strong>Effects: </strong></span> Constructs an instance of <code class="computeroutput"><span class="identifier">indirect_iterator</span></code> with <code class="computeroutput"><span class="identifier">m_iterator</span></code>
copy constructed from <code class="computeroutput"><span class="identifier">x</span></code>.
</p>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span>
<span class="keyword">class</span> <span class="identifier">Iterator2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Value2</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">Access</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Traversal</span>
<span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Reference2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Difference2</span>
<span class="special">&gt;</span>
<span class="identifier">indirect_iterator</span><span class="special">(</span>
<span class="identifier">indirect_iterator</span><span class="special">&lt;</span>
<span class="identifier">Iterator2</span><span class="special">,</span> <span class="identifier">Value2</span><span class="special">,</span> <span class="identifier">Access</span><span class="special">,</span> <span class="identifier">Traversal</span><span class="special">,</span> <span class="identifier">Reference2</span><span class="special">,</span> <span class="identifier">Difference2</span>
<span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">y</span>
<span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">enable_if_convertible</span><span class="special">&lt;</span><span class="identifier">Iterator2</span><span class="special">,</span> <span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">type</span><span class="special">*</span> <span class="special">=</span> <span class="number">0</span> <span class="comment">// exposition</span>
<span class="special">);</span>
</pre>
<p>
<span class="bold"><strong>Requires: </strong></span> <code class="computeroutput"><span class="identifier">Iterator2</span></code>
is implicitly convertible to <code class="computeroutput"><span class="identifier">Iterator</span></code>.<br>
<span class="bold"><strong>Effects: </strong></span> Constructs an instance of <code class="computeroutput"><span class="identifier">indirect_iterator</span></code> whose <code class="computeroutput"><span class="identifier">m_iterator</span></code>
subobject is constructed from <code class="computeroutput"><span class="identifier">y</span><span class="special">.</span><span class="identifier">base</span><span class="special">()</span></code>.
</p>
<pre class="programlisting"><span class="identifier">Iterator</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">base</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
</pre>
<p>
<span class="bold"><strong>Returns: </strong></span> <code class="computeroutput"><span class="identifier">m_iterator</span></code>
</p>
<pre class="programlisting"><span class="identifier">reference</span> <span class="keyword">operator</span><span class="special">*()</span> <span class="keyword">const</span><span class="special">;</span>
</pre>
<p>
<span class="bold"><strong>Returns: </strong></span> <code class="computeroutput"><span class="special">**</span><span class="identifier">m_iterator</span></code>
</p>
<pre class="programlisting"><span class="identifier">indirect_iterator</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">++();</span>
</pre>
<p>
<span class="bold"><strong>Effects: </strong></span> <code class="computeroutput"><span class="special">++</span><span class="identifier">m_iterator</span></code><br> <span class="bold"><strong>Returns:
</strong></span> <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>
</p>
<pre class="programlisting"><span class="identifier">indirect_iterator</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">--();</span>
</pre>
<p>
<span class="bold"><strong>Effects: </strong></span> <code class="computeroutput"><span class="special">--</span><span class="identifier">m_iterator</span></code><br> <span class="bold"><strong>Returns:
</strong></span> <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003, 2005 David Abrahams Jeremy Siek Thomas
Witt<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at &lt;ulink url="http://www.boost.org/LICENSE_1_0.txt"&gt;
http://www.boost.org/LICENSE_1_0.txt &lt;/ulink&gt;)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="function_output.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../specialized.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="permutation.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
libs/iterator/doc/html/iterator/specialized/permutation.html
+277
View File
@@ -0,0 +1,277 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Permutation Iterator</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="up" href="../specialized.html" title="Specialized Adaptors">
<link rel="prev" href="indirect.html" title="Indirect Iterator">
<link rel="next" href="reverse.html" title="Reverse Iterator">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="indirect.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../specialized.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="reverse.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="iterator.specialized.permutation"></a><a class="link" href="permutation.html" title="Permutation Iterator">Permutation Iterator</a>
</h3></div></div></div>
<p>
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. The adaptor takes two arguments:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
an iterator to the range V on which the permutation will be applied
</li>
<li class="listitem">
the reindexing scheme that defines how the elements of V will be permuted.
</li>
</ul></div>
<p>
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.
</p>
<h3>
<a name="iterator.specialized.permutation.h0"></a>
<span class="phrase"><a name="iterator.specialized.permutation.example"></a></span><a class="link" href="permutation.html#iterator.specialized.permutation.example">Example</a>
</h3>
<pre class="programlisting"><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">;</span>
<span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span> <span class="keyword">int</span> <span class="special">&gt;</span> <span class="identifier">element_range_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special">&lt;</span> <span class="keyword">int</span> <span class="special">&gt;</span> <span class="identifier">index_type</span><span class="special">;</span>
<span class="keyword">static</span> <span class="keyword">const</span> <span class="keyword">int</span> <span class="identifier">element_range_size</span> <span class="special">=</span> <span class="number">10</span><span class="special">;</span>
<span class="keyword">static</span> <span class="keyword">const</span> <span class="keyword">int</span> <span class="identifier">index_size</span> <span class="special">=</span> <span class="number">4</span><span class="special">;</span>
<span class="identifier">element_range_type</span> <span class="identifier">elements</span><span class="special">(</span> <span class="identifier">element_range_size</span> <span class="special">);</span>
<span class="keyword">for</span><span class="special">(</span><span class="identifier">element_range_type</span><span class="special">::</span><span class="identifier">iterator</span> <span class="identifier">el_it</span> <span class="special">=</span> <span class="identifier">elements</span><span class="special">.</span><span class="identifier">begin</span><span class="special">()</span> <span class="special">;</span> <span class="identifier">el_it</span> <span class="special">!=</span> <span class="identifier">elements</span><span class="special">.</span><span class="identifier">end</span><span class="special">()</span> <span class="special">;</span> <span class="special">++</span><span class="identifier">el_it</span><span class="special">)</span>
<span class="special">*</span><span class="identifier">el_it</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">distance</span><span class="special">(</span><span class="identifier">elements</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">el_it</span><span class="special">);</span>
<span class="identifier">index_type</span> <span class="identifier">indices</span><span class="special">(</span> <span class="identifier">index_size</span> <span class="special">);</span>
<span class="keyword">for</span><span class="special">(</span><span class="identifier">index_type</span><span class="special">::</span><span class="identifier">iterator</span> <span class="identifier">i_it</span> <span class="special">=</span> <span class="identifier">indices</span><span class="special">.</span><span class="identifier">begin</span><span class="special">()</span> <span class="special">;</span> <span class="identifier">i_it</span> <span class="special">!=</span> <span class="identifier">indices</span><span class="special">.</span><span class="identifier">end</span><span class="special">()</span> <span class="special">;</span> <span class="special">++</span><span class="identifier">i_it</span> <span class="special">)</span>
<span class="special">*</span><span class="identifier">i_it</span> <span class="special">=</span> <span class="identifier">element_range_size</span> <span class="special">-</span> <span class="identifier">index_size</span> <span class="special">+</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">distance</span><span class="special">(</span><span class="identifier">indices</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">i_it</span><span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">reverse</span><span class="special">(</span> <span class="identifier">indices</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">indices</span><span class="special">.</span><span class="identifier">end</span><span class="special">()</span> <span class="special">);</span>
<span class="keyword">typedef</span> <span class="identifier">permutation_iterator</span><span class="special">&lt;</span> <span class="identifier">element_range_type</span><span class="special">::</span><span class="identifier">iterator</span><span class="special">,</span> <span class="identifier">index_type</span><span class="special">::</span><span class="identifier">iterator</span> <span class="special">&gt;</span> <span class="identifier">permutation_type</span><span class="special">;</span>
<span class="identifier">permutation_type</span> <span class="identifier">begin</span> <span class="special">=</span> <span class="identifier">make_permutation_iterator</span><span class="special">(</span> <span class="identifier">elements</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">indices</span><span class="special">.</span><span class="identifier">begin</span><span class="special">()</span> <span class="special">);</span>
<span class="identifier">permutation_type</span> <span class="identifier">it</span> <span class="special">=</span> <span class="identifier">begin</span><span class="special">;</span>
<span class="identifier">permutation_type</span> <span class="identifier">end</span> <span class="special">=</span> <span class="identifier">make_permutation_iterator</span><span class="special">(</span> <span class="identifier">elements</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">indices</span><span class="special">.</span><span class="identifier">end</span><span class="special">()</span> <span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"The original range is : "</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">copy</span><span class="special">(</span> <span class="identifier">elements</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">elements</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream_iterator</span><span class="special">&lt;</span> <span class="keyword">int</span> <span class="special">&gt;(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">,</span> <span class="string">" "</span> <span class="special">)</span> <span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"The reindexing scheme is : "</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">copy</span><span class="special">(</span> <span class="identifier">indices</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">indices</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream_iterator</span><span class="special">&lt;</span> <span class="keyword">int</span> <span class="special">&gt;(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">,</span> <span class="string">" "</span> <span class="special">)</span> <span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"The permutated range is : "</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">copy</span><span class="special">(</span> <span class="identifier">begin</span><span class="special">,</span> <span class="identifier">end</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream_iterator</span><span class="special">&lt;</span> <span class="keyword">int</span> <span class="special">&gt;(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">,</span> <span class="string">" "</span> <span class="special">)</span> <span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Elements at even indices in the permutation : "</span><span class="special">;</span>
<span class="identifier">it</span> <span class="special">=</span> <span class="identifier">begin</span><span class="special">;</span>
<span class="keyword">for</span><span class="special">(</span><span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="identifier">index_size</span> <span class="special">/</span> <span class="number">2</span> <span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">,</span> <span class="identifier">it</span><span class="special">+=</span><span class="number">2</span> <span class="special">)</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="special">*</span><span class="identifier">it</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Permutation backwards : "</span><span class="special">;</span>
<span class="identifier">it</span> <span class="special">=</span> <span class="identifier">begin</span> <span class="special">+</span> <span class="special">(</span><span class="identifier">index_size</span><span class="special">);</span>
<span class="identifier">assert</span><span class="special">(</span> <span class="identifier">it</span> <span class="special">!=</span> <span class="identifier">begin</span> <span class="special">);</span>
<span class="keyword">for</span><span class="special">(</span> <span class="special">;</span> <span class="identifier">it</span><span class="special">--</span> <span class="special">!=</span> <span class="identifier">begin</span> <span class="special">;</span> <span class="special">)</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="special">*</span><span class="identifier">it</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Iterate backward with stride 2 : "</span><span class="special">;</span>
<span class="identifier">it</span> <span class="special">=</span> <span class="identifier">begin</span> <span class="special">+</span> <span class="special">(</span><span class="identifier">index_size</span> <span class="special">-</span> <span class="number">1</span><span class="special">);</span>
<span class="keyword">for</span><span class="special">(</span><span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span> <span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="identifier">index_size</span> <span class="special">/</span> <span class="number">2</span> <span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">,</span> <span class="identifier">it</span><span class="special">-=</span><span class="number">2</span> <span class="special">)</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="special">*</span><span class="identifier">it</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
</pre>
<p>
The output is:
</p>
<pre class="programlisting"><span class="identifier">The</span> <span class="identifier">original</span> <span class="identifier">range</span> <span class="identifier">is</span> <span class="special">:</span> <span class="number">0</span> <span class="number">1</span> <span class="number">2</span> <span class="number">3</span> <span class="number">4</span> <span class="number">5</span> <span class="number">6</span> <span class="number">7</span> <span class="number">8</span> <span class="number">9</span>
<span class="identifier">The</span> <span class="identifier">reindexing</span> <span class="identifier">scheme</span> <span class="identifier">is</span> <span class="special">:</span> <span class="number">9</span> <span class="number">8</span> <span class="number">7</span> <span class="number">6</span>
<span class="identifier">The</span> <span class="identifier">permutated</span> <span class="identifier">range</span> <span class="identifier">is</span> <span class="special">:</span> <span class="number">9</span> <span class="number">8</span> <span class="number">7</span> <span class="number">6</span>
<span class="identifier">Elements</span> <span class="identifier">at</span> <span class="identifier">even</span> <span class="identifier">indices</span> <span class="identifier">in</span> <span class="identifier">the</span> <span class="identifier">permutation</span> <span class="special">:</span> <span class="number">9</span> <span class="number">7</span>
<span class="identifier">Permutation</span> <span class="identifier">backwards</span> <span class="special">:</span> <span class="number">6</span> <span class="number">7</span> <span class="number">8</span> <span class="number">9</span>
<span class="identifier">Iterate</span> <span class="identifier">backward</span> <span class="identifier">with</span> <span class="identifier">stride</span> <span class="number">2</span> <span class="special">:</span> <span class="number">6</span> <span class="number">8</span>
</pre>
<p>
The source code for this example can be found <a href="../../../example/permutation_iter_example.cpp" target="_top">here</a>.
</p>
<h3>
<a name="iterator.specialized.permutation.h1"></a>
<span class="phrase"><a name="iterator.specialized.permutation.reference"></a></span><a class="link" href="permutation.html#iterator.specialized.permutation.reference">Reference</a>
</h3>
<h4>
<a name="iterator.specialized.permutation.h2"></a>
<span class="phrase"><a name="iterator.specialized.permutation.synopsis"></a></span><a class="link" href="permutation.html#iterator.specialized.permutation.synopsis">Synopsis</a>
</h4>
<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">class</span> <span class="identifier">ElementIterator</span>
<span class="special">,</span> <span class="keyword">class</span> <span class="identifier">IndexIterator</span>
<span class="special">,</span> <span class="keyword">class</span> <span class="identifier">ValueT</span> <span class="special">=</span> <span class="identifier">use_default</span>
<span class="special">,</span> <span class="keyword">class</span> <span class="identifier">CategoryT</span> <span class="special">=</span> <span class="identifier">use_default</span>
<span class="special">,</span> <span class="keyword">class</span> <span class="identifier">ReferenceT</span> <span class="special">=</span> <span class="identifier">use_default</span>
<span class="special">,</span> <span class="keyword">class</span> <span class="identifier">DifferenceT</span> <span class="special">=</span> <span class="identifier">use_default</span> <span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">permutation_iterator</span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>
<span class="identifier">permutation_iterator</span><span class="special">();</span>
<span class="keyword">explicit</span> <span class="identifier">permutation_iterator</span><span class="special">(</span><span class="identifier">ElementIterator</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">IndexIterator</span> <span class="identifier">y</span><span class="special">);</span>
<span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">class</span> <span class="identifier">OEIter</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">OIIter</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">C</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">D</span> <span class="special">&gt;</span>
<span class="identifier">permutation_iterator</span><span class="special">(</span>
<span class="identifier">permutation_iterator</span><span class="special">&lt;</span><span class="identifier">OEIter</span><span class="special">,</span> <span class="identifier">OIIter</span><span class="special">,</span> <span class="identifier">V</span><span class="special">,</span> <span class="identifier">C</span><span class="special">,</span> <span class="identifier">R</span><span class="special">,</span> <span class="identifier">D</span><span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">r</span>
<span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">enable_if_convertible</span><span class="special">&lt;</span><span class="identifier">OEIter</span><span class="special">,</span> <span class="identifier">ElementIterator</span><span class="special">&gt;::</span><span class="identifier">type</span><span class="special">*</span> <span class="special">=</span> <span class="number">0</span>
<span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">enable_if_convertible</span><span class="special">&lt;</span><span class="identifier">OIIter</span><span class="special">,</span> <span class="identifier">IndexIterator</span><span class="special">&gt;::</span><span class="identifier">type</span><span class="special">*</span> <span class="special">=</span> <span class="number">0</span>
<span class="special">);</span>
<span class="identifier">reference</span> <span class="keyword">operator</span><span class="special">*()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="identifier">permutation_iterator</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">++();</span>
<span class="identifier">ElementIterator</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">base</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="keyword">private</span><span class="special">:</span>
<span class="identifier">ElementIterator</span> <span class="identifier">m_elt</span><span class="special">;</span> <span class="comment">// exposition only</span>
<span class="identifier">IndexIterator</span> <span class="identifier">m_order</span><span class="special">;</span> <span class="comment">// exposition only</span>
<span class="special">};</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">ElementIterator</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">IndexIterator</span><span class="special">&gt;</span>
<span class="identifier">permutation_iterator</span><span class="special">&lt;</span><span class="identifier">ElementIterator</span><span class="special">,</span> <span class="identifier">IndexIterator</span><span class="special">&gt;</span>
<span class="identifier">make_permutation_iterator</span><span class="special">(</span> <span class="identifier">ElementIterator</span> <span class="identifier">e</span><span class="special">,</span> <span class="identifier">IndexIterator</span> <span class="identifier">i</span><span class="special">);</span>
</pre>
<h4>
<a name="iterator.specialized.permutation.h3"></a>
<span class="phrase"><a name="iterator.specialized.permutation.requirements"></a></span><a class="link" href="permutation.html#iterator.specialized.permutation.requirements">Requirements</a>
</h4>
<p>
<code class="computeroutput"><span class="identifier">ElementIterator</span></code> shall model
Random Access Traversal Iterator. <code class="computeroutput"><span class="identifier">IndexIterator</span></code>
shall model Readable Iterator. The value type of the <code class="computeroutput"><span class="identifier">IndexIterator</span></code>
must be convertible to the difference type of <code class="computeroutput"><span class="identifier">ElementIterator</span></code>.
</p>
<h4>
<a name="iterator.specialized.permutation.h4"></a>
<span class="phrase"><a name="iterator.specialized.permutation.concepts"></a></span><a class="link" href="permutation.html#iterator.specialized.permutation.concepts">Concepts</a>
</h4>
<p>
<code class="computeroutput"><span class="identifier">permutation_iterator</span></code> models
the same iterator traversal concepts as <code class="computeroutput"><span class="identifier">IndexIterator</span></code>
and the same iterator access concepts as <code class="computeroutput"><span class="identifier">ElementIterator</span></code>.
</p>
<p>
If <code class="computeroutput"><span class="identifier">IndexIterator</span></code> models Single
Pass Iterator and <code class="computeroutput"><span class="identifier">ElementIterator</span></code>
models Readable Iterator then <code class="computeroutput"><span class="identifier">permutation_iterator</span></code>
models Input Iterator.
</p>
<p>
If <code class="computeroutput"><span class="identifier">IndexIterator</span></code> models Forward
Traversal Iterator and <code class="computeroutput"><span class="identifier">ElementIterator</span></code>
models Readable Lvalue Iterator then <code class="computeroutput"><span class="identifier">permutation_iterator</span></code>
models Forward Iterator.
</p>
<p>
If <code class="computeroutput"><span class="identifier">IndexIterator</span></code> models Bidirectional
Traversal Iterator and <code class="computeroutput"><span class="identifier">ElementIterator</span></code>
models Readable Lvalue Iterator then <code class="computeroutput"><span class="identifier">permutation_iterator</span></code>
models Bidirectional Iterator.
</p>
<p>
If <code class="computeroutput"><span class="identifier">IndexIterator</span></code> models Random
Access Traversal Iterator and <code class="computeroutput"><span class="identifier">ElementIterator</span></code>
models Readable Lvalue Iterator then <code class="computeroutput"><span class="identifier">permutation_iterator</span></code>
models Random Access Iterator.
</p>
<p>
<code class="computeroutput"><span class="identifier">permutation_iterator</span><span class="special">&lt;</span><span class="identifier">E1</span><span class="special">,</span> <span class="identifier">X</span><span class="special">,</span> <span class="identifier">V1</span><span class="special">,</span>
<span class="identifier">C2</span><span class="special">,</span> <span class="identifier">R1</span><span class="special">,</span> <span class="identifier">D1</span><span class="special">&gt;</span></code> is interoperable with <code class="computeroutput"><span class="identifier">permutation_iterator</span><span class="special">&lt;</span><span class="identifier">E2</span><span class="special">,</span> <span class="identifier">Y</span><span class="special">,</span>
<span class="identifier">V2</span><span class="special">,</span> <span class="identifier">C2</span><span class="special">,</span> <span class="identifier">R2</span><span class="special">,</span> <span class="identifier">D2</span><span class="special">&gt;</span></code>
if and only if <code class="computeroutput"><span class="identifier">X</span></code> is interoperable
with <code class="computeroutput"><span class="identifier">Y</span></code> and <code class="computeroutput"><span class="identifier">E1</span></code> is convertible to <code class="computeroutput"><span class="identifier">E2</span></code>.
</p>
<h4>
<a name="iterator.specialized.permutation.h5"></a>
<span class="phrase"><a name="iterator.specialized.permutation.operations"></a></span><a class="link" href="permutation.html#iterator.specialized.permutation.operations">Operations</a>
</h4>
<p>
In addition to those operations required by the concepts that <code class="computeroutput"><span class="identifier">permutation_iterator</span></code> models, <code class="computeroutput"><span class="identifier">permutation_iterator</span></code> provides the following
operations.
</p>
<pre class="programlisting"><span class="identifier">permutation_iterator</span><span class="special">();</span>
</pre>
<p>
<span class="bold"><strong>Effects: </strong></span> Default constructs <code class="computeroutput"><span class="identifier">m_elt</span></code> and <code class="computeroutput"><span class="identifier">m_order</span></code>.
</p>
<pre class="programlisting"><span class="keyword">explicit</span> <span class="identifier">permutation_iterator</span><span class="special">(</span><span class="identifier">ElementIterator</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">IndexIterator</span> <span class="identifier">y</span><span class="special">);</span>
</pre>
<p>
<span class="bold"><strong>Effects: </strong></span> Constructs <code class="computeroutput"><span class="identifier">m_elt</span></code>
from <code class="computeroutput"><span class="identifier">x</span></code> and <code class="computeroutput"><span class="identifier">m_order</span></code> from <code class="computeroutput"><span class="identifier">y</span></code>.
</p>
<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">class</span> <span class="identifier">OEIter</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">OIIter</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">C</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">D</span> <span class="special">&gt;</span>
<span class="identifier">permutation_iterator</span><span class="special">(</span>
<span class="identifier">permutation_iterator</span><span class="special">&lt;</span><span class="identifier">OEIter</span><span class="special">,</span> <span class="identifier">OIIter</span><span class="special">,</span> <span class="identifier">V</span><span class="special">,</span> <span class="identifier">C</span><span class="special">,</span> <span class="identifier">R</span><span class="special">,</span> <span class="identifier">D</span><span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">r</span>
<span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">enable_if_convertible</span><span class="special">&lt;</span><span class="identifier">OEIter</span><span class="special">,</span> <span class="identifier">ElementIterator</span><span class="special">&gt;::</span><span class="identifier">type</span><span class="special">*</span> <span class="special">=</span> <span class="number">0</span>
<span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">enable_if_convertible</span><span class="special">&lt;</span><span class="identifier">OIIter</span><span class="special">,</span> <span class="identifier">IndexIterator</span><span class="special">&gt;::</span><span class="identifier">type</span><span class="special">*</span> <span class="special">=</span> <span class="number">0</span>
<span class="special">);</span>
</pre>
<p>
<span class="bold"><strong>Effects: </strong></span> Constructs <code class="computeroutput"><span class="identifier">m_elt</span></code>
from <code class="computeroutput"><span class="identifier">r</span><span class="special">.</span><span class="identifier">m_elt</span></code> and <code class="computeroutput"><span class="identifier">m_order</span></code>
from <code class="computeroutput"><span class="identifier">y</span><span class="special">.</span><span class="identifier">m_order</span></code>.
</p>
<pre class="programlisting"><span class="identifier">reference</span> <span class="keyword">operator</span><span class="special">*()</span> <span class="keyword">const</span><span class="special">;</span>
</pre>
<p>
<span class="bold"><strong>Returns: </strong></span> <code class="computeroutput"><span class="special">*(</span><span class="identifier">m_elt</span> <span class="special">+</span> <span class="special">*</span><span class="identifier">m_order</span><span class="special">)</span></code>
</p>
<pre class="programlisting"><span class="identifier">permutation_iterator</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">++();</span>
</pre>
<p>
<span class="bold"><strong>Effects: </strong></span> <code class="computeroutput"><span class="special">++</span><span class="identifier">m_order</span></code><br> <span class="bold"><strong>Returns:
</strong></span> <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>
</p>
<pre class="programlisting"><span class="identifier">ElementIterator</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">base</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
</pre>
<p>
<span class="bold"><strong>Returns: </strong></span> <code class="computeroutput"><span class="identifier">m_order</span></code>
</p>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">ElementIterator</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">IndexIterator</span><span class="special">&gt;</span>
<span class="identifier">permutation_iterator</span><span class="special">&lt;</span><span class="identifier">ElementIterator</span><span class="special">,</span> <span class="identifier">IndexIterator</span><span class="special">&gt;</span>
<span class="identifier">make_permutation_iterator</span><span class="special">(</span><span class="identifier">ElementIterator</span> <span class="identifier">e</span><span class="special">,</span> <span class="identifier">IndexIterator</span> <span class="identifier">i</span><span class="special">);</span>
</pre>
<p>
<span class="bold"><strong>Returns: </strong></span> <code class="computeroutput"><span class="identifier">permutation_iterator</span><span class="special">&lt;</span><span class="identifier">ElementIterator</span><span class="special">,</span> <span class="identifier">IndexIterator</span><span class="special">&gt;(</span><span class="identifier">e</span><span class="special">,</span> <span class="identifier">i</span><span class="special">)</span></code>
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003, 2005 David Abrahams Jeremy Siek Thomas
Witt<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at &lt;ulink url="http://www.boost.org/LICENSE_1_0.txt"&gt;
http://www.boost.org/LICENSE_1_0.txt &lt;/ulink&gt;)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="indirect.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../specialized.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="reverse.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
libs/iterator/doc/html/iterator/specialized/reverse.html
+286
View File
@@ -0,0 +1,286 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Reverse Iterator</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="up" href="../specialized.html" title="Specialized Adaptors">
<link rel="prev" href="permutation.html" title="Permutation Iterator">
<link rel="next" href="shared_container.html" title="Shared Container Iterator">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="permutation.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../specialized.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="shared_container.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="iterator.specialized.reverse"></a><a class="link" href="reverse.html" title="Reverse Iterator">Reverse Iterator</a>
</h3></div></div></div>
<p>
The reverse iterator adaptor iterates through the adapted iterator range
in the opposite direction.
</p>
<h3>
<a name="iterator.specialized.reverse.h0"></a>
<span class="phrase"><a name="iterator.specialized.reverse.example"></a></span><a class="link" href="reverse.html#iterator.specialized.reverse.example">Example</a>
</h3>
<p>
The following example prints an array of characters in reverse order using
<code class="computeroutput"><span class="identifier">reverse_iterator</span></code>.
</p>
<pre class="programlisting"><span class="keyword">char</span> <span class="identifier">letters_</span><span class="special">[]</span> <span class="special">=</span> <span class="string">"hello world!"</span><span class="special">;</span>
<span class="keyword">const</span> <span class="keyword">int</span> <span class="identifier">N</span> <span class="special">=</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">letters_</span><span class="special">)/</span><span class="keyword">sizeof</span><span class="special">(</span><span class="keyword">char</span><span class="special">)</span> <span class="special">-</span> <span class="number">1</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">base_iterator</span><span class="special">;</span>
<span class="identifier">base_iterator</span> <span class="identifier">letters</span><span class="special">(</span><span class="identifier">letters_</span><span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"original sequence of letters:\t\t\t"</span> <span class="special">&lt;&lt;</span> <span class="identifier">letters_</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">reverse_iterator</span><span class="special">&lt;</span><span class="identifier">base_iterator</span><span class="special">&gt;</span>
<span class="identifier">reverse_letters_first</span><span class="special">(</span><span class="identifier">letters</span> <span class="special">+</span> <span class="identifier">N</span><span class="special">),</span>
<span class="identifier">reverse_letters_last</span><span class="special">(</span><span class="identifier">letters</span><span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"sequence in reverse order:\t\t\t"</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">copy</span><span class="special">(</span><span class="identifier">reverse_letters_first</span><span class="special">,</span> <span class="identifier">reverse_letters_last</span><span class="special">,</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream_iterator</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">));</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"sequence in double-reversed (normal) order:\t"</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">copy</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_reverse_iterator</span><span class="special">(</span><span class="identifier">reverse_letters_last</span><span class="special">),</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_reverse_iterator</span><span class="special">(</span><span class="identifier">reverse_letters_first</span><span class="special">),</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream_iterator</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">));</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
</pre>
<p>
The output is:
</p>
<pre class="programlisting"><span class="identifier">original</span> <span class="identifier">sequence</span> <span class="identifier">of</span> <span class="identifier">letters</span><span class="special">:</span> <span class="identifier">hello</span> <span class="identifier">world</span><span class="special">!</span>
<span class="identifier">sequence</span> <span class="identifier">in</span> <span class="identifier">reverse</span> <span class="identifier">order</span><span class="special">:</span> <span class="special">!</span><span class="identifier">dlrow</span> <span class="identifier">olleh</span>
<span class="identifier">sequence</span> <span class="identifier">in</span> <span class="keyword">double</span><span class="special">-</span><span class="identifier">reversed</span> <span class="special">(</span><span class="identifier">normal</span><span class="special">)</span> <span class="identifier">order</span><span class="special">:</span> <span class="identifier">hello</span> <span class="identifier">world</span><span class="special">!</span>
</pre>
<p>
The source code for this example can be found <a href="../../../example/reverse_iterator_example.cpp" target="_top">here</a>.
</p>
<h3>
<a name="iterator.specialized.reverse.h1"></a>
<span class="phrase"><a name="iterator.specialized.reverse.reference"></a></span><a class="link" href="reverse.html#iterator.specialized.reverse.reference">Reference</a>
</h3>
<h4>
<a name="iterator.specialized.reverse.h2"></a>
<span class="phrase"><a name="iterator.specialized.reverse.synopsis"></a></span><a class="link" href="reverse.html#iterator.specialized.reverse.synopsis">Synopsis</a>
</h4>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">reverse_iterator</span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>
<span class="keyword">typedef</span> <span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">value_type</span> <span class="identifier">value_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">reference</span> <span class="identifier">reference</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">pointer</span> <span class="identifier">pointer</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">difference_type</span> <span class="identifier">difference_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="comment">/* see below */</span> <span class="identifier">iterator_category</span><span class="special">;</span>
<span class="identifier">reverse_iterator</span><span class="special">()</span> <span class="special">{}</span>
<span class="keyword">explicit</span> <span class="identifier">reverse_iterator</span><span class="special">(</span><span class="identifier">Iterator</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">;</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">OtherIterator</span><span class="special">&gt;</span>
<span class="identifier">reverse_iterator</span><span class="special">(</span>
<span class="identifier">reverse_iterator</span><span class="special">&lt;</span><span class="identifier">OtherIterator</span><span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">r</span>
<span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">enable_if_convertible</span><span class="special">&lt;</span><span class="identifier">OtherIterator</span><span class="special">,</span> <span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">type</span><span class="special">*</span> <span class="special">=</span> <span class="number">0</span> <span class="comment">// exposition</span>
<span class="special">);</span>
<span class="identifier">Iterator</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">base</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="identifier">reference</span> <span class="keyword">operator</span><span class="special">*()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="identifier">reverse_iterator</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">++();</span>
<span class="identifier">reverse_iterator</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">--();</span>
<span class="keyword">private</span><span class="special">:</span>
<span class="identifier">Iterator</span> <span class="identifier">m_iterator</span><span class="special">;</span> <span class="comment">// exposition</span>
<span class="special">};</span>
</pre>
<p>
If <code class="computeroutput"><span class="identifier">Iterator</span></code> models Random
Access Traversal Iterator and Readable Lvalue Iterator, then <code class="computeroutput"><span class="identifier">iterator_category</span></code> is convertible to <code class="computeroutput"><span class="identifier">random_access_iterator_tag</span></code>. Otherwise,
if <code class="computeroutput"><span class="identifier">Iterator</span></code> models Bidirectional
Traversal Iterator and Readable Lvalue Iterator, then <code class="computeroutput"><span class="identifier">iterator_category</span></code>
is convertible to <code class="computeroutput"><span class="identifier">bidirectional_iterator_tag</span></code>.
Otherwise, <code class="computeroutput"><span class="identifier">iterator_category</span></code>
is convertible to <code class="computeroutput"><span class="identifier">input_iterator_tag</span></code>.
</p>
<h4>
<a name="iterator.specialized.reverse.h3"></a>
<span class="phrase"><a name="iterator.specialized.reverse.requirements"></a></span><a class="link" href="reverse.html#iterator.specialized.reverse.requirements">Requirements</a>
</h4>
<p>
<code class="computeroutput"><span class="identifier">Iterator</span></code> must be a model
of Bidirectional Traversal Iterator. The type <code class="computeroutput"><span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">reference</span></code>
must be the type of <code class="computeroutput"><span class="special">*</span><span class="identifier">i</span></code>,
where <code class="computeroutput"><span class="identifier">i</span></code> is an object of type
<code class="computeroutput"><span class="identifier">Iterator</span></code>.
</p>
<h4>
<a name="iterator.specialized.reverse.h4"></a>
<span class="phrase"><a name="iterator.specialized.reverse.concepts"></a></span><a class="link" href="reverse.html#iterator.specialized.reverse.concepts">Concepts</a>
</h4>
<p>
A specialization of <code class="computeroutput"><span class="identifier">reverse_iterator</span></code>
models the same iterator traversal and iterator access concepts modeled by
its <code class="computeroutput"><span class="identifier">Iterator</span></code> argument. In
addition, it may model old iterator concepts specified in the following table:
</p>
<div class="table">
<a name="iterator.specialized.reverse.categories"></a><p class="title"><b>Table&#160;1.15.&#160;Categories</b></p>
<div class="table-contents"><table class="table" summary="Categories">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
If <code class="computeroutput"><span class="identifier">I</span></code> models
</p>
</th>
<th>
<p>
then <code class="computeroutput"><span class="identifier">reverse_iterator</span><span class="special">&lt;</span><span class="identifier">I</span><span class="special">&gt;</span></code> models
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
Readable Lvalue Iterator, Bidirectional Traversal Iterator
</p>
</td>
<td>
<p>
Bidirectional Iterator
</p>
</td>
</tr>
<tr>
<td>
<p>
Writable Lvalue Iterator, Bidirectional Traversal Iterator
</p>
</td>
<td>
<p>
Mutable Bidirectional Iterator
</p>
</td>
</tr>
<tr>
<td>
<p>
Readable Lvalue Iterator, Random Access Traversal Iterator
</p>
</td>
<td>
<p>
Random Access Iterator
</p>
</td>
</tr>
<tr>
<td>
<p>
Writable Lvalue Iterator, Random Access Traversal Iterator
</p>
</td>
<td>
<p>
Mutable Random Access Iterator
</p>
</td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
<code class="computeroutput"><span class="identifier">reverse_iterator</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">&gt;</span></code> is
interoperable with <code class="computeroutput"><span class="identifier">reverse_iterator</span><span class="special">&lt;</span><span class="identifier">Y</span><span class="special">&gt;</span></code>
if and only if <code class="computeroutput"><span class="identifier">X</span></code> is interoperable
with <code class="computeroutput"><span class="identifier">Y</span></code>.
</p>
<h4>
<a name="iterator.specialized.reverse.h5"></a>
<span class="phrase"><a name="iterator.specialized.reverse.operations"></a></span><a class="link" href="reverse.html#iterator.specialized.reverse.operations">Operations</a>
</h4>
<p>
In addition to the operations required by the concepts modeled by <code class="computeroutput"><span class="identifier">reverse_iterator</span></code>, <code class="computeroutput"><span class="identifier">reverse_iterator</span></code>
provides the following operations.
</p>
<pre class="programlisting"><span class="identifier">reverse_iterator</span><span class="special">();</span>
</pre>
<p>
<span class="bold"><strong>Requires: </strong></span> <code class="computeroutput"><span class="identifier">Iterator</span></code>
must be Default Constructible.<br> <span class="bold"><strong>Effects: </strong></span>
Constructs an instance of <code class="computeroutput"><span class="identifier">reverse_iterator</span></code>
with <code class="computeroutput"><span class="identifier">m_iterator</span></code> default constructed.
</p>
<pre class="programlisting"><span class="keyword">explicit</span> <span class="identifier">reverse_iterator</span><span class="special">(</span><span class="identifier">Iterator</span> <span class="identifier">x</span><span class="special">);</span>
</pre>
<p>
<span class="bold"><strong>Effects: </strong></span> Constructs an instance of <code class="computeroutput"><span class="identifier">reverse_iterator</span></code> with <code class="computeroutput"><span class="identifier">m_iterator</span></code>
copy constructed from <code class="computeroutput"><span class="identifier">x</span></code>.
</p>
<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">OtherIterator</span><span class="special">&gt;</span>
<span class="identifier">reverse_iterator</span><span class="special">(</span>
<span class="identifier">reverse_iterator</span><span class="special">&lt;</span><span class="identifier">OtherIterator</span><span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">r</span>
<span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">enable_if_convertible</span><span class="special">&lt;</span><span class="identifier">OtherIterator</span><span class="special">,</span> <span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">type</span><span class="special">*</span> <span class="special">=</span> <span class="number">0</span> <span class="comment">// exposition</span>
<span class="special">);</span>
</pre>
<p>
<span class="bold"><strong>Requires: </strong></span> <code class="computeroutput"><span class="identifier">OtherIterator</span></code>
is implicitly convertible to <code class="computeroutput"><span class="identifier">Iterator</span></code>.<br>
<span class="bold"><strong>Effects: </strong></span> Constructs instance of <code class="computeroutput"><span class="identifier">reverse_iterator</span></code> whose <code class="computeroutput"><span class="identifier">m_iterator</span></code>
subobject is constructed from <code class="computeroutput"><span class="identifier">y</span><span class="special">.</span><span class="identifier">base</span><span class="special">()</span></code>.
</p>
<pre class="programlisting"><span class="identifier">Iterator</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">base</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
</pre>
<p>
<span class="bold"><strong>Returns: </strong></span> <code class="computeroutput"><span class="identifier">m_iterator</span></code>
</p>
<pre class="programlisting"><span class="identifier">reference</span> <span class="keyword">operator</span><span class="special">*()</span> <span class="keyword">const</span><span class="special">;</span>
</pre>
<p>
<span class="bold"><strong>Effects: </strong></span> Iterator tmp = m_iterator; return
*--tmp;
</p>
<pre class="programlisting"><span class="identifier">reverse_iterator</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">++();</span>
</pre>
<p>
<span class="bold"><strong>Effects: </strong></span> <code class="computeroutput"><span class="special">--</span><span class="identifier">m_iterator</span></code><br> <span class="bold"><strong>Returns:
</strong></span> <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>
</p>
<pre class="programlisting"><span class="identifier">reverse_iterator</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">--();</span>
</pre>
<p>
<span class="bold"><strong>Effects: </strong></span> <code class="computeroutput"><span class="special">++</span><span class="identifier">m_iterator</span></code><br> <span class="bold"><strong>Returns:
</strong></span> <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003, 2005 David Abrahams Jeremy Siek Thomas
Witt<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at &lt;ulink url="http://www.boost.org/LICENSE_1_0.txt"&gt;
http://www.boost.org/LICENSE_1_0.txt &lt;/ulink&gt;)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="permutation.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../specialized.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="shared_container.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
libs/iterator/doc/html/iterator/specialized/shared_container.html
+221
View File
@@ -0,0 +1,221 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Shared Container Iterator</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="up" href="../specialized.html" title="Specialized Adaptors">
<link rel="prev" href="reverse.html" title="Reverse Iterator">
<link rel="next" href="shared_container/shared_container_object_generator.html" title="The Shared Container Iterator Object Generator">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="reverse.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../specialized.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="shared_container/shared_container_object_generator.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="iterator.specialized.shared_container"></a><a class="link" href="shared_container.html" title="Shared Container Iterator">Shared Container
Iterator</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="shared_container.html#iterator.specialized.shared_container.shared_container_type">The
Shared Container Iterator Type</a></span></dt>
<dt><span class="section"><a href="shared_container/shared_container_object_generator.html">The
Shared Container Iterator Object Generator</a></span></dt>
<dt><span class="section"><a href="shared_container/shared_container_generator.html">The
Shared Container Iterator Range Generator</a></span></dt>
</dl></div>
<p>
Defined in header <a href="../../../../../boost/shared_container_iterator.hpp" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">shared_container_iterator</span><span class="special">.</span><span class="identifier">hpp</span></code></a>.
</p>
<p>
The purpose of the shared container iterator is to attach the lifetime of
a container to the lifetime of its iterators. In other words, the container
will not be deleted until after all its iterators are destroyed. The shared
container iterator is typically used to implement functions that return iterators
over a range of objects that only need to exist for the lifetime of the iterators.
By returning a pair of shared iterators from a function, the callee can return
a heap-allocated range of objects whose lifetime is automatically managed.
</p>
<p>
The shared container iterator augments an iterator over a shared container.
It maintains a reference count on the shared container. If only shared container
iterators hold references to the container, the container's lifetime will
end when the last shared container iterator over it is destroyed. In any
case, the shared container is guaranteed to persist beyond the lifetime of
all the iterators. In all other ways, the shared container iterator behaves
the same as its base iterator.
</p>
<h3>
<a name="iterator.specialized.shared_container.h0"></a>
<span class="phrase"><a name="iterator.specialized.shared_container.synopsis"></a></span><a class="link" href="shared_container.html#iterator.specialized.shared_container.synopsis">Synopsis</a>
</h3>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">shared_container_iterator</span><span class="special">;</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">&gt;</span>
<span class="identifier">shared_container_iterator</span><span class="special">&lt;</span><span class="identifier">Container</span><span class="special">&gt;</span>
<span class="identifier">make_shared_container_iterator</span><span class="special">(</span><span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">iterator</span> <span class="identifier">base</span><span class="special">,</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span><span class="identifier">Container</span><span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">container</span><span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span>
<span class="keyword">typename</span> <span class="identifier">shared_container_iterator</span><span class="special">&lt;</span><span class="identifier">Container</span><span class="special">&gt;,</span>
<span class="keyword">typename</span> <span class="identifier">shared_container_iterator</span><span class="special">&lt;</span><span class="identifier">Container</span><span class="special">&gt;</span>
<span class="special">&gt;</span>
<span class="identifier">make_shared_container_range</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span><span class="identifier">Container</span><span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">container</span><span class="special">);</span>
<span class="special">}</span>
</pre>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="iterator.specialized.shared_container.shared_container_type"></a><a class="link" href="shared_container.html#iterator.specialized.shared_container.shared_container_type" title="The Shared Container Iterator Type">The
Shared Container Iterator Type</a>
</h4></div></div></div>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">&gt;</span> <span class="keyword">class</span> <span class="identifier">shared_container_iterator</span><span class="special">;</span>
</pre>
<p>
The class template <code class="computeroutput"><span class="identifier">shared_container_iterator</span></code>
is the shared container iterator type. The <code class="computeroutput"><span class="identifier">Container</span></code>
template type argument must model the <a href="http://www.sgi.com/tech/stl/Container.html" target="_top">Container</a>
concept.
</p>
<h3>
<a name="iterator.specialized.shared_container.shared_container_type.h0"></a>
<span class="phrase"><a name="iterator.specialized.shared_container.shared_container_type.example"></a></span><a class="link" href="shared_container.html#iterator.specialized.shared_container.shared_container_type.example">Example</a>
</h3>
<p>
The following example illustrates how to create an iterator that regulates
the lifetime of a reference counted <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code>.
Though the original shared pointer <code class="computeroutput"><span class="identifier">ints</span></code>
ceases to exist after <code class="computeroutput"><span class="identifier">set_range</span><span class="special">()</span></code> returns, the <code class="computeroutput"><span class="identifier">shared_counter_iterator</span></code>
objects maintain references to the underlying vector and thereby extend
the container's lifetime.
</p>
<p>
<a href="../../../../../libs/utility/shared_iterator_example1.cpp" target="_top"><code class="computeroutput"><span class="identifier">shared_iterator_example1</span><span class="special">.</span><span class="identifier">cpp</span></code></a>:
</p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="string">"shared_container_iterator.hpp"</span>
<span class="preprocessor">#include</span> <span class="string">"boost/shared_ptr.hpp"</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">algorithm</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">vector</span><span class="special">&gt;</span>
<span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_container_iterator</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">iterator</span><span class="special">;</span>
<span class="keyword">void</span> <span class="identifier">set_range</span><span class="special">(</span><span class="identifier">iterator</span><span class="special">&amp;</span> <span class="identifier">i</span><span class="special">,</span> <span class="identifier">iterator</span><span class="special">&amp;</span> <span class="identifier">end</span><span class="special">)</span> <span class="special">{</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">ints</span><span class="special">(</span><span class="keyword">new</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;());</span>
<span class="identifier">ints</span><span class="special">-&gt;</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">0</span><span class="special">);</span>
<span class="identifier">ints</span><span class="special">-&gt;</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">1</span><span class="special">);</span>
<span class="identifier">ints</span><span class="special">-&gt;</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">2</span><span class="special">);</span>
<span class="identifier">ints</span><span class="special">-&gt;</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">3</span><span class="special">);</span>
<span class="identifier">ints</span><span class="special">-&gt;</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">4</span><span class="special">);</span>
<span class="identifier">ints</span><span class="special">-&gt;</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">5</span><span class="special">);</span>
<span class="identifier">i</span> <span class="special">=</span> <span class="identifier">iterator</span><span class="special">(</span><span class="identifier">ints</span><span class="special">-&gt;</span><span class="identifier">begin</span><span class="special">(),</span><span class="identifier">ints</span><span class="special">);</span>
<span class="identifier">end</span> <span class="special">=</span> <span class="identifier">iterator</span><span class="special">(</span><span class="identifier">ints</span><span class="special">-&gt;</span><span class="identifier">end</span><span class="special">(),</span><span class="identifier">ints</span><span class="special">);</span>
<span class="special">}</span>
<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> <span class="special">{</span>
<span class="identifier">iterator</span> <span class="identifier">i</span><span class="special">,</span><span class="identifier">end</span><span class="special">;</span>
<span class="identifier">set_range</span><span class="special">(</span><span class="identifier">i</span><span class="special">,</span><span class="identifier">end</span><span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">copy</span><span class="special">(</span><span class="identifier">i</span><span class="special">,</span><span class="identifier">end</span><span class="special">,</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream_iterator</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">,</span><span class="string">","</span><span class="special">));</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">.</span><span class="identifier">put</span><span class="special">(</span><span class="char">'\n'</span><span class="special">);</span>
<span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
The output from this part is:
</p>
<pre class="programlisting"><span class="number">0</span><span class="special">,</span><span class="number">1</span><span class="special">,</span><span class="number">2</span><span class="special">,</span><span class="number">3</span><span class="special">,</span><span class="number">4</span><span class="special">,</span><span class="number">5</span><span class="special">,</span>
</pre>
<div class="table">
<a name="iterator.specialized.shared_container.shared_container_type.template_parameters"></a><p class="title"><b>Table&#160;1.16.&#160;Template Parameters</b></p>
<div class="table-contents"><table class="table" summary="Template Parameters">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Parameter
</p>
</th>
<th>
<p>
Description
</p>
</th>
</tr></thead>
<tbody><tr>
<td>
<p>
Container
</p>
</td>
<td>
<p>
The type of the container that we wish to iterate over. It must
be a model of the Container concept.
</p>
</td>
</tr></tbody>
</table></div>
</div>
<br class="table-break"><h3>
<a name="iterator.specialized.shared_container.shared_container_type.h1"></a>
<span class="phrase"><a name="iterator.specialized.shared_container.shared_container_type.concepts"></a></span><a class="link" href="shared_container.html#iterator.specialized.shared_container.shared_container_type.concepts">Concepts</a>
</h3>
<p>
The <code class="computeroutput"><span class="identifier">shared_container_iterator</span></code>
type models the same iterator concept as the base iterator (<code class="computeroutput"><span class="identifier">Container</span><span class="special">::</span><span class="identifier">iterator</span></code>).
</p>
<h3>
<a name="iterator.specialized.shared_container.shared_container_type.h2"></a>
<span class="phrase"><a name="iterator.specialized.shared_container.shared_container_type.operations"></a></span><a class="link" href="shared_container.html#iterator.specialized.shared_container.shared_container_type.operations">Operations</a>
</h3>
<p>
The <code class="computeroutput"><span class="identifier">shared_container_iterator</span></code>
type implements the member functions and operators required of the <a href="http://www.sgi.com/tech/stl/RandomAccessIterator.html" target="_top">Random Access
Iterator</a> concept, though only operations defined for the base iterator
will be valid. In addition it has the following constructor:
</p>
<pre class="programlisting"><span class="identifier">shared_container_iterator</span><span class="special">(</span><span class="identifier">Container</span><span class="special">::</span><span class="identifier">iterator</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">it</span><span class="special">,</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span><span class="identifier">Container</span><span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">container</span><span class="special">)</span>
</pre>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003, 2005 David Abrahams Jeremy Siek Thomas
Witt<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at &lt;ulink url="http://www.boost.org/LICENSE_1_0.txt"&gt;
http://www.boost.org/LICENSE_1_0.txt &lt;/ulink&gt;)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="reverse.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../specialized.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="shared_container/shared_container_object_generator.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
libs/iterator/doc/html/iterator/specialized/shared_container/shared_container_generator.html
+109
View File
@@ -0,0 +1,109 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>The Shared Container Iterator Range Generator</title>
<link rel="stylesheet" href="../../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="up" href="../shared_container.html" title="Shared Container Iterator">
<link rel="prev" href="shared_container_object_generator.html" title="The Shared Container Iterator Object Generator">
<link rel="next" href="../transform.html" title="Transform Iterator">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="shared_container_object_generator.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../shared_container.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../transform.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="iterator.specialized.shared_container.shared_container_generator"></a><a class="link" href="shared_container_generator.html" title="The Shared Container Iterator Range Generator">The
Shared Container Iterator Range Generator</a>
</h4></div></div></div>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">&gt;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span>
<span class="identifier">shared_container_iterator</span><span class="special">&lt;</span><span class="identifier">Container</span><span class="special">&gt;,</span>
<span class="identifier">shared_container_iterator</span><span class="special">&lt;</span><span class="identifier">Container</span><span class="special">&gt;</span>
<span class="special">&gt;</span>
<span class="identifier">make_shared_container_range</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span><span class="identifier">Container</span><span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">container</span><span class="special">);</span>
<span class="identifier">Class</span> <span class="identifier">shared_container_iterator</span> <span class="identifier">is</span> <span class="identifier">meant</span> <span class="identifier">primarily</span> <span class="identifier">to</span> <span class="keyword">return</span><span class="special">,</span> <span class="keyword">using</span> <span class="identifier">iterators</span><span class="special">,</span> <span class="identifier">a</span> <span class="identifier">range</span> <span class="identifier">of</span> <span class="identifier">values</span> <span class="identifier">that</span> <span class="identifier">we</span> <span class="identifier">can</span> <span class="identifier">guarantee</span> <span class="identifier">will</span> <span class="identifier">be</span> <span class="identifier">alive</span> <span class="identifier">as</span> <span class="keyword">long</span> <span class="identifier">as</span> <span class="identifier">the</span> <span class="identifier">iterators</span> <span class="identifier">are</span><span class="special">.</span> <span class="identifier">This</span> <span class="identifier">is</span> <span class="identifier">a</span> <span class="identifier">convenience</span> <span class="identifier">function</span> <span class="identifier">to</span> <span class="keyword">do</span> <span class="identifier">just</span> <span class="identifier">that</span><span class="special">.</span> <span class="identifier">It</span> <span class="identifier">is</span> <span class="identifier">equivalent</span> <span class="identifier">to</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">make_pair</span><span class="special">(</span><span class="identifier">make_shared_container_iterator</span><span class="special">(</span><span class="identifier">container</span><span class="special">-&gt;</span><span class="identifier">begin</span><span class="special">(),</span><span class="identifier">container</span><span class="special">),</span>
<span class="identifier">make_shared_container_iterator</span><span class="special">(</span><span class="identifier">container</span><span class="special">-&gt;</span><span class="identifier">end</span><span class="special">(),</span><span class="identifier">container</span><span class="special">));</span>
</pre>
<h3>
<a name="iterator.specialized.shared_container.shared_container_generator.h0"></a>
<span class="phrase"><a name="iterator.specialized.shared_container.shared_container_generator.example"></a></span><a class="link" href="shared_container_generator.html#iterator.specialized.shared_container.shared_container_generator.example">Example</a>
</h3>
<p>
In the following example, a range of values is returned as a pair of shared_container_iterator
objects.
</p>
<p>
<a href="../../../../../../libs/utility/shared_iterator_example3.cpp" target="_top"><code class="computeroutput"><span class="identifier">shared_iterator_example3</span><span class="special">.</span><span class="identifier">cpp</span></code></a>:
</p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="string">"shared_container_iterator.hpp"</span>
<span class="preprocessor">#include</span> <span class="string">"boost/shared_ptr.hpp"</span>
<span class="preprocessor">#include</span> <span class="string">"boost/tuple/tuple.hpp"</span> <span class="comment">// for boost::tie</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">algorithm</span><span class="special">&gt;</span> <span class="comment">// for std::copy</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">vector</span><span class="special">&gt;</span>
<span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_container_iterator</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">iterator</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">iterator</span><span class="special">,</span><span class="identifier">iterator</span><span class="special">&gt;</span>
<span class="identifier">return_range</span><span class="special">()</span> <span class="special">{</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">range</span><span class="special">(</span><span class="keyword">new</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;());</span>
<span class="identifier">range</span><span class="special">-&gt;</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">0</span><span class="special">);</span>
<span class="identifier">range</span><span class="special">-&gt;</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">1</span><span class="special">);</span>
<span class="identifier">range</span><span class="special">-&gt;</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">2</span><span class="special">);</span>
<span class="identifier">range</span><span class="special">-&gt;</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">3</span><span class="special">);</span>
<span class="identifier">range</span><span class="special">-&gt;</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">4</span><span class="special">);</span>
<span class="identifier">range</span><span class="special">-&gt;</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">5</span><span class="special">);</span>
<span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_shared_container_range</span><span class="special">(</span><span class="identifier">range</span><span class="special">);</span>
<span class="special">}</span>
<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> <span class="special">{</span>
<span class="identifier">iterator</span> <span class="identifier">i</span><span class="special">,</span><span class="identifier">end</span><span class="special">;</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">tie</span><span class="special">(</span><span class="identifier">i</span><span class="special">,</span><span class="identifier">end</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">return_range</span><span class="special">();</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">copy</span><span class="special">(</span><span class="identifier">i</span><span class="special">,</span><span class="identifier">end</span><span class="special">,</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream_iterator</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">,</span><span class="string">","</span><span class="special">));</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">.</span><span class="identifier">put</span><span class="special">(</span><span class="char">'\n'</span><span class="special">);</span>
<span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
Though the range object only lives for the duration of the <code class="computeroutput"><span class="identifier">return_range</span></code> call, the reference counted
<code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code> will live until <code class="computeroutput"><span class="identifier">i</span></code> and <code class="computeroutput"><span class="identifier">end</span></code>
are both destroyed. The output from this example is the same as the previous
two.
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003, 2005 David Abrahams Jeremy Siek Thomas
Witt<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at &lt;ulink url="http://www.boost.org/LICENSE_1_0.txt"&gt;
http://www.boost.org/LICENSE_1_0.txt &lt;/ulink&gt;)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="shared_container_object_generator.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../shared_container.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../transform.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
libs/iterator/doc/html/iterator/specialized/shared_container/shared_container_object_generator.html
+110
View File
@@ -0,0 +1,110 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>The Shared Container Iterator Object Generator</title>
<link rel="stylesheet" href="../../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="up" href="../shared_container.html" title="Shared Container Iterator">
<link rel="prev" href="../shared_container.html" title="Shared Container Iterator">
<link rel="next" href="shared_container_generator.html" title="The Shared Container Iterator Range Generator">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../shared_container.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../shared_container.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="shared_container_generator.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="iterator.specialized.shared_container.shared_container_object_generator"></a><a class="link" href="shared_container_object_generator.html" title="The Shared Container Iterator Object Generator">The
Shared Container Iterator Object Generator</a>
</h4></div></div></div>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">&gt;</span>
<span class="identifier">shared_container_iterator</span><span class="special">&lt;</span><span class="identifier">Container</span><span class="special">&gt;</span>
<span class="identifier">make_shared_container_iterator</span><span class="special">(</span><span class="identifier">Container</span><span class="special">::</span><span class="identifier">iterator</span> <span class="identifier">base</span><span class="special">,</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span><span class="identifier">Container</span><span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">container</span><span class="special">)</span>
</pre>
<p>
This function provides an alternative to directly constructing a <code class="computeroutput"><span class="identifier">shared_container_iterator</span></code>. Using the
object generator, a <code class="computeroutput"><span class="identifier">shared_container_iterator</span></code>
can be created and passed to a function without explicitly specifying its
type.
</p>
<h3>
<a name="iterator.specialized.shared_container.shared_container_object_generator.h0"></a>
<span class="phrase"><a name="iterator.specialized.shared_container.shared_container_object_generator.example"></a></span><a class="link" href="shared_container_object_generator.html#iterator.specialized.shared_container.shared_container_object_generator.example">Example</a>
</h3>
<p>
This example, similar to the previous, uses <code class="computeroutput"><span class="identifier">make_shared_container_iterator</span><span class="special">()</span></code> to create the iterators.
</p>
<p>
<a href="../../../../../../libs/utility/shared_iterator_example2.cpp" target="_top"><code class="computeroutput"><span class="identifier">shared_iterator_example2</span><span class="special">.</span><span class="identifier">cpp</span></code></a>:
</p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="string">"shared_container_iterator.hpp"</span>
<span class="preprocessor">#include</span> <span class="string">"boost/shared_ptr.hpp"</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">algorithm</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iterator</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">vector</span><span class="special">&gt;</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
<span class="keyword">void</span> <span class="identifier">print_range_nl</span> <span class="special">(</span><span class="identifier">Iterator</span> <span class="identifier">begin</span><span class="special">,</span> <span class="identifier">Iterator</span> <span class="identifier">end</span><span class="special">)</span> <span class="special">{</span>
<span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">value_type</span> <span class="identifier">val</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">copy</span><span class="special">(</span><span class="identifier">begin</span><span class="special">,</span><span class="identifier">end</span><span class="special">,</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream_iterator</span><span class="special">&lt;</span><span class="identifier">val</span><span class="special">&gt;(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">,</span><span class="string">","</span><span class="special">));</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">.</span><span class="identifier">put</span><span class="special">(</span><span class="char">'\n'</span><span class="special">);</span>
<span class="special">}</span>
<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> <span class="special">{</span>
<span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">ints_t</span><span class="special">;</span>
<span class="special">{</span>
<span class="identifier">ints_t</span> <span class="identifier">ints</span><span class="special">(</span><span class="keyword">new</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;());</span>
<span class="identifier">ints</span><span class="special">-&gt;</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">0</span><span class="special">);</span>
<span class="identifier">ints</span><span class="special">-&gt;</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">1</span><span class="special">);</span>
<span class="identifier">ints</span><span class="special">-&gt;</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">2</span><span class="special">);</span>
<span class="identifier">ints</span><span class="special">-&gt;</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">3</span><span class="special">);</span>
<span class="identifier">ints</span><span class="special">-&gt;</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">4</span><span class="special">);</span>
<span class="identifier">ints</span><span class="special">-&gt;</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">5</span><span class="special">);</span>
<span class="identifier">print_range_nl</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_shared_container_iterator</span><span class="special">(</span><span class="identifier">ints</span><span class="special">-&gt;</span><span class="identifier">begin</span><span class="special">(),</span><span class="identifier">ints</span><span class="special">),</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_shared_container_iterator</span><span class="special">(</span><span class="identifier">ints</span><span class="special">-&gt;</span><span class="identifier">end</span><span class="special">(),</span><span class="identifier">ints</span><span class="special">));</span>
<span class="special">}</span>
<span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
Observe that the <code class="computeroutput"><span class="identifier">shared_container_iterator</span></code>
type is never explicitly named. The output from this example is the same
as the previous.
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003, 2005 David Abrahams Jeremy Siek Thomas
Witt<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at &lt;ulink url="http://www.boost.org/LICENSE_1_0.txt"&gt;
http://www.boost.org/LICENSE_1_0.txt &lt;/ulink&gt;)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../shared_container.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../shared_container.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="shared_container_generator.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
libs/iterator/doc/html/iterator/specialized/transform.html
+355
View File
@@ -0,0 +1,355 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Transform Iterator</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="up" href="../specialized.html" title="Specialized Adaptors">
<link rel="prev" href="shared_container/shared_container_generator.html" title="The Shared Container Iterator Range Generator">
<link rel="next" href="zip.html" title="Zip Iterator">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="shared_container/shared_container_generator.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../specialized.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="zip.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="iterator.specialized.transform"></a><a class="link" href="transform.html" title="Transform Iterator">Transform Iterator</a>
</h3></div></div></div>
<p>
The transform iterator adapts an iterator by modifying the <code class="computeroutput"><span class="keyword">operator</span><span class="special">*</span></code>
to apply a function object to the result of dereferencing the iterator and
returning the result.
</p>
<h3>
<a name="iterator.specialized.transform.h0"></a>
<span class="phrase"><a name="iterator.specialized.transform.example"></a></span><a class="link" href="transform.html#iterator.specialized.transform.example">Example</a>
</h3>
<p>
This is a simple example of using the transform_iterators class to generate
iterators that multiply (or add to) the value returned by dereferencing the
iterator. It would be cooler to use lambda library in this example.
</p>
<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">x</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span> <span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">,</span> <span class="number">3</span><span class="special">,</span> <span class="number">4</span><span class="special">,</span> <span class="number">5</span><span class="special">,</span> <span class="number">6</span><span class="special">,</span> <span class="number">7</span><span class="special">,</span> <span class="number">8</span> <span class="special">};</span>
<span class="keyword">const</span> <span class="keyword">int</span> <span class="identifier">N</span> <span class="special">=</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">x</span><span class="special">)/</span><span class="keyword">sizeof</span><span class="special">(</span><span class="keyword">int</span><span class="special">);</span>
<span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">binder1st</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">multiplies</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">Function</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">transform_iterator</span><span class="special">&lt;</span><span class="identifier">Function</span><span class="special">,</span> <span class="keyword">int</span><span class="special">*&gt;</span> <span class="identifier">doubling_iterator</span><span class="special">;</span>
<span class="identifier">doubling_iterator</span> <span class="identifier">i</span><span class="special">(</span><span class="identifier">x</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind1st</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">multiplies</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(),</span> <span class="number">2</span><span class="special">)),</span>
<span class="identifier">i_end</span><span class="special">(</span><span class="identifier">x</span> <span class="special">+</span> <span class="identifier">N</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind1st</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">multiplies</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(),</span> <span class="number">2</span><span class="special">));</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"multiplying the array by 2:"</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="keyword">while</span> <span class="special">(</span><span class="identifier">i</span> <span class="special">!=</span> <span class="identifier">i_end</span><span class="special">)</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="special">*</span><span class="identifier">i</span><span class="special">++</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"adding 4 to each element in the array:"</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">copy</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_transform_iterator</span><span class="special">(</span><span class="identifier">x</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind1st</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">plus</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(),</span> <span class="number">4</span><span class="special">)),</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_transform_iterator</span><span class="special">(</span><span class="identifier">x</span> <span class="special">+</span> <span class="identifier">N</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind1st</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">plus</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(),</span> <span class="number">4</span><span class="special">)),</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream_iterator</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">,</span> <span class="string">" "</span><span class="special">));</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
</pre>
<p>
The output is:
</p>
<pre class="programlisting"><span class="identifier">multiplying</span> <span class="identifier">the</span> <span class="identifier">array</span> <span class="identifier">by</span> <span class="number">2</span><span class="special">:</span>
<span class="number">2</span> <span class="number">4</span> <span class="number">6</span> <span class="number">8</span> <span class="number">10</span> <span class="number">12</span> <span class="number">14</span> <span class="number">16</span>
<span class="identifier">adding</span> <span class="number">4</span> <span class="identifier">to</span> <span class="identifier">each</span> <span class="identifier">element</span> <span class="identifier">in</span> <span class="identifier">the</span> <span class="identifier">array</span><span class="special">:</span>
<span class="number">5</span> <span class="number">6</span> <span class="number">7</span> <span class="number">8</span> <span class="number">9</span> <span class="number">10</span> <span class="number">11</span> <span class="number">12</span>
</pre>
<p>
The source code for this example can be found <a href="../../../example/transform_iterator_example.cpp" target="_top">here</a>.
</p>
<h3>
<a name="iterator.specialized.transform.h1"></a>
<span class="phrase"><a name="iterator.specialized.transform.reference"></a></span><a class="link" href="transform.html#iterator.specialized.transform.reference">Reference</a>
</h3>
<h4>
<a name="iterator.specialized.transform.h2"></a>
<span class="phrase"><a name="iterator.specialized.transform.synopsis"></a></span><a class="link" href="transform.html#iterator.specialized.transform.synopsis">Synopsis</a>
</h4>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">UnaryFunction</span><span class="special">,</span>
<span class="keyword">class</span> <span class="identifier">Iterator</span><span class="special">,</span>
<span class="keyword">class</span> <span class="identifier">Reference</span> <span class="special">=</span> <span class="identifier">use_default</span><span class="special">,</span>
<span class="keyword">class</span> <span class="identifier">Value</span> <span class="special">=</span> <span class="identifier">use_default</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">transform_iterator</span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>
<span class="keyword">typedef</span> <span class="comment">/* see below */</span> <span class="identifier">value_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="comment">/* see below */</span> <span class="identifier">reference</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="comment">/* see below */</span> <span class="identifier">pointer</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">difference_type</span> <span class="identifier">difference_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="comment">/* see below */</span> <span class="identifier">iterator_category</span><span class="special">;</span>
<span class="identifier">transform_iterator</span><span class="special">();</span>
<span class="identifier">transform_iterator</span><span class="special">(</span><span class="identifier">Iterator</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">UnaryFunction</span> <span class="identifier">f</span><span class="special">);</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">I2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V2</span><span class="special">&gt;</span>
<span class="identifier">transform_iterator</span><span class="special">(</span>
<span class="identifier">transform_iterator</span><span class="special">&lt;</span><span class="identifier">F2</span><span class="special">,</span> <span class="identifier">I2</span><span class="special">,</span> <span class="identifier">R2</span><span class="special">,</span> <span class="identifier">V2</span><span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">t</span>
<span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">enable_if_convertible</span><span class="special">&lt;</span><span class="identifier">I2</span><span class="special">,</span> <span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">type</span><span class="special">*</span> <span class="special">=</span> <span class="number">0</span> <span class="comment">// exposition only</span>
<span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">enable_if_convertible</span><span class="special">&lt;</span><span class="identifier">F2</span><span class="special">,</span> <span class="identifier">UnaryFunction</span><span class="special">&gt;::</span><span class="identifier">type</span><span class="special">*</span> <span class="special">=</span> <span class="number">0</span> <span class="comment">// exposition only</span>
<span class="special">);</span>
<span class="identifier">UnaryFunction</span> <span class="identifier">functor</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="identifier">Iterator</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">base</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="identifier">reference</span> <span class="keyword">operator</span><span class="special">*()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="identifier">transform_iterator</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">++();</span>
<span class="identifier">transform_iterator</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">--();</span>
<span class="keyword">private</span><span class="special">:</span>
<span class="identifier">Iterator</span> <span class="identifier">m_iterator</span><span class="special">;</span> <span class="comment">// exposition only</span>
<span class="identifier">UnaryFunction</span> <span class="identifier">m_f</span><span class="special">;</span> <span class="comment">// exposition only</span>
<span class="special">};</span>
</pre>
<p>
If <code class="computeroutput"><span class="identifier">Reference</span></code> is <code class="computeroutput"><span class="identifier">use_default</span></code> then the <code class="computeroutput"><span class="identifier">reference</span></code>
member of <code class="computeroutput"><span class="identifier">transform_iterator</span></code>
is<br> <code class="computeroutput"><span class="identifier">result_of</span><span class="special">&lt;</span><span class="identifier">UnaryFunction</span><span class="special">(</span><span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">reference</span><span class="special">)&gt;::</span><span class="identifier">type</span></code>. Otherwise, <code class="computeroutput"><span class="identifier">reference</span></code>
is <code class="computeroutput"><span class="identifier">Reference</span></code>.
</p>
<p>
If <code class="computeroutput"><span class="identifier">Value</span></code> is <code class="computeroutput"><span class="identifier">use_default</span></code> then the <code class="computeroutput"><span class="identifier">value_type</span></code>
member is <code class="computeroutput"><span class="identifier">remove_cv</span><span class="special">&lt;</span><span class="identifier">remove_reference</span><span class="special">&lt;</span><span class="identifier">reference</span><span class="special">&gt;</span>
<span class="special">&gt;::</span><span class="identifier">type</span></code>.
Otherwise, <code class="computeroutput"><span class="identifier">value_type</span></code> is
<code class="computeroutput"><span class="identifier">Value</span></code>.
</p>
<p>
If <code class="computeroutput"><span class="identifier">Iterator</span></code> models Readable
Lvalue Iterator and if <code class="computeroutput"><span class="identifier">Iterator</span></code>
models Random Access Traversal Iterator, then <code class="computeroutput"><span class="identifier">iterator_category</span></code>
is convertible to <code class="computeroutput"><span class="identifier">random_access_iterator_tag</span></code>.
Otherwise, if <code class="computeroutput"><span class="identifier">Iterator</span></code> models
Bidirectional Traversal Iterator, then <code class="computeroutput"><span class="identifier">iterator_category</span></code>
is convertible to <code class="computeroutput"><span class="identifier">bidirectional_iterator_tag</span></code>.
Otherwise <code class="computeroutput"><span class="identifier">iterator_category</span></code>
is convertible to <code class="computeroutput"><span class="identifier">forward_iterator_tag</span></code>.
If <code class="computeroutput"><span class="identifier">Iterator</span></code> does not model
Readable Lvalue Iterator then <code class="computeroutput"><span class="identifier">iterator_category</span></code>
is convertible to <code class="computeroutput"><span class="identifier">input_iterator_tag</span></code>.
</p>
<h4>
<a name="iterator.specialized.transform.h3"></a>
<span class="phrase"><a name="iterator.specialized.transform.requirements"></a></span><a class="link" href="transform.html#iterator.specialized.transform.requirements">Requirements</a>
</h4>
<p>
The type <code class="computeroutput"><span class="identifier">UnaryFunction</span></code> must
be Assignable, Copy Constructible, and the expression <code class="computeroutput"><span class="identifier">f</span><span class="special">(*</span><span class="identifier">i</span><span class="special">)</span></code>
must be valid where <code class="computeroutput"><span class="identifier">f</span></code> is
an object of type <code class="computeroutput"><span class="identifier">UnaryFunction</span></code>,
<code class="computeroutput"><span class="identifier">i</span></code> is an object of type <code class="computeroutput"><span class="identifier">Iterator</span></code>, and where the type of <code class="computeroutput"><span class="identifier">f</span><span class="special">(*</span><span class="identifier">i</span><span class="special">)</span></code> must be <code class="computeroutput"><span class="identifier">result_of</span><span class="special">&lt;</span><span class="identifier">UnaryFunction</span><span class="special">(</span><span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">reference</span><span class="special">)&gt;::</span><span class="identifier">type</span></code>.
</p>
<p>
The argument <code class="computeroutput"><span class="identifier">Iterator</span></code> shall
model Readable Iterator.
</p>
<h4>
<a name="iterator.specialized.transform.h4"></a>
<span class="phrase"><a name="iterator.specialized.transform.concepts"></a></span><a class="link" href="transform.html#iterator.specialized.transform.concepts">Concepts</a>
</h4>
<p>
The resulting <code class="computeroutput"><span class="identifier">transform_iterator</span></code>
models the most refined of the following that is also modeled by <code class="computeroutput"><span class="identifier">Iterator</span></code>.
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
Writable Lvalue Iterator if <code class="computeroutput"><span class="identifier">transform_iterator</span><span class="special">::</span><span class="identifier">reference</span></code>
is a non-const reference.
</li>
<li class="listitem">
Readable Lvalue Iterator if <code class="computeroutput"><span class="identifier">transform_iterator</span><span class="special">::</span><span class="identifier">reference</span></code>
is a const reference.
</li>
<li class="listitem">
Readable Iterator otherwise.
</li>
</ul></div>
<p>
The <code class="computeroutput"><span class="identifier">transform_iterator</span></code> models
the most refined standard traversal concept that is modeled by the <code class="computeroutput"><span class="identifier">Iterator</span></code> argument.
</p>
<p>
If <code class="computeroutput"><span class="identifier">transform_iterator</span></code> is
a model of Readable Lvalue Iterator then it models the following original
iterator concepts depending on what the <code class="computeroutput"><span class="identifier">Iterator</span></code>
argument models.
</p>
<div class="table">
<a name="iterator.specialized.transform.category"></a><p class="title"><b>Table&#160;1.17.&#160;Category</b></p>
<div class="table-contents"><table class="table" summary="Category">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
If <code class="computeroutput"><span class="identifier">Iterator</span></code> models
</p>
</th>
<th>
<p>
then <code class="computeroutput"><span class="identifier">transform_iterator</span></code>
models
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
Single Pass Iterator
</p>
</td>
<td>
<p>
Input Iterator
</p>
</td>
</tr>
<tr>
<td>
<p>
Forward Traversal Iterator
</p>
</td>
<td>
<p>
Forward Iterator
</p>
</td>
</tr>
<tr>
<td>
<p>
Bidirectional Traversal Iterator
</p>
</td>
<td>
<p>
Bidirectional Iterator
</p>
</td>
</tr>
<tr>
<td>
<p>
Random Access Traversal Iterator
</p>
</td>
<td>
<p>
Random Access Iterator
</p>
</td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
If <code class="computeroutput"><span class="identifier">transform_iterator</span></code> models
Writable Lvalue Iterator then it is a mutable iterator (as defined in the
old iterator requirements).
</p>
<p>
<code class="computeroutput"><span class="identifier">transform_iterator</span><span class="special">&lt;</span><span class="identifier">F1</span><span class="special">,</span> <span class="identifier">X</span><span class="special">,</span> <span class="identifier">R1</span><span class="special">,</span>
<span class="identifier">V1</span><span class="special">&gt;</span></code>
is interoperable with <code class="computeroutput"><span class="identifier">transform_iterator</span><span class="special">&lt;</span><span class="identifier">F2</span><span class="special">,</span> <span class="identifier">Y</span><span class="special">,</span>
<span class="identifier">R2</span><span class="special">,</span> <span class="identifier">V2</span><span class="special">&gt;</span></code>
if and only if <code class="computeroutput"><span class="identifier">X</span></code> is interoperable
with <code class="computeroutput"><span class="identifier">Y</span></code>.
</p>
<h4>
<a name="iterator.specialized.transform.h5"></a>
<span class="phrase"><a name="iterator.specialized.transform.operations"></a></span><a class="link" href="transform.html#iterator.specialized.transform.operations">Operations</a>
</h4>
<p>
In addition to the operations required by the <a class="link" href="transform.html#iterator.specialized.transform.concepts">concepts</a>
modeled by <code class="computeroutput"><span class="identifier">transform_iterator</span></code>,
<code class="computeroutput"><span class="identifier">transform_iterator</span></code> provides
the following operations:
</p>
<pre class="programlisting"><span class="identifier">transform_iterator</span><span class="special">();</span>
</pre>
<p>
<span class="bold"><strong>Returns: </strong></span> An instance of <code class="computeroutput"><span class="identifier">transform_iterator</span></code>
with <code class="computeroutput"><span class="identifier">m_f</span></code> and <code class="computeroutput"><span class="identifier">m_iterator</span></code> default constructed.
</p>
<pre class="programlisting"><span class="identifier">transform_iterator</span><span class="special">(</span><span class="identifier">Iterator</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">UnaryFunction</span> <span class="identifier">f</span><span class="special">);</span>
</pre>
<p>
<span class="bold"><strong>Returns: </strong></span> An instance of <code class="computeroutput"><span class="identifier">transform_iterator</span></code>
with <code class="computeroutput"><span class="identifier">m_f</span></code> initialized to
<code class="computeroutput"><span class="identifier">f</span></code> and <code class="computeroutput"><span class="identifier">m_iterator</span></code>
initialized to <code class="computeroutput"><span class="identifier">x</span></code>.
</p>
<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">I2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V2</span><span class="special">&gt;</span>
<span class="identifier">transform_iterator</span><span class="special">(</span>
<span class="identifier">transform_iterator</span><span class="special">&lt;</span><span class="identifier">F2</span><span class="special">,</span> <span class="identifier">I2</span><span class="special">,</span> <span class="identifier">R2</span><span class="special">,</span> <span class="identifier">V2</span><span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">t</span>
<span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">enable_if_convertible</span><span class="special">&lt;</span><span class="identifier">I2</span><span class="special">,</span> <span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">type</span><span class="special">*</span> <span class="special">=</span> <span class="number">0</span> <span class="comment">// exposition only</span>
<span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">enable_if_convertible</span><span class="special">&lt;</span><span class="identifier">F2</span><span class="special">,</span> <span class="identifier">UnaryFunction</span><span class="special">&gt;::</span><span class="identifier">type</span><span class="special">*</span> <span class="special">=</span> <span class="number">0</span> <span class="comment">// exposition only</span>
<span class="special">);</span>
</pre>
<p>
<span class="bold"><strong>Returns: </strong></span> An instance of <code class="computeroutput"><span class="identifier">transform_iterator</span></code>
with <code class="computeroutput"><span class="identifier">m_f</span></code> initialized to
<code class="computeroutput"><span class="identifier">t</span><span class="special">.</span><span class="identifier">functor</span><span class="special">()</span></code>
and <code class="computeroutput"><span class="identifier">m_iterator</span></code> initialized
to <code class="computeroutput"><span class="identifier">t</span><span class="special">.</span><span class="identifier">base</span><span class="special">()</span></code>.<br>
<span class="bold"><strong>Requires: </strong></span> <code class="computeroutput"><span class="identifier">OtherIterator</span></code>
is implicitly convertible to <code class="computeroutput"><span class="identifier">Iterator</span></code>.
</p>
<pre class="programlisting"><span class="identifier">UnaryFunction</span> <span class="identifier">functor</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
</pre>
<p>
<span class="bold"><strong>Returns: </strong></span> <code class="computeroutput"><span class="identifier">m_f</span></code>
</p>
<pre class="programlisting"><span class="identifier">Iterator</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">base</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
</pre>
<p>
<span class="bold"><strong>Returns: </strong></span> <code class="computeroutput"><span class="identifier">m_iterator</span></code>
</p>
<pre class="programlisting"><span class="identifier">reference</span> <span class="keyword">operator</span><span class="special">*()</span> <span class="keyword">const</span><span class="special">;</span>
</pre>
<p>
<span class="bold"><strong>Returns: </strong></span> <code class="computeroutput"><span class="identifier">m_f</span><span class="special">(*</span><span class="identifier">m_iterator</span><span class="special">)</span></code>
</p>
<pre class="programlisting"><span class="identifier">transform_iterator</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">++();</span>
</pre>
<p>
<span class="bold"><strong>Effects: </strong></span> <code class="computeroutput"><span class="special">++</span><span class="identifier">m_iterator</span></code><br> <span class="bold"><strong>Returns:
</strong></span> <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>
</p>
<pre class="programlisting"><span class="identifier">transform_iterator</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">--();</span>
</pre>
<p>
<span class="bold"><strong>Effects: </strong></span> <code class="computeroutput"><span class="special">--</span><span class="identifier">m_iterator</span></code><br> <span class="bold"><strong>Returns:
</strong></span> <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003, 2005 David Abrahams Jeremy Siek Thomas
Witt<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at &lt;ulink url="http://www.boost.org/LICENSE_1_0.txt"&gt;
http://www.boost.org/LICENSE_1_0.txt &lt;/ulink&gt;)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="shared_container/shared_container_generator.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../specialized.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="zip.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
libs/iterator/doc/html/iterator/specialized/zip.html
+177
View File
@@ -0,0 +1,177 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Zip Iterator</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="up" href="../specialized.html" title="Specialized Adaptors">
<link rel="prev" href="transform.html" title="Transform Iterator">
<link rel="next" href="zip/zip_reference.html" title="Reference">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="transform.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../specialized.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="zip/zip_reference.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="iterator.specialized.zip"></a><a class="link" href="zip.html" title="Zip Iterator">Zip Iterator</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="zip.html#iterator.specialized.zip.zip_example">Example</a></span></dt>
<dt><span class="section"><a href="zip/zip_reference.html">Reference</a></span></dt>
</dl></div>
<p>
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.
</p>
<p>
The tuple of iterators is now implemented in terms of a Boost fusion sequence.
Because of this the 'tuple' may be any Boost fusion sequence and, for backwards
compatibility through a Boost fusion sequence adapter, a Boost tuple. Because
the 'tuple' may be any boost::fusion sequence the 'tuple' may also be any
type for which a Boost fusion adapter exists. This includes, among others,
a std::tuple and a std::pair. Just remember to include the appropriate Boost
fusion adapter header files for these other Boost fusion adapters. The zip_iterator
header file already includes the Boost fusion adapter header file for Boost
tuple, so you need not include it yourself to use a Boost tuple as your 'tuple'.
</p>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="iterator.specialized.zip.zip_example"></a><a class="link" href="zip.html#iterator.specialized.zip.zip_example" title="Example">Example</a>
</h4></div></div></div>
<p>
There are two main types of applications of the <code class="computeroutput"><span class="identifier">zip_iterator</span></code>.
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 <code class="computeroutput"><span class="identifier">for_each</span></code> algorithm,
then it is more efficient to perform just one parallel-iteration rather
than several individual iterations. For an example, assume that <code class="computeroutput"><span class="identifier">vect_of_doubles</span></code> and <code class="computeroutput"><span class="identifier">vect_of_ints</span></code>
are two vectors of equal length containing doubles and ints, respectively,
and consider the following two iterations:
</p>
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;::</span><span class="identifier">const_iterator</span> <span class="identifier">beg1</span> <span class="special">=</span> <span class="identifier">vect_of_doubles</span><span class="special">.</span><span class="identifier">begin</span><span class="special">();</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;::</span><span class="identifier">const_iterator</span> <span class="identifier">end1</span> <span class="special">=</span> <span class="identifier">vect_of_doubles</span><span class="special">.</span><span class="identifier">end</span><span class="special">();</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;::</span><span class="identifier">const_iterator</span> <span class="identifier">beg2</span> <span class="special">=</span> <span class="identifier">vect_of_ints</span><span class="special">.</span><span class="identifier">begin</span><span class="special">();</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;::</span><span class="identifier">const_iterator</span> <span class="identifier">end2</span> <span class="special">=</span> <span class="identifier">vect_of_ints</span><span class="special">.</span><span class="identifier">end</span><span class="special">();</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">beg1</span><span class="special">,</span> <span class="identifier">end1</span><span class="special">,</span> <span class="identifier">func_0</span><span class="special">());</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">beg2</span><span class="special">,</span> <span class="identifier">end2</span><span class="special">,</span> <span class="identifier">func_1</span><span class="special">());</span>
</pre>
<p>
These two iterations can now be replaced with a single one as follows:
</p>
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_zip_iterator</span><span class="special">(</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">beg1</span><span class="special">,</span> <span class="identifier">beg2</span><span class="special">)</span>
<span class="special">),</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_zip_iterator</span><span class="special">(</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">end1</span><span class="special">,</span> <span class="identifier">end2</span><span class="special">)</span>
<span class="special">),</span>
<span class="identifier">zip_func</span><span class="special">()</span>
<span class="special">);</span>
</pre>
<p>
A non-generic implementation of <code class="computeroutput"><span class="identifier">zip_func</span></code>
could look as follows:
</p>
<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">zip_func</span> <span class="special">:</span>
<span class="keyword">public</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">unary_function</span><span class="special">&lt;</span><span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">tuple</span><span class="special">&lt;</span><span class="keyword">const</span> <span class="keyword">double</span><span class="special">&amp;,</span> <span class="keyword">const</span> <span class="keyword">int</span><span class="special">&amp;&gt;&amp;,</span> <span class="keyword">void</span><span class="special">&gt;</span>
<span class="special">{</span>
<span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span><span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">tuple</span><span class="special">&lt;</span><span class="keyword">const</span> <span class="keyword">double</span><span class="special">&amp;,</span> <span class="keyword">const</span> <span class="keyword">int</span><span class="special">&amp;&gt;&amp;</span> <span class="identifier">t</span><span class="special">)</span> <span class="keyword">const</span>
<span class="special">{</span>
<span class="identifier">m_f0</span><span class="special">(</span><span class="identifier">t</span><span class="special">.</span><span class="identifier">get</span><span class="special">&lt;</span><span class="number">0</span><span class="special">&gt;());</span>
<span class="identifier">m_f1</span><span class="special">(</span><span class="identifier">t</span><span class="special">.</span><span class="identifier">get</span><span class="special">&lt;</span><span class="number">1</span><span class="special">&gt;());</span>
<span class="special">}</span>
<span class="keyword">private</span><span class="special">:</span>
<span class="identifier">func_0</span> <span class="identifier">m_f0</span><span class="special">;</span>
<span class="identifier">func_1</span> <span class="identifier">m_f1</span><span class="special">;</span>
<span class="special">};</span>
</pre>
<p>
The second important application of the <code class="computeroutput"><span class="identifier">zip_iterator</span></code>
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 <code class="computeroutput"><span class="identifier">zip_iterator</span></code>
in conjunction with the <code class="computeroutput"><span class="identifier">transform_iterator</span></code>.
</p>
<p>
Suppose, for example, that you have two vectors of doubles, say <code class="computeroutput"><span class="identifier">vect_1</span></code> and <code class="computeroutput"><span class="identifier">vect_2</span></code>,
and you need to expose to a client a controlled sequence containing the
products of the elements of <code class="computeroutput"><span class="identifier">vect_1</span></code>
and <code class="computeroutput"><span class="identifier">vect_2</span></code>. 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 <code class="computeroutput"><span class="identifier">tuple_multiplies</span></code> is a functor that works
like <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">multiplies</span></code>, except that it takes its
two arguments packaged in a tuple. Then the two iterators <code class="computeroutput"><span class="identifier">it_begin</span></code> and <code class="computeroutput"><span class="identifier">it_end</span></code>
defined below delimit a controlled sequence containing the products of
the elements of <code class="computeroutput"><span class="identifier">vect_1</span></code>
and <code class="computeroutput"><span class="identifier">vect_2</span></code>:
</p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">tuple</span><span class="special">&lt;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;::</span><span class="identifier">const_iterator</span><span class="special">,</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;::</span><span class="identifier">const_iterator</span>
<span class="special">&gt;</span> <span class="identifier">the_iterator_tuple</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">zip_iterator</span><span class="special">&lt;</span>
<span class="identifier">the_iterator_tuple</span>
<span class="special">&gt;</span> <span class="identifier">the_zip_iterator</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">transform_iterator</span><span class="special">&lt;</span>
<span class="identifier">tuple_multiplies</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;,</span>
<span class="identifier">the_zip_iterator</span>
<span class="special">&gt;</span> <span class="identifier">the_transform_iterator</span><span class="special">;</span>
<span class="identifier">the_transform_iterator</span> <span class="identifier">it_begin</span><span class="special">(</span>
<span class="identifier">the_zip_iterator</span><span class="special">(</span>
<span class="identifier">the_iterator_tuple</span><span class="special">(</span>
<span class="identifier">vect_1</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span>
<span class="identifier">vect_2</span><span class="special">.</span><span class="identifier">begin</span><span class="special">()</span>
<span class="special">)</span>
<span class="special">),</span>
<span class="identifier">tuple_multiplies</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;()</span>
<span class="special">);</span>
<span class="identifier">the_transform_iterator</span> <span class="identifier">it_end</span><span class="special">(</span>
<span class="identifier">the_zip_iterator</span><span class="special">(</span>
<span class="identifier">the_iterator_tuple</span><span class="special">(</span>
<span class="identifier">vect_1</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span>
<span class="identifier">vect_2</span><span class="special">.</span><span class="identifier">end</span><span class="special">()</span>
<span class="special">)</span>
<span class="special">),</span>
<span class="identifier">tuple_multiplies</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;()</span>
<span class="special">);</span>
</pre>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003, 2005 David Abrahams Jeremy Siek Thomas
Witt<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at &lt;ulink url="http://www.boost.org/LICENSE_1_0.txt"&gt;
http://www.boost.org/LICENSE_1_0.txt &lt;/ulink&gt;)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="transform.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../specialized.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="zip/zip_reference.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
libs/iterator/doc/html/iterator/specialized/zip/zip_reference.html
+213
View File
@@ -0,0 +1,213 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Reference</title>
<link rel="stylesheet" href="../../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="up" href="../zip.html" title="Zip Iterator">
<link rel="prev" href="../zip.html" title="Zip Iterator">
<link rel="next" href="../../utilities.html" title="Utilities">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../zip.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../zip.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../../utilities.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="iterator.specialized.zip.zip_reference"></a><a class="link" href="zip_reference.html" title="Reference">Reference</a>
</h4></div></div></div>
<h3>
<a name="iterator.specialized.zip.zip_reference.h0"></a>
<span class="phrase"><a name="iterator.specialized.zip.zip_reference.synopsis"></a></span><a class="link" href="zip_reference.html#iterator.specialized.zip.zip_reference.synopsis">Synopsis</a>
</h3>
<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">IteratorTuple</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">zip_iterator</span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>
<span class="keyword">typedef</span> <span class="comment">/* see below */</span> <span class="identifier">reference</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">reference</span> <span class="identifier">value_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">value_type</span><span class="special">*</span> <span class="identifier">pointer</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="comment">/* see below */</span> <span class="identifier">difference_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="comment">/* see below */</span> <span class="identifier">iterator_category</span><span class="special">;</span>
<span class="identifier">zip_iterator</span><span class="special">();</span>
<span class="identifier">zip_iterator</span><span class="special">(</span><span class="identifier">IteratorTuple</span> <span class="identifier">iterator_tuple</span><span class="special">);</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">OtherIteratorTuple</span><span class="special">&gt;</span>
<span class="identifier">zip_iterator</span><span class="special">(</span>
<span class="keyword">const</span> <span class="identifier">zip_iterator</span><span class="special">&lt;</span><span class="identifier">OtherIteratorTuple</span><span class="special">&gt;&amp;</span> <span class="identifier">other</span>
<span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">enable_if_convertible</span><span class="special">&lt;</span>
<span class="identifier">OtherIteratorTuple</span>
<span class="special">,</span> <span class="identifier">IteratorTuple</span><span class="special">&gt;::</span><span class="identifier">type</span><span class="special">*</span> <span class="special">=</span> <span class="number">0</span> <span class="comment">// exposition only</span>
<span class="special">);</span>
<span class="keyword">const</span> <span class="identifier">IteratorTuple</span><span class="special">&amp;</span> <span class="identifier">get_iterator_tuple</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
<span class="keyword">private</span><span class="special">:</span>
<span class="identifier">IteratorTuple</span> <span class="identifier">m_iterator_tuple</span><span class="special">;</span> <span class="comment">// exposition only</span>
<span class="special">};</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">IteratorTuple</span><span class="special">&gt;</span>
<span class="identifier">zip_iterator</span><span class="special">&lt;</span><span class="identifier">IteratorTuple</span><span class="special">&gt;</span>
<span class="identifier">make_zip_iterator</span><span class="special">(</span><span class="identifier">IteratorTuple</span> <span class="identifier">t</span><span class="special">);</span>
</pre>
<p>
The <code class="computeroutput"><span class="identifier">reference</span></code> member of
<code class="computeroutput"><span class="identifier">zip_iterator</span></code> is the type
of the tuple made of the reference types of the iterator types in the
<code class="computeroutput"><span class="identifier">IteratorTuple</span></code> argument.
</p>
<p>
The <code class="computeroutput"><span class="identifier">difference_type</span></code> member
of <code class="computeroutput"><span class="identifier">zip_iterator</span></code> is the
<code class="computeroutput"><span class="identifier">difference_type</span></code> of the
first of the iterator types in the <code class="computeroutput"><span class="identifier">IteratorTuple</span></code>
argument.
</p>
<p>
The <code class="computeroutput"><span class="identifier">iterator_category</span></code> member
of <code class="computeroutput"><span class="identifier">zip_iterator</span></code> is convertible
to the minimum of the traversal categories of the iterator types in the
<code class="computeroutput"><span class="identifier">IteratorTuple</span></code> argument.
For example, if the <code class="computeroutput"><span class="identifier">zip_iterator</span></code>
holds only vector iterators, then <code class="computeroutput"><span class="identifier">iterator_category</span></code>
is convertible to <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">random_access_traversal_tag</span></code>.
If you add a list iterator, then <code class="computeroutput"><span class="identifier">iterator_category</span></code>
will be convertible to <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">bidirectional_traversal_tag</span></code>,
but no longer to <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">random_access_traversal_tag</span></code>.
</p>
<h3>
<a name="iterator.specialized.zip.zip_reference.h1"></a>
<span class="phrase"><a name="iterator.specialized.zip.zip_reference.requirements"></a></span><a class="link" href="zip_reference.html#iterator.specialized.zip.zip_reference.requirements">Requirements</a>
</h3>
<p>
All iterator types in the argument <code class="computeroutput"><span class="identifier">IteratorTuple</span></code>
shall model Readable Iterator.
</p>
<h3>
<a name="iterator.specialized.zip.zip_reference.h2"></a>
<span class="phrase"><a name="iterator.specialized.zip.zip_reference.concepts"></a></span><a class="link" href="zip_reference.html#iterator.specialized.zip.zip_reference.concepts">Concepts</a>
</h3>
<p>
The resulting <code class="computeroutput"><span class="identifier">zip_iterator</span></code>
models Readable Iterator.
</p>
<p>
The fact that the <code class="computeroutput"><span class="identifier">zip_iterator</span></code>
models only Readable Iterator does not prevent you from modifying the values
that the individual iterators point to. The tuple returned by the <code class="computeroutput"><span class="identifier">zip_iterator</span></code>'s <code class="computeroutput"><span class="keyword">operator</span><span class="special">*</span></code> is a tuple constructed from the reference
types of the individual iterators, not their value types. For example,
if <code class="computeroutput"><span class="identifier">zip_it</span></code> is a <code class="computeroutput"><span class="identifier">zip_iterator</span></code> whose first member iterator
is an <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;::</span><span class="identifier">iterator</span></code>, then the following line will
modify the value which the first member iterator of <code class="computeroutput"><span class="identifier">zip_it</span></code>
currently points to:
</p>
<pre class="programlisting"><span class="identifier">zip_it</span><span class="special">-&gt;</span><span class="identifier">get</span><span class="special">&lt;</span><span class="number">0</span><span class="special">&gt;()</span> <span class="special">=</span> <span class="number">42.0</span><span class="special">;</span>
</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 <code class="computeroutput"><span class="identifier">IteratorTuple</span></code>
argument.The <code class="computeroutput"><span class="identifier">zip_iterator</span></code>
models the least refined standard traversal concept in this set.
</p>
<p>
<code class="computeroutput"><span class="identifier">zip_iterator</span><span class="special">&lt;</span><span class="identifier">IteratorTuple1</span><span class="special">&gt;</span></code>
is interoperable with <code class="computeroutput"><span class="identifier">zip_iterator</span><span class="special">&lt;</span><span class="identifier">IteratorTuple2</span><span class="special">&gt;</span></code> if and only if <code class="computeroutput"><span class="identifier">IteratorTuple1</span></code>
is interoperable with <code class="computeroutput"><span class="identifier">IteratorTuple2</span></code>.
</p>
<h3>
<a name="iterator.specialized.zip.zip_reference.h3"></a>
<span class="phrase"><a name="iterator.specialized.zip.zip_reference.operations"></a></span><a class="link" href="zip_reference.html#iterator.specialized.zip.zip_reference.operations">Operations</a>
</h3>
<p>
In addition to the operations required by the concepts modeled by <code class="computeroutput"><span class="identifier">zip_iterator</span></code>, <code class="computeroutput"><span class="identifier">zip_iterator</span></code>
provides the following operations.
</p>
<pre class="programlisting"><span class="identifier">zip_iterator</span><span class="special">();</span>
</pre>
<p>
<span class="bold"><strong>Returns:</strong></span> An instance of <code class="computeroutput"><span class="identifier">zip_iterator</span></code> with <code class="computeroutput"><span class="identifier">m_iterator_tuple</span></code>
default constructed.
</p>
<pre class="programlisting"><span class="identifier">zip_iterator</span><span class="special">(</span><span class="identifier">IteratorTuple</span> <span class="identifier">iterator_tuple</span><span class="special">);</span>
</pre>
<p>
<span class="bold"><strong>Returns:</strong></span> An instance of <code class="computeroutput"><span class="identifier">zip_iterator</span></code> with <code class="computeroutput"><span class="identifier">m_iterator_tuple</span></code>
initialized to <code class="computeroutput"><span class="identifier">iterator_tuple</span></code>.
</p>
<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">OtherIteratorTuple</span><span class="special">&gt;</span>
<span class="identifier">zip_iterator</span><span class="special">(</span>
<span class="keyword">const</span> <span class="identifier">zip_iterator</span><span class="special">&lt;</span><span class="identifier">OtherIteratorTuple</span><span class="special">&gt;&amp;</span> <span class="identifier">other</span>
<span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">enable_if_convertible</span><span class="special">&lt;</span>
<span class="identifier">OtherIteratorTuple</span>
<span class="special">,</span> <span class="identifier">IteratorTuple</span><span class="special">&gt;::</span><span class="identifier">type</span><span class="special">*</span> <span class="special">=</span> <span class="number">0</span> <span class="comment">// exposition only</span>
<span class="special">);</span>
</pre>
<p>
<span class="bold"><strong>Returns:</strong></span> An instance of <code class="computeroutput"><span class="identifier">zip_iterator</span></code> that is a copy of <code class="computeroutput"><span class="identifier">other</span></code>.<br> <span class="bold"><strong>Requires:</strong></span>
<code class="computeroutput"><span class="identifier">OtherIteratorTuple</span></code> is implicitly
convertible to <code class="computeroutput"><span class="identifier">IteratorTuple</span></code>.
</p>
<pre class="programlisting"><span class="keyword">const</span> <span class="identifier">IteratorTuple</span><span class="special">&amp;</span> <span class="identifier">get_iterator_tuple</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
</pre>
<p>
<span class="bold"><strong>Returns:</strong></span> <code class="computeroutput"><span class="identifier">m_iterator_tuple</span></code>
</p>
<pre class="programlisting"><span class="identifier">reference</span> <span class="keyword">operator</span><span class="special">*()</span> <span class="keyword">const</span><span class="special">;</span>
</pre>
<p>
<span class="bold"><strong>Returns:</strong></span> A tuple consisting of the results
of dereferencing all iterators in <code class="computeroutput"><span class="identifier">m_iterator_tuple</span></code>.
</p>
<pre class="programlisting"><span class="identifier">zip_iterator</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">++();</span>
</pre>
<p>
<span class="bold"><strong>Effects:</strong></span> Increments each iterator in
<code class="computeroutput"><span class="identifier">m_iterator_tuple</span></code>.<br>
<span class="bold"><strong>Returns:</strong></span> <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>
</p>
<pre class="programlisting"><span class="identifier">zip_iterator</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">--();</span>
</pre>
<p>
<span class="bold"><strong>Effects:</strong></span> Decrements each iterator in
<code class="computeroutput"><span class="identifier">m_iterator_tuple</span></code>.<br>
<span class="bold"><strong>Returns:</strong></span> <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>
</p>
<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">IteratorTuple</span><span class="special">&gt;</span>
<span class="identifier">zip_iterator</span><span class="special">&lt;</span><span class="identifier">IteratorTuple</span><span class="special">&gt;</span>
<span class="identifier">make_zip_iterator</span><span class="special">(</span><span class="identifier">IteratorTuple</span> <span class="identifier">t</span><span class="special">);</span>
</pre>
<p>
<span class="bold"><strong>Returns:</strong></span> An instance of <code class="computeroutput"><span class="identifier">zip_iterator</span><span class="special">&lt;</span><span class="identifier">IteratorTuple</span><span class="special">&gt;</span></code>
with <code class="computeroutput"><span class="identifier">m_iterator_tuple</span></code> initialized
to <code class="computeroutput"><span class="identifier">t</span></code>.
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003, 2005 David Abrahams Jeremy Siek Thomas
Witt<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at &lt;ulink url="http://www.boost.org/LICENSE_1_0.txt"&gt;
http://www.boost.org/LICENSE_1_0.txt &lt;/ulink&gt;)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../zip.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../zip.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../../utilities.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
libs/iterator/doc/html/iterator/upgrading.html
+72
View File
@@ -0,0 +1,72 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Upgrading from the old Boost Iterator Adaptor Library</title>
<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="up" href="../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="prev" href="utilities/utilities/utilities_testing.html" title="Testing and Concept Checking">
<link rel="next" href="history.html" title="History">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
<td align="center"><a href="../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="utilities/utilities/utilities_testing.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="history.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="iterator.upgrading"></a><a class="link" href="upgrading.html" title="Upgrading from the old Boost Iterator Adaptor Library">Upgrading from the old Boost Iterator
Adaptor Library</a>
</h2></div></div></div>
<p>
If you have been using the old Boost Iterator Adaptor library to implement
iterators, you probably wrote a <code class="computeroutput"><span class="identifier">Policies</span></code>
class which captures the core operations of your iterator. In the new library
design, you'll move those same core operations into the body of the iterator
class itself. If you were writing a family of iterators, you probably wrote
a <a href="http://www.boost.org/more/generic_programming.html#type_generator" target="_top">type
generator</a> to build the <code class="computeroutput"><span class="identifier">iterator_adaptor</span></code>
specialization you needed; in the new library design you don't need a type
generator (though may want to keep it around as a compatibility aid for older
code) because, due to the use of the Curiously Recurring Template Pattern (CRTP)
[Cop95]_, you can now define the iterator class yourself and acquire functionality
through inheritance from <code class="computeroutput"><span class="identifier">iterator_facade</span></code>
or <code class="computeroutput"><span class="identifier">iterator_adaptor</span></code>. As a result,
you also get much finer control over how your iterator works: you can add additional
constructors, or even override the iterator functionality provided by the library.
</p>
<p>
If you're looking for the old <code class="computeroutput"><span class="identifier">projection_iterator</span></code>
component, its functionality has been merged into <span class="underline">transform_iterator</span>:
as long as the function object's <code class="computeroutput"><span class="identifier">result_type</span></code>
(or the <code class="computeroutput"><span class="identifier">Reference</span></code> template
argument, if explicitly specified) is a true reference type, <span class="underline">transform_iterator</span>
will behave like <code class="computeroutput"><span class="identifier">projection_iterator</span></code>
used to.
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003, 2005 David Abrahams Jeremy Siek Thomas
Witt<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at &lt;ulink url="http://www.boost.org/LICENSE_1_0.txt"&gt;
http://www.boost.org/LICENSE_1_0.txt &lt;/ulink&gt;)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="utilities/utilities/utilities_testing.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="history.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
libs/iterator/doc/html/iterator/utilities.html
+233
View File
@@ -0,0 +1,233 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Utilities</title>
<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="up" href="../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="prev" href="specialized/zip/zip_reference.html" title="Reference">
<link rel="next" href="utilities/concept_checking.html" title="Concept Checking">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
<td align="center"><a href="../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="specialized/zip/zip_reference.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="utilities/concept_checking.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="iterator.utilities"></a><a class="link" href="utilities.html" title="Utilities">Utilities</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="utilities.html#iterator.utilities.archetypes">Iterator Archetypes</a></span></dt>
<dt><span class="section"><a href="utilities/concept_checking.html">Concept Checking</a></span></dt>
<dt><span class="section"><a href="utilities/traits.html">Iterator Traits</a></span></dt>
<dt><span class="section"><a href="utilities/utilities.html">Iterator Utilities</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="utilities/utilities.html#iterator.utilities.utilities.utilities_traits">Traits</a></span></dt>
<dt><span class="section"><a href="utilities/utilities/utilities_testing.html">Testing
and Concept Checking</a></span></dt>
</dl></dd>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="iterator.utilities.archetypes"></a><a class="link" href="utilities.html#iterator.utilities.archetypes" title="Iterator Archetypes">Iterator Archetypes</a>
</h3></div></div></div>
<p>
The <code class="computeroutput"><span class="identifier">iterator_archetype</span></code> class
constructs a minimal implementation of one of the iterator access concepts
and one of the iterator traversal concepts. This is used for doing a compile-time
check to see if a the type requirements of a template are really enough to
cover the implementation of the template. For further information see the
documentation for the |concepts|_ library.
</p>
<h3>
<a name="iterator.utilities.archetypes.h0"></a>
<span class="phrase"><a name="iterator.utilities.archetypes.synopsis"></a></span><a class="link" href="utilities.html#iterator.utilities.archetypes.synopsis">Synopsis</a>
</h3>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">iterator_archetypes</span>
<span class="special">{</span>
<span class="comment">// Access categories</span>
<span class="keyword">typedef</span> <span class="comment">/*implementation defined*/</span> <span class="identifier">readable_iterator_t</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="comment">/*implementation defined*/</span> <span class="identifier">writable_iterator_t</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="comment">/*implementation defined*/</span> <span class="identifier">readable_writable_iterator_t</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="comment">/*implementation defined*/</span> <span class="identifier">readable_lvalue_iterator_t</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="comment">/*implementation defined*/</span> <span class="identifier">writable_lvalue_iterator_t</span><span class="special">;</span>
<span class="special">}</span>
<span class="keyword">template</span> <span class="special">&lt;</span>
<span class="keyword">class</span> <span class="identifier">Value</span>
<span class="special">,</span> <span class="keyword">class</span> <span class="identifier">AccessCategory</span>
<span class="special">,</span> <span class="keyword">class</span> <span class="identifier">TraversalCategory</span>
<span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">iterator_archetype</span>
<span class="special">{</span>
<span class="keyword">typedef</span> <span class="comment">/* see below */</span> <span class="identifier">value_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="comment">/* see below */</span> <span class="identifier">reference</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="comment">/* see below */</span> <span class="identifier">pointer</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="comment">/* see below */</span> <span class="identifier">difference_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="comment">/* see below */</span> <span class="identifier">iterator_category</span><span class="special">;</span>
<span class="special">};</span>
</pre>
<h4>
<a name="iterator.utilities.archetypes.h1"></a>
<span class="phrase"><a name="iterator.utilities.archetypes.access_category_tags"></a></span><a class="link" href="utilities.html#iterator.utilities.archetypes.access_category_tags">Access
Category Tags</a>
</h4>
<p>
The access category types provided correspond to the following standard iterator
access concept combinations:
</p>
<pre class="programlisting"><span class="identifier">readable_iterator_t</span> <span class="special">:=</span>
<span class="identifier">Readable</span> <span class="identifier">Iterator</span>
<span class="identifier">writable_iterator_t</span> <span class="special">:=</span>
<span class="identifier">Writeable</span> <span class="identifier">Iterator</span>
<span class="identifier">readable_writable_iterator_t</span> <span class="special">:=</span>
<span class="identifier">Readable</span> <span class="identifier">Iterator</span> <span class="special">&amp;</span> <span class="identifier">Writeable</span> <span class="identifier">Iterator</span> <span class="special">&amp;</span> <span class="identifier">Swappable</span> <span class="identifier">Iterator</span>
<span class="identifier">readable_lvalue_iterator_t</span> <span class="special">:=</span>
<span class="identifier">Readable</span> <span class="identifier">Iterator</span> <span class="special">&amp;</span> <span class="identifier">Lvalue</span> <span class="identifier">Iterator</span>
<span class="identifier">writeable_lvalue_iterator_t</span> <span class="special">:=</span>
<span class="identifier">Readable</span> <span class="identifier">Iterator</span> <span class="special">&amp;</span> <span class="identifier">Writeable</span> <span class="identifier">Iterator</span> <span class="special">&amp;</span> <span class="identifier">Swappable</span> <span class="identifier">Iterator</span> <span class="special">&amp;</span> <span class="identifier">Lvalue</span> <span class="identifier">Iterator</span>
</pre>
<h4>
<a name="iterator.utilities.archetypes.h2"></a>
<span class="phrase"><a name="iterator.utilities.archetypes.traits"></a></span><a class="link" href="utilities.html#iterator.utilities.archetypes.traits">Traits</a>
</h4>
<p>
The nested trait types are defined as follows:
</p>
<pre class="programlisting"><span class="keyword">if</span> <span class="special">(</span><span class="identifier">AccessCategory</span> <span class="special">==</span> <span class="identifier">readable_iterator_t</span><span class="special">)</span>
<span class="identifier">value_type</span> <span class="special">=</span> <span class="identifier">Value</span>
<span class="identifier">reference</span> <span class="special">=</span> <span class="identifier">Value</span>
<span class="identifier">pointer</span> <span class="special">=</span> <span class="identifier">Value</span><span class="special">*</span>
<span class="keyword">else</span> <span class="keyword">if</span> <span class="special">(</span><span class="identifier">AccessCategory</span> <span class="special">==</span> <span class="identifier">writable_iterator_t</span><span class="special">)</span>
<span class="identifier">value_type</span> <span class="special">=</span> <span class="keyword">void</span>
<span class="identifier">reference</span> <span class="special">=</span> <span class="keyword">void</span>
<span class="identifier">pointer</span> <span class="special">=</span> <span class="keyword">void</span>
<span class="keyword">else</span> <span class="keyword">if</span> <span class="special">(</span><span class="identifier">AccessCategory</span> <span class="special">==</span> <span class="identifier">readable_writable_iterator_t</span><span class="special">)</span>
<span class="identifier">value_type</span> <span class="special">=</span> <span class="identifier">Value</span>
<span class="identifier">reference</span> <span class="special">:=</span>
<span class="identifier">A</span> <span class="identifier">type</span> <span class="identifier">X</span> <span class="identifier">that</span> <span class="identifier">is</span> <span class="identifier">convertible</span> <span class="identifier">to</span> <span class="identifier">Value</span> <span class="keyword">for</span> <span class="identifier">which</span> <span class="identifier">the</span> <span class="identifier">following</span>
<span class="identifier">expression</span> <span class="identifier">is</span> <span class="identifier">valid</span><span class="special">.</span> <span class="identifier">Given</span> <span class="identifier">an</span> <span class="identifier">object</span> <span class="identifier">x</span> <span class="identifier">of</span> <span class="identifier">type</span> <span class="identifier">X</span> <span class="keyword">and</span> <span class="identifier">v</span> <span class="identifier">of</span> <span class="identifier">type</span>
<span class="identifier">Value</span><span class="special">.</span>
<span class="identifier">x</span> <span class="special">=</span> <span class="identifier">v</span>
<span class="identifier">pointer</span> <span class="special">=</span> <span class="identifier">Value</span><span class="special">*</span>
<span class="keyword">else</span> <span class="keyword">if</span> <span class="special">(</span><span class="identifier">AccessCategory</span> <span class="special">==</span> <span class="identifier">readable_lvalue_iterator_t</span><span class="special">)</span>
<span class="identifier">value_type</span> <span class="special">=</span> <span class="identifier">Value</span>
<span class="identifier">reference</span> <span class="special">=</span> <span class="identifier">Value</span> <span class="keyword">const</span><span class="special">&amp;</span>
<span class="identifier">pointer</span> <span class="special">=</span> <span class="identifier">Value</span> <span class="keyword">const</span><span class="special">*</span>
<span class="keyword">else</span> <span class="keyword">if</span> <span class="special">(</span><span class="identifier">AccessCategory</span> <span class="special">==</span> <span class="identifier">writable_lvalue_iterator_t</span><span class="special">)</span>
<span class="identifier">value_type</span> <span class="special">=</span> <span class="identifier">Value</span>
<span class="identifier">reference</span> <span class="special">=</span> <span class="identifier">Value</span><span class="special">&amp;</span>
<span class="identifier">pointer</span> <span class="special">=</span> <span class="identifier">Value</span><span class="special">*</span>
<span class="keyword">if</span> <span class="special">(</span> <span class="identifier">TraversalCategory</span> <span class="identifier">is</span> <span class="identifier">convertible</span> <span class="identifier">to</span> <span class="identifier">forward_traversal_tag</span> <span class="special">)</span>
<span class="identifier">difference_type</span> <span class="special">:=</span> <span class="identifier">ptrdiff_t</span>
<span class="keyword">else</span>
<span class="identifier">difference_type</span> <span class="special">:=</span> <span class="identifier">unspecified</span> <span class="identifier">type</span>
<span class="identifier">iterator_category</span> <span class="special">:=</span>
<span class="identifier">A</span> <span class="identifier">type</span> <span class="identifier">X</span> <span class="identifier">satisfying</span> <span class="identifier">the</span> <span class="identifier">following</span> <span class="identifier">two</span> <span class="identifier">constraints</span><span class="special">:</span>
<span class="number">1.</span> <span class="identifier">X</span> <span class="identifier">is</span> <span class="identifier">convertible</span> <span class="identifier">to</span> <span class="identifier">X1</span><span class="special">,</span> <span class="keyword">and</span> <span class="keyword">not</span> <span class="identifier">to</span> <span class="identifier">any</span> <span class="identifier">more</span><span class="special">-</span><span class="identifier">derived</span>
<span class="identifier">type</span><span class="special">,</span> <span class="identifier">where</span> <span class="identifier">X1</span> <span class="identifier">is</span> <span class="identifier">defined</span> <span class="identifier">by</span><span class="special">:</span>
<span class="keyword">if</span> <span class="special">(</span><span class="identifier">reference</span> <span class="identifier">is</span> <span class="identifier">a</span> <span class="identifier">reference</span> <span class="identifier">type</span>
<span class="special">&amp;&amp;</span> <span class="identifier">TraversalCategory</span> <span class="identifier">is</span> <span class="identifier">convertible</span> <span class="identifier">to</span> <span class="identifier">forward_traversal_tag</span><span class="special">)</span>
<span class="special">{</span>
<span class="keyword">if</span> <span class="special">(</span><span class="identifier">TraversalCategory</span> <span class="identifier">is</span> <span class="identifier">convertible</span> <span class="identifier">to</span> <span class="identifier">random_access_traversal_tag</span><span class="special">)</span>
<span class="identifier">X1</span> <span class="special">=</span> <span class="identifier">random_access_iterator_tag</span>
<span class="keyword">else</span> <span class="keyword">if</span> <span class="special">(</span><span class="identifier">TraversalCategory</span> <span class="identifier">is</span> <span class="identifier">convertible</span> <span class="identifier">to</span> <span class="identifier">bidirectional_traversal_tag</span><span class="special">)</span>
<span class="identifier">X1</span> <span class="special">=</span> <span class="identifier">bidirectional_iterator_tag</span>
<span class="keyword">else</span>
<span class="identifier">X1</span> <span class="special">=</span> <span class="identifier">forward_iterator_tag</span>
<span class="special">}</span>
<span class="keyword">else</span>
<span class="special">{</span>
<span class="keyword">if</span> <span class="special">(</span><span class="identifier">TraversalCategory</span> <span class="identifier">is</span> <span class="identifier">convertible</span> <span class="identifier">to</span> <span class="identifier">single_pass_traversal_tag</span>
<span class="special">&amp;&amp;</span> <span class="identifier">reference</span> <span class="special">!=</span> <span class="keyword">void</span><span class="special">)</span>
<span class="identifier">X1</span> <span class="special">=</span> <span class="identifier">input_iterator_tag</span>
<span class="keyword">else</span>
<span class="identifier">X1</span> <span class="special">=</span> <span class="identifier">output_iterator_tag</span>
<span class="special">}</span>
<span class="number">2.</span> <span class="identifier">X</span> <span class="identifier">is</span> <span class="identifier">convertible</span> <span class="identifier">to</span> <span class="identifier">TraversalCategory</span>
</pre>
<h3>
<a name="iterator.utilities.archetypes.h3"></a>
<span class="phrase"><a name="iterator.utilities.archetypes.requirements"></a></span><a class="link" href="utilities.html#iterator.utilities.archetypes.requirements">Requirements</a>
</h3>
<p>
The <code class="computeroutput"><span class="identifier">AccessCategory</span></code> argument
must be one of the predefined access category tags. The <code class="computeroutput"><span class="identifier">TraversalCategory</span></code>
must be one of the standard traversal tags. The <code class="computeroutput"><span class="identifier">Value</span></code>
type must satisfy the requirements of the iterator concept specified by
<code class="computeroutput"><span class="identifier">AccessCategory</span></code> and <code class="computeroutput"><span class="identifier">TraversalCategory</span></code> as implied by the nested
traits types.
</p>
<h3>
<a name="iterator.utilities.archetypes.h4"></a>
<span class="phrase"><a name="iterator.utilities.archetypes.concepts"></a></span><a class="link" href="utilities.html#iterator.utilities.archetypes.concepts">Concepts</a>
</h3>
<p>
<code class="computeroutput"><span class="identifier">iterator_archetype</span></code> models
the iterator concepts specified by the <code class="computeroutput"><span class="identifier">AccessCategory</span></code>
and <code class="computeroutput"><span class="identifier">TraversalCategory</span></code> arguments.
<code class="computeroutput"><span class="identifier">iterator_archetype</span></code> does not
model any other access concepts or any more derived traversal concepts.
</p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003, 2005 David Abrahams Jeremy Siek Thomas
Witt<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at &lt;ulink url="http://www.boost.org/LICENSE_1_0.txt"&gt;
http://www.boost.org/LICENSE_1_0.txt &lt;/ulink&gt;)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="specialized/zip/zip_reference.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="utilities/concept_checking.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
libs/iterator/doc/html/iterator/utilities/concept_checking.html
+99
View File
@@ -0,0 +1,99 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Concept Checking</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="up" href="../utilities.html" title="Utilities">
<link rel="prev" href="../utilities.html" title="Utilities">
<link rel="next" href="traits.html" title="Iterator Traits">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../utilities.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../utilities.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="traits.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="iterator.utilities.concept_checking"></a><a class="link" href="concept_checking.html" title="Concept Checking">Concept Checking</a>
</h3></div></div></div>
<p>
The iterator concept checking classes provide a mechanism for a template
to report better error messages when a user instantiates the template with
a type that does not meet the requirements of the template. For an introduction
to using concept checking classes, see the documentation for the boost::concept_check
library.
</p>
<h3>
<a name="iterator.utilities.concept_checking.h0"></a>
<span class="phrase"><a name="iterator.utilities.concept_checking.iterator_concepts_hpp_synopsis"></a></span><a class="link" href="concept_checking.html#iterator.utilities.concept_checking.iterator_concepts_hpp_synopsis"><code class="computeroutput"><span class="identifier">iterator_concepts</span><span class="special">.</span><span class="identifier">hpp</span></code> Synopsis</a>
</h3>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost_concepts</span> <span class="special">{</span>
<span class="comment">// Iterator Access Concepts</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">ReadableIteratorConcept</span><span class="special">;</span>
<span class="keyword">template</span> <span class="special">&lt;</span>
<span class="keyword">typename</span> <span class="identifier">Iterator</span>
<span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">ValueType</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">value_type</span>
<span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">WritableIteratorConcept</span><span class="special">;</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">SwappableIteratorConcept</span><span class="special">;</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">LvalueIteratorConcept</span><span class="special">;</span>
<span class="comment">// Iterator Traversal Concepts</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">IncrementableIteratorConcept</span><span class="special">;</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">SinglePassIteratorConcept</span><span class="special">;</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">ForwardTraversalConcept</span><span class="special">;</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">BidirectionalTraversalConcept</span><span class="special">;</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">RandomAccessTraversalConcept</span><span class="special">;</span>
<span class="comment">// Interoperability</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">ConstIterator</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">InteroperableIteratorConcept</span><span class="special">;</span>
<span class="special">}</span>
</pre>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003, 2005 David Abrahams Jeremy Siek Thomas
Witt<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at &lt;ulink url="http://www.boost.org/LICENSE_1_0.txt"&gt;
http://www.boost.org/LICENSE_1_0.txt &lt;/ulink&gt;)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../utilities.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../utilities.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="traits.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
libs/iterator/doc/html/iterator/utilities/traits.html
+101
View File
@@ -0,0 +1,101 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Iterator Traits</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="up" href="../utilities.html" title="Utilities">
<link rel="prev" href="concept_checking.html" title="Concept Checking">
<link rel="next" href="utilities.html" title="Iterator Utilities">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="concept_checking.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../utilities.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="utilities.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="iterator.utilities.traits"></a><a class="link" href="traits.html" title="Iterator Traits">Iterator Traits</a>
</h3></div></div></div>
<p>
<code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">iterator_traits</span></code> provides access to five
associated types of any iterator: its <code class="computeroutput"><span class="identifier">value_type</span></code>,
<code class="computeroutput"><span class="identifier">reference</span></code>, <code class="computeroutput"><span class="identifier">pointer</span></code>, <code class="computeroutput"><span class="identifier">iterator_category</span></code>,
and <code class="computeroutput"><span class="identifier">difference_type</span></code>. Unfortunately,
such a "multi-valued" traits template can be difficult to use in
a metaprogramming context. <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">iterator</span><span class="special">/</span><span class="identifier">iterator_traits</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></code>
provides access to these types using a standard metafunctions_.
</p>
<h3>
<a name="iterator.utilities.traits.h0"></a>
<span class="phrase"><a name="iterator.utilities.traits.synopsis"></a></span><a class="link" href="traits.html#iterator.utilities.traits.synopsis">Synopsis</a>
</h3>
<p>
Header <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">iterator</span><span class="special">/</span><span class="identifier">iterator_traits</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></code>:
</p>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">iterator_value</span>
<span class="special">{</span>
<span class="keyword">typedef</span> <span class="keyword">typename</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">value_type</span>
<span class="identifier">type</span><span class="special">;</span>
<span class="special">};</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">iterator_reference</span>
<span class="special">{</span>
<span class="keyword">typedef</span> <span class="keyword">typename</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">reference</span>
<span class="identifier">type</span><span class="special">;</span>
<span class="special">};</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">iterator_pointer</span>
<span class="special">{</span>
<span class="keyword">typedef</span> <span class="keyword">typename</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">pointer</span>
<span class="identifier">type</span><span class="special">;</span>
<span class="special">};</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">iterator_difference</span>
<span class="special">{</span>
<span class="keyword">typedef</span> <span class="keyword">typename</span>
<span class="identifier">detail</span><span class="special">::</span><span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">difference_type</span>
<span class="identifier">type</span><span class="special">;</span>
<span class="special">};</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">iterator_category</span>
<span class="special">{</span>
<span class="keyword">typedef</span> <span class="keyword">typename</span>
<span class="identifier">detail</span><span class="special">::</span><span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">iterator_category</span>
<span class="identifier">type</span><span class="special">;</span>
<span class="special">};</span>
</pre>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003, 2005 David Abrahams Jeremy Siek Thomas
Witt<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at &lt;ulink url="http://www.boost.org/LICENSE_1_0.txt"&gt;
http://www.boost.org/LICENSE_1_0.txt &lt;/ulink&gt;)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="concept_checking.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../utilities.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="utilities.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
libs/iterator/doc/html/iterator/utilities/utilities.html
+346
View File
@@ -0,0 +1,346 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Iterator Utilities</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="up" href="../utilities.html" title="Utilities">
<link rel="prev" href="traits.html" title="Iterator Traits">
<link rel="next" href="utilities/utilities_testing.html" title="Testing and Concept Checking">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="traits.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../utilities.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="utilities/utilities_testing.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="iterator.utilities.utilities"></a><a class="link" href="utilities.html" title="Iterator Utilities">Iterator Utilities</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="utilities.html#iterator.utilities.utilities.utilities_traits">Traits</a></span></dt>
<dt><span class="section"><a href="utilities/utilities_testing.html">Testing
and Concept Checking</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="iterator.utilities.utilities.utilities_traits"></a><a class="link" href="utilities.html#iterator.utilities.utilities.utilities_traits" title="Traits">Traits</a>
</h4></div></div></div>
<h3>
<a name="iterator.utilities.utilities.utilities_traits.h0"></a>
<span class="phrase"><a name="iterator.utilities.utilities.utilities_traits.overview"></a></span><a class="link" href="utilities.html#iterator.utilities.utilities.utilities_traits.overview">Overview</a>
</h3>
<p>
Have you ever wanted to write a generic function that can operate on any
kind of dereferenceable object? If you have, you've probably run into the
problem of how to determine the type that the object "points at":
</p>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Dereferenceable</span><span class="special">&gt;</span>
<span class="keyword">void</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">Dereferenceable</span> <span class="identifier">p</span><span class="special">)</span>
<span class="special">{</span>
<span class="special">*</span><span class="identifier">what</span><span class="special">-</span><span class="identifier">goes</span><span class="special">-</span><span class="identifier">here</span><span class="special">?*</span> <span class="identifier">value</span> <span class="special">=</span> <span class="special">\*</span><span class="identifier">p</span><span class="special">;</span>
<span class="special">...</span>
<span class="special">}</span>
</pre>
<h3>
<a name="iterator.utilities.utilities.utilities_traits.h1"></a>
<span class="phrase"><a name="iterator.utilities.utilities.utilities_traits.pointee"></a></span><a class="link" href="utilities.html#iterator.utilities.utilities.utilities_traits.pointee"><code class="computeroutput"><span class="identifier">pointee</span></code></a>
</h3>
<p>
It turns out to be impossible to come up with a fully-general algorithm
to do determine <span class="bold"><strong>what-goes-here</strong></span> directly,
but it is possible to require that <code class="computeroutput"><span class="identifier">pointee</span><span class="special">&lt;</span><span class="identifier">Dereferenceable</span><span class="special">&gt;::</span><span class="identifier">type</span></code>
is correct. Naturally, <code class="computeroutput"><span class="identifier">pointee</span></code>
has the same difficulty: it can't determine the appropriate <code class="computeroutput"><span class="special">::</span><span class="identifier">type</span></code>
reliably for all <code class="computeroutput"><span class="identifier">Dereferenceable</span></code>s,
but it makes very good guesses (it works for all pointers, standard and
boost smart pointers, and iterators), and when it guesses wrongly, it can
be specialized as necessary:
</p>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span>
<span class="special">{</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">pointee</span><span class="special">&lt;</span><span class="identifier">third_party_lib</span><span class="special">::</span><span class="identifier">smart_pointer</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="special">&gt;</span>
<span class="special">{</span>
<span class="keyword">typedef</span> <span class="identifier">T</span> <span class="identifier">type</span><span class="special">;</span>
<span class="special">};</span>
<span class="special">}</span>
</pre>
<h3>
<a name="iterator.utilities.utilities.utilities_traits.h2"></a>
<span class="phrase"><a name="iterator.utilities.utilities.utilities_traits.indirect_reference"></a></span><a class="link" href="utilities.html#iterator.utilities.utilities.utilities_traits.indirect_reference"><code class="computeroutput"><span class="identifier">indirect_reference</span></code></a>
</h3>
<p>
<code class="computeroutput"><span class="identifier">indirect_reference</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">type</span></code> is rather more specialized than
<code class="computeroutput"><span class="identifier">pointee</span></code>, and is meant to
be used to forward the result of dereferencing an object of its argument
type. Most dereferenceable types just return a reference to their pointee,
but some return proxy references or return the pointee by value. When that
information is needed, call on <code class="computeroutput"><span class="identifier">indirect_reference</span></code>.
</p>
<p>
Both of these templates are essential to the correct functioning of <a class="link" href="../specialized/indirect.html" title="Indirect Iterator"><code class="computeroutput"><span class="identifier">indirect_iterator</span></code></a>.
</p>
<h3>
<a name="iterator.utilities.utilities.utilities_traits.h3"></a>
<span class="phrase"><a name="iterator.utilities.utilities.utilities_traits.minimum_category"></a></span><a class="link" href="utilities.html#iterator.utilities.utilities.utilities_traits.minimum_category"><code class="computeroutput"><span class="identifier">minimum_category</span></code></a>
</h3>
<p>
<code class="computeroutput"><span class="identifier">minimum_category</span></code> takes
two iterator categories or two iterator traversal tags and returns the
one that is the weakest (i.e. least advanced). For example:
</p>
<pre class="programlisting"><span class="keyword">static_assert</span><span class="special">(</span>
<span class="identifier">is_same</span><span class="special">&lt;</span>
<span class="identifier">minimum_category</span><span class="special">&lt;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">forward_iterator_tag</span><span class="special">,</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">random_access_iterator_tag</span>
<span class="special">&gt;::</span><span class="identifier">type</span><span class="special">,</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">forward_iterator_tag</span>
<span class="special">&gt;::</span><span class="identifier">value</span><span class="special">,</span>
<span class="string">"Unexpected minimum_category result"</span>
<span class="special">);</span>
</pre>
<h3>
<a name="iterator.utilities.utilities.utilities_traits.h4"></a>
<span class="phrase"><a name="iterator.utilities.utilities.utilities_traits.iterator_category_and_traversal_"></a></span><a class="link" href="utilities.html#iterator.utilities.utilities.utilities_traits.iterator_category_and_traversal_">Iterator
category and traversal tags manipulation</a>
</h3>
<p>
The library provides several utilities to simplify conversions between
iterator categories and traversal tags:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<code class="computeroutput"><span class="identifier">iterator_category_to_traversal</span><span class="special">&lt;</span><span class="identifier">C</span><span class="special">&gt;::</span><span class="identifier">type</span></code>
- the metafunction takes an iterator category <code class="computeroutput"><span class="identifier">C</span></code>
and returns the corresponding traversal tag.
</li>
<li class="listitem">
<code class="computeroutput"><span class="identifier">iterator_traversal</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">type</span></code>
- a shorthand for <code class="computeroutput"><span class="identifier">iterator_category_to_traversal</span><span class="special">&lt;</span><span class="identifier">iterator_category</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">type</span><span class="special">&gt;::</span><span class="identifier">type</span></code>.
</li>
<li class="listitem">
<code class="computeroutput"><span class="identifier">pure_traversal_tag</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">type</span></code>
- the metafunction takes a tag <code class="computeroutput"><span class="identifier">T</span></code>
which derives from one of the iterator traversal tags and returns that
traversal tag. <code class="computeroutput"><span class="identifier">T</span></code> may
also derive from other tags describing the iterator (e.g. whether this
is a <code class="computeroutput"><span class="keyword">const</span></code>-iterator or
not), these additional tags are not considered.
</li>
<li class="listitem">
<code class="computeroutput"><span class="identifier">pure_iterator_traversal</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">type</span></code>
- a shorthand for <code class="computeroutput"><span class="identifier">pure_traversal_tag</span><span class="special">&lt;</span><span class="identifier">iterator_traversal</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">type</span><span class="special">&gt;::</span><span class="identifier">type</span></code>.
</li>
</ul></div>
<h3>
<a name="iterator.utilities.utilities.utilities_traits.h5"></a>
<span class="phrase"><a name="iterator.utilities.utilities.utilities_traits.reference"></a></span><a class="link" href="utilities.html#iterator.utilities.utilities.utilities_traits.reference">Reference</a>
</h3>
<h4>
<a name="iterator.utilities.utilities.utilities_traits.h6"></a>
<span class="phrase"><a name="iterator.utilities.utilities.utilities_traits.pointee0"></a></span><a class="link" href="utilities.html#iterator.utilities.utilities.utilities_traits.pointee0"><code class="computeroutput"><span class="identifier">pointee</span></code></a>
</h4>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Dereferenceable</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">pointee</span>
<span class="special">{</span>
<span class="keyword">typedef</span> <span class="comment">/* see below */</span> <span class="identifier">type</span><span class="special">;</span>
<span class="special">};</span>
</pre>
<p>
<span class="bold"><strong>Requires:</strong></span> For an object <code class="computeroutput"><span class="identifier">x</span></code> of type <code class="computeroutput"><span class="identifier">Dereferenceable</span></code>,
<code class="computeroutput"><span class="special">*</span><span class="identifier">x</span></code>
is well-formed. If <code class="computeroutput"><span class="special">++</span><span class="identifier">x</span></code>
is ill-formed it shall neither be ambiguous nor shall it violate access
control, and <code class="computeroutput"><span class="identifier">Dereferenceable</span><span class="special">::</span><span class="identifier">element_type</span></code>
shall be an accessible type. Otherwise <code class="computeroutput"><span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Dereferenceable</span><span class="special">&gt;::</span><span class="identifier">value_type</span></code>
shall be well formed. [Note: These requirements need not apply to explicit
or partial specializations of <code class="computeroutput"><span class="identifier">pointee</span></code>]
</p>
<p>
<code class="computeroutput"><span class="identifier">type</span></code> is determined according
to the following algorithm, where <code class="computeroutput"><span class="identifier">x</span></code>
is an object of type <code class="computeroutput"><span class="identifier">Dereferenceable</span></code>:
</p>
<pre class="programlisting"><span class="keyword">if</span> <span class="special">(</span> <span class="special">++</span><span class="identifier">x</span> <span class="identifier">is</span> <span class="identifier">ill</span><span class="special">-</span><span class="identifier">formed</span> <span class="special">)</span>
<span class="special">{</span>
<span class="keyword">return</span> <span class="identifier">Dereferenceable</span><span class="special">::</span><span class="identifier">element_type</span>
<span class="special">}</span>
<span class="keyword">else</span> <span class="keyword">if</span> <span class="special">(*</span><span class="identifier">x</span> <span class="identifier">is</span> <span class="identifier">a</span> <span class="keyword">mutable</span> <span class="identifier">reference</span> <span class="identifier">to</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Dereferenceable</span><span class="special">&gt;::</span><span class="identifier">value_type</span><span class="special">)</span>
<span class="special">{</span>
<span class="keyword">return</span> <span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Dereferenceable</span><span class="special">&gt;::</span><span class="identifier">value_type</span>
<span class="special">}</span>
<span class="keyword">else</span>
<span class="special">{</span>
<span class="keyword">return</span> <span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Dereferenceable</span><span class="special">&gt;::</span><span class="identifier">value_type</span> <span class="keyword">const</span>
<span class="special">}</span>
</pre>
<h4>
<a name="iterator.utilities.utilities.utilities_traits.h7"></a>
<span class="phrase"><a name="iterator.utilities.utilities.utilities_traits.indirect_reference0"></a></span><a class="link" href="utilities.html#iterator.utilities.utilities.utilities_traits.indirect_reference0"><code class="computeroutput"><span class="identifier">indirect_reference</span></code></a>
</h4>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Dereferenceable</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">indirect_reference</span>
<span class="special">{</span>
<span class="keyword">typedef</span> <span class="comment">/* see below */</span> <span class="identifier">type</span><span class="special">;</span>
<span class="special">};</span>
</pre>
<p>
<span class="bold"><strong>Requires:</strong></span> For an object <code class="computeroutput"><span class="identifier">x</span></code> of type <code class="computeroutput"><span class="identifier">Dereferenceable</span></code>,
<code class="computeroutput"><span class="special">*</span><span class="identifier">x</span></code>
is well-formed. If <code class="computeroutput"><span class="special">++</span><span class="identifier">x</span></code>
is ill-formed it shall neither be ambiguous nor shall it violate access
control, and <code class="computeroutput"><span class="identifier">pointee</span><span class="special">&lt;</span><span class="identifier">Dereferenceable</span><span class="special">&gt;::</span><span class="identifier">type</span><span class="special">&amp;</span></code>
shall be well-formed. Otherwise <code class="computeroutput"><span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Dereferenceable</span><span class="special">&gt;::</span><span class="identifier">reference</span></code>
shall be well formed. [Note: These requirements need not apply to explicit
or partial specializations of <code class="computeroutput"><span class="identifier">indirect_reference</span></code>]
</p>
<p>
<code class="computeroutput"><span class="identifier">type</span></code> is determined according
to the following algorithm, where <code class="computeroutput"><span class="identifier">x</span></code>
is an object of type <code class="computeroutput"><span class="identifier">Dereferenceable</span></code>:
</p>
<pre class="programlisting"><span class="keyword">if</span> <span class="special">(</span> <span class="special">++</span><span class="identifier">x</span> <span class="identifier">is</span> <span class="identifier">ill</span><span class="special">-</span><span class="identifier">formed</span> <span class="special">)</span>
<span class="keyword">return</span> <span class="identifier">pointee</span><span class="special">&lt;</span><span class="identifier">Dereferenceable</span><span class="special">&gt;::</span><span class="identifier">type</span><span class="special">&amp;</span>
<span class="keyword">else</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Dereferenceable</span><span class="special">&gt;::</span><span class="identifier">reference</span>
</pre>
<h4>
<a name="iterator.utilities.utilities.utilities_traits.h8"></a>
<span class="phrase"><a name="iterator.utilities.utilities.utilities_traits.minimum_category0"></a></span><a class="link" href="utilities.html#iterator.utilities.utilities.utilities_traits.minimum_category0"><code class="computeroutput"><span class="identifier">minimum_category</span></code></a>
</h4>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">C1</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">C2</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">minimum_category</span>
<span class="special">{</span>
<span class="keyword">typedef</span> <span class="comment">/* see below */</span> <span class="identifier">type</span><span class="special">;</span>
<span class="special">};</span>
</pre>
<p>
<span class="bold"><strong>Requires:</strong></span> Both <code class="computeroutput"><span class="identifier">C1</span></code>
and <code class="computeroutput"><span class="identifier">C2</span></code> shall be standard
iterator categories or iterator traversal tags.
</p>
<p>
<code class="computeroutput"><span class="identifier">type</span></code> is determined according
to the following algorithm, where <code class="computeroutput"><span class="identifier">c1</span></code>
is an object of type <code class="computeroutput"><span class="identifier">C1</span></code>
and <code class="computeroutput"><span class="identifier">c2</span></code> is an object of
type <code class="computeroutput"><span class="identifier">C2</span></code>:
</p>
<pre class="programlisting"><span class="keyword">if</span> <span class="special">(</span><span class="identifier">c1</span> <span class="identifier">is</span> <span class="identifier">convertible</span> <span class="identifier">to</span> <span class="identifier">c2</span><span class="special">)</span>
<span class="keyword">return</span> <span class="identifier">C2</span><span class="special">;</span>
<span class="keyword">else</span>
<span class="keyword">return</span> <span class="identifier">C1</span><span class="special">;</span>
</pre>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
The above definition relies on the fact that the more restricting categories
and traversal tags are convertible to the less restricting ones.
</p></td></tr>
</table></div>
<h4>
<a name="iterator.utilities.utilities.utilities_traits.h9"></a>
<span class="phrase"><a name="iterator.utilities.utilities.utilities_traits.iterator_category_to_traversal"></a></span><a class="link" href="utilities.html#iterator.utilities.utilities.utilities_traits.iterator_category_to_traversal"><code class="computeroutput"><span class="identifier">iterator_category_to_traversal</span></code></a>
</h4>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">C</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">iterator_category_to_traversal</span>
<span class="special">{</span>
<span class="keyword">typedef</span> <span class="comment">/* see below */</span> <span class="identifier">type</span><span class="special">;</span>
<span class="special">};</span>
</pre>
<p>
<span class="bold"><strong>Requires:</strong></span> <code class="computeroutput"><span class="identifier">C</span></code>
shall be a standard iterator category or an iterator traversal tag.
</p>
<p>
If <code class="computeroutput"><span class="identifier">C</span></code> is an iterator traversal
tag or convertible to one, <code class="computeroutput"><span class="identifier">type</span></code>
equivalent to <code class="computeroutput"><span class="identifier">C</span></code>. Otherwise,
<code class="computeroutput"><span class="identifier">type</span></code> is defined to the
closest iterator traversal tag matching <code class="computeroutput"><span class="identifier">C</span></code>.
</p>
<h4>
<a name="iterator.utilities.utilities.utilities_traits.h10"></a>
<span class="phrase"><a name="iterator.utilities.utilities.utilities_traits.iterator_traversal"></a></span><a class="link" href="utilities.html#iterator.utilities.utilities.utilities_traits.iterator_traversal"><code class="computeroutput"><span class="identifier">iterator_traversal</span></code></a>
</h4>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">iterator_traversal</span>
<span class="special">{</span>
<span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">iterator_category_to_traversal</span><span class="special">&lt;</span>
<span class="keyword">typename</span> <span class="identifier">iterator_category</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">type</span>
<span class="special">&gt;::</span><span class="identifier">type</span> <span class="identifier">type</span><span class="special">;</span>
<span class="special">};</span>
</pre>
<p>
<span class="bold"><strong>Requires:</strong></span> <code class="computeroutput"><span class="identifier">Iterator</span></code>
shall be an iterator.
</p>
<h4>
<a name="iterator.utilities.utilities.utilities_traits.h11"></a>
<span class="phrase"><a name="iterator.utilities.utilities.utilities_traits.pure_traversal_tag"></a></span><a class="link" href="utilities.html#iterator.utilities.utilities.utilities_traits.pure_traversal_tag"><code class="computeroutput"><span class="identifier">pure_traversal_tag</span></code></a>
</h4>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">T</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">pure_traversal_tag</span>
<span class="special">{</span>
<span class="keyword">typedef</span> <span class="comment">/* see below */</span> <span class="identifier">type</span><span class="special">;</span>
<span class="special">};</span>
</pre>
<p>
<span class="bold"><strong>Requires:</strong></span> <code class="computeroutput"><span class="identifier">T</span></code>
shall be convertible to an iterator traversal tag.
</p>
<p>
<code class="computeroutput"><span class="identifier">type</span></code> is defined to be the
most advanced traversal tag <code class="computeroutput"><span class="identifier">Tag</span></code>
so that <code class="computeroutput"><span class="identifier">T</span></code> is convertible
to <code class="computeroutput"><span class="identifier">Tag</span></code>.
</p>
<h4>
<a name="iterator.utilities.utilities.utilities_traits.h12"></a>
<span class="phrase"><a name="iterator.utilities.utilities.utilities_traits.pure_iterator_traversal"></a></span><a class="link" href="utilities.html#iterator.utilities.utilities.utilities_traits.pure_iterator_traversal"><code class="computeroutput"><span class="identifier">pure_iterator_traversal</span></code></a>
</h4>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">pure_iterator_traversal</span>
<span class="special">{</span>
<span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">pure_traversal_tag</span><span class="special">&lt;</span>
<span class="keyword">typename</span> <span class="identifier">iterator_traversal</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">type</span>
<span class="special">&gt;::</span><span class="identifier">type</span> <span class="identifier">type</span><span class="special">;</span>
<span class="special">};</span>
</pre>
<p>
<span class="bold"><strong>Requires:</strong></span> <code class="computeroutput"><span class="identifier">Iterator</span></code>
shall be an iterator.
</p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003, 2005 David Abrahams Jeremy Siek Thomas
Witt<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at &lt;ulink url="http://www.boost.org/LICENSE_1_0.txt"&gt;
http://www.boost.org/LICENSE_1_0.txt &lt;/ulink&gt;)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="traits.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../utilities.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="utilities/utilities_testing.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
libs/iterator/doc/html/iterator/utilities/utilities/utilities_testing.html
+146
View File
@@ -0,0 +1,146 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Testing and Concept Checking</title>
<link rel="stylesheet" href="../../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../../index.html" title="Chapter&#160;1.&#160;Boost.Iterator">
<link rel="up" href="../utilities.html" title="Iterator Utilities">
<link rel="prev" href="../utilities.html" title="Iterator Utilities">
<link rel="next" href="../../upgrading.html" title="Upgrading from the old Boost Iterator Adaptor Library">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../utilities.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../utilities.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../../upgrading.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="iterator.utilities.utilities.utilities_testing"></a><a class="link" href="utilities_testing.html" title="Testing and Concept Checking">Testing
and Concept Checking</a>
</h4></div></div></div>
<p>
The iterator concept checking classes provide a mechanism for a template
to report better error messages when a user instantiates the template with
a type that does not meet the requirements of the template.
</p>
<p>
For an introduction to using concept checking classes, see the documentation
for the <a href="../../../../../concept_check/index.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">concept_check</span></code></a>
library.
</p>
<h3>
<a name="iterator.utilities.utilities.utilities_testing.h0"></a>
<span class="phrase"><a name="iterator.utilities.utilities.utilities_testing.reference"></a></span><a class="link" href="utilities_testing.html#iterator.utilities.utilities.utilities_testing.reference">Reference</a>
</h3>
<h4>
<a name="iterator.utilities.utilities.utilities_testing.h1"></a>
<span class="phrase"><a name="iterator.utilities.utilities.utilities_testing.iterator_access_concepts"></a></span><a class="link" href="utilities_testing.html#iterator.utilities.utilities.utilities_testing.iterator_access_concepts">Iterator
Access Concepts</a>
</h4>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
|Readable|_
</li>
<li class="listitem">
|Writable|_
</li>
<li class="listitem">
|Swappable|_
</li>
<li class="listitem">
|Lvalue|_
</li>
</ul></div>
<p>
Iterator Traversal Concepts ...........................
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
|Incrementable|_
</li>
<li class="listitem">
|SinglePass|_
</li>
<li class="listitem">
|Forward|_
</li>
<li class="listitem">
|Bidir|_
</li>
<li class="listitem">
|Random|_
</li>
</ul></div>
<h4>
<a name="iterator.utilities.utilities.utilities_testing.h2"></a>
<span class="phrase"><a name="iterator.utilities.utilities.utilities_testing.iterator_concepts_hpp_synopsis"></a></span><a class="link" href="utilities_testing.html#iterator.utilities.utilities.utilities_testing.iterator_concepts_hpp_synopsis"><code class="computeroutput"><span class="identifier">iterator_concepts</span><span class="special">.</span><span class="identifier">hpp</span></code> Synopsis</a>
</h4>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost_concepts</span> <span class="special">{</span>
<span class="comment">// Iterator Access Concepts</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">ReadableIteratorConcept</span><span class="special">;</span>
<span class="keyword">template</span> <span class="special">&lt;</span>
<span class="keyword">typename</span> <span class="identifier">Iterator</span>
<span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">ValueType</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">value_type</span>
<span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">WritableIteratorConcept</span><span class="special">;</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">SwappableIteratorConcept</span><span class="special">;</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">LvalueIteratorConcept</span><span class="special">;</span>
<span class="comment">// Iterator Traversal Concepts</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">IncrementableIteratorConcept</span><span class="special">;</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">SinglePassIteratorConcept</span><span class="special">;</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">ForwardTraversalConcept</span><span class="special">;</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">BidirectionalTraversalConcept</span><span class="special">;</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">RandomAccessTraversalConcept</span><span class="special">;</span>
<span class="comment">// Interoperability</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">ConstIterator</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">InteroperableIteratorConcept</span><span class="special">;</span>
<span class="special">}</span>
</pre>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003, 2005 David Abrahams Jeremy Siek Thomas
Witt<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at &lt;ulink url="http://www.boost.org/LICENSE_1_0.txt"&gt;
http://www.boost.org/LICENSE_1_0.txt &lt;/ulink&gt;)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../utilities.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../utilities.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../../upgrading.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
libs/iterator/doc/html/standalone_HTML.manifest
+25
View File
@@ -0,0 +1,25 @@
index.html
iterator/concepts.html
iterator/concepts/concepts_traversal.html
iterator/generic.html
iterator/generic/adaptor.html
iterator/generic/adaptor/adaptor_tutorial.html
iterator/specialized.html
iterator/specialized/filter.html
iterator/specialized/function_output.html
iterator/specialized/indirect.html
iterator/specialized/permutation.html
iterator/specialized/reverse.html
iterator/specialized/shared_container.html
iterator/specialized/shared_container/shared_container_object_generator.html
iterator/specialized/shared_container/shared_container_generator.html
iterator/specialized/transform.html
iterator/specialized/zip.html
iterator/specialized/zip/zip_reference.html
iterator/utilities.html
iterator/utilities/concept_checking.html
iterator/utilities/traits.html
iterator/utilities/utilities.html
iterator/utilities/utilities/utilities_testing.html
iterator/upgrading.html
iterator/history.html
libs/iterator/doc/index.html
+249
View File
@@ -0,0 +1,249 @@
<?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.6: http://docutils.sourceforge.net/" />
<title>The Boost.Iterator Library Boost</title>
<link rel="stylesheet" href="../../../rst.css" type="text/css" />
</head>
<body>
<div class="document" id="the-boost-iterator-library-logo">
<h1 class="title">The Boost.Iterator Library <a class="reference external" href="../../../index.htm"><img alt="Boost" src="../../../boost.png" /></a></h1>
<!-- Distributed under 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) -->
<hr class="docutils" />
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Authors:</th><td class="field-body">David Abrahams, Jeremy Siek, Thomas Witt</td>
</tr>
<tr class="field"><th class="field-name">Contact:</th><td class="field-body"><a class="reference external" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference external" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="reference external" href="mailto:witt&#64;styleadvisor.com">witt&#64;styleadvisor.com</a></td>
</tr>
<tr class="field"><th class="field-name">organizations:</th><td class="field-body"><a class="reference external" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference external" href="http://www.osl.iu.edu">Open Systems
Lab</a>, <a class="reference external" href="http://www.styleadvisor.com">Zephyr Associates, Inc.</a></td>
</tr>
<tr class="field"><th class="field-name">date:</th><td class="field-body">$Date$</td>
</tr>
<tr class="field"><th class="field-name">copyright:</th><td class="field-body">Copyright David Abrahams, Jeremy Siek, Thomas Witt 2003.</td>
</tr>
</tbody>
</table>
<table class="docutils 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 Boost Iterator Library contains two parts. The first
is a system of <a class="reference external" href="http://www.boost.org/more/generic_programming.html#concept">concepts</a> which extend the C++ standard
iterator requirements. The second is a framework of
components for building iterators based on these
extended concepts and includes several useful iterator
adaptors. The extended iterator concepts have been
carefully designed so that old-style iterators
can fit in the new concepts and so that new-style
iterators will be compatible with old-style algorithms,
though algorithms may need to be updated if they want to
take full advantage of the new-style iterator
capabilities. Several components of this library have
been accepted into the C++ standard technical report.
The components of the Boost Iterator Library replace the
older Boost Iterator Adaptor Library.</td>
</tr>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first"><strong>Table of Contents</strong></p>
<ul class="simple">
<li><a class="reference internal" href="#new-style-iterators" id="id23">New-Style Iterators</a></li>
<li><a class="reference internal" href="#iterator-facade-and-adaptor" id="id24">Iterator Facade and Adaptor</a></li>
<li><a class="reference internal" href="#specialized-adaptors" id="id25">Specialized Adaptors</a></li>
<li><a class="reference internal" href="#iterator-utilities" id="id26">Iterator Utilities</a><ul>
<li><a class="reference internal" href="#traits" id="id27">Traits</a></li>
<li><a class="reference internal" href="#testing-and-concept-checking" id="id28">Testing and Concept Checking</a></li>
</ul>
</li>
<li><a class="reference internal" href="#upgrading-from-the-old-boost-iterator-adaptor-library" id="id29">Upgrading from the old Boost Iterator Adaptor Library</a></li>
<li><a class="reference internal" href="#history" id="id30">History</a></li>
</ul>
</div>
<hr class="docutils" />
<div class="section" id="new-style-iterators">
<h1><a class="toc-backref" href="#id23">New-Style Iterators</a></h1>
<p>The iterator categories defined in C++98 are extremely limiting
because they bind together two orthogonal concepts: traversal and
element access. For example, because a random access iterator is
required to return a reference (and not a proxy) when dereferenced,
it is impossible to capture the capabilities of
<tt class="docutils literal"><span class="pre">vector&lt;bool&gt;::iterator</span></tt> using the C++98 categories. This is the
infamous &quot;<tt class="docutils literal"><span class="pre">vector&lt;bool&gt;</span></tt> is not a container, and its iterators
aren't random access iterators&quot;, debacle about which Herb Sutter
wrote two papers for the standards comittee (<a class="reference external" href="http://www.gotw.ca/publications/N1185.pdf">n1185</a> and <a class="reference external" href="http://www.gotw.ca/publications/N1211.pdf">n1211</a>),
and a <a class="reference external" href="http://www.gotw.ca/gotw/050.htm">Guru of the Week</a>. New-style iterators go well beyond
patching up <tt class="docutils literal"><span class="pre">vector&lt;bool&gt;</span></tt>, though: there are lots of other
iterators already in use which can't be adequately represented by
the existing concepts. For details about the new iterator
concepts, see our</p>
<blockquote>
<a class="reference external" href="new-iter-concepts.html">Standard Proposal For New-Style Iterators</a> (<a class="reference external" href="new-iter-concepts.pdf">PDF</a>)</blockquote>
</div>
<div class="section" id="iterator-facade-and-adaptor">
<h1><a class="toc-backref" href="#id24">Iterator Facade and Adaptor</a></h1>
<p>Writing standard-conforming iterators is tricky, but the need comes
up often. In order to ease the implementation of new iterators,
the Boost.Iterator library provides the <tt class="docutils literal"><span class="pre">iterator_facade</span></tt> class template,
which implements many useful defaults and compile-time checks
designed to help the iterator author ensure that his iterator is
correct.</p>
<p>It is also common to define a new iterator that is similar to some
underlying iterator or iterator-like type, but that modifies some
aspect of the underlying type's behavior. For that purpose, the
library supplies the <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> class template, which is specially
designed to take advantage of as much of the underlying type's
behavior as possible.</p>
<p>The documentation for these two classes can be found at the following
web pages:</p>
<ul class="simple">
<li><a class="reference external" href="iterator_facade.html"><tt class="docutils literal"><span class="pre">iterator_facade</span></tt></a> (<a class="reference external" href="iterator_facade.pdf">PDF</a>)</li>
<li><a class="reference external" href="iterator_adaptor.html"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt></a> (<a class="reference external" href="iterator_adaptor.pdf">PDF</a>)</li>
</ul>
<p>Both <tt class="docutils literal"><span class="pre">iterator_facade</span></tt> and <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> as well as many of the <a class="reference internal" href="#specialized-adaptors">specialized
adaptors</a> mentioned below have been proposed for standardization,
and accepted into the first C++ technical report; see our</p>
<blockquote>
<a class="reference external" href="facade-and-adaptor.html">Standard Proposal For Iterator Facade and Adaptor</a> (<a class="reference external" href="facade-and-adaptor.pdf">PDF</a>)</blockquote>
<p>for more details.</p>
</div>
<div class="section" id="specialized-adaptors">
<h1><a class="toc-backref" href="#id25">Specialized Adaptors</a></h1>
<p>The iterator library supplies a useful suite of standard-conforming
iterator templates based on the Boost <a class="reference internal" href="#iterator-facade-and-adaptor">iterator facade and adaptor</a>.</p>
<ul class="simple">
<li><a class="reference external" href="counting_iterator.html"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt></a> (<a class="reference external" href="counting_iterator.pdf">PDF</a>): an iterator over a sequence of consecutive values.
Implements a &quot;lazy sequence&quot;</li>
<li><a class="reference external" href="filter_iterator.html"><tt class="docutils literal"><span class="pre">filter_iterator</span></tt></a> (<a class="reference external" href="filter_iterator.pdf">PDF</a>): an iterator over the subset of elements of some
sequence which satisfy a given predicate</li>
<li><a class="reference external" href="function_input_iterator.html"><tt class="docutils literal"><span class="pre">function_input_iterator</span></tt></a> (<a class="reference external" href="function_input_iterator.pdf">PDF</a>): an input iterator wrapping a generator (nullary
function object); each time the iterator is dereferenced, the function object
is called to get the value to return.</li>
<li><a class="reference external" href="function_output_iterator.html"><tt class="docutils literal"><span class="pre">function_output_iterator</span></tt></a> (<a class="reference external" href="function_output_iterator.pdf">PDF</a>): an output iterator wrapping a unary function
object; each time an element is written into the dereferenced
iterator, it is passed as a parameter to the function object.</li>
<li><a class="reference external" href="indirect_iterator.html"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt></a> (<a class="reference external" href="indirect_iterator.pdf">PDF</a>): an iterator over the objects <em>pointed-to</em> by the
elements of some sequence.</li>
<li><a class="reference external" href="permutation_iterator.html"><tt class="docutils literal"><span class="pre">permutation_iterator</span></tt></a> (<a class="reference external" href="permutation_iterator.pdf">PDF</a>): an iterator over the elements of some random-access
sequence, rearranged according to some sequence of integer indices.</li>
<li><a class="reference external" href="reverse_iterator.html"><tt class="docutils literal"><span class="pre">reverse_iterator</span></tt></a> (<a class="reference external" href="reverse_iterator.pdf">PDF</a>): an iterator which traverses the elements of some
bidirectional sequence in reverse. Corrects many of the
shortcomings of C++98's <tt class="docutils literal"><span class="pre">std::reverse_iterator</span></tt>.</li>
<li><a class="reference external" href="../../utility/shared_container_iterator.html"><tt class="docutils literal"><span class="pre">shared_container_iterator</span></tt></a>: an iterator over elements of a container whose
lifetime is maintained by a <a class="reference external" href="../../smart_ptr/shared_ptr.htm"><tt class="docutils literal"><span class="pre">shared_ptr</span></tt></a> stored in the iterator.</li>
<li><a class="reference external" href="transform_iterator.html"><tt class="docutils literal"><span class="pre">transform_iterator</span></tt></a> (<a class="reference external" href="transform_iterator.pdf">PDF</a>): an iterator over elements which are the result of
applying some functional transformation to the elements of an
underlying sequence. This component also replaces the old
<tt class="docutils literal"><span class="pre">projection_iterator_adaptor</span></tt>.</li>
<li><a class="reference external" href="zip_iterator.html"><tt class="docutils literal"><span class="pre">zip_iterator</span></tt></a> (<a class="reference external" href="zip_iterator.pdf">PDF</a>): an iterator over tuples of the elements at corresponding
positions of heterogeneous underlying iterators.</li>
</ul>
</div>
<div class="section" id="iterator-utilities">
<h1><a class="toc-backref" href="#id26">Iterator Utilities</a></h1>
<div class="section" id="traits">
<h2><a class="toc-backref" href="#id27">Traits</a></h2>
<ul class="simple">
<li><a class="reference external" href="pointee.html"><tt class="docutils literal"><span class="pre">pointee.hpp</span></tt></a> (<a class="reference external" href="pointee.pdf">PDF</a>): Provides the capability to deduce the referent types
of pointers, smart pointers and iterators in generic code. Used
in <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt>.</li>
<li><a class="reference external" href="iterator_traits.html"><tt class="docutils literal"><span class="pre">iterator_traits.hpp</span></tt></a> (<a class="reference external" href="iterator_traits.pdf">PDF</a>): Provides <a class="reference external" href="../../mpl/doc/index.html">MPL</a>-compatible metafunctions which
retrieve an iterator's traits. Also corrects for the deficiencies
of broken implementations of <tt class="docutils literal"><span class="pre">std::iterator_traits</span></tt>.</li>
</ul>
<!-- * |interoperable|_ (PDF__): Provides an MPL_\ -compatible metafunction for
testing iterator interoperability -->
<!-- comment! __ interoperable.pdf -->
</div>
<div class="section" id="testing-and-concept-checking">
<h2><a class="toc-backref" href="#id28">Testing and Concept Checking</a></h2>
<ul class="simple">
<li><a class="reference external" href="iterator_concepts.html"><tt class="docutils literal"><span class="pre">iterator_concepts.hpp</span></tt></a> (<a class="reference external" href="iterator_concepts.pdf">PDF</a>): Concept checking classes for the new iterator concepts.</li>
<li><a class="reference external" href="iterator_archetypes.html"><tt class="docutils literal"><span class="pre">iterator_archetypes.hpp</span></tt></a> (<a class="reference external" href="iterator_archetypes.pdf">PDF</a>): Concept archetype classes for the new iterators concepts.</li>
</ul>
</div>
</div>
<div class="section" id="upgrading-from-the-old-boost-iterator-adaptor-library">
<h1><a class="toc-backref" href="#id29">Upgrading from the old Boost Iterator Adaptor Library</a></h1>
<p id="upgrading">If you have been using the old Boost Iterator Adaptor library to
implement iterators, you probably wrote a <tt class="docutils literal"><span class="pre">Policies</span></tt> class which
captures the core operations of your iterator. In the new library
design, you'll move those same core operations into the body of the
iterator class itself. If you were writing a family of iterators,
you probably wrote a <a class="reference external" href="http://www.boost.org/more/generic_programming.html#type_generator">type generator</a> to build the
<tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> specialization you needed; in the new library
design you don't need a type generator (though may want to keep it
around as a compatibility aid for older code) because, due to the
use of the Curiously Recurring Template Pattern (CRTP) <a class="citation-reference" href="#cop95" id="id22">[Cop95]</a>,
you can now define the iterator class yourself and acquire
functionality through inheritance from <tt class="docutils literal"><span class="pre">iterator_facade</span></tt> or
<tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>. As a result, you also get much finer control
over how your iterator works: you can add additional constructors,
or even override the iterator functionality provided by the
library.</p>
<p>If you're looking for the old <tt class="docutils literal"><span class="pre">projection_iterator</span></tt> component,
its functionality has been merged into <tt class="docutils literal"><span class="pre">transform_iterator</span></tt>: as
long as the function object's <tt class="docutils literal"><span class="pre">result_type</span></tt> (or the <tt class="docutils literal"><span class="pre">Reference</span></tt>
template argument, if explicitly specified) is a true reference
type, <tt class="docutils literal"><span class="pre">transform_iterator</span></tt> will behave like
<tt class="docutils literal"><span class="pre">projection_iterator</span></tt> used to.</p>
</div>
<div class="section" id="history">
<h1><a class="toc-backref" href="#id30">History</a></h1>
<p>In 2000 Dave Abrahams was writing an iterator for a container of
pointers, which would access the pointed-to elements when
dereferenced. Naturally, being a library writer, he decided to
generalize the idea and the Boost Iterator Adaptor library was born.
Dave was inspired by some writings of Andrei Alexandrescu and chose a
policy based design (though he probably didn't capture Andrei's idea
very well - there was only one policy class for all the iterator's
orthogonal properties). Soon Jeremy Siek realized he would need the
library and they worked together to produce a &quot;Boostified&quot; version,
which was reviewed and accepted into the library. They wrote a paper
and made several important revisions of the code.</p>
<p>Eventually, several shortcomings of the older library began to make
the need for a rewrite apparent. Dave and Jeremy started working
at the Santa Cruz C++ committee meeting in 2002, and had quickly
generated a working prototype. At the urging of Mat Marcus, they
decided to use the GenVoca/CRTP pattern approach, and moved the
policies into the iterator class itself. Thomas Witt expressed
interest and became the voice of strict compile-time checking for
the project, adding uses of the SFINAE technique to eliminate false
converting constructors and operators from the overload set. He
also recognized the need for a separate <tt class="docutils literal"><span class="pre">iterator_facade</span></tt>, and
factored it out of <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>. Finally, after a
near-complete rewrite of the prototype, they came up with the
library you see today.</p>
<table class="docutils citation" frame="void" id="cop95" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id22">[Cop95]</a></td><td>[Coplien, 1995] Coplien, J., Curiously Recurring Template
Patterns, C++ Report, February 1995, pp. 24-27.</td></tr>
</tbody>
</table>
<!-- LocalWords: Abrahams Siek Witt const bool Sutter's WG int UL LI href Lvalue
LocalWords: ReadableIterator WritableIterator SwappableIterator cv pre iter
LocalWords: ConstantLvalueIterator MutableLvalueIterator CopyConstructible TR
LocalWords: ForwardTraversalIterator BidirectionalTraversalIterator lvalue
LocalWords: RandomAccessTraversalIterator dereferenceable Incrementable tmp
LocalWords: incrementable xxx min prev inplace png oldeqnew AccessTag struct
LocalWords: TraversalTag typename lvalues DWA Hmm JGS -->
</div>
</div>
<div class="footer">
<hr class="footer" />
<a class="reference external" href="index.rst">View document source</a>.
Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div>
</body>
</html>
libs/iterator/doc/index.rst
+331
View File
@@ -0,0 +1,331 @@
.. Distributed under 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)
+++++++++++++++++++++++++++++++++++++++++++++++++
The Boost.Iterator Library |(logo)|__
+++++++++++++++++++++++++++++++++++++++++++++++++
.. |(logo)| image:: ../../../boost.png
:alt: Boost
__ ../../../index.htm
-------------------------------------
:Authors: David Abrahams, Jeremy Siek, Thomas Witt
:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@styleadvisor.com
:organizations: `Boost Consulting`_, Indiana University `Open Systems
Lab`_, `Zephyr Associates, Inc.`_
:date: $Date$
:copyright: Copyright David Abrahams, Jeremy Siek, Thomas Witt 2003.
.. _`Boost Consulting`: http://www.boost-consulting.com
.. _`Open Systems Lab`: http://www.osl.iu.edu
.. _`Zephyr Associates, Inc.`: http://www.styleadvisor.com
:Abstract: The Boost Iterator Library contains two parts. The first
is a system of concepts_ which extend the C++ standard
iterator requirements. The second is a framework of
components for building iterators based on these
extended concepts and includes several useful iterator
adaptors. The extended iterator concepts have been
carefully designed so that old-style iterators
can fit in the new concepts and so that new-style
iterators will be compatible with old-style algorithms,
though algorithms may need to be updated if they want to
take full advantage of the new-style iterator
capabilities. Several components of this library have
been accepted into the C++ standard technical report.
The components of the Boost Iterator Library replace the
older Boost Iterator Adaptor Library.
.. _concepts: http://www.boost.org/more/generic_programming.html#concept
.. contents:: **Table of Contents**
-------------------------------------
=====================
New-Style Iterators
=====================
The iterator categories defined in C++98 are extremely limiting
because they bind together two orthogonal concepts: traversal and
element access. For example, because a random access iterator is
required to return a reference (and not a proxy) when dereferenced,
it is impossible to capture the capabilities of
``vector<bool>::iterator`` using the C++98 categories. This is the
infamous "``vector<bool>`` is not a container, and its iterators
aren't random access iterators", debacle about which Herb Sutter
wrote two papers for the standards comittee (n1185_ and n1211_),
and a `Guru of the Week`__. New-style iterators go well beyond
patching up ``vector<bool>``, though: there are lots of other
iterators already in use which can't be adequately represented by
the existing concepts. For details about the new iterator
concepts, see our
.. _n1185: http://www.gotw.ca/publications/N1185.pdf
.. _n1211: http://www.gotw.ca/publications/N1211.pdf
__ http://www.gotw.ca/gotw/050.htm
`Standard Proposal For New-Style Iterators`__ (PDF__)
__ new-iter-concepts.html
__ new-iter-concepts.pdf
=============================
Iterator Facade and Adaptor
=============================
Writing standard-conforming iterators is tricky, but the need comes
up often. In order to ease the implementation of new iterators,
the Boost.Iterator library provides the |facade| class template,
which implements many useful defaults and compile-time checks
designed to help the iterator author ensure that his iterator is
correct.
It is also common to define a new iterator that is similar to some
underlying iterator or iterator-like type, but that modifies some
aspect of the underlying type's behavior. For that purpose, the
library supplies the |adaptor| class template, which is specially
designed to take advantage of as much of the underlying type's
behavior as possible.
The documentation for these two classes can be found at the following
web pages:
* |facade|_ (PDF__)
* |adaptor|_ (PDF__)
.. |facade| replace:: ``iterator_facade``
.. _facade: iterator_facade.html
__ iterator_facade.pdf
.. |adaptor| replace:: ``iterator_adaptor``
.. _adaptor: iterator_adaptor.html
__ iterator_adaptor.pdf
Both |facade| and |adaptor| as well as many of the `specialized
adaptors`_ mentioned below have been proposed for standardization,
and accepted into the first C++ technical report; see our
`Standard Proposal For Iterator Facade and Adaptor`__ (PDF__)
for more details.
__ facade-and-adaptor.html
__ facade-and-adaptor.pdf
======================
Specialized Adaptors
======================
The iterator library supplies a useful suite of standard-conforming
iterator templates based on the Boost `iterator facade and adaptor`_.
* |counting|_ (PDF__): an iterator over a sequence of consecutive values.
Implements a "lazy sequence"
* |filter|_ (PDF__): an iterator over the subset of elements of some
sequence which satisfy a given predicate
* |function_input|_ (PDF__): an input iterator wrapping a generator (nullary
function object); each time the iterator is dereferenced, the function object
is called to get the value to return.
* |function_output|_ (PDF__): an output iterator wrapping a unary function
object; each time an element is written into the dereferenced
iterator, it is passed as a parameter to the function object.
* |indirect|_ (PDF__): an iterator over the objects *pointed-to* by the
elements of some sequence.
* |permutation|_ (PDF__): an iterator over the elements of some random-access
sequence, rearranged according to some sequence of integer indices.
* |reverse|_ (PDF__): an iterator which traverses the elements of some
bidirectional sequence in reverse. Corrects many of the
shortcomings of C++98's ``std::reverse_iterator``.
* |shared|_: an iterator over elements of a container whose
lifetime is maintained by a |shared_ptr|_ stored in the iterator.
* |transform|_ (PDF__): an iterator over elements which are the result of
applying some functional transformation to the elements of an
underlying sequence. This component also replaces the old
``projection_iterator_adaptor``.
* |zip|_ (PDF__): an iterator over tuples of the elements at corresponding
positions of heterogeneous underlying iterators.
.. |counting| replace:: ``counting_iterator``
.. _counting: counting_iterator.html
__ counting_iterator.pdf
.. |filter| replace:: ``filter_iterator``
.. _filter: filter_iterator.html
__ filter_iterator.pdf
.. |function_input| replace:: ``function_input_iterator``
.. _function_input: function_input_iterator.html
__ function_input_iterator.pdf
.. |function_output| replace:: ``function_output_iterator``
.. _function_output: function_output_iterator.html
__ function_output_iterator.pdf
.. |indirect| replace:: ``indirect_iterator``
.. _indirect: indirect_iterator.html
__ indirect_iterator.pdf
.. |permutation| replace:: ``permutation_iterator``
.. _permutation: permutation_iterator.html
__ permutation_iterator.pdf
.. |reverse| replace:: ``reverse_iterator``
.. _reverse: reverse_iterator.html
__ reverse_iterator.pdf
.. |shared| replace:: ``shared_container_iterator``
.. _shared: ../../utility/shared_container_iterator.html
.. |transform| replace:: ``transform_iterator``
.. _transform: transform_iterator.html
__ transform_iterator.pdf
.. |zip| replace:: ``zip_iterator``
.. _zip: zip_iterator.html
__ zip_iterator.pdf
.. |shared_ptr| replace:: ``shared_ptr``
.. _shared_ptr: ../../smart_ptr/shared_ptr.htm
====================
Iterator Utilities
====================
Traits
------
* |pointee|_ (PDF__): Provides the capability to deduce the referent types
of pointers, smart pointers and iterators in generic code. Used
in |indirect|.
* |iterator_traits|_ (PDF__): Provides MPL_\ -compatible metafunctions which
retrieve an iterator's traits. Also corrects for the deficiencies
of broken implementations of ``std::iterator_traits``.
.. * |interoperable|_ (PDF__): Provides an MPL_\ -compatible metafunction for
testing iterator interoperability
.. |pointee| replace:: ``pointee.hpp``
.. _pointee: pointee.html
__ pointee.pdf
.. |iterator_traits| replace:: ``iterator_traits.hpp``
.. _iterator_traits: iterator_traits.html
__ iterator_traits.pdf
.. |interoperable| replace:: ``interoperable.hpp``
.. _interoperable: interoperable.html
.. comment! __ interoperable.pdf
.. _MPL: ../../mpl/doc/index.html
Testing and Concept Checking
----------------------------
* |iterator_concepts|_ (PDF__): Concept checking classes for the new iterator concepts.
* |iterator_archetypes|_ (PDF__): Concept archetype classes for the new iterators concepts.
.. |iterator_concepts| replace:: ``iterator_concepts.hpp``
.. _iterator_concepts: iterator_concepts.html
__ iterator_concepts.pdf
.. |iterator_archetypes| replace:: ``iterator_archetypes.hpp``
.. _iterator_archetypes: iterator_archetypes.html
__ iterator_archetypes.pdf
=======================================================
Upgrading from the old Boost Iterator Adaptor Library
=======================================================
.. _Upgrading:
If you have been using the old Boost Iterator Adaptor library to
implement iterators, you probably wrote a ``Policies`` class which
captures the core operations of your iterator. In the new library
design, you'll move those same core operations into the body of the
iterator class itself. If you were writing a family of iterators,
you probably wrote a `type generator`_ to build the
``iterator_adaptor`` specialization you needed; in the new library
design you don't need a type generator (though may want to keep it
around as a compatibility aid for older code) because, due to the
use of the Curiously Recurring Template Pattern (CRTP) [Cop95]_,
you can now define the iterator class yourself and acquire
functionality through inheritance from ``iterator_facade`` or
``iterator_adaptor``. As a result, you also get much finer control
over how your iterator works: you can add additional constructors,
or even override the iterator functionality provided by the
library.
.. _`type generator`: http://www.boost.org/more/generic_programming.html#type_generator
If you're looking for the old ``projection_iterator`` component,
its functionality has been merged into ``transform_iterator``: as
long as the function object's ``result_type`` (or the ``Reference``
template argument, if explicitly specified) is a true reference
type, ``transform_iterator`` will behave like
``projection_iterator`` used to.
=========
History
=========
In 2000 Dave Abrahams was writing an iterator for a container of
pointers, which would access the pointed-to elements when
dereferenced. Naturally, being a library writer, he decided to
generalize the idea and the Boost Iterator Adaptor library was born.
Dave was inspired by some writings of Andrei Alexandrescu and chose a
policy based design (though he probably didn't capture Andrei's idea
very well - there was only one policy class for all the iterator's
orthogonal properties). Soon Jeremy Siek realized he would need the
library and they worked together to produce a "Boostified" version,
which was reviewed and accepted into the library. They wrote a paper
and made several important revisions of the code.
Eventually, several shortcomings of the older library began to make
the need for a rewrite apparent. Dave and Jeremy started working
at the Santa Cruz C++ committee meeting in 2002, and had quickly
generated a working prototype. At the urging of Mat Marcus, they
decided to use the GenVoca/CRTP pattern approach, and moved the
policies into the iterator class itself. Thomas Witt expressed
interest and became the voice of strict compile-time checking for
the project, adding uses of the SFINAE technique to eliminate false
converting constructors and operators from the overload set. He
also recognized the need for a separate ``iterator_facade``, and
factored it out of ``iterator_adaptor``. Finally, after a
near-complete rewrite of the prototype, they came up with the
library you see today.
.. [Cop95] [Coplien, 1995] Coplien, J., Curiously Recurring Template
Patterns, C++ Report, February 1995, pp. 24-27.
..
LocalWords: Abrahams Siek Witt const bool Sutter's WG int UL LI href Lvalue
LocalWords: ReadableIterator WritableIterator SwappableIterator cv pre iter
LocalWords: ConstantLvalueIterator MutableLvalueIterator CopyConstructible TR
LocalWords: ForwardTraversalIterator BidirectionalTraversalIterator lvalue
LocalWords: RandomAccessTraversalIterator dereferenceable Incrementable tmp
LocalWords: incrementable xxx min prev inplace png oldeqnew AccessTag struct
LocalWords: TraversalTag typename lvalues DWA Hmm JGS
libs/iterator/doc/indirect_iterator.html
+345
View File
@@ -0,0 +1,345 @@
<?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.5: http://docutils.sourceforge.net/" />
<title>Indirect Iterator</title>
<meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" />
<meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, University of Hanover Institute for Transport Railway Operation and Construction" />
<meta name="date" content="2006-09-11" />
<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003." />
<link rel="stylesheet" href="../../../rst.css" type="text/css" />
</head>
<body>
<div class="document" id="indirect-iterator">
<h1 class="title">Indirect 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, Jeremy Siek, Thomas Witt</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first reference external" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference external" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="last reference external" href="mailto:witt&#64;ive.uni-hannover.de">witt&#64;ive.uni-hannover.de</a></td></tr>
<tr><th class="docinfo-name">Organization:</th>
<td><a class="first reference external" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference external" href="http://www.osl.iu.edu">Open Systems
Lab</a>, University of Hanover <a class="last reference external" href="http://www.ive.uni-hannover.de">Institute for Transport
Railway Operation and Construction</a></td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2006-09-11</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003.</td></tr>
</tbody>
</table>
<!-- Distributed under 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) -->
<table class="docutils 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"><!-- Copyright David Abrahams 2006. Distributed under 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) -->
<tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> adapts an iterator by applying an
<em>extra</em> dereference inside of <tt class="docutils literal"><span class="pre">operator*()</span></tt>. For example, this
iterator adaptor makes it possible to view a container of pointers
(e.g. <tt class="docutils literal"><span class="pre">list&lt;foo*&gt;</span></tt>) as if it were a container of the pointed-to type
(e.g. <tt class="docutils literal"><span class="pre">list&lt;foo&gt;</span></tt>). <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> depends on two
auxiliary traits, <tt class="docutils literal"><span class="pre">pointee</span></tt> and <tt class="docutils literal"><span class="pre">indirect_reference</span></tt>, to
provide support for underlying iterators whose <tt class="docutils literal"><span class="pre">value_type</span></tt> is
not an iterator.</td>
</tr>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#indirect-iterator-synopsis" id="id2"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> synopsis</a></li>
<li><a class="reference internal" href="#indirect-iterator-requirements" id="id3"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> requirements</a></li>
<li><a class="reference internal" href="#indirect-iterator-models" id="id4"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> models</a></li>
<li><a class="reference internal" href="#indirect-iterator-operations" id="id5"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> operations</a></li>
<li><a class="reference internal" href="#example" id="id6">Example</a></li>
</ul>
</div>
<div class="section" id="indirect-iterator-synopsis">
<h1><a class="toc-backref" href="#id2"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> synopsis</a></h1>
<!-- Copyright David Abrahams 2006. Distributed under 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) -->
<pre class="literal-block">
template &lt;
class Iterator
, class Value = use_default
, class CategoryOrTraversal = use_default
, class Reference = use_default
, class Difference = use_default
&gt;
class indirect_iterator
{
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);
template &lt;
class Iterator2, class Value2, class Category2
, class Reference2, class Difference2
&gt;
indirect_iterator(
indirect_iterator&lt;
Iterator2, Value2, Category2, Reference2, Difference2
&gt; const&amp; y
, typename enable_if_convertible&lt;Iterator2, Iterator&gt;::type* = 0 // exposition
);
Iterator const&amp; base() const;
reference operator*() const;
indirect_iterator&amp; operator++();
indirect_iterator&amp; operator--();
private:
Iterator m_iterator; // exposition
};
</pre>
<p>The member types of <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> are defined according to
the following pseudo-code, where <tt class="docutils literal"><span class="pre">V</span></tt> is
<tt class="docutils literal"><span class="pre">iterator_traits&lt;Iterator&gt;::value_type</span></tt></p>
<pre class="literal-block">
if (Value is use_default) then
typedef remove_const&lt;pointee&lt;V&gt;::type&gt;::type value_type;
else
typedef remove_const&lt;Value&gt;::type value_type;
if (Reference is use_default) then
if (Value is use_default) then
typedef indirect_reference&lt;V&gt;::type reference;
else
typedef Value&amp; reference;
else
typedef Reference reference;
if (Value is use_default) then
typedef pointee&lt;V&gt;::type* pointer;
else
typedef Value* pointer;
if (Difference is use_default)
typedef iterator_traits&lt;Iterator&gt;::difference_type difference_type;
else
typedef Difference difference_type;
if (CategoryOrTraversal is use_default)
typedef <em>iterator-category</em> (
iterator_traversal&lt;Iterator&gt;::type,``reference``,``value_type``
) iterator_category;
else
typedef <em>iterator-category</em> (
CategoryOrTraversal,``reference``,``value_type``
) iterator_category;
</pre>
</div>
<div class="section" id="indirect-iterator-requirements">
<h1><a class="toc-backref" href="#id3"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> requirements</a></h1>
<p>The expression <tt class="docutils literal"><span class="pre">*v</span></tt>, where <tt class="docutils literal"><span class="pre">v</span></tt> is an object of
<tt class="docutils literal"><span class="pre">iterator_traits&lt;Iterator&gt;::value_type</span></tt>, shall be valid
expression and convertible to <tt class="docutils literal"><span class="pre">reference</span></tt>. <tt class="docutils literal"><span class="pre">Iterator</span></tt> shall
model the traversal concept indicated by <tt class="docutils literal"><span class="pre">iterator_category</span></tt>.
<tt class="docutils literal"><span class="pre">Value</span></tt>, <tt class="docutils literal"><span class="pre">Reference</span></tt>, and <tt class="docutils literal"><span class="pre">Difference</span></tt> shall be chosen so
that <tt class="docutils literal"><span class="pre">value_type</span></tt>, <tt class="docutils literal"><span class="pre">reference</span></tt>, and <tt class="docutils literal"><span class="pre">difference_type</span></tt> meet
the requirements indicated by <tt class="docutils literal"><span class="pre">iterator_category</span></tt>.</p>
<p>[Note: there are further requirements on the
<tt class="docutils literal"><span class="pre">iterator_traits&lt;Iterator&gt;::value_type</span></tt> if the <tt class="docutils literal"><span class="pre">Value</span></tt>
parameter is not <tt class="docutils literal"><span class="pre">use_default</span></tt>, as implied by the algorithm for
deducing the default for the <tt class="docutils literal"><span class="pre">value_type</span></tt> member.]</p>
</div>
<div class="section" id="indirect-iterator-models">
<h1><a class="toc-backref" href="#id4"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> models</a></h1>
<p>In addition to the concepts indicated by <tt class="docutils literal"><span class="pre">iterator_category</span></tt>
and by <tt class="docutils literal"><span class="pre">iterator_traversal&lt;indirect_iterator&gt;::type</span></tt>, a
specialization of <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> models the following
concepts, Where <tt class="docutils literal"><span class="pre">v</span></tt> is an object of
<tt class="docutils literal"><span class="pre">iterator_traits&lt;Iterator&gt;::value_type</span></tt>:</p>
<blockquote>
<ul class="simple">
<li>Readable Iterator if <tt class="docutils literal"><span class="pre">reference(*v)</span></tt> is convertible to
<tt class="docutils literal"><span class="pre">value_type</span></tt>.</li>
<li>Writable Iterator if <tt class="docutils literal"><span class="pre">reference(*v)</span> <span class="pre">=</span> <span class="pre">t</span></tt> is a valid
expression (where <tt class="docutils literal"><span class="pre">t</span></tt> is an object of type
<tt class="docutils literal"><span class="pre">indirect_iterator::value_type</span></tt>)</li>
<li>Lvalue Iterator if <tt class="docutils literal"><span class="pre">reference</span></tt> is a reference type.</li>
</ul>
</blockquote>
<p><tt class="docutils literal"><span class="pre">indirect_iterator&lt;X,V1,C1,R1,D1&gt;</span></tt> is interoperable with
<tt class="docutils literal"><span class="pre">indirect_iterator&lt;Y,V2,C2,R2,D2&gt;</span></tt> if and only if <tt class="docutils literal"><span class="pre">X</span></tt> is
interoperable with <tt class="docutils literal"><span class="pre">Y</span></tt>.</p>
</div>
<div class="section" id="indirect-iterator-operations">
<h1><a class="toc-backref" href="#id5"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> operations</a></h1>
<p>In addition to the operations required by the concepts described
above, specializations of <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> provide the
following operations.</p>
<p><tt class="docutils literal"><span class="pre">indirect_iterator();</span></tt></p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="docutils literal"><span class="pre">Iterator</span></tt> must be Default Constructible.</td>
</tr>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Constructs an instance of <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> with
a default-constructed <tt class="docutils literal"><span class="pre">m_iterator</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">indirect_iterator(Iterator</span> <span class="pre">x);</span></tt></p>
<table class="docutils 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">Constructs an instance of <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> with
<tt class="docutils literal"><span class="pre">m_iterator</span></tt> copy constructed from <tt class="docutils literal"><span class="pre">x</span></tt>.</td>
</tr>
</tbody>
</table>
<pre class="literal-block">
template &lt;
class Iterator2, class Value2, unsigned Access, class Traversal
, class Reference2, class Difference2
&gt;
indirect_iterator(
indirect_iterator&lt;
Iterator2, Value2, Access, Traversal, Reference2, Difference2
&gt; const&amp; y
, typename enable_if_convertible&lt;Iterator2, Iterator&gt;::type* = 0 // exposition
);
</pre>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="docutils literal"><span class="pre">Iterator2</span></tt> is implicitly convertible to <tt class="docutils literal"><span class="pre">Iterator</span></tt>.</td>
</tr>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Constructs an instance of <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> whose
<tt class="docutils literal"><span class="pre">m_iterator</span></tt> subobject is constructed from <tt class="docutils literal"><span class="pre">y.base()</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">Iterator</span> <span class="pre">const&amp;</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
<table class="docutils 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="docutils literal"><span class="pre">m_iterator</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">reference</span> <span class="pre">operator*()</span> <span class="pre">const;</span></tt></p>
<table class="docutils 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="docutils literal"><span class="pre">**m_iterator</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">indirect_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
<table class="docutils 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"><tt class="docutils literal"><span class="pre">++m_iterator</span></tt></td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">indirect_iterator&amp;</span> <span class="pre">operator--();</span></tt></p>
<table class="docutils 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"><tt class="docutils literal"><span class="pre">--m_iterator</span></tt></td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
</tr>
</tbody>
</table>
<!-- Copyright David Abrahams 2006. Distributed under 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) -->
</div>
<div class="section" id="example">
<h1><a class="toc-backref" href="#id6">Example</a></h1>
<p>This example prints an array of characters, using
<tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> to access the array of characters through an
array of pointers. Next <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> is used with the
<tt class="docutils literal"><span class="pre">transform</span></tt> algorithm to copy the characters (incremented by one) to
another array. A constant indirect iterator is used for the source and
a mutable indirect iterator is used for the destination. The last part
of the example prints the original array of characters, but this time
using the <tt class="docutils literal"><span class="pre">make_indirect_iterator</span></tt> helper function.</p>
<pre class="literal-block">
char characters[] = &quot;abcdefg&quot;;
const int N = sizeof(characters)/sizeof(char) - 1; // -1 since characters has a null char
char* pointers_to_chars[N]; // at the end.
for (int i = 0; i &lt; N; ++i)
pointers_to_chars[i] = &amp;characters[i];
// Example of using indirect_iterator
boost::indirect_iterator&lt;char**, char&gt;
indirect_first(pointers_to_chars), indirect_last(pointers_to_chars + N);
std::copy(indirect_first, indirect_last, std::ostream_iterator&lt;char&gt;(std::cout, &quot;,&quot;));
std::cout &lt;&lt; std::endl;
// Example of making mutable and constant indirect iterators
char mutable_characters[N];
char* pointers_to_mutable_chars[N];
for (int j = 0; j &lt; N; ++j)
pointers_to_mutable_chars[j] = &amp;mutable_characters[j];
boost::indirect_iterator&lt;char* const*&gt; mutable_indirect_first(pointers_to_mutable_chars),
mutable_indirect_last(pointers_to_mutable_chars + N);
boost::indirect_iterator&lt;char* const*, char const&gt; const_indirect_first(pointers_to_chars),
const_indirect_last(pointers_to_chars + N);
std::transform(const_indirect_first, const_indirect_last,
mutable_indirect_first, std::bind1st(std::plus&lt;char&gt;(), 1));
std::copy(mutable_indirect_first, mutable_indirect_last,
std::ostream_iterator&lt;char&gt;(std::cout, &quot;,&quot;));
std::cout &lt;&lt; std::endl;
// Example of using make_indirect_iterator()
std::copy(boost::make_indirect_iterator(pointers_to_chars),
boost::make_indirect_iterator(pointers_to_chars + N),
std::ostream_iterator&lt;char&gt;(std::cout, &quot;,&quot;));
std::cout &lt;&lt; std::endl;
</pre>
<p>The output is:</p>
<pre class="literal-block">
a,b,c,d,e,f,g,
b,c,d,e,f,g,h,
a,b,c,d,e,f,g,
</pre>
<p>The source code for this example can be found <a class="reference external" href="../example/indirect_iterator_example.cpp">here</a>.</p>
</div>
</div>
<div class="footer">
<hr class="footer" />
<a class="reference external" href="indirect_iterator.rst">View document source</a>.
Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div>
</body>
</html>
libs/iterator/doc/indirect_iterator.pdf
BIN
View File
Binary file not shown.
libs/iterator/doc/indirect_iterator.rst
+34
View File
@@ -0,0 +1,34 @@
.. Distributed under 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)
+++++++++++++++++++
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 David Abrahams, Jeremy Siek, and Thomas Witt 2003.
.. _`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
``indirect_iterator`` synopsis
..............................
.. include:: indirect_iterator_ref.rst
.. include:: indirect_iterator_eg.rst
.. _iterator-category: iterator_facade.html#iterator-category
.. |iterator-category| replace:: *iterator-category*
libs/iterator/doc/indirect_iterator_abstract.rst
+15
View File
@@ -0,0 +1,15 @@
.. Copyright David Abrahams 2006. Distributed under 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)
``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>``). ``indirect_iterator`` depends on two
auxiliary traits, ``pointee`` and ``indirect_reference``, to
provide support for underlying iterators whose ``value_type`` is
not an iterator.
libs/iterator/doc/indirect_iterator_eg.rst
+73
View File
@@ -0,0 +1,73 @@
.. Copyright David Abrahams 2006. Distributed under 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)
Example
.......
This example prints an array of characters, using
``indirect_iterator`` to access the array of characters through an
array of pointers. Next ``indirect_iterator`` is used with the
``transform`` algorithm to copy the characters (incremented by one) to
another array. A constant indirect iterator is used for the source and
a mutable indirect iterator is used for the destination. The last part
of the example prints the original array of characters, but this time
using the ``make_indirect_iterator`` helper function.
::
char characters[] = "abcdefg";
const int N = sizeof(characters)/sizeof(char) - 1; // -1 since characters has a null char
char* pointers_to_chars[N]; // at the end.
for (int i = 0; i < N; ++i)
pointers_to_chars[i] = &characters[i];
// Example of using indirect_iterator
boost::indirect_iterator<char**, char>
indirect_first(pointers_to_chars), indirect_last(pointers_to_chars + N);
std::copy(indirect_first, indirect_last, std::ostream_iterator<char>(std::cout, ","));
std::cout << std::endl;
// Example of making mutable and constant indirect iterators
char mutable_characters[N];
char* pointers_to_mutable_chars[N];
for (int j = 0; j < N; ++j)
pointers_to_mutable_chars[j] = &mutable_characters[j];
boost::indirect_iterator<char* const*> mutable_indirect_first(pointers_to_mutable_chars),
mutable_indirect_last(pointers_to_mutable_chars + N);
boost::indirect_iterator<char* const*, char const> const_indirect_first(pointers_to_chars),
const_indirect_last(pointers_to_chars + N);
std::transform(const_indirect_first, const_indirect_last,
mutable_indirect_first, std::bind1st(std::plus<char>(), 1));
std::copy(mutable_indirect_first, mutable_indirect_last,
std::ostream_iterator<char>(std::cout, ","));
std::cout << std::endl;
// Example of using make_indirect_iterator()
std::copy(boost::make_indirect_iterator(pointers_to_chars),
boost::make_indirect_iterator(pointers_to_chars + N),
std::ostream_iterator<char>(std::cout, ","));
std::cout << std::endl;
The output is::
a,b,c,d,e,f,g,
b,c,d,e,f,g,h,
a,b,c,d,e,f,g,
The source code for this example can be found `here`__.
__ ../example/indirect_iterator_example.cpp
libs/iterator/doc/indirect_iterator_ref.rst
+181
View File
@@ -0,0 +1,181 @@
.. Copyright David Abrahams 2006. Distributed under 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)
::
template <
class Iterator
, class Value = use_default
, class CategoryOrTraversal = use_default
, class Reference = use_default
, class Difference = use_default
>
class indirect_iterator
{
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);
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
);
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
..................................
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.]
``indirect_iterator`` models
............................
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``:
* Readable Iterator if ``reference(*v)`` is convertible to
``value_type``.
* Writable Iterator if ``reference(*v) = t`` is a valid
expression (where ``t`` is an object of type
``indirect_iterator::value_type``)
* 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
................................
In addition to the operations required by the concepts described
above, specializations of ``indirect_iterator`` provide the
following operations.
``indirect_iterator();``
:Requires: ``Iterator`` must be Default Constructible.
:Effects: Constructs an instance of ``indirect_iterator`` with
a default-constructed ``m_iterator``.
``indirect_iterator(Iterator x);``
:Effects: Constructs an instance of ``indirect_iterator`` with
``m_iterator`` copy constructed from ``x``.
::
template <
class Iterator2, class Value2, unsigned Access, class Traversal
, class Reference2, class Difference2
>
indirect_iterator(
indirect_iterator<
Iterator2, Value2, Access, Traversal, Reference2, Difference2
> const& y
, typename enable_if_convertible<Iterator2, Iterator>::type* = 0 // exposition
);
:Requires: ``Iterator2`` is implicitly convertible to ``Iterator``.
:Effects: Constructs an instance of ``indirect_iterator`` whose
``m_iterator`` subobject is constructed from ``y.base()``.
``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``
libs/iterator/doc/indirect_reference_ref.rst
+29
View File
@@ -0,0 +1,29 @@
.. 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)
::
template <class Dereferenceable>
struct indirect_reference
{
typedef /* see below */ type;
};
:Requires: For an object ``x`` of type ``Dereferenceable``, ``*x``
is well-formed. If ``++x`` is ill-formed it shall neither be
ambiguous nor shall it violate access control, and
``pointee<Dereferenceable>::type&`` shall be well-formed.
Otherwise ``iterator_traits<Dereferenceable>::reference`` shall
be well formed. [Note: These requirements need not apply to
explicit or partial specializations of ``indirect_reference``]
``type`` is determined according to the following algorithm, where
``x`` is an object of type ``Dereferenceable``::
if ( ++x is ill-formed )
return ``pointee<Dereferenceable>::type&``
else
std::iterator_traits<Dereferenceable>::reference
libs/iterator/doc/interoperability-revisited.rst
+238
View File
@@ -0,0 +1,238 @@
++++++++++++++++++++++++++++
Interoperability Revisited
++++++++++++++++++++++++++++
:date: $Date$
:copyright: Copyright Thomas Witt 2004.
.. Distributed under 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)
Problem
=======
The current iterator_facade specification makes it unneccessarily tedious to
implement interoperable iterators.
In the following text a simplified example of the current iterator_facade specification is used to
illustrate the problem.
In the current specification binary operators are implemented in the following way::
template <class Derived>
struct Facade
{
};
template <class T1, T2>
struct is_interoperable :
or_<
is_convertible<T1, T2>
, is_convertible<T2, T1>
>
{};
template<
class Derived1
, class Derived2
>
enable_if<is_interoperable<Derived1, Derived2>, bool> operator==(
Derived1 const& lhs
, Derived2 const& rhs
)
{
return static_cast<Derived1 const&>(lhs).equal_to(static_cast<Derived2 const&(rhs));
}
The problem with this is that operator== always forwards to Derived1::equal_to. The net effect is that the
following "obvious" implementation of to interoperable types does
not quite work. ::
struct Mutable : Facade<Mutable>
{
bool equal_to(Mutable const&);
};
struct Constant : Facade<Constant>
{
Constant();
Constant(Constant const&);
Constant(Mutable const&);
...
bool equal_to(Constant const&);
};
Constant c;
Mutable m;
c == m; // ok, dispatched to Constant::equal_to
m == c; // !! error, dispatched to Mutable::equal_to
Instead the following "slightly" more complicated implementation is necessary
struct Mutable : Facade<Mutable>
{
template <class T>
enable_if<is_convertible<Mutable, T> || is_convertible<T, Mutable>, bool>::type equal_to(T const&);
};
struct Constant : Tag<Constant>
{
Constant();
Constant(Constant const&);
Constant(Mutable const&);
template <class T>
enable_if<is_convertible<Constant, T> || is_convertible<T, Constant>, bool>::type equal_to(T const&);
};
Beside the fact that the code is significantly more complex to understand and to teach there is
a major design problem lurking here. Note that in both types equal_to is a function template with
an unconstrained argument T. This is necessary so that further types can be made interoperable with
Mutable or Constant. Would Mutable be defined as ::
struct Mutable : Facade<Mutable>
{
bool equal_to(Mutable const&);
bool equal_to(Constant const&);
};
Constant and Mutable would still be interoperable but no further interoperable could be added
without changing Mutable. Even if this would be considered acceptable the current specification forces
a two way dependency between interoperable types. Note in the templated equal_to case this dependency
is implicitly created when specializing equal_to.
Solution
========
The two way dependency can be avoided by enabling type conversion in the binary operator
implementation. Note that this is the usual way interoperability betwween types is achieved
for binary operators and one reason why binary operators are usually implemented as non-members.
A simple implementation of this strategy would look like this ::
template<
class T1
, class T2
>
struct interoperable_base :
if_<
is_convertible<
T2
, T1
>
, T1
, T2>
{};
template<
class Derived1
, class Derived2
>
enable_if<is_interoperable<Derived1, Derived2>, bool> operator==(
Derived1 const& lhs
, Derived2 const& rhs
)
{
typedef interoperable_base<
Derived1
, Derived2
>::type Base;
return static_cast<Base const&>(lhs).equal_to(static_cast<Derived2 const&(rhs));
}
This way our original simple and "obvious" implementation would
work again. ::
c == m; // ok, dispatched to Constant::equal_to
m == c; // ok, dispatched to Constant::equal_to, m converted to Constant
The backdraw of this approach is that a possibly costly conversion of iterator objects
is forced on the user even in cases where direct comparison could be implemented
in a much more efficient way. This problem arises especially for iterator_adaptor
specializations and can be significantly slow down the iteration over ranges. Given the fact
that iteration is a very basic operation this possible performance degradation is not
acceptable.
Luckily whe can have our cake and eat it by a slightly more clever implementation of the binary
operators. ::
template<
class Derived1
, class Derived2
>
enable_if<is_convertible<Derived2, Derived1>, bool> operator==(
Derived1 const& lhs
, Derived2 const& rhs
)
{
return static_cast<Derived1 const&>(lhs).equal_to(static_cast<Derived2 const&(rhs));
}
template<
class Derived1
, class Derived2
>
enable_if<is_convertible<Derived1, Derived2>, bool> operator==(
Derived1 const& lhs
, Derived2 const& rhs
)
{
return static_cast<Derived2 const&>(rhs).equal_to(static_cast<Derived1 const&(lhs));
}
Given our simple and obvious definition of Mutable and Constant nothing has changed yet. ::
c == m; // ok, dispatched to Constant::equal_to, m converted to Constant
m == c; // ok, dispatched to Constant::equal_to, m converted to Constant
But now the user can avoid the type conversion by supplying the
appropriate overload in Constant ::
struct Constant : Facade<Constant>
{
Constant();
Constant(Constant const&);
Constant(Mutable const&);
...
bool equal_to(Constant const&);
bool equal_to(Mutable const&);
};
c == m; // ok, dispatched to Constant::equal_to(Mutable const&), no conversion
m == c; // ok, dispatched to Constant::equal_to(Mutable const&), no conversion
This definition of operator== introduces a possible ambiguity when both types are convertible
to each other. I don't think this is a problem as this behaviour is the same with concrete types.
I.e. ::
struct A {};
bool operator==(A, A);
struct B { B(A); };
bool operator==(B, B);
A a;
B b(a);
a == b; // error, ambiguous overload
Effect
======
Iterator implementations using iterator_facade look exactly as if they were
"hand-implemented" (I am working on better wording).
a) Less burden for the user
b) The definition (standardese) of specialized adpters might be easier
(This has to be proved yet)
libs/iterator/doc/issues.rst
+152
View File
@@ -0,0 +1,152 @@
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Problem with ``is_writable`` and ``is_swappable`` in N1550_
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
.. _N1550: http://www.boost-consulting.com/writing/n1550.html
.. _N1530: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2003/n1530.html
:Author: David Abrahams and Jeremy Siek
:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu
:Organization: `Boost Consulting`_, Indiana University Bloomington
:date: $Date$
:Copyright: Copyright David Abrahams, Jeremy Siek 2003. 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)
.. _`Boost Consulting`: http://www.boost-consulting.com
.. contents:: Table of Contents
==============
Introduction
==============
The ``is_writable`` and ``is_swappable`` traits classes in N1550_
provide a mechanism for determining at compile time if an iterator
type is a model of the new Writable Iterator and Swappable Iterator
concepts, analogous to ``iterator_traits<X>::iterator_category``
for the old iterator concepts. For backward compatibility,
``is_writable`` and ``is_swappable`` not only work with new
iterators, but they also are intended to work for old
iterators (iterators that meet the requirements for one of the
iterator concepts in the current standard). In the case of old
iterators, the writability and swapability is deduced based on the
``iterator_category`` and also the ``reference`` type. The
specification for this deduction gives false positives for forward
iterators that have non-assignable value types.
To review, the part of the ``is_writable`` trait definition which
applies to old iterators is::
if (cat is convertible to output_iterator_tag)
return true;
else if (cat is convertible to forward_iterator_tag
and iterator_traits<Iterator>::reference is a
mutable reference)
return true;
else
return false;
Suppose the ``value_type`` of the iterator ``It`` has a private
assignment operator::
class B {
public:
...
private:
B& operator=(const B&);
};
and suppose the ``reference`` type of the iterator is ``B&``. In
that case, ``is_writable<It>::value`` will be true when in fact
attempting to write into ``B`` will cause an error.
The same problem applies to ``is_swappable``.
====================
Proposed Resolution
====================
1. Remove the ``is_writable`` and ``is_swappable`` traits, and remove the
requirements in the Writable Iterator and Swappable Iterator concepts
that require their models to support these traits.
2. Change the ``is_readable`` specification to be:
``is_readable<X>::type`` is ``true_type`` if the
result type of ``X::operator*`` is convertible to
``iterator_traits<X>::value_type`` and is ``false_type``
otherwise. Also, ``is_readable`` is required to satisfy
the requirements for the UnaryTypeTrait concept
(defined in the type traits proposal).
Remove the requirement for support of the ``is_readable`` trait from
the Readable Iterator concept.
3. Remove the ``iterator_tag`` class.
4. Change the specification of ``traversal_category`` to::
traversal-category(Iterator) =
let cat = iterator_traits<Iterator>::iterator_category
if (cat is convertible to incrementable_iterator_tag)
return cat; // Iterator is a new iterator
else if (cat is convertible to random_access_iterator_tag)
return random_access_traversal_tag;
else if (cat is convertible to bidirectional_iterator_tag)
return bidirectional_traversal_tag;
else if (cat is convertible to forward_iterator_tag)
return forward_traversal_tag;
else if (cat is convertible to input_iterator_tag)
return single_pass_iterator_tag;
else if (cat is convertible to output_iterator_tag)
return incrementable_iterator_tag;
else
return null_category_tag;
==========
Rationale
==========
1. There are two reasons for removing ``is_writable``
and ``is_swappable``. The first is that we do not know of
a way to fix the specification so that it gives the correct
answer for all iterators. Second, there was only a weak
motivation for having ``is_writable`` and ``is_swappable``
there in the first place. The main motivation was simply
uniformity: we have tags for the old iterator categories
so we should have tags for the new iterator categories.
While having tags and the capability to dispatch based
on the traversal categories is often used, we see
less of a need for dispatching based on writability
and swappability, since typically algorithms
that need these capabilities have no alternative if
they are not provided.
2. We discovered that the ``is_readable`` trait can be implemented
using only the iterator type itself and its ``value_type``.
Therefore we remove the requirement for ``is_readable`` from the
Readable Iterator concept, and change the definition of
``is_readable`` so that it works for any iterator type.
3. The purpose of the ``iterator_tag`` class was to
bundle the traversal and access category tags
into the ``iterator_category`` typedef.
With ``is_writable`` and ``is_swappable`` gone, and
``is_readable`` no longer in need of special hints,
there is no reason for iterators to provide
information about the access capabilities of an iterator.
Thus there is no need for the ``iterator_tag``. The
traversal tag can be directly used for the
``iterator_category``. If a new iterator is intended to be backward
compatible with old iterator concepts, a tag type
that is convertible to both one of the new traversal tags
and also to an old iterator tag can be created and use
for the ``iterator_category``.
4. The changes to the specification of ``traversal_category`` are a
direct result of the removal of ``iterator_tag``.
libs/iterator/doc/iterator_adaptor.html
+461
View File
@@ -0,0 +1,461 @@
<?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.5: http://docutils.sourceforge.net/" />
<title>Iterator Adaptor</title>
<meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" />
<meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, University of Hanover Institute for Transport Railway Operation and Construction" />
<meta name="date" content="2006-09-11" />
<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003." />
<link rel="stylesheet" href="../../../rst.css" type="text/css" />
</head>
<body>
<div class="document" id="iterator-adaptor">
<h1 class="title">Iterator Adaptor</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 external" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference external" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="last reference external" href="mailto:witt&#64;ive.uni-hannover.de">witt&#64;ive.uni-hannover.de</a></td></tr>
<tr><th class="docinfo-name">Organization:</th>
<td><a class="first reference external" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference external" href="http://www.osl.iu.edu">Open Systems
Lab</a>, University of Hanover <a class="last reference external" href="http://www.ive.uni-hannover.de">Institute for Transport
Railway Operation and Construction</a></td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2006-09-11</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003.</td></tr>
</tbody>
</table>
<!-- Distributed under 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) -->
<table class="docutils 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"></td>
</tr>
</tbody>
</table>
<!-- Distributed under 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) -->
<!-- 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. -->
<p>Each specialization of the <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> class template is derived from
a specialization of <tt class="docutils literal"><span class="pre">iterator_facade</span></tt>. The core interface functions
expected by <tt class="docutils literal"><span class="pre">iterator_facade</span></tt> are implemented in terms of the
<tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>'s <tt class="docutils literal"><span class="pre">Base</span></tt> template parameter. A class derived
from <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> typically redefines some of the core
interface functions to adapt the behavior of the <tt class="docutils literal"><span class="pre">Base</span></tt> type.
Whether the derived class models any of the standard iterator concepts
depends on the operations supported by the <tt class="docutils literal"><span class="pre">Base</span></tt> type and which
core interface functions of <tt class="docutils literal"><span class="pre">iterator_facade</span></tt> are redefined in the
<tt class="docutils literal"><span class="pre">Derived</span></tt> class.</p>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#overview" id="id6">Overview</a></li>
<li><a class="reference internal" href="#reference" id="id7">Reference</a><ul>
<li><a class="reference internal" href="#iterator-adaptor-requirements" id="id8"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> requirements</a></li>
<li><a class="reference internal" href="#iterator-adaptor-base-class-parameters" id="id9"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> base class parameters</a></li>
<li><a class="reference internal" href="#iterator-adaptor-public-operations" id="id10"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> public operations</a></li>
<li><a class="reference internal" href="#iterator-adaptor-protected-member-functions" id="id11"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> protected member functions</a></li>
<li><a class="reference internal" href="#iterator-adaptor-private-member-functions" id="id12"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> private member functions</a></li>
</ul>
</li>
<li><a class="reference internal" href="#tutorial-example" id="id13">Tutorial Example</a></li>
</ul>
</div>
<div class="section" id="overview">
<h1><a class="toc-backref" href="#id6">Overview</a></h1>
<!-- Distributed under 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) -->
<!-- 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. -->
<p>The <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> class template adapts some <tt class="docutils literal"><span class="pre">Base</span></tt><a class="footnote-reference" href="#base" id="id1"><sup>1</sup></a>
type to create a new iterator. Instantiations of <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>
are derived from a corresponding instantiation of <tt class="docutils literal"><span class="pre">iterator_facade</span></tt>
and implement the core behaviors in terms of the <tt class="docutils literal"><span class="pre">Base</span></tt> type. In
essence, <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> merely forwards all operations to an
instance of the <tt class="docutils literal"><span class="pre">Base</span></tt> type, which it stores as a member.</p>
<table class="docutils footnote" frame="void" id="base" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[1]</td><td><em>(<a class="fn-backref" href="#id1">1</a>, <a class="fn-backref" href="#id3">2</a>)</em> The term &quot;Base&quot; here does not refer to a base class and is
not meant to imply the use of derivation. We have followed the lead
of the standard library, which provides a base() function to access
the underlying iterator object of a <tt class="docutils literal"><span class="pre">reverse_iterator</span></tt> adaptor.</td></tr>
</tbody>
</table>
<p>The user of <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> creates a class derived from an
instantiation of <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> and then selectively
redefines some of the core member functions described in the
<tt class="docutils literal"><span class="pre">iterator_facade</span></tt> core requirements table. The <tt class="docutils literal"><span class="pre">Base</span></tt> type need
not meet the full requirements for an iterator; it need only
support the operations used by the core interface functions of
<tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> that have not been redefined in the user's
derived class.</p>
<p>Several of the template parameters of <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> default
to <tt class="docutils literal"><span class="pre">use_default</span></tt>. 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
complicated, so metaprogramming is required to compute them, and
<tt class="docutils literal"><span class="pre">use_default</span></tt> can help to simplify the implementation. Finally,
the identity of the <tt class="docutils literal"><span class="pre">use_default</span></tt> type is not left unspecified
because specification helps to highlight that the <tt class="docutils literal"><span class="pre">Reference</span></tt>
template parameter may not always be identical to the iterator's
<tt class="docutils literal"><span class="pre">reference</span></tt> type, and will keep users from making mistakes based on
that assumption.</p>
</div>
<div class="section" id="reference">
<h1><a class="toc-backref" href="#id7">Reference</a></h1>
<!-- Distributed under 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) -->
<!-- Version 1.4 of this ReStructuredText document corresponds to
n1530_, the paper accepted by the LWG for TR1. -->
<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. -->
<pre class="literal-block">
template &lt;
class Derived
, class Base
, class Value = use_default
, class CategoryOrTraversal = use_default
, class Reference = use_default
, class Difference = use_default
&gt;
class iterator_adaptor
: public iterator_facade&lt;Derived, <em>V'</em>, <em>C'</em>, <em>R'</em>, <em>D'</em>&gt; // see <a class="reference internal" href="#base-parameters">details</a>
{
friend class iterator_core_access;
public:
iterator_adaptor();
explicit iterator_adaptor(Base const&amp; iter);
typedef Base base_type;
Base const&amp; base() const;
protected:
typedef iterator_adaptor iterator_adaptor_;
Base const&amp; base_reference() const;
Base&amp; base_reference();
private: // Core iterator interface for iterator_facade.
typename iterator_adaptor::reference dereference() const;
template &lt;
class OtherDerived, class OtherIterator, class V, class C, class R, class D
&gt;
bool equal(iterator_adaptor&lt;OtherDerived, OtherIterator, V, C, R, D&gt; const&amp; x) const;
void advance(typename iterator_adaptor::difference_type n);
void increment();
void decrement();
template &lt;
class OtherDerived, class OtherIterator, class V, class C, class R, class D
&gt;
typename iterator_adaptor::difference_type distance_to(
iterator_adaptor&lt;OtherDerived, OtherIterator, V, C, R, D&gt; const&amp; y) const;
private:
Base m_iterator; // exposition only
};
</pre>
<div class="section" id="iterator-adaptor-requirements">
<span id="requirements"></span><h2><a class="toc-backref" href="#id8"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> requirements</a></h2>
<p><tt class="docutils literal"><span class="pre">static_cast&lt;Derived*&gt;(iterator_adaptor*)</span></tt> shall be well-formed.
The <tt class="docutils literal"><span class="pre">Base</span></tt> argument shall be Assignable and Copy Constructible.</p>
</div>
<div class="section" id="iterator-adaptor-base-class-parameters">
<span id="base-parameters"></span><h2><a class="toc-backref" href="#id9"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> base class parameters</a></h2>
<p>The <em>V'</em>, <em>C'</em>, <em>R'</em>, and <em>D'</em> parameters of the <tt class="docutils literal"><span class="pre">iterator_facade</span></tt>
used as a base class in the summary of <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>
above are defined as follows:</p>
<pre class="literal-block">
<em>V'</em> = if (Value is use_default)
return iterator_traits&lt;Base&gt;::value_type
else
return Value
<em>C'</em> = if (CategoryOrTraversal is use_default)
return iterator_traversal&lt;Base&gt;::type
else
return CategoryOrTraversal
<em>R'</em> = if (Reference is use_default)
if (Value is use_default)
return iterator_traits&lt;Base&gt;::reference
else
return Value&amp;
else
return Reference
<em>D'</em> = if (Difference is use_default)
return iterator_traits&lt;Base&gt;::difference_type
else
return Difference
</pre>
<!-- ``iterator_adaptor`` models
- - - - - - - - - - - - - - - - - - - - - - - - - - -
In order for ``Derived`` to model the iterator concepts corresponding
to ``iterator_traits<Derived>::iterator_category``, the expressions
involving ``m_iterator`` in the specifications of those private member
functions of ``iterator_adaptor`` that may be called by
``iterator_facade<Derived, V, C, R, D>`` in evaluating any valid
expression involving ``Derived`` in those concepts' requirements. -->
<!-- The above is confusing and needs a rewrite. -JGS -->
<!-- That's why it's removed. We're embracing inheritance, remember? -->
</div>
<div class="section" id="iterator-adaptor-public-operations">
<h2><a class="toc-backref" href="#id10"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> public operations</a></h2>
<p><tt class="docutils literal"><span class="pre">iterator_adaptor();</span></tt></p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Requires:</th><td class="field-body">The <tt class="docutils literal"><span class="pre">Base</span></tt> type must be Default Constructible.</td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> with
<tt class="docutils literal"><span class="pre">m_iterator</span></tt> default constructed.</td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">explicit</span> <span class="pre">iterator_adaptor(Base</span> <span class="pre">const&amp;</span> <span class="pre">iter);</span></tt></p>
<table class="docutils 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="docutils literal"><span class="pre">iterator_adaptor</span></tt> with
<tt class="docutils literal"><span class="pre">m_iterator</span></tt> copy constructed from <tt class="docutils literal"><span class="pre">iter</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">Base</span> <span class="pre">const&amp;</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
<table class="docutils 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="docutils literal"><span class="pre">m_iterator</span></tt></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="iterator-adaptor-protected-member-functions">
<h2><a class="toc-backref" href="#id11"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> protected member functions</a></h2>
<p><tt class="docutils literal"><span class="pre">Base</span> <span class="pre">const&amp;</span> <span class="pre">base_reference()</span> <span class="pre">const;</span></tt></p>
<table class="docutils 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 const reference to <tt class="docutils literal"><span class="pre">m_iterator</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">Base&amp;</span> <span class="pre">base_reference();</span></tt></p>
<table class="docutils 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 non-const reference to <tt class="docutils literal"><span class="pre">m_iterator</span></tt>.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="iterator-adaptor-private-member-functions">
<h2><a class="toc-backref" href="#id12"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> private member functions</a></h2>
<p><tt class="docutils literal"><span class="pre">typename</span> <span class="pre">iterator_adaptor::reference</span> <span class="pre">dereference()</span> <span class="pre">const;</span></tt></p>
<table class="docutils 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="docutils literal"><span class="pre">*m_iterator</span></tt></td>
</tr>
</tbody>
</table>
<pre class="literal-block">
template &lt;
class OtherDerived, class OtherIterator, class V, class C, class R, class D
&gt;
bool equal(iterator_adaptor&lt;OtherDerived, OtherIterator, V, C, R, D&gt; const&amp; x) const;
</pre>
<table class="docutils 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="docutils literal"><span class="pre">m_iterator</span> <span class="pre">==</span> <span class="pre">x.base()</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">void</span> <span class="pre">advance(typename</span> <span class="pre">iterator_adaptor::difference_type</span> <span class="pre">n);</span></tt></p>
<table class="docutils 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"><tt class="docutils literal"><span class="pre">m_iterator</span> <span class="pre">+=</span> <span class="pre">n;</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">void</span> <span class="pre">increment();</span></tt></p>
<table class="docutils 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"><tt class="docutils literal"><span class="pre">++m_iterator;</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">void</span> <span class="pre">decrement();</span></tt></p>
<table class="docutils 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"><tt class="docutils literal"><span class="pre">--m_iterator;</span></tt></td>
</tr>
</tbody>
</table>
<pre class="literal-block">
template &lt;
class OtherDerived, class OtherIterator, class V, class C, class R, class D
&gt;
typename iterator_adaptor::difference_type distance_to(
iterator_adaptor&lt;OtherDerived, OtherIterator, V, C, R, D&gt; const&amp; y) const;
</pre>
<table class="docutils 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="docutils literal"><span class="pre">y.base()</span> <span class="pre">-</span> <span class="pre">m_iterator</span></tt></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="tutorial-example">
<h1><a class="toc-backref" href="#id13">Tutorial Example</a></h1>
<!-- 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) -->
<p>In this section we'll further refine the <tt class="docutils literal"><span class="pre">node_iter</span></tt> class
template we developed in the <a class="reference external" href="iterator_facade.html#tutorial-example"><tt class="docutils literal"><span class="pre">iterator_facade</span></tt> tutorial</a>. If you haven't already
read that material, you should go back now and check it out because
we're going to pick up right where it left off.</p>
<div class="sidebar">
<p class="first sidebar-title"><tt class="docutils literal"><span class="pre">node_base*</span></tt> really <em>is</em> an iterator</p>
<p class="last">It's not really a very interesting iterator, since <tt class="docutils literal"><span class="pre">node_base</span></tt>
is an abstract class: a pointer to a <tt class="docutils literal"><span class="pre">node_base</span></tt> just points
at some base subobject of an instance of some other class, and
incrementing a <tt class="docutils literal"><span class="pre">node_base*</span></tt> moves it past this base subobject
to who-knows-where? The most we can do with that incremented
position is to compare another <tt class="docutils literal"><span class="pre">node_base*</span></tt> to it. In other
words, the original iterator traverses a one-element array.</p>
</div>
<p>You probably didn't think of it this way, but the <tt class="docutils literal"><span class="pre">node_base*</span></tt>
object that underlies <tt class="docutils literal"><span class="pre">node_iterator</span></tt> is itself an iterator,
just like all other pointers. If we examine that pointer closely
from an iterator perspective, we can see that it has much in common
with the <tt class="docutils literal"><span class="pre">node_iterator</span></tt> we're building. First, they share most
of the same associated types (<tt class="docutils literal"><span class="pre">value_type</span></tt>, <tt class="docutils literal"><span class="pre">reference</span></tt>,
<tt class="docutils literal"><span class="pre">pointer</span></tt>, and <tt class="docutils literal"><span class="pre">difference_type</span></tt>). Second, even some of the
core functionality is the same: <tt class="docutils literal"><span class="pre">operator*</span></tt> and <tt class="docutils literal"><span class="pre">operator==</span></tt> on
the <tt class="docutils literal"><span class="pre">node_iterator</span></tt> return the result of invoking the same
operations on the underlying pointer, via the <tt class="docutils literal"><span class="pre">node_iterator</span></tt>'s
<a class="reference external" href="iterator_facade.html#implementing-the-core-operations"><tt class="docutils literal"><span class="pre">dereference</span></tt> and <tt class="docutils literal"><span class="pre">equal</span></tt> member functions</a>). The only real behavioral difference
between <tt class="docutils literal"><span class="pre">node_base*</span></tt> and <tt class="docutils literal"><span class="pre">node_iterator</span></tt> can be observed when
they are incremented: <tt class="docutils literal"><span class="pre">node_iterator</span></tt> follows the
<tt class="docutils literal"><span class="pre">m_next</span></tt> pointer, while <tt class="docutils literal"><span class="pre">node_base*</span></tt> just applies an address offset.</p>
<p>It turns out that the pattern of building an iterator on another
iterator-like type (the <tt class="docutils literal"><span class="pre">Base</span></tt><a class="footnote-reference" href="#base" id="id3"><sup>1</sup></a> type) while modifying
just a few aspects of the underlying type's behavior is an
extremely common one, and it's the pattern addressed by
<tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>. Using <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> is very much like
using <tt class="docutils literal"><span class="pre">iterator_facade</span></tt>, but because iterator_adaptor tries to
mimic as much of the <tt class="docutils literal"><span class="pre">Base</span></tt> type's behavior as possible, we
neither have to supply a <tt class="docutils literal"><span class="pre">Value</span></tt> argument, nor implement any core
behaviors other than <tt class="docutils literal"><span class="pre">increment</span></tt>. The implementation of
<tt class="docutils literal"><span class="pre">node_iter</span></tt> is thus reduced to:</p>
<pre class="literal-block">
template &lt;class Value&gt;
class node_iter
: public boost::iterator_adaptor&lt;
node_iter&lt;Value&gt; // Derived
, Value* // Base
, boost::use_default // Value
, boost::forward_traversal_tag // CategoryOrTraversal
&gt;
{
private:
struct enabler {}; // a private type avoids misuse
public:
node_iter()
: node_iter::iterator_adaptor_(0) {}
explicit node_iter(Value* p)
: node_iter::iterator_adaptor_(p) {}
template &lt;class OtherValue&gt;
node_iter(
node_iter&lt;OtherValue&gt; const&amp; other
, typename boost::enable_if&lt;
boost::is_convertible&lt;OtherValue*,Value*&gt;
, enabler
&gt;::type = enabler()
)
: node_iter::iterator_adaptor_(other.base()) {}
private:
friend class boost::iterator_core_access;
void increment() { this-&gt;base_reference() = this-&gt;base()-&gt;next(); }
};
</pre>
<p>Note the use of <tt class="docutils literal"><span class="pre">node_iter::iterator_adaptor_</span></tt> here: because
<tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> defines a nested <tt class="docutils literal"><span class="pre">iterator_adaptor_</span></tt> type
that refers to itself, that gives us a convenient way to refer to
the complicated base class type of <tt class="docutils literal"><span class="pre">node_iter&lt;Value&gt;</span></tt>. [Note:
this technique is known not to work with Borland C++ 5.6.4 and
Metrowerks CodeWarrior versions prior to 9.0]</p>
<p>You can see an example program that exercises this version of the
node iterators <a class="reference external" href="../example/node_iterator3.cpp">here</a>.</p>
<p>In the case of <tt class="docutils literal"><span class="pre">node_iter</span></tt>, it's not very compelling to pass
<tt class="docutils literal"><span class="pre">boost::use_default</span></tt> as <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>'s <tt class="docutils literal"><span class="pre">Value</span></tt>
argument; we could have just passed <tt class="docutils literal"><span class="pre">node_iter</span></tt>'s <tt class="docutils literal"><span class="pre">Value</span></tt>
along to <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>, and that'd even be shorter! Most
iterator class templates built with <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> are
parameterized on another iterator type, rather than on its
<tt class="docutils literal"><span class="pre">value_type</span></tt>. For example, <tt class="docutils literal"><span class="pre">boost::reverse_iterator</span></tt> takes an
iterator type argument and reverses its direction of traversal,
since the original iterator and the reversed one have all the same
associated types, <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>'s delegation of default
types to its <tt class="docutils literal"><span class="pre">Base</span></tt> saves the implementor of
<tt class="docutils literal"><span class="pre">boost::reverse_iterator</span></tt> from writing:</p>
<pre class="literal-block">
std::iterator_traits&lt;Iterator&gt;::<em>some-associated-type</em>
</pre>
<p>at least four times.</p>
<p>We urge you to review the documentation and implementations of
<a class="reference external" href="reverse_iterator.html"><tt class="docutils literal"><span class="pre">reverse_iterator</span></tt></a> and the other Boost <a class="reference external" href="index.html#specialized-adaptors">specialized iterator
adaptors</a> to get an idea of the sorts of things you can do with
<tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>. In particular, have a look at
<a class="reference external" href="transform_iterator.html"><tt class="docutils literal"><span class="pre">transform_iterator</span></tt></a>, which is perhaps the most straightforward
adaptor, and also <a class="reference external" href="counting_iterator.html"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt></a>, which demonstrates that
<tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>'s <tt class="docutils literal"><span class="pre">Base</span></tt> type needn't be an iterator.</p>
</div>
</div>
<div class="footer">
<hr class="footer" />
<a class="reference external" href="iterator_adaptor.rst">View document source</a>.
Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div>
</body>
</html>
libs/iterator/doc/iterator_adaptor.pdf
BIN
View File
Binary file not shown.
libs/iterator/doc/iterator_adaptor.rst
+41
View File
@@ -0,0 +1,41 @@
.. Distributed under 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)
+++++++++++++++++
Iterator Adaptor
+++++++++++++++++
: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 David Abrahams, Jeremy Siek, and Thomas Witt 2003.
.. _`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:: iterator_adaptor_abstract.rst
.. contents:: Table of Contents
Overview
========
.. include:: iterator_adaptor_body.rst
Reference
=========
.. include:: iterator_adaptor_ref.rst
Tutorial Example
================
.. include:: iterator_adaptor_tutorial.rst
libs/iterator/doc/iterator_adaptor_abstract.rst
+19
View File
@@ -0,0 +1,19 @@
.. Distributed under 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)
.. 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.
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
interface functions to adapt the behavior of the ``Base`` type.
Whether the derived class models any of the standard iterator concepts
depends on the operations supported by the ``Base`` type and which
core interface functions of ``iterator_facade`` are redefined in the
``Derived`` class.
libs/iterator/doc/iterator_adaptor_body.rst
+43
View File
@@ -0,0 +1,43 @@
.. Distributed under 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)
.. 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.
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``
and implement the core behaviors in terms of the ``Base`` type. In
essence, ``iterator_adaptor`` merely forwards all operations to an
instance of the ``Base`` type, which it stores as a member.
.. [#base] The term "Base" here does not refer to a base class and is
not meant to imply the use of derivation. We have followed the lead
of the standard library, which provides a base() function to access
the underlying iterator object of a ``reverse_iterator`` adaptor.
The user of ``iterator_adaptor`` creates a class derived from an
instantiation of ``iterator_adaptor`` and then selectively
redefines some of the core member functions described in the
``iterator_facade`` core requirements table. The ``Base`` type need
not meet the full requirements for an iterator; it need only
support the operations used by the core interface functions of
``iterator_adaptor`` that have not been redefined in the user's
derived class.
Several of the template parameters of ``iterator_adaptor`` default
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
complicated, so metaprogramming is required to compute them, and
``use_default`` can help to simplify the implementation. Finally,
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 from making mistakes based on
that assumption.
libs/iterator/doc/iterator_adaptor_ref.rst
+182
View File
@@ -0,0 +1,182 @@
.. Distributed under 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)
.. Version 1.4 of this ReStructuredText document corresponds to
n1530_, the paper accepted by the LWG for TR1.
.. Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003.
.. parsed-literal::
template <
class Derived
, class Base
, class Value = use_default
, class CategoryOrTraversal = use_default
, class Reference = use_default
, class Difference = use_default
>
class iterator_adaptor
: public iterator_facade<Derived, *V'*, *C'*, *R'*, *D'*> // see details__
{
friend class iterator_core_access;
public:
iterator_adaptor();
explicit iterator_adaptor(Base const& iter);
typedef Base base_type;
Base const& base() const;
protected:
typedef iterator_adaptor iterator_adaptor\_;
Base const& base_reference() const;
Base& base_reference();
private: // Core iterator interface for iterator_facade.
typename iterator_adaptor::reference dereference() const;
template <
class OtherDerived, class OtherIterator, class V, class C, class R, class D
>
bool equal(iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& x) const;
void advance(typename iterator_adaptor::difference_type n);
void increment();
void decrement();
template <
class OtherDerived, class OtherIterator, class V, class C, class R, class D
>
typename iterator_adaptor::difference_type distance_to(
iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& y) const;
private:
Base m_iterator; // exposition only
};
__ base_parameters_
.. _requirements:
``iterator_adaptor`` requirements
---------------------------------
``static_cast<Derived*>(iterator_adaptor*)`` shall be well-formed.
The ``Base`` argument shall be Assignable and Copy Constructible.
.. _base_parameters:
``iterator_adaptor`` base class parameters
------------------------------------------
The *V'*, *C'*, *R'*, and *D'* parameters of the ``iterator_facade``
used as a base class in the summary of ``iterator_adaptor``
above are defined as follows:
.. parsed-literal::
*V'* = if (Value is use_default)
return iterator_traits<Base>::value_type
else
return Value
*C'* = if (CategoryOrTraversal is use_default)
return iterator_traversal<Base>::type
else
return CategoryOrTraversal
*R'* = if (Reference is use_default)
if (Value is use_default)
return iterator_traits<Base>::reference
else
return Value&
else
return Reference
*D'* = if (Difference is use_default)
return iterator_traits<Base>::difference_type
else
return Difference
.. ``iterator_adaptor`` models
---------------------------
In order for ``Derived`` to model the iterator concepts corresponding
to ``iterator_traits<Derived>::iterator_category``, the expressions
involving ``m_iterator`` in the specifications of those private member
functions of ``iterator_adaptor`` that may be called by
``iterator_facade<Derived, V, C, R, D>`` in evaluating any valid
expression involving ``Derived`` in those concepts' requirements.
.. The above is confusing and needs a rewrite. -JGS
.. That's why it's removed. We're embracing inheritance, remember?
``iterator_adaptor`` public operations
--------------------------------------
``iterator_adaptor();``
:Requires: The ``Base`` type must be Default Constructible.
:Returns: An instance of ``iterator_adaptor`` with
``m_iterator`` default constructed.
``explicit iterator_adaptor(Base const& iter);``
:Returns: An instance of ``iterator_adaptor`` with
``m_iterator`` copy constructed from ``iter``.
``Base const& base() const;``
:Returns: ``m_iterator``
``iterator_adaptor`` protected member functions
-----------------------------------------------
``Base const& base_reference() const;``
:Returns: A const reference to ``m_iterator``.
``Base& base_reference();``
:Returns: A non-const reference to ``m_iterator``.
``iterator_adaptor`` private member functions
---------------------------------------------
``typename iterator_adaptor::reference dereference() const;``
:Returns: ``*m_iterator``
::
template <
class OtherDerived, class OtherIterator, class V, class C, class R, class D
>
bool equal(iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& x) const;
:Returns: ``m_iterator == x.base()``
``void advance(typename iterator_adaptor::difference_type n);``
:Effects: ``m_iterator += n;``
``void increment();``
:Effects: ``++m_iterator;``
``void decrement();``
:Effects: ``--m_iterator;``
::
template <
class OtherDerived, class OtherIterator, class V, class C, class R, class D
>
typename iterator_adaptor::difference_type distance_to(
iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& y) const;
:Returns: ``y.base() - m_iterator``
libs/iterator/doc/iterator_adaptor_tutorial.rst
+135
View File
@@ -0,0 +1,135 @@
.. 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)
In this section we'll further refine the ``node_iter`` class
template we developed in the |fac_tut|_. If you haven't already
read that material, you should go back now and check it out because
we're going to pick up right where it left off.
.. |fac_tut| replace:: ``iterator_facade`` tutorial
.. _fac_tut: iterator_facade.html#tutorial-example
.. sidebar:: ``node_base*`` really *is* an iterator
It's not really a very interesting iterator, since ``node_base``
is an abstract class: a pointer to a ``node_base`` just points
at some base subobject of an instance of some other class, and
incrementing a ``node_base*`` moves it past this base subobject
to who-knows-where? The most we can do with that incremented
position is to compare another ``node_base*`` to it. In other
words, the original iterator traverses a one-element array.
You probably didn't think of it this way, but the ``node_base*``
object that underlies ``node_iterator`` is itself an iterator,
just like all other pointers. If we examine that pointer closely
from an iterator perspective, we can see that it has much in common
with the ``node_iterator`` we're building. First, they share most
of the same associated types (``value_type``, ``reference``,
``pointer``, and ``difference_type``). Second, even some of the
core functionality is the same: ``operator*`` and ``operator==`` on
the ``node_iterator`` return the result of invoking the same
operations on the underlying pointer, via the ``node_iterator``\ 's
|dereference_and_equal|_). The only real behavioral difference
between ``node_base*`` and ``node_iterator`` can be observed when
they are incremented: ``node_iterator`` follows the
``m_next`` pointer, while ``node_base*`` just applies an address offset.
.. |dereference_and_equal| replace:: ``dereference`` and ``equal`` member functions
.. _dereference_and_equal: iterator_facade.html#implementing-the-core-operations
It turns out that the pattern of building an iterator on another
iterator-like type (the ``Base`` [#base]_ type) while modifying
just a few aspects of the underlying type's behavior is an
extremely common one, and it's the pattern addressed by
``iterator_adaptor``. Using ``iterator_adaptor`` is very much like
using ``iterator_facade``, but because iterator_adaptor tries to
mimic as much of the ``Base`` type's behavior as possible, we
neither have to supply a ``Value`` argument, nor implement any core
behaviors other than ``increment``. The implementation of
``node_iter`` is thus reduced to::
template <class Value>
class node_iter
: public boost::iterator_adaptor<
node_iter<Value> // Derived
, Value* // Base
, boost::use_default // Value
, boost::forward_traversal_tag // CategoryOrTraversal
>
{
private:
struct enabler {}; // a private type avoids misuse
public:
node_iter()
: node_iter::iterator_adaptor_(0) {}
explicit node_iter(Value* p)
: node_iter::iterator_adaptor_(p) {}
template <class OtherValue>
node_iter(
node_iter<OtherValue> const& other
, typename boost::enable_if<
boost::is_convertible<OtherValue*,Value*>
, enabler
>::type = enabler()
)
: node_iter::iterator_adaptor_(other.base()) {}
private:
friend class boost::iterator_core_access;
void increment() { this->base_reference() = this->base()->next(); }
};
Note the use of ``node_iter::iterator_adaptor_`` here: because
``iterator_adaptor`` defines a nested ``iterator_adaptor_`` type
that refers to itself, that gives us a convenient way to refer to
the complicated base class type of ``node_iter<Value>``. [Note:
this technique is known not to work with Borland C++ 5.6.4 and
Metrowerks CodeWarrior versions prior to 9.0]
You can see an example program that exercises this version of the
node iterators `here`__.
__ ../example/node_iterator3.cpp
In the case of ``node_iter``, it's not very compelling to pass
``boost::use_default`` as ``iterator_adaptor``\ 's ``Value``
argument; we could have just passed ``node_iter``\ 's ``Value``
along to ``iterator_adaptor``, and that'd even be shorter! Most
iterator class templates built with ``iterator_adaptor`` are
parameterized on another iterator type, rather than on its
``value_type``. For example, ``boost::reverse_iterator`` takes an
iterator type argument and reverses its direction of traversal,
since the original iterator and the reversed one have all the same
associated types, ``iterator_adaptor``\ 's delegation of default
types to its ``Base`` saves the implementor of
``boost::reverse_iterator`` from writing:
.. parsed-literal::
std::iterator_traits<Iterator>::*some-associated-type*
at least four times.
We urge you to review the documentation and implementations of
|reverse_iterator|_ and the other Boost `specialized iterator
adaptors`__ to get an idea of the sorts of things you can do with
``iterator_adaptor``. In particular, have a look at
|transform_iterator|_, which is perhaps the most straightforward
adaptor, and also |counting_iterator|_, which demonstrates that
``iterator_adaptor``\ 's ``Base`` type needn't be an iterator.
.. |reverse_iterator| replace:: ``reverse_iterator``
.. _reverse_iterator: reverse_iterator.html
.. |counting_iterator| replace:: ``counting_iterator``
.. _counting_iterator: counting_iterator.html
.. |transform_iterator| replace:: ``transform_iterator``
.. _transform_iterator: transform_iterator.html
__ index.html#specialized-adaptors
libs/iterator/doc/iterator_archetypes.html
+224
View File
@@ -0,0 +1,224 @@
<?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.5: 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="2006-09-11" />
<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2004." />
<link rel="stylesheet" href="../../../rst.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 external" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference external" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="last reference external" 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 external" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference external" href="http://www.osl.iu.edu">Open Systems
Lab</a>, <a class="last reference external" href="http://www.styleadvisor.com">Zephyr Associates, Inc.</a></td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2006-09-11</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2004.</td></tr>
</tbody>
</table>
<!-- Distributed under 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) -->
<table class="docutils 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 <tt class="docutils literal"><span class="pre">iterator_archetype</span></tt> class constructs a minimal implementation of
one of the iterator access concepts and one of the iterator traversal concepts.
This is used for doing a compile-time check to see if a the type requirements
of a template are really enough to cover the implementation of the template.
For further information see the documentation for the <a class="reference external" href="../../concept_check/index.html"><tt class="docutils literal"><span class="pre">boost::concept_check</span></tt></a> library.</td>
</tr>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#reference" id="id1">Reference</a><ul>
<li><a class="reference internal" href="#iterator-archetype-synopsis" id="id2"><tt class="docutils literal"><span class="pre">iterator_archetype</span></tt> Synopsis</a></li>
<li><a class="reference internal" href="#access-category-tags" id="id3"><tt class="docutils literal"><span class="pre">Access</span> <span class="pre">Category</span> <span class="pre">Tags</span></tt></a></li>
<li><a class="reference internal" href="#iterator-archetype-requirements" id="id4"><tt class="docutils literal"><span class="pre">iterator_archetype</span></tt> Requirements</a></li>
<li><a class="reference internal" href="#iterator-archetype-models" id="id5"><tt class="docutils literal"><span class="pre">iterator_archetype</span></tt> Models</a></li>
<li><a class="reference internal" href="#traits" id="id6"><tt class="docutils 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">Reference</a></h1>
<div class="section" id="iterator-archetype-synopsis">
<h2><a class="toc-backref" href="#id2"><tt class="docutils 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"><tt class="docutils 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"><tt class="docutils literal"><span class="pre">iterator_archetype</span></tt> Requirements</a></h2>
<p>The <tt class="docutils literal"><span class="pre">AccessCategory</span></tt> argument must be one of the predefined access
category tags. The <tt class="docutils literal"><span class="pre">TraversalCategory</span></tt> must be one of the standard
traversal tags. The <tt class="docutils literal"><span class="pre">Value</span></tt> type must satisfy the requirements of
the iterator concept specified by <tt class="docutils literal"><span class="pre">AccessCategory</span></tt> and
<tt class="docutils 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"><tt class="docutils literal"><span class="pre">iterator_archetype</span></tt> Models</a></h2>
<p><tt class="docutils literal"><span class="pre">iterator_archetype</span></tt> models the iterator concepts specified by the
<tt class="docutils literal"><span class="pre">AccessCategory</span></tt> and <tt class="docutils literal"><span class="pre">TraversalCategory</span></tt>
arguments. <tt class="docutils 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"><tt class="docutils 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>
<div class="footer">
<hr class="footer" />
<a class="reference external" href="iterator_archetypes.rst">View document source</a>.
Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div>
</body>
</html>
libs/iterator/doc/iterator_archetypes.pdf
BIN
View File
Binary file not shown.
libs/iterator/doc/iterator_archetypes.rst
+193
View File
@@ -0,0 +1,193 @@
.. Distributed under 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)
++++++++++++++++++++
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.
.. _`Boost Consulting`: http://www.boost-consulting.com
.. _`Open Systems Lab`: http://www.osl.iu.edu
.. _`Zephyr Associates, Inc.`: http://www.styleadvisor.com
:abstract: The ``iterator_archetype`` class constructs a minimal implementation of
one of the iterator access concepts and one of the iterator traversal concepts.
This is used for doing a compile-time check to see if a the type requirements
of a template are really enough to cover the implementation of the template.
For further information see the documentation for the |concepts|_ library.
.. |concepts| replace:: ``boost::concept_check``
.. _concepts: ../../concept_check/index.html
.. 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
libs/iterator/doc/iterator_concepts.html
+127
View File
@@ -0,0 +1,127 @@
<?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.5: http://docutils.sourceforge.net/" />
<title>Iterator Concepts</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="2006-09-11" />
<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2004." />
<link rel="stylesheet" href="../../../rst.css" type="text/css" />
</head>
<body>
<div class="document" id="iterator-concepts">
<h1 class="title">Iterator Concepts</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 external" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference external" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="last reference external" 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 external" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference external" href="http://www.osl.iu.edu">Open Systems
Lab</a>, <a class="last reference external" href="http://www.styleadvisor.com">Zephyr Associates, Inc.</a></td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2006-09-11</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2004.</td></tr>
</tbody>
</table>
<!-- Distributed under 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) -->
<table class="docutils 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 iterator concept checking classes provide a mechanism for
a template to report better error messages when a user instantiates
the template with a type that does not meet the requirements of
the template.</td>
</tr>
</tbody>
</table>
<p>For an introduction to using concept checking classes, see
the documentation for the <a class="reference external" href="../../concept_check/index.html"><tt class="docutils literal"><span class="pre">boost::concept_check</span></tt></a> library.</p>
<div class="section" id="reference">
<h1>Reference</h1>
<div class="section" id="iterator-access-concepts">
<h2>Iterator Access Concepts</h2>
<ul class="simple">
<li><a class="reference external" href="ReadableIterator.html"><em>Readable Iterator</em></a></li>
<li><a class="reference external" href="WritableIterator.html"><em>Writable Iterator</em></a></li>
<li><a class="reference external" href="SwappableIterator.html"><em>Swappable Iterator</em></a></li>
<li><a class="reference external" href="LvalueIterator.html"><em>Lvalue Iterator</em></a></li>
</ul>
</div>
<div class="section" id="iterator-traversal-concepts">
<h2>Iterator Traversal Concepts</h2>
<ul class="simple">
<li><a class="reference external" href="IncrementableIterator.html"><em>Incrementable Iterator</em></a></li>
<li><a class="reference external" href="SinglePassIterator.html"><em>Single Pass Iterator</em></a></li>
<li><a class="reference external" href="ForwardTraversal.html"><em>Forward Traversal</em></a></li>
<li><a class="reference external" href="BidirectionalTraversal.html"><em>Bidirectional Traversal</em></a></li>
<li><a class="reference external" href="RandomAccessTraversal.html"><em>Random Access Traversal</em></a></li>
</ul>
</div>
<div class="section" id="iterator-concepts-hpp-synopsis">
<h2><tt class="docutils literal"><span class="pre">iterator_concepts.hpp</span></tt> Synopsis</h2>
<pre class="literal-block">
namespace boost_concepts {
// Iterator Access Concepts
template &lt;typename Iterator&gt;
class ReadableIteratorConcept;
template &lt;
typename Iterator
, typename ValueType = std::iterator_traits&lt;Iterator&gt;::value_type
&gt;
class WritableIteratorConcept;
template &lt;typename Iterator&gt;
class SwappableIteratorConcept;
template &lt;typename Iterator&gt;
class LvalueIteratorConcept;
// Iterator Traversal Concepts
template &lt;typename Iterator&gt;
class IncrementableIteratorConcept;
template &lt;typename Iterator&gt;
class SinglePassIteratorConcept;
template &lt;typename Iterator&gt;
class ForwardTraversalConcept;
template &lt;typename Iterator&gt;
class BidirectionalTraversalConcept;
template &lt;typename Iterator&gt;
class RandomAccessTraversalConcept;
// Interoperability
template &lt;typename Iterator, typename ConstIterator&gt;
class InteroperableIteratorConcept;
}
</pre>
</div>
</div>
</div>
<div class="footer">
<hr class="footer" />
<a class="reference external" href="iterator_concepts.rst">View document source</a>.
Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div>
</body>
</html>
libs/iterator/doc/iterator_concepts.pdf
BIN
View File
Binary file not shown.

Some files were not shown because too many files have changed in this diff Show More