boost_mirror/utility
1
0
Fork 0
mirror of https://github.com/boostorg/utility.git synced 2025-05-08 18:34:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

new files

Browse Source 
[SVN r9109]
This commit is contained in:
Jeremy Siek 2001-02-11 05:25:19 +00:00
parent 5c6dd2f172
commit 8935232248
2 changed files with 233 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

189
transform_iterator.htm Normal file
View File

@ -0,0 +1,189 @@
<html>
<head>
<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>Transform 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>Transform Iterator Adaptor</h1>
Defined in header
<a href="../../boost/iterator_adaptors.hpp">boost/iterator_adaptors.hpp</a>
<p>
The transform iterator adaptor augments an iterator by applying some
function object to the result of dereferencing the iterator. Another
words, the <tt>operator*</tt> of the transform iterator first
dereferences the base iterator, passes the result of this to the
function object, and then returns the result. The following
<b>pseudo-code</b> shows the basic idea:
<pre>
value_type transform_iterator::operator*() const {
return f(*this->base_iterator);
}
</pre>
All of the other operators of the transform iterator behave in the
same fashion as the base iterator.
<h2>Synopsis</h2>
<pre>
namespace boost {
template &lt;class <a href="http://www.sgi.com/tech/stl/AdaptableUnaryFunction.html">AdaptableUnaryFunction</a>, class BaseIterator&gt;
class transform_iterator_generator;
template &lt;class <a href="http://www.sgi.com/tech/stl/AdaptableUnaryFunction.html">AdaptableUnaryFunction</a>, class BaseIterator&gt;
typename transform_iterator_generator&lt;AdaptableUnaryFunction,Iterator&gt;::type
make_transform_iterator(BaseIterator base, const AdaptableUnaryFunction&amp; f = AdaptableUnaryFunction());
}
</pre>
<h2><a name="transform_iterator_generator">The Transform Iterator Type
Generator</a></h2>
The class <tt>transform_iterator_generator</tt> is a helper class who's
purpose is to construct a transform iterator type. The template
parameters for this class are the <tt>AdaptableUnaryFunction</tt> function object
type and the <tt>BaseIterator</tt> type that is being wrapped.
<pre>
template &lt;class AdaptableUnaryFunction, class Iterator&gt;
class transform_iterator_generator
{
public:
typedef <a href="./iterator_adaptor.htm">iterator_adaptor</a>&lt;...&gt; type;
};
</pre>
<h3>Example</h3>
<p>
The following is an example of how to use the
<tt>transform_iterator_generator</tt> class to iterate through a range of
numbers, multiplying each of them by 2 when they are dereferenced.
<p>
<PRE>
#include &lt;functional&gt;
#include &lt;iostream&gt;
#include &lt;boost/iterator_adaptors.hpp&gt;
int
main(int, char*[])
{
int x[] = { 1, 2, 3, 4, 5, 6, 7, 8 };
typedef std::binder1st&lt; std::multiplies&lt;int&gt; &gt; Function;
typedef boost::transform_iterator_generator&lt;Function, int*&gt;::type doubling_iterator;
doubling_iterator i(x, std::bind1st(std::multiplies&lt;int&gt;(), 2)),
i_end(x + sizeof(x)/sizeof(int), std::bind1st(std::multiplies&lt;int&gt;(), 2));
std::cout &lt;&lt; "multiplying the array by 2:" &lt;&lt; std::endl;
while (i != i_end)
std::cout &lt;&lt; *i++ &lt;&lt; " ";
std::cout &lt;&lt; std::endl;
// to be continued...
</PRE>
The output from this part is:
<pre>
2 4 6 8 10 12 14 16
</pre>
<h3>Template Parameters</h3>
<Table border>
<TR>
<TH>Parameter</TH><TH>Description</TH>
</TR>
<TR>
<TD><a href="http://www.sgi.com/tech/stl/AdaptableUnaryFunction.html"><tt>AdaptableUnaryFunction</tt></a></TD>
<TD>The function object that transforms each element in the iterator range.
</TR>
<TR>
<TD><tt>BaseIterator</tt></TD>
<TD>The iterator type being wrapped. This type must at least be a model
of the <a href="http://www.sgi.com/tech/stl/InputIterator">InputIterator</a> concept.</TD>
</TR>
</Table>
<h3>Model of</h3>
The transform iterator adaptor (the type
<tt>transform_iterator_generator<...>::type</tt>) is a model of <a
href="www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a><a href="#1">[1]</a>.
<h3>Members</h3>
The transform 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, except that the <tt>reference</tt> type is the same as the <tt>value_type</tt>
so <tt>operator*()</tt> returns by-value. In addition it has the following constructor:
<pre>transform_iterator_generator::type(const BaseIterator&amp; it, const AdaptableUnaryFunction&amp; f = AdaptableUnaryFunction())</pre>
<p>
<hr>
<p>
<h2><a name="make_transform_iterator">The Make Transform Iterator Function</a></h2>
<pre>
template &lt;class AdaptableUnaryFunction, class BaseIterator&gt;
typename transform_iterator_generator&lt;AdaptableUnaryFunction,BaseIterator&gt;::type
make_transform_iterator(BaseIterator base, const AdaptableUnaryFunction&amp; f = AdaptableUnaryFunction());
</pre>
This function provides a convenient way to create transform iterators.
<h3>Example</h3>
Continuing from the previous example, we use the <tt>make_transform_iterator()</tt>
function to add four to each element of the array.
<pre>
std::cout << "adding 4 to each element in the array:" << std::endl;
std::copy(boost::make_transform_iterator(x, std::bind1st(std::plus<int>(), 4)),
boost::make_transform_iterator(x + N, std::bind1st(std::plus<int>(), 4)),
std::ostream_iterator<int>(std::cout, " "));
std::cout << std::endl;
return 0;
}
</pre>
The output from this part is:
<pre>
5 6 7 8 9 10 11 12
</pre>
<h3>Notes</h3>
<a name="1">[1]</a> If the base iterator is a model of <a
href="http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random Access Iterator</a>
then the transform iterator will also suppport most of the
functionality required by the Random Access Iterator concept. However, a
transform iterator can never completely satisfy the requirements for
<a
href="http://www.sgi.com/tech/stl/ForwardIterator.html">Forward Iterator</a>
(or of any concepts that refine Forward Iterator, which includes
Random Access Iterator and Bidirectional Iterator) since the <tt>operator*</tt> of the transform
iterator always returns by-value.

44
transform_iterator_example.cpp Normal file
View File

@ -0,0 +1,44 @@
// (C) Copyright Jeremy Siek 2000. Permission to copy, use, modify, sell and
// distribute this software is granted provided this copyright notice appears
// in all copies. This software is provided "as is" without express or implied
// warranty, and with no claim as to its suitability for any purpose.
#include <functional>
#include <algorithm>
#include <iostream>
#include <boost/iterator_adaptors.hpp>
int
main(int, char*[])
{
// This is a simple example of using the transform_iterators class to
// generate iterators that multiply the value returned by dereferencing
// the iterator. In this case we are multiplying by 2.
// Would be cooler to use lambda library in this example.
int x[] = { 1, 2, 3, 4, 5, 6, 7, 8 };
const int N = sizeof(x)/sizeof(int);
typedef std::binder1st< std::multiplies<int> > Function;
typedef boost::transform_iterator_generator<Function, int*>::type doubling_iterator;
doubling_iterator i(x, std::bind1st(std::multiplies<int>(), 2)),
i_end(x + N, std::bind1st(std::multiplies<int>(), 2));
std::cout << "multiplying the array by 2:" << std::endl;
while (i != i_end)
std::cout << *i++ << " ";
std::cout << std::endl;
std::cout << "adding 4 to each element in the array:" << std::endl;
std::copy(boost::make_transform_iterator(x, std::bind1st(std::plus<int>(), 4)),
boost::make_transform_iterator(x + N, std::bind1st(std::plus<int>(), 4)),
std::ostream_iterator<int>(std::cout, " "));
std::cout << std::endl;
return 0;
}