[DEV] add v1.66.0

This commit is contained in:
2018-01-12 21:47:58 +01:00
parent 87059bb1af
commit a97e9ae7d4
49032 changed files with 7668950 additions and 0 deletions

View File

@@ -0,0 +1,344 @@
<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.access">Access</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="iterator/concepts.html#iterator.concepts.access.readable">Readable Iterator
Concept</a></span></dt>
<dt><span class="section"><a href="iterator/concepts.html#iterator.concepts.access.writable">Writable Iterator
Concept</a></span></dt>
<dt><span class="section"><a href="iterator/concepts.html#iterator.concepts.access.swappable">Swappable Iterator
Concept</a></span></dt>
<dt><span class="section"><a href="iterator/concepts.html#iterator.concepts.access.lvalue">Lvalue Iterator Concept</a></span></dt>
</dl></dd>
<dt><span class="section"><a href="iterator/concepts/traversal.html">Traversal</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="iterator/concepts/traversal.html#iterator.concepts.traversal.incrementable">Incrementable
Iterator Concept</a></span></dt>
<dt><span class="section"><a href="iterator/concepts/traversal.html#iterator.concepts.traversal.single_pass">Single Pass
Iterator Concept</a></span></dt>
<dt><span class="section"><a href="iterator/concepts/traversal.html#iterator.concepts.traversal.forward">Forward Traversal
Concept</a></span></dt>
<dt><span class="section"><a href="iterator/concepts/traversal.html#iterator.concepts.traversal.bidirectional">Bidirectional
Traversal Concept</a></span></dt>
<dt><span class="section"><a href="iterator/concepts/traversal.html#iterator.concepts.traversal.random_access">Random Access
Traversal Concept</a></span></dt>
</dl></dd>
</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.html#iterator.generic.adaptor.adaptor_tutorial">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.html#iterator.specialized.shared_container.shared_container_object_generator">The
Shared Container Iterator Object Generator</a></span></dt>
<dt><span class="section"><a href="iterator/specialized/shared_container.html#iterator.specialized.shared_container.shared_container_generator">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.html#iterator.specialized.zip.zip_reference">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/iterator_traits.html">Iterator Traits</a></span></dt>
<dt><span class="section"><a href="iterator/utilities/traits.html">Type Traits</a></span></dt>
</dl></dd>
<dt><span class="section"><a href="iterator/algorithms.html">Algorithms</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="iterator/algorithms.html#iterator.algorithms.advance">Function template <code class="computeroutput"><span class="identifier">advance</span><span class="special">()</span></code></a></span></dt>
<dt><span class="section"><a href="iterator/algorithms/distance.html">Function template <code class="computeroutput"><span class="identifier">distance</span><span class="special">()</span></code></a></span></dt>
<dt><span class="section"><a href="iterator/algorithms/next_prior.html">Function templates <code class="computeroutput"><span class="identifier">next</span><span class="special">()</span></code> and
<code class="computeroutput"><span class="identifier">prior</span><span class="special">()</span></code></a></span></dt>
</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 <a class="link" href="iterator/specialized.html" title="Specialized Adaptors">specialized adaptors</a>
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 class="link" href="iterator/specialized.html#iterator.specialized.counting" title="Counting Iterator"><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 class="link" href="iterator/specialized/filter.html" title="Filter Iterator"><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_input_iterator.html" target="_top"><code class="computeroutput"><span class="identifier">function_input_iterator</span></code></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 class="listitem">
<a class="link" href="iterator/specialized/function_output.html" title="Function Output Iterator"><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="../generator_iterator.htm" target="_top"><code class="computeroutput"><span class="identifier">generator_iterator</span></code></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. An outdated analogue of <a href="../function_input_iterator.html" target="_top"><code class="computeroutput"><span class="identifier">function_input_iterator</span></code></a>.
</li>
<li class="listitem">
<a class="link" href="iterator/specialized/indirect.html" title="Indirect Iterator"><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 class="link" href="iterator/specialized/permutation.html" title="Permutation Iterator"><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">
<a class="link" href="iterator/specialized/reverse.html" title="Reverse Iterator"><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 <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">reverse_iterator</span></code>.
</li>
<li class="listitem">
<a class="link" href="iterator/specialized/shared_container.html" title="Shared Container Iterator"><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">
<a class="link" href="iterator/specialized/transform.html" title="Transform Iterator"><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 <code class="computeroutput"><span class="identifier">projection_iterator_adaptor</span></code>.
</li>
<li class="listitem">
<a class="link" href="iterator/specialized/zip.html" title="Zip Iterator"><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 class="link" href="iterator/utilities/traits.html" title="Type Traits"><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 class="link" href="iterator/specialized/indirect.html" title="Indirect Iterator"><code class="computeroutput"><span class="identifier">indirect_iterator</span></code></a>.
</li>
<li class="listitem">
<a class="link" href="iterator/utilities/iterator_traits.html" title="Iterator Traits"><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>
<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 class="link" href="iterator/concepts.html" title="Iterator Concepts"><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 class="link" href="iterator/utilities.html#iterator.utilities.archetypes" title="Iterator Archetypes"><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>
<h3>
<a name="iterator.intro.h6"></a>
<span class="phrase"><a name="iterator.intro.iterator_algorithms"></a></span><a class="link" href="index.html#iterator.intro.iterator_algorithms">Iterator
Algorithms</a>
</h3>
<p>
The library provides a number of generic algorithms for use with iterators.
These algorithms take advantage of the new concepts defined by the library
to provide better performance and functionality.
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<a class="link" href="iterator/algorithms.html#iterator.algorithms.advance" title="Function template advance()"><code class="computeroutput"><span class="identifier">advance</span><span class="special">.</span><span class="identifier">hpp</span></code></a>:
Provides <code class="computeroutput"><span class="identifier">advance</span><span class="special">()</span></code>
function for advancing an iterator a given number of positions forward
or backward.
</li>
<li class="listitem">
<a class="link" href="iterator/algorithms/distance.html" title="Function template distance()"><code class="computeroutput"><span class="identifier">distance</span><span class="special">.</span><span class="identifier">hpp</span></code></a>:
Provides <code class="computeroutput"><span class="identifier">distance</span><span class="special">()</span></code>
function for computing distance between two iterators.
</li>
<li class="listitem">
<a class="link" href="iterator/algorithms/next_prior.html" title="Function templates next() and prior()"><code class="computeroutput"><span class="identifier">next_prior</span><span class="special">.</span><span class="identifier">hpp</span></code></a>:
Provides <code class="computeroutput"><span class="identifier">next</span><span class="special">()</span></code>
and <code class="computeroutput"><span class="identifier">prior</span><span class="special">()</span></code>
functions for obtaining next and prior iterators to a given iterator. The
functions are also compatible with non-iterator types.
</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 14, 2017 at 00:16:44 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>

View File

@@ -0,0 +1,135 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Algorithms</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/traits.html" title="Type Traits">
<link rel="next" href="algorithms/distance.html" title="Function template distance()">
</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/traits.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="algorithms/distance.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.algorithms"></a><a class="link" href="algorithms.html" title="Algorithms">Algorithms</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="algorithms.html#iterator.algorithms.advance">Function template <code class="computeroutput"><span class="identifier">advance</span><span class="special">()</span></code></a></span></dt>
<dt><span class="section"><a href="algorithms/distance.html">Function template <code class="computeroutput"><span class="identifier">distance</span><span class="special">()</span></code></a></span></dt>
<dt><span class="section"><a href="algorithms/next_prior.html">Function templates <code class="computeroutput"><span class="identifier">next</span><span class="special">()</span></code> and
<code class="computeroutput"><span class="identifier">prior</span><span class="special">()</span></code></a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="iterator.algorithms.advance"></a><a class="link" href="algorithms.html#iterator.algorithms.advance" title="Function template advance()">Function template <code class="computeroutput"><span class="identifier">advance</span><span class="special">()</span></code></a>
</h3></div></div></div>
<p>
The <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">iterators</span><span class="special">::</span><span class="identifier">advance</span></code> function template is an adapted
version of <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">advance</span></code> for the Boost iterator <a class="link" href="concepts/traversal.html" title="Traversal">traversal
concepts</a>.
</p>
<h5>
<a name="iterator.algorithms.advance.h0"></a>
<span class="phrase"><a name="iterator.algorithms.advance.header"></a></span><a class="link" href="algorithms.html#iterator.algorithms.advance.header">Header</a>
</h5>
<pre class="programlisting"><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">advance</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
</pre>
<h5>
<a name="iterator.algorithms.advance.h1"></a>
<span class="phrase"><a name="iterator.algorithms.advance.synopsis"></a></span><a class="link" href="algorithms.html#iterator.algorithms.advance.synopsis">Synopsis</a>
</h5>
<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">,</span> <span class="keyword">typename</span> <span class="identifier">Distance</span><span class="special">&gt;</span>
<span class="keyword">constexpr</span> <span class="keyword">void</span> <span class="identifier">advance</span><span class="special">(</span><span class="identifier">Iterator</span><span class="special">&amp;</span> <span class="identifier">it</span><span class="special">,</span> <span class="identifier">Distance</span> <span class="identifier">n</span><span class="special">);</span>
</pre>
<h5>
<a name="iterator.algorithms.advance.h2"></a>
<span class="phrase"><a name="iterator.algorithms.advance.description"></a></span><a class="link" href="algorithms.html#iterator.algorithms.advance.description">Description</a>
</h5>
<p>
Moves <code class="computeroutput"><span class="identifier">it</span></code> forward by <code class="computeroutput"><span class="identifier">n</span></code> increments (or backward by <code class="computeroutput"><span class="special">|</span><span class="identifier">n</span><span class="special">|</span></code>
decrements if <code class="computeroutput"><span class="identifier">n</span></code> is negative).
</p>
<h5>
<a name="iterator.algorithms.advance.h3"></a>
<span class="phrase"><a name="iterator.algorithms.advance.requirements"></a></span><a class="link" href="algorithms.html#iterator.algorithms.advance.requirements">Requirements</a>
</h5>
<p>
<code class="computeroutput"><span class="identifier">Iterator</span></code> should model Incrementable
Iterator.
</p>
<h5>
<a name="iterator.algorithms.advance.h4"></a>
<span class="phrase"><a name="iterator.algorithms.advance.preconditions"></a></span><a class="link" href="algorithms.html#iterator.algorithms.advance.preconditions">Preconditions</a>
</h5>
<p>
Let <code class="computeroutput"><span class="identifier">it</span></code><sub><code class="computeroutput"><span class="identifier">i</span></code></sub> be
the iterator obtained by incrementing (or decrementing if <code class="computeroutput"><span class="identifier">n</span></code>
is negative) <code class="computeroutput"><span class="identifier">it</span></code> by <code class="computeroutput"><span class="identifier">i</span></code>. All the iterators <code class="computeroutput"><span class="identifier">it</span></code><sub><code class="computeroutput"><span class="identifier">i</span></code></sub> for <code class="computeroutput"><span class="identifier">i</span></code>
= 0, 1, 2, ..., <code class="computeroutput"><span class="special">|</span><span class="identifier">n</span><span class="special">|</span></code> should be valid.
</p>
<p>
If <code class="computeroutput"><span class="identifier">Iterator</span></code> does not model
<a class="link" href="concepts/traversal.html#iterator.concepts.traversal.bidirectional" title="Bidirectional Traversal Concept">Bidirectional Traversal
Iterator</a>, <code class="computeroutput"><span class="identifier">n</span></code> should
be non-negative.
</p>
<h5>
<a name="iterator.algorithms.advance.h5"></a>
<span class="phrase"><a name="iterator.algorithms.advance.complexity"></a></span><a class="link" href="algorithms.html#iterator.algorithms.advance.complexity">Complexity</a>
</h5>
<p>
If <code class="computeroutput"><span class="identifier">Iterator</span></code> models <a class="link" href="concepts/traversal.html#iterator.concepts.traversal.random_access" title="Random Access Traversal Concept">Random Access Traversal
Iterator</a>, it takes constant time; otherwise it takes linear time.
</p>
<h5>
<a name="iterator.algorithms.advance.h6"></a>
<span class="phrase"><a name="iterator.algorithms.advance.notes"></a></span><a class="link" href="algorithms.html#iterator.algorithms.advance.notes">Notes</a>
</h5>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
This function is not a customization point and is protected against being
found by argument-dependent lookup (ADL).
</li>
<li class="listitem">
This function is <code class="computeroutput"><span class="keyword">constexpr</span></code>
only in C++14 or later.
</li>
</ul></div>
<h5>
<a name="iterator.algorithms.advance.h7"></a>
<span class="phrase"><a name="iterator.algorithms.advance.acknowledgements"></a></span><a class="link" href="algorithms.html#iterator.algorithms.advance.acknowledgements">Acknowledgements</a>
</h5>
<p>
Contributed by Michel Morin.
</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="utilities/traits.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="algorithms/distance.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,118 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Function template distance()</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="../algorithms.html" title="Algorithms">
<link rel="prev" href="../algorithms.html" title="Algorithms">
<link rel="next" href="next_prior.html" title="Function templates next() and prior()">
</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="../algorithms.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../algorithms.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="next_prior.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.algorithms.distance"></a><a class="link" href="distance.html" title="Function template distance()">Function template <code class="computeroutput"><span class="identifier">distance</span><span class="special">()</span></code></a>
</h3></div></div></div>
<p>
The <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">iterators</span><span class="special">::</span><span class="identifier">distance</span></code> function template is an adapted
version of <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">distance</span></code> for the Boost iterator <a class="link" href="../concepts/traversal.html" title="Traversal">traversal
concepts</a>.
</p>
<h5>
<a name="iterator.algorithms.distance.h0"></a>
<span class="phrase"><a name="iterator.algorithms.distance.header"></a></span><a class="link" href="distance.html#iterator.algorithms.distance.header">Header</a>
</h5>
<pre class="programlisting"><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">distance</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
</pre>
<h5>
<a name="iterator.algorithms.distance.h1"></a>
<span class="phrase"><a name="iterator.algorithms.distance.synopsis"></a></span><a class="link" href="distance.html#iterator.algorithms.distance.synopsis">Synopsis</a>
</h5>
<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">constexpr</span> <span class="keyword">typename</span> <span class="identifier">iterator_difference</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</span><span class="identifier">type</span>
<span class="identifier">distance</span><span class="special">(</span><span class="identifier">Iterator</span> <span class="identifier">first</span><span class="special">,</span> <span class="identifier">Iterator</span> <span class="identifier">last</span><span class="special">);</span>
</pre>
<h5>
<a name="iterator.algorithms.distance.h2"></a>
<span class="phrase"><a name="iterator.algorithms.distance.description"></a></span><a class="link" href="distance.html#iterator.algorithms.distance.description">Description</a>
</h5>
<p>
Computes the (signed) distance from <code class="computeroutput"><span class="identifier">first</span></code>
to <code class="computeroutput"><span class="identifier">last</span></code>.
</p>
<h5>
<a name="iterator.algorithms.distance.h3"></a>
<span class="phrase"><a name="iterator.algorithms.distance.requirements"></a></span><a class="link" href="distance.html#iterator.algorithms.distance.requirements">Requirements</a>
</h5>
<p>
<code class="computeroutput"><span class="identifier">Iterator</span></code> should model <a class="link" href="../concepts/traversal.html#iterator.concepts.traversal.single_pass" title="Single Pass Iterator Concept">Single Pass Iterator</a>.
</p>
<h5>
<a name="iterator.algorithms.distance.h4"></a>
<span class="phrase"><a name="iterator.algorithms.distance.preconditions"></a></span><a class="link" href="distance.html#iterator.algorithms.distance.preconditions">Preconditions</a>
</h5>
<p>
If <code class="computeroutput"><span class="identifier">Iterator</span></code> models <a class="link" href="../concepts/traversal.html#iterator.concepts.traversal.random_access" title="Random Access Traversal Concept">Random Access Traversal
Iterator</a>, <code class="computeroutput"><span class="special">[</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">)</span></code> or <code class="computeroutput"><span class="special">[</span><span class="identifier">last</span><span class="special">,</span> <span class="identifier">first</span><span class="special">)</span></code>
should be valid; otherwise <code class="computeroutput"><span class="special">[</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">)</span></code> should
be valid.
</p>
<h5>
<a name="iterator.algorithms.distance.h5"></a>
<span class="phrase"><a name="iterator.algorithms.distance.complexity"></a></span><a class="link" href="distance.html#iterator.algorithms.distance.complexity">Complexity</a>
</h5>
<p>
If <code class="computeroutput"><span class="identifier">Iterator</span></code> models <a class="link" href="../concepts/traversal.html#iterator.concepts.traversal.random_access" title="Random Access Traversal Concept">Random Access Traversal
Iterator</a>, it takes constant time; otherwise it takes linear time.
</p>
<h5>
<a name="iterator.algorithms.distance.h6"></a>
<span class="phrase"><a name="iterator.algorithms.distance.notes"></a></span><a class="link" href="distance.html#iterator.algorithms.distance.notes">Notes</a>
</h5>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
This function is not a customization point and is protected against being
found by argument-dependent lookup (ADL).
</li>
<li class="listitem">
This function is <code class="computeroutput"><span class="keyword">constexpr</span></code>
only in C++14 or later.
</li>
</ul></div>
<h5>
<a name="iterator.algorithms.distance.h7"></a>
<span class="phrase"><a name="iterator.algorithms.distance.acknowledgements"></a></span><a class="link" href="distance.html#iterator.algorithms.distance.acknowledgements">Acknowledgements</a>
</h5>
<p>
Contributed by Michel Morin.
</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="../algorithms.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../algorithms.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="next_prior.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,156 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Function templates next() and prior()</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="../algorithms.html" title="Algorithms">
<link rel="prev" href="distance.html" title="Function template distance()">
<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="distance.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../algorithms.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><h3 class="title">
<a name="iterator.algorithms.next_prior"></a><a class="link" href="next_prior.html" title="Function templates next() and prior()">Function templates <code class="computeroutput"><span class="identifier">next</span><span class="special">()</span></code> and
<code class="computeroutput"><span class="identifier">prior</span><span class="special">()</span></code></a>
</h3></div></div></div>
<p>
Certain data types, such as the C++ Standard Library's forward and bidirectional
iterators, do not provide addition and subtraction via <code class="computeroutput"><span class="keyword">operator</span><span class="special">+()</span></code> or <code class="computeroutput"><span class="keyword">operator</span><span class="special">-()</span></code>. This means that non-modifying computation
of the next or prior value requires a temporary, even though <code class="computeroutput"><span class="keyword">operator</span><span class="special">++()</span></code>
or <code class="computeroutput"><span class="keyword">operator</span><span class="special">--()</span></code>
is provided. It also means that writing code like <code class="computeroutput"><span class="identifier">itr</span><span class="special">+</span><span class="number">1</span></code> inside a
template restricts the iterator category to random access iterators.
</p>
<p>
The <code class="computeroutput"><span class="identifier">next</span><span class="special">()</span></code>
and <code class="computeroutput"><span class="identifier">prior</span><span class="special">()</span></code>
functions defined in <code class="computeroutput"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">next_prior</span><span class="special">.</span><span class="identifier">hpp</span></code> provide
a simple way around these problems.
</p>
<h5>
<a name="iterator.algorithms.next_prior.h0"></a>
<span class="phrase"><a name="iterator.algorithms.next_prior.synopsis"></a></span><a class="link" href="next_prior.html#iterator.algorithms.next_prior.synopsis">Synopsis</a>
</h5>
<pre class="programlisting"><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="identifier">T</span> <span class="identifier">next</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">x</span><span class="special">)</span>
<span class="special">{</span>
<span class="keyword">return</span> <span class="special">++</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">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Distance</span><span class="special">&gt;</span>
<span class="identifier">T</span> <span class="identifier">next</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">Distance</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">advance</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="keyword">return</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">T</span><span class="special">&gt;</span>
<span class="identifier">T</span> <span class="identifier">prior</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">x</span><span class="special">)</span>
<span class="special">{</span>
<span class="keyword">return</span> <span class="special">--</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">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Distance</span><span class="special">&gt;</span>
<span class="identifier">T</span> <span class="identifier">prior</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">Distance</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">advance</span><span class="special">(</span><span class="identifier">x</span><span class="special">,</span> <span class="special">-</span><span class="identifier">n</span><span class="special">);</span>
<span class="keyword">return</span> <span class="identifier">x</span><span class="special">;</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>
Function implementations above are given for exposition only. The actual
implementation has the same effect for iterators, but has different properties,
as documented later.
</p></td></tr>
</table></div>
<h5>
<a name="iterator.algorithms.next_prior.h1"></a>
<span class="phrase"><a name="iterator.algorithms.next_prior.usage"></a></span><a class="link" href="next_prior.html#iterator.algorithms.next_prior.usage">Usage</a>
</h5>
<p>
Usage is simple:
</p>
<pre class="programlisting"><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">iterator</span> <span class="identifier">p</span> <span class="special">=</span> <span class="identifier">get_some_iterator</span><span class="special">();</span>
<span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">iterator</span> <span class="identifier">prev</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">prior</span><span class="special">(</span><span class="identifier">p</span><span class="special">);</span>
<span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">iterator</span> <span class="identifier">next</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">next</span><span class="special">(</span><span class="identifier">prev</span><span class="special">,</span> <span class="number">2</span><span class="special">);</span>
</pre>
<p>
The distance from the given iterator should be supplied as an absolute value.
For example, the iterator four iterators prior to the given iterator <code class="computeroutput"><span class="identifier">p</span></code> may be obtained by <code class="computeroutput"><span class="identifier">prior</span><span class="special">(</span><span class="identifier">p</span><span class="special">,</span>
<span class="number">4</span><span class="special">)</span></code>.
</p>
<p>
With C++11, the Standard Library provides <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">next</span><span class="special">()</span></code> and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">prev</span><span class="special">()</span></code> function templates, which serve the same
purpose. However, there are advantages to <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">next</span><span class="special">()</span></code> and <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">prior</span><span class="special">()</span></code>.
</p>
<p>
First, <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">next</span><span class="special">()</span></code>
and <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">prior</span><span class="special">()</span></code>
are compatible not only with iterators but with any type that provides arithmetic
operators <code class="computeroutput"><span class="keyword">operator</span><span class="special">++()</span></code>,
<code class="computeroutput"><span class="keyword">operator</span><span class="special">--()</span></code>,
<code class="computeroutput"><span class="keyword">operator</span><span class="special">+()</span></code>,
<code class="computeroutput"><span class="keyword">operator</span><span class="special">-()</span></code>,
<code class="computeroutput"><span class="keyword">operator</span><span class="special">+=()</span></code>
or <code class="computeroutput"><span class="keyword">operator</span><span class="special">-=()</span></code>.
For example, this is possible:
</p>
<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">x</span> <span class="special">=</span> <span class="number">10</span><span class="special">;</span>
<span class="keyword">int</span> <span class="identifier">y</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">next</span><span class="special">(</span><span class="identifier">x</span><span class="special">,</span> <span class="number">5</span><span class="special">);</span>
<span class="identifier">assert</span><span class="special">(</span><span class="identifier">y</span> <span class="special">==</span> <span class="number">15</span><span class="special">);</span>
</pre>
<p>
Second, <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">next</span><span class="special">()</span></code>
and <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">prior</span><span class="special">()</span></code>
use <a class="link" href="../concepts/traversal.html" title="Traversal">traversal categories</a>
to select the most efficient implementation. For some kinds of iterators,
such as <a class="link" href="../specialized/transform.html" title="Transform Iterator">transform iterators</a>,
the standard iterator category does not reflect the traversal category correctly
and therefore <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">next</span><span class="special">()</span></code>
and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">prev</span><span class="special">()</span></code>
will fall back to linear complexity.
</p>
<h5>
<a name="iterator.algorithms.next_prior.h2"></a>
<span class="phrase"><a name="iterator.algorithms.next_prior.acknowledgements"></a></span><a class="link" href="next_prior.html#iterator.algorithms.next_prior.acknowledgements">Acknowledgements</a>
</h5>
<p>
Contributed by <a href="http://www.boost.org/people/dave_abrahams.htm" target="_top">Dave
Abrahams</a>. Two-argument versions by Daniel Walker.
</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="distance.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../algorithms.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>

View File

@@ -0,0 +1,371 @@
<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/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/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.access">Access</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="concepts.html#iterator.concepts.access.readable">Readable Iterator
Concept</a></span></dt>
<dt><span class="section"><a href="concepts.html#iterator.concepts.access.writable">Writable Iterator
Concept</a></span></dt>
<dt><span class="section"><a href="concepts.html#iterator.concepts.access.swappable">Swappable Iterator
Concept</a></span></dt>
<dt><span class="section"><a href="concepts.html#iterator.concepts.access.lvalue">Lvalue Iterator Concept</a></span></dt>
</dl></dd>
<dt><span class="section"><a href="concepts/traversal.html">Traversal</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="concepts/traversal.html#iterator.concepts.traversal.incrementable">Incrementable
Iterator Concept</a></span></dt>
<dt><span class="section"><a href="concepts/traversal.html#iterator.concepts.traversal.single_pass">Single Pass
Iterator Concept</a></span></dt>
<dt><span class="section"><a href="concepts/traversal.html#iterator.concepts.traversal.forward">Forward Traversal
Concept</a></span></dt>
<dt><span class="section"><a href="concepts/traversal.html#iterator.concepts.traversal.bidirectional">Bidirectional
Traversal Concept</a></span></dt>
<dt><span class="section"><a href="concepts/traversal.html#iterator.concepts.traversal.random_access">Random Access
Traversal Concept</a></span></dt>
</dl></dd>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="iterator.concepts.access"></a><a class="link" href="concepts.html#iterator.concepts.access" title="Access">Access</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="concepts.html#iterator.concepts.access.readable">Readable Iterator
Concept</a></span></dt>
<dt><span class="section"><a href="concepts.html#iterator.concepts.access.writable">Writable Iterator
Concept</a></span></dt>
<dt><span class="section"><a href="concepts.html#iterator.concepts.access.swappable">Swappable Iterator
Concept</a></span></dt>
<dt><span class="section"><a href="concepts.html#iterator.concepts.access.lvalue">Lvalue Iterator Concept</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="iterator.concepts.access.readable"></a><a class="link" href="concepts.html#iterator.concepts.access.readable" title="Readable Iterator Concept">Readable Iterator
Concept</a>
</h4></div></div></div>
<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.access.readable.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">
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="iterator.concepts.access.writable"></a><a class="link" href="concepts.html#iterator.concepts.access.writable" title="Writable Iterator Concept">Writable Iterator
Concept</a>
</h4></div></div></div>
<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.access.writable.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">
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="iterator.concepts.access.swappable"></a><a class="link" href="concepts.html#iterator.concepts.access.swappable" title="Swappable Iterator Concept">Swappable Iterator
Concept</a>
</h4></div></div></div>
<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.access.swappable.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="blurb">
<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>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="iterator.concepts.access.lvalue"></a><a class="link" href="concepts.html#iterator.concepts.access.lvalue" title="Lvalue Iterator Concept">Lvalue Iterator Concept</a>
</h4></div></div></div>
<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.access.lvalue.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>
</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/traversal.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,818 @@
<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.traversal"></a><a class="link" href="traversal.html" title="Traversal">Traversal</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="traversal.html#iterator.concepts.traversal.incrementable">Incrementable
Iterator Concept</a></span></dt>
<dt><span class="section"><a href="traversal.html#iterator.concepts.traversal.single_pass">Single Pass
Iterator Concept</a></span></dt>
<dt><span class="section"><a href="traversal.html#iterator.concepts.traversal.forward">Forward Traversal
Concept</a></span></dt>
<dt><span class="section"><a href="traversal.html#iterator.concepts.traversal.bidirectional">Bidirectional
Traversal Concept</a></span></dt>
<dt><span class="section"><a href="traversal.html#iterator.concepts.traversal.random_access">Random Access
Traversal Concept</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="iterator.concepts.traversal.incrementable"></a><a class="link" href="traversal.html#iterator.concepts.traversal.incrementable" title="Incrementable Iterator Concept">Incrementable
Iterator Concept</a>
</h4></div></div></div>
<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.traversal.incrementable.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">
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="iterator.concepts.traversal.single_pass"></a><a class="link" href="traversal.html#iterator.concepts.traversal.single_pass" title="Single Pass Iterator Concept">Single Pass
Iterator Concept</a>
</h4></div></div></div>
<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.traversal.single_pass.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_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">single_pass_traversal_tag</span></code>
</p>
</td>
<td>
</td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break">
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="iterator.concepts.traversal.forward"></a><a class="link" href="traversal.html#iterator.concepts.traversal.forward" title="Forward Traversal Concept">Forward Traversal
Concept</a>
</h4></div></div></div>
<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.traversal.forward.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_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">
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="iterator.concepts.traversal.bidirectional"></a><a class="link" href="traversal.html#iterator.concepts.traversal.bidirectional" title="Bidirectional Traversal Concept">Bidirectional
Traversal Concept</a>
</h4></div></div></div>
<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.traversal.bidirectional.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">
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="iterator.concepts.traversal.random_access"></a><a class="link" href="traversal.html#iterator.concepts.traversal.random_access" title="Random Access Traversal Concept">Random Access
Traversal Concept</a>
</h4></div></div></div>
<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.traversal.random_access.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>
</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>

File diff suppressed because it is too large Load Diff

View File

@@ -0,0 +1,436 @@
<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="../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="../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="../specialized.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.html#iterator.generic.adaptor.adaptor_tutorial">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 class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="iterator.generic.adaptor.adaptor_tutorial"></a><a class="link" href="adaptor.html#iterator.generic.adaptor.adaptor_tutorial" 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="blurb">
<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>
</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="../specialized.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

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>

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.html" title="Iterator Adaptor">
<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.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.html#iterator.specialized.shared_container.shared_container_object_generator">The
Shared Container Iterator Object Generator</a></span></dt>
<dt><span class="section"><a href="specialized/shared_container.html#iterator.specialized.shared_container.shared_container_generator">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.html#iterator.specialized.zip.zip_reference">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="blurb">
<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.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>

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>

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>

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="blurb">
<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>

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>

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>

View File

@@ -0,0 +1,360 @@
<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="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="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="transform.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.html#iterator.specialized.shared_container.shared_container_object_generator">The
Shared Container Iterator Object Generator</a></span></dt>
<dt><span class="section"><a href="shared_container.html#iterator.specialized.shared_container.shared_container_generator">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 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.html#iterator.specialized.shared_container.shared_container_object_generator" 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.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>
<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.html#iterator.specialized.shared_container.shared_container_generator" 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.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>
</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="transform.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,356 @@
<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.html" title="Shared Container Iterator">
<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.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="keyword">const</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
a const 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="keyword">const</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.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>

View File

@@ -0,0 +1,350 @@
<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="../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="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="../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.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.html#iterator.specialized.zip.zip_reference">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 class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="iterator.specialized.zip.zip_reference"></a><a class="link" href="zip.html#iterator.specialized.zip.zip_reference" 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.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.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.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.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>
</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="../utilities.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

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="algorithms/next_prior.html" title="Function templates next() and prior()">
<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="algorithms/next_prior.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="algorithms/next_prior.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>

View File

@@ -0,0 +1,228 @@
<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.html" title="Zip Iterator">
<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.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/iterator_traits.html">Iterator Traits</a></span></dt>
<dt><span class="section"><a href="utilities/traits.html">Type Traits</a></span></dt>
</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.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>

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="iterator_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="iterator_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 <a href="../../../../../concept_check/index.html" target="_top">Boost.ConceptCheck</a>
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="iterator_traits.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

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="traits.html" title="Type 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="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="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.iterator_traits"></a><a class="link" href="iterator_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.iterator_traits.h0"></a>
<span class="phrase"><a name="iterator.utilities.iterator_traits.synopsis"></a></span><a class="link" href="iterator_traits.html#iterator.utilities.iterator_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="traits.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,334 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Type 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="iterator_traits.html" title="Iterator Traits">
<link rel="next" href="../algorithms.html" title="Algorithms">
</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="iterator_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="../algorithms.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="Type Traits">Type Traits</a>
</h3></div></div></div>
<h3>
<a name="iterator.utilities.traits.h0"></a>
<span class="phrase"><a name="iterator.utilities.traits.overview"></a></span><a class="link" href="traits.html#iterator.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.traits.h1"></a>
<span class="phrase"><a name="iterator.utilities.traits.pointee"></a></span><a class="link" href="traits.html#iterator.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.traits.h2"></a>
<span class="phrase"><a name="iterator.utilities.traits.indirect_reference"></a></span><a class="link" href="traits.html#iterator.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.traits.h3"></a>
<span class="phrase"><a name="iterator.utilities.traits.minimum_category"></a></span><a class="link" href="traits.html#iterator.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.traits.h4"></a>
<span class="phrase"><a name="iterator.utilities.traits.iterator_category_and_traversal_"></a></span><a class="link" href="traits.html#iterator.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.traits.h5"></a>
<span class="phrase"><a name="iterator.utilities.traits.reference"></a></span><a class="link" href="traits.html#iterator.utilities.traits.reference">Reference</a>
</h3>
<h4>
<a name="iterator.utilities.traits.h6"></a>
<span class="phrase"><a name="iterator.utilities.traits.pointee0"></a></span><a class="link" href="traits.html#iterator.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.traits.h7"></a>
<span class="phrase"><a name="iterator.utilities.traits.indirect_reference0"></a></span><a class="link" href="traits.html#iterator.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.traits.h8"></a>
<span class="phrase"><a name="iterator.utilities.traits.minimum_category0"></a></span><a class="link" href="traits.html#iterator.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.traits.h9"></a>
<span class="phrase"><a name="iterator.utilities.traits.iterator_category_to_traversal"></a></span><a class="link" href="traits.html#iterator.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.traits.h10"></a>
<span class="phrase"><a name="iterator.utilities.traits.iterator_traversal"></a></span><a class="link" href="traits.html#iterator.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.traits.h11"></a>
<span class="phrase"><a name="iterator.utilities.traits.pure_traversal_tag"></a></span><a class="link" href="traits.html#iterator.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.traits.h12"></a>
<span class="phrase"><a name="iterator.utilities.traits.pure_iterator_traversal"></a></span><a class="link" href="traits.html#iterator.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>
<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="iterator_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="../algorithms.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,23 @@
index.html
iterator/concepts.html
iterator/concepts/traversal.html
iterator/generic.html
iterator/generic/adaptor.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/transform.html
iterator/specialized/zip.html
iterator/utilities.html
iterator/utilities/concept_checking.html
iterator/utilities/iterator_traits.html
iterator/utilities/traits.html
iterator/algorithms.html
iterator/algorithms/distance.html
iterator/algorithms/next_prior.html
iterator/upgrading.html
iterator/history.html