mirror of
https://github.com/boostorg/utility.git
synced 2025-05-09 15:04:00 +00:00
753 lines
29 KiB
HTML
753 lines
29 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
|
|
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
|
|
<meta name="ProgId" content="FrontPage.Editor.Document">
|
|
|
|
<title>Boost Iterator Adaptor Library</title>
|
|
</head>
|
|
|
|
<body bgcolor="#FFFFFF" text="#000000">
|
|
|
|
<img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align=
|
|
"center" width="277" height="86">
|
|
|
|
<h1>Boost Iterator Adaptor Library</h1>
|
|
|
|
<h2>Introduction</h2>
|
|
|
|
<p>The Iterator Adaptor library allows you transform an arbitrary ``base''
|
|
type into a standard-conforming iterator with the behaviors you choose.
|
|
Doing so is especially easy if the ``base'' type is itself an iterator. The
|
|
library also supplies several example <a href=
|
|
"../../more/generic_programming.html#adaptors">adaptors</a> which apply
|
|
specific useful behaviors to arbitrary base iterators.
|
|
|
|
<h2>Table of Contents</h2>
|
|
|
|
<ul>
|
|
<li>
|
|
Header <tt><a href=
|
|
"../../boost/iterator_adaptors.hpp">boost/iterator_adaptors.hpp</a></tt>
|
|
|
|
|
|
<ul>
|
|
<li>
|
|
Generalized Iterator Adaptor
|
|
|
|
<ul>
|
|
<li>Class template <tt><a href=
|
|
"#iterator_adaptor">iterator_adaptor</a></tt>
|
|
|
|
<li><a href="#template_parameters">Template Parameters</a>
|
|
|
|
<li><a href="#policies">The Policies Class</a>
|
|
|
|
<li><a href="#additional_members">Additional Class Members</a>
|
|
|
|
<li><a href="#example">Example</a>
|
|
|
|
<li>(<tt>const</tt>/non-<tt>const</tt>) <a href=
|
|
"#iterator_interactions">Iterator Interactions</a>
|
|
|
|
<li><a href="#challenge">Challenge</a>
|
|
|
|
<li><a href="#concept_model">Concept Model</a>
|
|
|
|
<li><a href="#declaration_synopsis">Declaration Synopsis</a>
|
|
|
|
<li><a href="#notes">Notes</a>
|
|
</ul>
|
|
|
|
<li>
|
|
Specialized Iterator Adaptors
|
|
|
|
<ul>
|
|
<li><a href="indirect_iterator.htm">Indirect Iterator Adaptor</a>
|
|
|
|
<li><a href="reverse_iterator.htm">Reverse Iterator Adaptor</a>
|
|
|
|
<li><a href="transform_iterator.htm">Transform Iterator
|
|
Adaptor</a>
|
|
|
|
<li><a href="projection_iterator.htm">Projection Iterator
|
|
Adaptor</a>
|
|
|
|
<li><a href="filter_iterator.htm">Filter Iterator Adaptor</a>
|
|
</ul>
|
|
</ul>
|
|
|
|
<li>Header <tt><a href=
|
|
"../../boost/counting_iterator.hpp">boost/counting_iterator.hpp</a></tt><br>
|
|
|
|
<a href="counting_iterator.htm">Counting Iterator Adaptor</a>
|
|
</ul>
|
|
|
|
<p><b><a href="http://www.boost.org/people/dave_abrahams.htm">Dave
|
|
Abrahams</a></b> started the library, applying <a href=
|
|
"../../more/generic_programming.html#policy">policy class</a> technique and
|
|
handling const/non-const iterator interactions. He also contributed the
|
|
<tt><a href="indirect_iterator.htm">indirect_</a></tt> and <tt><a href=
|
|
"reverse_iterator.htm">reverse_</a></tt> iterator generators, and expanded
|
|
<tt><a href="counting_iterator.htm">counting_iterator_generator</a></tt> to
|
|
cover all incrementable types. He edited most of the documentation,
|
|
sometimes heavily.<br>
|
|
<b><a href="http://www.boost.org/people/jeremy_siek.htm">Jeremy
|
|
Siek</a></b> contributed the <a href="transform_iterator.htm">transform
|
|
iterator</a> adaptor, the integer-only version of <tt><a href=
|
|
"counting_iterator.htm">counting_iterator_generator</a></tt>, and most of
|
|
the documentation.<br>
|
|
<b><a href="http://www.boost.org/people/john_potter.htm">John
|
|
Potter</a></b> contributed the <tt><a href=
|
|
"projection_iterator.htm">projection_</a></tt> and <tt><a href=
|
|
"filter_iterator.htm">filter_</a></tt> iterator generators and made some
|
|
simplifications to the main <tt><a href=
|
|
"#iterator_adaptor">iterator_adaptor</a></tt> template.<br>
|
|
|
|
|
|
<h2><a name="iterator_adaptor">Class template</a>
|
|
<tt>iterator_adaptor</tt></h2>
|
|
Implementing standard conforming iterators is a non-trivial task. There are
|
|
some fine points such as the interactions between an iterator and its
|
|
corresponding const_iterator, and there are myriad operators that should be
|
|
implemented but are easily forgotten or mishandled, such as
|
|
<tt>operator->()</tt>. Using <tt>iterator_adaptor</tt>, you can easily
|
|
implement an iterator class, and even more easily extend and <a href=
|
|
"../../more/generic_programming.html#adaptors">adapt</a> existing iterator
|
|
types. Moreover, it is easy to make a pair of interoperable <tt>const</tt>
|
|
and <tt>non-const</tt> iterators.
|
|
|
|
<p><tt>iterator_adaptor</tt> is declared like this:
|
|
<pre>
|
|
template <class Base, class Policies,
|
|
class Value = typename std::iterator_traits<Base>::value_type,
|
|
class Reference = <i>...(see below)</i>,
|
|
class Pointer = <i>...(see below)</i>,
|
|
class Category = typename std::iterator_traits<Base>::iterator_category,
|
|
class Distance = typename std::iterator_traits<Base>::difference_type>
|
|
struct iterator_adaptor;
|
|
</pre>
|
|
|
|
<h3><a name="template_parameters">Template Parameters</a></h3>
|
|
|
|
<p>Although <tt>iterator_adaptor</tt> takes seven template parameters,
|
|
defaults have been carefully chosen to minimize the number of parameters
|
|
you must supply in most cases, especially if <tt>BaseType</tt> is an
|
|
iterator.
|
|
|
|
<table border="1" summary="iterator_adaptor template parameters">
|
|
<tr>
|
|
<th>Parameter
|
|
|
|
<th>Description
|
|
|
|
<tr>
|
|
<td><tt>BaseType</tt>
|
|
|
|
<td>The type being wrapped.
|
|
|
|
<tr>
|
|
<td><tt>Policies</tt>
|
|
|
|
<td>A <a href="../../more/generic_programming.html#policy">policy
|
|
class</a> that supplies core functionality to the resulting iterator. A
|
|
detailed description can be found <a href="#policies">below</a>.
|
|
|
|
<tr>
|
|
<td><tt>Value</tt>
|
|
|
|
<td>The <tt>value_type</tt> of the resulting iterator, unless const. If
|
|
Value is <tt>const X</tt> the
|
|
<tt>value_type</tt> will be (<i>non-</i><tt>const</tt>) <tt>X</tt><a href=
|
|
"#1">[1]</a>.<br>
|
|
<b>Default:</b>
|
|
<tt>std::iterator_traits<BaseType>::value_type</tt> <a href=
|
|
"#2">[2]</a>
|
|
|
|
<tr>
|
|
<td><tt>Reference</tt>
|
|
|
|
<td>The <tt>reference</tt> type of the resulting iterator, and in
|
|
particular, the result type of <tt>operator*()</tt>.<br>
|
|
<b>Default:</b> If <tt>Value</tt> is supplied, <tt>Value&</tt> is
|
|
used. Otherwise
|
|
<tt>std::iterator_traits<BaseType>::reference</tt> is used.
|
|
|
|
<tr>
|
|
<td><tt>Pointer</tt>
|
|
|
|
<td>The <tt>pointer</tt> type of the resulting iterator, and in
|
|
particular, the result type of <tt>operator->()</tt>.<br>
|
|
<b>Default:</b> If <tt>Value</tt> was supplied, then <tt>Value*</tt>,
|
|
otherwise <tt>std::iterator_traits<BaseType>::pointer</tt>.
|
|
|
|
<tr>
|
|
<td><tt>Category</tt>
|
|
|
|
<td>The <tt>iterator_category</tt> type for the resulting iterator.<br>
|
|
<b>Default:</b>
|
|
<tt>std::iterator_traits<BaseType>::iterator_category</tt>
|
|
|
|
<tr>
|
|
<td><tt>Distance</tt>
|
|
|
|
<td>The <tt>difference_type</tt> for the resulting iterator.<br>
|
|
<b>Default:</b>
|
|
<tt>std::iterator_traits<BaseType>::difference_type</tt>
|
|
</table>
|
|
|
|
<h3><a name="policies">The Policies Class</a></h3>
|
|
|
|
<p>The main task in using <tt>iterator_adaptor</tt> is creating an
|
|
appropriate <tt>Policies</tt> class. The <tt>Policies</tt> class will
|
|
become the functional heart of the iterator adaptor, supplying the core
|
|
iterator operations that will determine how your new adaptor class will
|
|
behave. The <tt>iterator_adaptor</tt> template defines all of the operators
|
|
required of a <a href=
|
|
"http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random Access
|
|
Iterator</a>. Your <tt>Policies</tt> class must implement three, four, or
|
|
seven of the core iterator operations below depending on the iterator
|
|
categories you want it to support.
|
|
|
|
<table border="1" summary="iterator_adaptor Policies operations">
|
|
<caption>
|
|
<b>Core Iterator Operations</b>
|
|
</caption>
|
|
|
|
<tr>
|
|
<th>Operation
|
|
|
|
<th>Effects
|
|
|
|
<th>Required for Iterator Categories
|
|
|
|
<tr>
|
|
<td><tt>dereference</tt>
|
|
|
|
<td>returns an element of the iterator's <tt>reference</tt> type
|
|
|
|
<td rowspan="3"><a href=
|
|
"http://www.sgi.com/tech/stl/InputIterator.html">Input</a>/ <a href=
|
|
"http://www.sgi.com/tech/stl/OutputIterator.html">Output</a>/ <a href=
|
|
"http://www.sgi.com/tech/stl/ForwardIterator.html">Forward</a>/ <a
|
|
href=
|
|
"http://www.sgi.com/tech/stl/BidirectionalIterator.html">Bidirectional</a>/
|
|
<a href="http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random
|
|
Access</a>
|
|
|
|
<tr>
|
|
<td><tt>equal</tt>
|
|
|
|
<td>tests the iterator for equality
|
|
|
|
<tr>
|
|
<td><tt>increment</tt>
|
|
|
|
<td>increments the iterator
|
|
|
|
<tr>
|
|
<td><tt>decrement</tt>
|
|
|
|
<td>decrements the iterator
|
|
|
|
<td><a href=
|
|
"http://www.sgi.com/tech/stl/BidirectionalIterator.html">Bidirectional</a>/
|
|
<a href="http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random
|
|
Access</a>
|
|
|
|
<tr>
|
|
<td><tt>less</tt>
|
|
|
|
<td>imposes a <a href=
|
|
"http://www.sgi.com/tech/stl/StrictWeakOrdering.html">Strict Weak
|
|
Ordering</a> relation on the iterator's <tt>reference</tt> type
|
|
|
|
<td rowspan="3"><a href=
|
|
"http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random
|
|
Access</a>
|
|
|
|
<tr>
|
|
<td><tt>distance</tt>
|
|
|
|
<td>measures the distance between iterators
|
|
|
|
<tr>
|
|
<td><tt>advance</tt>
|
|
|
|
<td>adds an integer offset to iterators
|
|
</table>
|
|
|
|
<p>The library also supplies a "trivial" policy class,
|
|
<tt>default_iterator_policies</tt>, which implements all seven of the core
|
|
operations in the usual way. If you wish to create an iterator adaptor that
|
|
only changes a few of the base type's behaviors, then you can derive your
|
|
new policy class from <tt>default_iterator_policies</tt> to avoid retyping
|
|
the usual behaviors. You should also look at
|
|
<tt>default_iterator_policies</tt> as the ``boilerplate'' for your own
|
|
policy classes, defining functions with the same interface. This is the
|
|
definition of <tt>default_iterator_policies</tt>:<br>
|
|
<br>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
struct <a name="default_iterator_policies">default_iterator_policies</a>
|
|
{
|
|
template <class Reference, class BaseType>
|
|
Reference dereference(type<Reference>, const BaseType& x) const
|
|
{ return *x; }
|
|
|
|
template <class BaseType>
|
|
static void increment(BaseType& x)
|
|
{ ++x; }
|
|
|
|
template <class BaseType1, class BaseType2>
|
|
bool equal(BaseType1& x, BaseType2& y) const
|
|
{ return x == y; }
|
|
|
|
template <class BaseType>
|
|
static void decrement(BaseType& x)
|
|
{ --x; }
|
|
|
|
template <class BaseType, class DifferenceType>
|
|
static void advance(BaseType& x, DifferenceType n)
|
|
{ x += n; }
|
|
|
|
template <class Difference, class BaseType1, class BaseType2>
|
|
Difference distance(type<Difference>, BaseType1& x, BaseType2& y) const
|
|
{ return y - x; }
|
|
|
|
template <class BaseType1, class BaseType2>
|
|
bool less(BaseType1& x, BaseType2& y) const
|
|
{ return x < y; }
|
|
};
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>Template member functions are used throughout
|
|
<tt>default_iterator_policies</tt> so that it can be employed with a wide
|
|
range of iterators. If we had used concrete types above, we'd have tied the
|
|
usefulness of <tt>default_iterator_policies</tt> to a particular range of
|
|
adapted iterators. If you follow the same pattern with your
|
|
<tt>Policies</tt> classes, you may achieve the same sort of reusability.
|
|
|
|
<h3><a name="additional_members">Additional Members</a></h3>
|
|
In addition to all of the member functions required of a <a href=
|
|
"http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random Access
|
|
Iterator</a>, the <tt>iterator_adaptor</tt> class template defines the
|
|
following members. <br>
|
|
<br>
|
|
|
|
|
|
<table border="1" summary="additional iterator_adaptor members">
|
|
<tr>
|
|
<td><tt>explicit iterator_adaptor(const Base&, const Policies& =
|
|
Policies())</tt>
|
|
<br><br>
|
|
Construct an adapted iterator from a base object and a policies
|
|
object. As this constructor is <tt>explicit</tt>, it does not
|
|
provide for implicit conversions from the <tt>Base</tt> type to
|
|
the iterator adaptor.
|
|
|
|
<tr>
|
|
<td><tt>template <class B, class V, class R, class P><br>
|
|
iterator_adaptor(const
|
|
iterator_adaptor<B,Policies,V,R,P,Category,Distance>&)</tt>
|
|
<br><br>
|
|
This constructor allows for conversion from non-<tt>const</tt> to
|
|
constant adapted iterators. See <a href=
|
|
"#iterator_interactions">below</a> for more details.<br>
|
|
Requires: <tt>B</tt> is convertible to <tt>Base</tt>.
|
|
|
|
<tr>
|
|
<td><tt>base_type base() const;</tt>
|
|
<br><br>
|
|
Return a copy of the base object.
|
|
</table>
|
|
|
|
<h3><a name="example">Example</a></h3>
|
|
|
|
<p>It is often useful to automatically apply some function to the value
|
|
returned by dereferencing an iterator. The <a href=
|
|
"./transform_iterator.htm">transform iterator</a> makes it easy to create
|
|
an iterator adaptor which does just that. Here we will show how easy it is
|
|
to implement the transform iterator using the <tt>iterator_adaptor</tt>
|
|
template.
|
|
|
|
<p>We want to be able to adapt a range of iterators and functions, so the
|
|
policies class will have a template parameter for the function type and it
|
|
will have a data member of that type. We know that the function takes one
|
|
argument and that we'll need to be able to deduce the <tt>result_type</tt>
|
|
of the function so we can use it for the adapted iterator's
|
|
<tt>value_type</tt>. <a href=
|
|
"http://www.sgi.com/Technology/STL/AdaptableUnaryFunction.html">AdaptableUnaryFunction</a>
|
|
is the <a href="../../more/generic_programming.html#concept">Concept</a>
|
|
that fulfills those requirements.
|
|
|
|
<p>To implement a transform iterator we will only change one of the base
|
|
iterator's behaviors, so the <tt>transform_iterator_policies</tt> class can
|
|
inherit the rest from <tt>default_iterator_policies</tt>. We will define
|
|
the <tt>dereference()</tt> member function, which is used to implement
|
|
<tt>operator*()</tt> of the adapted iterator. The implementation will
|
|
dereference the base iterator and apply the function object. The
|
|
<tt>type<Reference></tt> parameter is used to convey the appropriate
|
|
return type. The complete code for <tt>transform_iterator_policies</tt>
|
|
is:<br>
|
|
<br>
|
|
|
|
|
|
<blockquote>
|
|
<pre>
|
|
template <class AdaptableUnaryFunction>
|
|
struct transform_iterator_policies : public default_iterator_policies
|
|
{
|
|
transform_iterator_policies() { }
|
|
|
|
transform_iterator_policies(const AdaptableUnaryFunction& f)
|
|
: m_f(f) { }
|
|
|
|
template <class Reference, class BaseIterator>
|
|
Reference dereference(type<Reference>, const BaseIterator& i) const
|
|
{ return m_f(*i); }
|
|
|
|
AdaptableUnaryFunction m_f;
|
|
};
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>The next step is to use the <tt>iterator_adaptor</tt> template to
|
|
construct the transform iterator type. The nicest way to package the
|
|
construction of the transform iterator is to create a <a href=
|
|
"../../more/generic_programming.html#type_generator">type generator</a>.
|
|
The first template parameter to the generator will be the type of the
|
|
function object and the second will be the base iterator type. We use
|
|
<tt>iterator_adaptor</tt> to define the transform iterator type as a nested
|
|
<tt>typedef</tt> inside the <tt>transform_iterator_generator</tt> class.
|
|
Because the function may return by-value, we must limit the
|
|
<tt>iterator_category</tt> to <a href=
|
|
"http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a>, and
|
|
the iterator's <tt>reference</tt> type cannot be a true reference (the
|
|
standard allows this for input iterators), so in this case we can use few
|
|
of <tt>iterator_adaptor</tt>'s default template arguments.<br>
|
|
<br>
|
|
|
|
|
|
<blockquote>
|
|
<pre>
|
|
template <class AdaptableUnaryFunction, class Iterator>
|
|
struct transform_iterator_generator
|
|
{
|
|
typedef typename AdaptableUnaryFunction::result_type value_type;
|
|
public:
|
|
typedef iterator_adaptor<Iterator,
|
|
transform_iterator_policies<AdaptableUnaryFunction>,
|
|
value_type, value_type, value_type*, std::input_iterator_tag>
|
|
type;
|
|
};
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>As a finishing touch, we will create an <a href=
|
|
"../../more/generic_programming.html#object_generator">object generator</a>
|
|
for the transform iterator. This is a function that makes it more
|
|
convenient to create a transform iterator.<br>
|
|
<br>
|
|
|
|
|
|
<blockquote>
|
|
<pre>
|
|
template <class AdaptableUnaryFunction, class Iterator>
|
|
typename transform_iterator_generator<AdaptableUnaryFunction,Iterator>::type
|
|
make_transform_iterator(Iterator base,
|
|
const AdaptableUnaryFunction& f = AdaptableUnaryFunction())
|
|
{
|
|
typedef typename transform_iterator_generator<AdaptableUnaryFunction,
|
|
Iterator>::type result_t;
|
|
return result_t(base, f);
|
|
}
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>Here is an example that shows how to use a transform iterator to iterate
|
|
through a range of numbers, multiplying each of them by 2 and printing the
|
|
result to standard output.<br>
|
|
<br>
|
|
|
|
|
|
<blockquote>
|
|
<pre>
|
|
#include <functional>
|
|
#include <algorithm>
|
|
#include <iostream>
|
|
#include <boost/iterator_adaptors.hpp>
|
|
|
|
int main(int, char*[])
|
|
{
|
|
int x[] = { 1, 2, 3, 4, 5, 6, 7, 8 };
|
|
const int N = sizeof(x)/sizeof(int);
|
|
std::cout << "multiplying the array by 2:" << std::endl;
|
|
std::copy(boost::make_transform_iterator(x, std::bind1st(std::multiplies<int>(), 2)),
|
|
boost::make_transform_iterator(x + N, std::bind1st(std::multiplies<int>(), 2)),
|
|
std::ostream_iterator<int>(std::cout, " "));
|
|
std::cout << std::endl;
|
|
return 0;
|
|
}
|
|
</pre>
|
|
This output is:
|
|
<pre>
|
|
2 4 6 8 10 12 14 16
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<h3><a name="iterator_interactions">Iterator Interactions</a></h3>
|
|
|
|
<p>C++ allows <tt>const</tt> and non-<tt>const</tt> pointers to interact in
|
|
the following intuitive ways:
|
|
|
|
<ul>
|
|
<li>a non-<tt>const</tt> pointer to <tt>T</tt> can be implicitly
|
|
converted to a <tt>const</tt> pointer to <tt>T</tt>.
|
|
|
|
<li><tt>const</tt> and non-<tt>const</tt> pointers to <tt>T</tt> can be
|
|
freely mixed in comparison expressions.
|
|
|
|
<li><tt>const</tt> and non-<tt>const</tt> pointers to <tt>T</tt> can be
|
|
freely subtracted, in any order.
|
|
</ul>
|
|
Getting user-defined iterators to work together that way is nontrivial, but
|
|
<tt>iterator_adaptor</tt> can make it easy. The rules are as follows:
|
|
|
|
<ul>
|
|
<li><a name="interoperable">Adapted iterators that share the same <tt>Policies</tt>,
|
|
<tt>Category</tt>, and <tt>Distance</tt> parameters are called
|
|
<i>interoperable</i>.</a>
|
|
|
|
<li>An adapted iterator can be implicitly converted to any other adapted
|
|
iterator with which it is interoperable, so long as the <tt>Base</tt>
|
|
type of the source iterator can be converted to the <tt>Base</tt> type of
|
|
the target iterator.
|
|
|
|
<li>Interoperable iterators can be freely mixed in comparison expressions
|
|
so long as the <tt>Policies</tt> class has <tt>equal</tt> (and, for
|
|
random access iterators, <tt>less</tt>) members that can accept both
|
|
<tt>Base</tt> types in either order.
|
|
|
|
<li>Interoperable iterators can be freely mixed in subtraction
|
|
expressions so long as the <tt>Policies</tt> class has a
|
|
<tt>distance</tt> member that can accept both <tt>Base</tt> types in
|
|
either order.
|
|
</ul>
|
|
|
|
<h4>Example</h4>
|
|
|
|
<p>The <a href="projection_iterator.htm">Projection Iterator</a> adaptor is similar to the <a
|
|
href="./transform_iterator.htm">transform iterator adaptor</a> in that
|
|
its <tt>operator*()</tt> applies some function to the result of
|
|
dereferencing the base iterator and then returns the result. The
|
|
difference is that the function must return a reference to some
|
|
existing object (for example, a data member within the
|
|
<tt>value_type</tt> of the base iterator).
|
|
|
|
<p>
|
|
The <a
|
|
href="projection_iterator.htm#projection_iterator_pair_generator">projection_iterator_pair_generator</a> template
|
|
is a special two-<a href="../../more/generic_programming.html#type_generator">type generator</a> for mutable and constant versions of a
|
|
projection iterator. It is defined as follows:
|
|
<blockquote>
|
|
<pre>
|
|
template <class AdaptableUnaryFunction, class Iterator, class ConstIterator>
|
|
struct projection_iterator_pair_generator {
|
|
typedef typename AdaptableUnaryFunction::result_type value_type;
|
|
typedef projection_iterator_policies<AdaptableUnaryFunction> policies;
|
|
public:
|
|
typedef iterator_adaptor<Iterator,policies,value_type> iterator;
|
|
typedef iterator_adaptor<ConstIterator,policies,value_type,
|
|
const value_type&,const value_type*> const_iterator;
|
|
};
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>It is assumed that the <tt>Iterator</tt> and <tt>ConstIterator</tt> arguments are corresponding mutable
|
|
and constant iterators. <ul>
|
|
<li>
|
|
Clearly, then, the
|
|
<tt>projection_iterator_pair_generator</tt>'s <tt>iterator</tt> and
|
|
<tt>const_iterator</tt> are <a href="#interoperable">interoperable</a>, since
|
|
they share the same <tt>Policies</tt> and since <tt>Category</tt> and
|
|
<tt>Distance</tt> as supplied by <tt>std::iterator_traits</tt> through the
|
|
<a href="#template_parameters">default template parameters</a> to
|
|
<tt>iterator_adaptor</tt> should be the same.
|
|
|
|
<li>Since <tt>Iterator</tt> can presumably be converted to
|
|
<tt>ConstIterator</tt>, the projection <tt>iterator</tt> will be convertible to
|
|
the projection <tt>const_iterator</tt>.
|
|
|
|
<li> Since <tt>projection_iterator_policies</tt> implements only the
|
|
<tt>dereference</tt> operation, and inherits all other behaviors from <tt><a
|
|
href="#default_iterator_policies">default_iterator_policies</a></tt>, which has
|
|
fully-templatized <tt>equal</tt>, <tt>less</tt>, and <tt>distance</tt>
|
|
operations, the <tt>iterator</tt> and <tt>const_iterator</tt> can be freely
|
|
mixed in comparison and subtraction expressions.
|
|
|
|
</ul>
|
|
|
|
<h3><a name="challenge">Challenge</a></h3>
|
|
|
|
<p>There is an unlimited number of ways the <tt>iterator_adaptors</tt>
|
|
class can be used to create iterators. One interesting exercise would be to
|
|
re-implement the iterators of <tt>std::list</tt> and <tt>std::slist</tt>
|
|
using <tt>iterator_adaptors</tt>, where the adapted <tt>Iterator</tt> types
|
|
would be node pointers.
|
|
|
|
<h3><a name="concept_model">Concept Model</a></h3>
|
|
Depending on the <tt>Base</tt> and <tt>Policies</tt> template parameters,
|
|
an <tt>iterator_adaptor</tt> can be a <a href=
|
|
"http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a>, <a
|
|
href="http://www.sgi.com/tech/stl/ForwardIterator.html">Forward
|
|
Iterator</a>, <a href=
|
|
"http://www.sgi.com/tech/stl/BidirectionalIterator.html">Bidirectional
|
|
Iterator</a>, or <a href=
|
|
"http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random Access
|
|
Iterator</a>.
|
|
|
|
<h3><a name="declaration_synopsis">Declaration Synopsis</a></h3>
|
|
<pre>
|
|
template <class Base, class Policies,
|
|
class Value = typename std::iterator_traits<Base>::value_type,
|
|
class Reference = <i>...(see below)</i>,
|
|
class Pointer = <i>...(see below)</i>,
|
|
class Category = typename std::iterator_traits<Base>::iterator_category,
|
|
class Distance = typename std::iterator_traits<Base>::difference_type
|
|
>
|
|
struct iterator_adaptor
|
|
{
|
|
typedef Distance difference_type;
|
|
typedef typename boost::remove_const<Value>::type value_type;
|
|
typedef Pointer pointer;
|
|
typedef Reference reference;
|
|
typedef Category iterator_category;
|
|
typedef Base base_type;
|
|
typedef Policies policies_type;
|
|
|
|
iterator_adaptor();
|
|
explicit iterator_adaptor(const Base&, const Policies& = Policies());
|
|
|
|
base_type base() const;
|
|
|
|
template <class B, class V, class R, class P>
|
|
iterator_adaptor(
|
|
const iterator_adaptor<B,Policies,V,R,P,Category,Distance>&);
|
|
|
|
reference operator*() const;
|
|
<i>operator_arrow_result_type</i> operator->() const; <a href=
|
|
"#3">[3]</a>
|
|
<i>value_type</i> operator[](difference_type n) const; <a href="#3">[4]</a>
|
|
|
|
iterator_adaptor& operator++();
|
|
iterator_adaptor& operator++(int);
|
|
iterator_adaptor& operator--();
|
|
iterator_adaptor& operator--(int);
|
|
|
|
iterator_adaptor& operator+=(difference_type n);
|
|
iterator_adaptor& operator-=(difference_type n);
|
|
|
|
iterator_adaptor& operator-(Distance x) const;
|
|
};
|
|
|
|
template <class B, class P, class V, class R, class Ptr,
|
|
class C, class D1, class D2>
|
|
iterator_adaptor<B,P,V,R,Ptr,C,D1>
|
|
operator+(iterator_adaptor<B,P,V,R,Ptr,C,D1>, D2);
|
|
|
|
template <class B, class P, class V, class R, class Ptr,
|
|
class C, class D1, class D2>
|
|
iterator_adaptor<B,P,V,R,P,C,D1>
|
|
operator+(D2, iterator_adaptor<B,P,V,R,Ptr,C,D1> p);
|
|
|
|
template <class B1, class B2, class P, class V1, class V2,
|
|
class R1, class R2, class P1, class P2, class C, class D>
|
|
Distance operator-(const iterator_adaptor<B1,P,V1,R1,P1,C,D>&,
|
|
const iterator_adaptor<B2,P,V2,R2,P2,C,D>&);
|
|
|
|
template <class B1, class B2, class P, class V1, class V2,
|
|
class R1, class R2, class P1, class P2, class C, class D>
|
|
bool operator==(const iterator_adaptor<B1,P,V1,R1,P1,C,D>&,
|
|
const iterator_adaptor<B2,P,V2,R2,P2,C,D>&);
|
|
|
|
// and similarly for operators !=, <, <=, >=, >
|
|
</pre>
|
|
|
|
<h3><a name="notes">Notes</a></h3>
|
|
|
|
<p><a name="1">[1]</a> The standard specifies that the <tt>value_type</tt>
|
|
of <tt>const</tt> iterators to <tt>T</tt> (e.g. <tt>const T*</tt>) is
|
|
<tt><i>non-</i>const T</tt>, while the <tt>pointer</tt> and
|
|
<tt>reference</tt> types for all <a href=
|
|
"http://www.sgi.com/tech/stl/ForwardIterator.html">Forward Iterators</a> are
|
|
<tt>const T*</tt> and <tt>const T&</tt>, respectively. Stripping the
|
|
<tt>const</tt>-ness of <tt>Value</tt> allows you to easily
|
|
make a <tt>const</tt> iterator adaptor by supplying a <tt>const</tt> type
|
|
for <tt>Value</tt>, and allowing the defaults for the <tt>Pointer</tt> and
|
|
<tt>Reference</tt> parameters to take effect. Although compilers that don't
|
|
support partial specialization won't strip <tt>const</tt> for you, having a
|
|
<tt>const value_type</tt> is often harmless in practice.
|
|
|
|
<p><a name="2">[2]</a> If your compiler does not support partial
|
|
specialization and the base iterator is a builtin pointer type, you
|
|
will not be able to use the default for <tt>Value</tt> and will have to
|
|
specify this type explicitly.
|
|
|
|
<p><a name="3">[3]</a> The result type for the <tt>operator->()</tt>
|
|
depends on the category and value type of the iterator and is somewhat
|
|
complicated to describe. But be assured, it works in a stardard conforming
|
|
fashion, providing access to members of the objects pointed to by the
|
|
iterator.
|
|
|
|
<p><a name="4">[4]</a> The result type of <tt>operator[]()</tt> is
|
|
<tt>value_type</tt> instead of <tt>reference</tt> as might be expected.
|
|
There are two reasons for this choice. First, the C++ standard only
|
|
requires that the return type of an arbitrary <a href=
|
|
"http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random Access
|
|
Iterator</a>'s <tt>operator[]</tt>be ``convertible to T'' (Table 76), so
|
|
when adapting an arbitrary base iterator we may not have a reference to
|
|
return. Second, and more importantly, for certain kinds of iterators,
|
|
returning a reference could cause serious memory problems due to the
|
|
reference being bound to a temporary object whose lifetime ends inside of
|
|
the <tt>operator[]</tt>.
|
|
<hr>
|
|
|
|
<p>Revised
|
|
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %b %Y" startspan -->15
|
|
Feb 2001<!--webbot bot="Timestamp" endspan i-checksum="14373" -->
|
|
|
|
|
|
<p>© Copyright Dave Abrahams and Jeremy Siek 2001. Permission to copy,
|
|
use, modify, sell and distribute this document is granted provided this
|
|
copyright notice appears in all copies. This document is provided "as is"
|
|
without express or implied warranty, and with no claim as to its
|
|
suitability for any purpose.
|
|
|
|
</body>
|
|
|
|
<!-- LocalWords: HTML html charset alt gif abrahams htm const
|
|
incrementable david abrahams
|
|
-->
|
|
|
|
<!-- LocalWords: jeremy siek mishandled interoperable typename struct Iter iter src
|
|
-->
|
|
|
|
<!-- LocalWords: int bool ForwardIterator BidirectionalIterator BaseIterator
|
|
-->
|
|
|
|
<!-- LocalWords: RandomAccessIterator DifferenceType AdaptableUnaryFunction
|
|
-->
|
|
|
|
<!-- LocalWords: iostream hpp sizeof InputIterator constness ConstIterator
|
|
David Abrahams
|
|
-->
|
|
</body>
|
|
</html>
|
|
|