mirror of
https://github.com/boostorg/utility.git
synced 2025-05-09 15:04:00 +00:00
444 lines
15 KiB
HTML
444 lines
15 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//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>Indirect Iterator Adaptor Documentation</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>Indirect Iterator Adaptor</h1>
|
||
Defined in header <a href=
|
||
"../../boost/iterator_adaptors.hpp">boost/iterator_adaptors.hpp</a>
|
||
|
||
<p>The indirect iterator adaptor augments an iterator by applying an
|
||
<b>extra</b> dereference inside of <tt>operator*()</tt>. For example, this
|
||
iterator makes it possible to view a container of pointers or
|
||
smart-pointers (e.g. <tt>std::list<boost::shared_ptr<foo>
|
||
></tt>) as if it were a container of the pointed-to type. The following
|
||
<b>pseudo-code</b> shows the basic idea of the indirect iterator:
|
||
|
||
<blockquote>
|
||
<pre>
|
||
// inside a hypothetical indirect_iterator class...
|
||
typedef std::iterator_traits<BaseIterator>::value_type Pointer;
|
||
typedef std::iterator_traits<Pointer>::reference reference;
|
||
|
||
reference indirect_iterator::operator*() const {
|
||
return **this->base_iterator;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<h2>Synopsis</h2>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
namespace boost {
|
||
template <class BaseIterator,
|
||
class Value, class Reference, class Category, class Pointer>
|
||
struct indirect_iterator_generator;
|
||
|
||
template <class BaseIterator,
|
||
class Value, class Reference, class ConstReference,
|
||
class Category, class Pointer, class ConstPointer>
|
||
struct indirect_iterator_pair_generator;
|
||
|
||
template <class BaseIterator>
|
||
typename indirect_iterator_generator<BaseIterator>::type
|
||
make_indirect_iterator(BaseIterator base)
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
<hr>
|
||
|
||
<h2><a name="indirect_iterator_generator">The Indirect Iterator Type
|
||
Generator</a></h2>
|
||
The <tt>indirect_iterator_generator</tt> template is a <a href=
|
||
"../../more/generic_programming.html#type_generator">generator</a> of
|
||
indirect iterator types. The main template parameter for this class is the
|
||
<tt>BaseIterator</tt> type that is being wrapped. In most cases the type of
|
||
the elements being pointed to can be deduced using
|
||
<tt>std::iterator_traits</tt>, but in some situations the user may want to
|
||
override this type, so there are also template parameters that allow a user
|
||
to control the <tt>value_type</tt>, <tt>pointer</tt>, and
|
||
<tt>reference</tt> types of the resulting iterators.
|
||
|
||
<blockquote>
|
||
<pre>
|
||
template <class BaseIterator,
|
||
class Value, class Reference, class Pointer>
|
||
class indirect_iterator_generator
|
||
{
|
||
public:
|
||
typedef <tt><a href=
|
||
"./iterator_adaptors.htm#iterator_adaptor">iterator_adaptor</a><...></tt> type; // the resulting indirect iterator type
|
||
};
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<h3>Example</h3>
|
||
This example uses the <tt>indirect_iterator_generator</tt> to create
|
||
indirect iterators which dereference the pointers stored in the
|
||
<tt>pointers_to_chars</tt> array to access the <tt>char</tt>s in the
|
||
<tt>characters</tt> array.
|
||
|
||
<blockquote>
|
||
<pre>
|
||
#include <boost/config.hpp>
|
||
#include <vector>
|
||
#include <iostream>
|
||
#include <iterator>
|
||
#include <boost/iterator_adaptors.hpp>
|
||
|
||
int main(int, char*[])
|
||
{
|
||
char characters[] = "abcdefg";
|
||
const int N = sizeof(characters)/sizeof(char) - 1; // -1 since characters has a null char
|
||
char* pointers_to_chars[N]; // at the end.
|
||
for (int i = 0; i < N; ++i)
|
||
pointers_to_chars[i] = &characters[i];
|
||
|
||
boost::indirect_iterator_generator<char**, char>::type
|
||
indirect_first(pointers_to_chars), indirect_last(pointers_to_chars + N);
|
||
|
||
std::copy(indirect_first, indirect_last, std::ostream_iterator<char>(std::cout, ","));
|
||
std::cout << std::endl;
|
||
|
||
// to be continued...
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<h3>Template Parameters</h3>
|
||
|
||
<table border>
|
||
<tr>
|
||
<th>Parameter
|
||
|
||
<th>Description
|
||
|
||
<tr>
|
||
<td><tt>BaseIterator</tt>
|
||
|
||
<td>The iterator type being wrapped. The <tt>value_type</tt>
|
||
of the base iterator should itself be dereferenceable.
|
||
The return type of the <tt>operator*</tt> for the
|
||
<tt>value_type</tt> should match the <tt>Reference</tt> type.
|
||
|
||
<tr>
|
||
<td><tt>Value</tt>
|
||
|
||
<td>The <tt>value_type</tt> of the resulting iterator, unless const. If
|
||
Value is <tt>const X</tt>, a conforming compiler makes the
|
||
<tt>value_type</tt> <tt><i>non-</i>const X</tt><a href=
|
||
"iterator_adaptors.htm#1">[1]</a>. Note that if the default
|
||
is used for <tt>Value</tt>, then there must be a valid specialization
|
||
of <tt>iterator_traits</tt> for the value type of the base iterator.
|
||
<br>
|
||
<b>Default:</b> <tt>std::iterator_traits<<br>
|
||
<20> std::iterator_traits<BaseIterator>::value_type
|
||
>::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> <tt>Value&</tt>
|
||
|
||
<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> <tt>Value*</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<BaseIterator>::iterator_category</tt>
|
||
|
||
</table>
|
||
|
||
<h3>Concept Model</h3>
|
||
The indirect iterator will model whichever <a href=
|
||
"http://www.sgi.com/tech/stl/Iterators.html">standard iterator
|
||
concept category</a> is modeled by the base iterator. Thus, if the
|
||
base iterator is a model of <a href=
|
||
"http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random
|
||
Access Iterator</a> then so is the resulting indirect iterator. If
|
||
the base iterator models a more restrictive concept, the resulting
|
||
indirect iterator will model the same concept <a href="#3">[3]</a>.
|
||
|
||
<h3>Members</h3>
|
||
The indirect iterator type implements the member functions and operators
|
||
required of the <a href=
|
||
"http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random Access
|
||
Iterator</a> concept. In addition it has the following constructor:
|
||
<pre>
|
||
explicit indirect_iterator_generator::type(const BaseIterator& it)
|
||
</pre>
|
||
<br>
|
||
<br>
|
||
|
||
<hr>
|
||
|
||
<p>
|
||
|
||
<h2><a name="indirect_iterator_pair_generator">The Indirect Iterator Pair
|
||
Generator</a></h2>
|
||
Sometimes a pair of <tt>const</tt>/non-<tt>const</tt> pair of iterators is
|
||
needed, such as when implementing a container. The
|
||
<tt>indirect_iterator_pair_generator</tt> class makes it more convenient to
|
||
create this pair of iterator types.
|
||
|
||
<blockquote>
|
||
<pre>
|
||
template <class BaseIterator,
|
||
class Value, class Pointer, class Reference,
|
||
class ConstPointer, class ConstReference>
|
||
class indirect_iterator_pair_generator
|
||
{
|
||
public:
|
||
typedef <tt><a href=
|
||
"./iterator_adaptors.htm#iterator_adaptor">iterator_adaptor</a><...></tt> iterator; // the mutable indirect iterator type
|
||
typedef <tt><a href=
|
||
"./iterator_adaptors.htm#iterator_adaptor">iterator_adaptor</a><...></tt> const_iterator; // the immutable indirect iterator type
|
||
};
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<h3>Example</h3>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
// continuing from the last example...
|
||
|
||
typedef boost::indirect_iterator_pair_generator<char**,
|
||
char, char*, char&, const char*, const char&> PairGen;
|
||
|
||
char mutable_characters[N];
|
||
char* pointers_to_mutable_chars[N];
|
||
for (int i = 0; i < N; ++i)
|
||
pointers_to_mutable_chars[i] = &mutable_characters[i];
|
||
|
||
PairGen::iterator mutable_indirect_first(pointers_to_mutable_chars),
|
||
mutable_indirect_last(pointers_to_mutable_chars + N);
|
||
PairGen::const_iterator const_indirect_first(pointers_to_chars),
|
||
const_indirect_last(pointers_to_chars + N);
|
||
|
||
std::transform(const_indirect_first, const_indirect_last,
|
||
mutable_indirect_first, std::bind1st(std::plus<char>(), 1));
|
||
|
||
std::copy(mutable_indirect_first, mutable_indirect_last,
|
||
std::ostream_iterator<char>(std::cout, ","));
|
||
std::cout << std::endl;
|
||
// to be continued...
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>The output is:
|
||
|
||
<blockquote>
|
||
<pre>
|
||
b,c,d,e,f,g,h,
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<h3>Template Parameters</h3>
|
||
|
||
<table border>
|
||
<tr>
|
||
<th>Parameter
|
||
|
||
<th>Description
|
||
|
||
<tr>
|
||
<td><tt>BaseIterator</tt>
|
||
|
||
<td>The iterator type being wrapped. The <tt>value_type</tt> of the
|
||
base iterator should itself be dereferenceable.
|
||
The return type of the <tt>operator*</tt> for the
|
||
<tt>value_type</tt> should match the <tt>Reference</tt> type.
|
||
|
||
<tr>
|
||
<td><tt>Value</tt>
|
||
|
||
<td>The <tt>value_type</tt> of the resulting iterators.
|
||
If Value is <tt>const X</tt>, a conforming compiler makes the
|
||
<tt>value_type</tt> <tt><i>non-</i>const X</tt><a href=
|
||
"iterator_adaptors.htm#1">[1]</a>. Note that if the default
|
||
is used for <tt>Value</tt>, then there must be a valid
|
||
specialization of <tt>iterator_traits</tt> for the value type
|
||
of the base iterator.<br>
|
||
|
||
<b>Default:</b> <tt>std::iterator_traits<<br>
|
||
<20> std::iterator_traits<BaseIterator>::value_type
|
||
>::value_type</tt><a href="#2">[2]</a>
|
||
|
||
<tr>
|
||
<td><tt>Reference</tt>
|
||
|
||
<td>The <tt>reference</tt> type of the resulting <tt>iterator</tt>, and
|
||
in particular, the result type of its <tt>operator*()</tt>.<br>
|
||
<b>Default:</b> <tt>Value&</tt>
|
||
|
||
<tr>
|
||
<td><tt>Pointer</tt>
|
||
|
||
<td>The <tt>pointer</tt> type of the resulting <tt>iterator</tt>, and
|
||
in particular, the result type of its <tt>operator->()</tt>.<br>
|
||
<b>Default:</b> <tt>Value*</tt>
|
||
|
||
<tr>
|
||
<td><tt>ConstReference</tt>
|
||
|
||
<td>The <tt>reference</tt> type of the resulting
|
||
<tt>const_iterator</tt>, and in particular, the result type of its
|
||
<tt>operator*()</tt>.<br>
|
||
<b>Default:</b> <tt>const Value&</tt>
|
||
|
||
<tr>
|
||
<td><tt>ConstPointer</tt>
|
||
|
||
<td>The <tt>pointer</tt> type of the resulting <tt>const_iterator</tt>,
|
||
and in particular, the result type of its <tt>operator->()</tt>.<br>
|
||
<b>Default:</b> <tt>const Value*</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<BaseIterator>::iterator_category</tt>
|
||
</table>
|
||
|
||
<h3>Concept Model</h3>
|
||
|
||
The indirect iterators will model whichever <a href=
|
||
"http://www.sgi.com/tech/stl/Iterators.html">standard iterator
|
||
concept category</a> is modeled by the base iterator. Thus, if the
|
||
base iterator is a model of <a href=
|
||
"http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random
|
||
Access Iterator</a> then so are the resulting indirect
|
||
iterators. If the base iterator models a more restrictive concept,
|
||
the resulting indirect iterators will model the same concept <a
|
||
href="#3">[3]</a>.
|
||
|
||
|
||
<h3>Members</h3>
|
||
The resulting <tt>iterator</tt> and <tt>const_iterator</tt> types implement
|
||
the member functions and operators required of the <a href=
|
||
"http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random Access
|
||
Iterator</a> concept. In addition they support the following constructors:
|
||
|
||
<blockquote>
|
||
<pre>
|
||
explicit indirect_iterator_pair_generator::iterator(const BaseIterator& it)
|
||
explicit indirect_iterator_pair_generator::const_iterator(const BaseIterator& it)
|
||
</pre>
|
||
</blockquote>
|
||
<br>
|
||
<br>
|
||
|
||
<hr>
|
||
|
||
<p>
|
||
|
||
<h2><a name="make_indirect_iterator">The Indirect Iterator Object
|
||
Generator</a></h2>
|
||
The <tt>make_indirect_iterator()</tt> function provides a more convenient
|
||
way to create indirect iterator objects. The function saves the user the
|
||
trouble of explicitly writing out the iterator types.
|
||
|
||
<blockquote>
|
||
<pre>
|
||
template <class BaseIterator>
|
||
typename indirect_iterator_generator<BaseIterator>::type
|
||
make_indirect_iterator(BaseIterator base)
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<h3>Example</h3>
|
||
Here we again print the <tt>char</tt>s from the array <tt>characters</tt>
|
||
by accessing them through the array of pointers <tt>pointer_to_chars</tt>,
|
||
but this time we use the <tt>make_indirect_iterator()</tt> function which
|
||
saves us some typing.
|
||
|
||
<blockquote>
|
||
<pre>
|
||
// continuing from the last example...
|
||
|
||
std::copy(boost::make_indirect_iterator(pointers_to_chars),
|
||
boost::make_indirect_iterator(pointers_to_chars + N),
|
||
std::ostream_iterator<char>(std::cout, ","));
|
||
std::cout << std::endl;
|
||
|
||
return 0;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
The output is:
|
||
|
||
<blockquote>
|
||
<pre>
|
||
a,b,c,d,e,f,g,
|
||
</pre>
|
||
</blockquote>
|
||
<hr>
|
||
|
||
<h3>Notes</h3>
|
||
|
||
<p>
|
||
|
||
<p><a name="2">[2]</a> If your compiler does not support partial
|
||
specialization and the base iterator or its <tt>value_type</tt> is a
|
||
builtin pointer type, you will not be able to use the default for
|
||
<tt>Value</tt> and will need to specify this type explicitly.
|
||
|
||
<p><a name="3">[3]</a>There is a caveat to which concept the
|
||
indirect iterator can model. If the return type of the
|
||
<tt>operator*</tt> for the base iterator's value type is not a
|
||
true reference, then strickly speaking, the indirect iterator can
|
||
not be a model of <a href=
|
||
"http://www.sgi.com/tech/stl/ForwardIterator.html">Forward
|
||
Iterator</a> or any of the concepts that refine it. In this case
|
||
the <tt>Category</tt> for the indirect iterator should be
|
||
specified as <tt>std::input_iterator_tag</tt>. However, even in
|
||
this case, if the base iterator is a random access iterator, the
|
||
resulting indirect iterator will still satisfy most of the
|
||
requirements for <a href=
|
||
"http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random
|
||
Access Iterator</a>.
|
||
|
||
<hr>
|
||
|
||
<p>Revised
|
||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %b %Y" startspan -->17 Aug 2001<!--webbot bot="Timestamp" endspan i-checksum="14763" -->
|
||
|
||
|
||
<p>© Copyright Jeremy Siek and David Abrahams 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.
|
||
<!-- LocalWords: html charset alt gif hpp BaseIterator const namespace struct
|
||
-->
|
||
|
||
<!-- LocalWords: ConstPointer ConstReference typename iostream int abcdefg
|
||
-->
|
||
<!-- LocalWords: sizeof PairGen pre Jeremy Siek David Abrahams
|
||
-->
|
||
|
||
|
||
</body>
|
||
</html>
|