mirror of
https://github.com/boostorg/utility.git
synced 2025-05-08 18:34:02 +00:00
224 lines
7.3 KiB
HTML
224 lines
7.3 KiB
HTML
<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 this->f(*this->base_iterator);
|
||
}
|
||
</pre>
|
||
|
||
All of the other operators of the transform iterator behave in the
|
||
same fashion as those of the base iterator.
|
||
|
||
|
||
<h2>Synopsis</h2>
|
||
|
||
<pre>
|
||
namespace boost {
|
||
template <class <a href="http://www.sgi.com/tech/stl/AdaptableUnaryFunction.html">AdaptableUnaryFunction</a>, class BaseIterator>
|
||
class transform_iterator_generator;
|
||
|
||
template <class <a href="http://www.sgi.com/tech/stl/AdaptableUnaryFunction.html">AdaptableUnaryFunction</a>, class BaseIterator>
|
||
typename transform_iterator_generator<AdaptableUnaryFunction,Iterator>::type
|
||
make_transform_iterator(BaseIterator base, const AdaptableUnaryFunction& f = AdaptableUnaryFunction());
|
||
}
|
||
</pre>
|
||
|
||
<hr>
|
||
|
||
<h2><a name="transform_iterator_generator">The Transform Iterator Type
|
||
Generator</a></h2>
|
||
|
||
The class <tt>transform_iterator_generator</tt> is a helper class whose
|
||
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 <class AdaptableUnaryFunction, class Iterator>
|
||
class transform_iterator_generator
|
||
{
|
||
public:
|
||
typedef <a href="./iterator_adaptors.htm#iterator_adaptor">iterator_adaptor</a><...> 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.
|
||
The <tt>boost::binder1st</tt> class is used instead of the standard
|
||
one because tranform iterator requires the function object to be
|
||
Default Constructible.
|
||
|
||
<p>
|
||
<PRE>
|
||
#include <functional>
|
||
#include <iostream>
|
||
#include <boost/iterator_adaptors.hpp>
|
||
|
||
// definition of class boost::binder1st and function boost::bind1st() ...
|
||
|
||
int
|
||
main(int, char*[])
|
||
{
|
||
int x[] = { 1, 2, 3, 4, 5, 6, 7, 8 };
|
||
|
||
typedef boost::binder1st< std::multiplies<int> > Function;
|
||
typedef boost::transform_iterator_generator<Function, int*>::type doubling_iterator;
|
||
|
||
doubling_iterator i(x, boost::bind1st(std::multiplies<int>(), 2)),
|
||
i_end(x + sizeof(x)/sizeof(int), boost::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;
|
||
|
||
// 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. The <tt>argument_type</tt> of the function object must match
|
||
the value type of the base iterator. The <tt>result_type</tt> of the
|
||
function object will be the resulting iterator's
|
||
<tt>value_type</tt>. If you want the resulting iterator to behave as
|
||
an iterator, the result of the function should be solely a function of
|
||
its argument. Also, the function object must be <a
|
||
href="http://www.sgi.com/tech/stl/DefaultConstructible.html"> Default
|
||
Constructible</a> (which many of the standard function objects are not).</TD>
|
||
</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="http://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& it,
|
||
const AdaptableUnaryFunction& f = AdaptableUnaryFunction())
|
||
</pre>
|
||
|
||
<p>
|
||
<hr>
|
||
<p>
|
||
|
||
|
||
<h2><a name="make_transform_iterator">The Transform Iterator Object Generator</a></h2>
|
||
|
||
<pre>
|
||
template <class AdaptableUnaryFunction, class BaseIterator>
|
||
typename transform_iterator_generator<AdaptableUnaryFunction,BaseIterator>::type
|
||
make_transform_iterator(BaseIterator base,
|
||
const AdaptableUnaryFunction& 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, boost::bind1st(std::plus<int>(), 4)),
|
||
boost::make_transform_iterator(x + N, boost::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.
|
||
|
||
|
||
|
||
<hr>
|
||
<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %b %Y" startspan -->19 Aug 2001<!--webbot bot="Timestamp" endspan i-checksum="14767" --></p>
|
||
<p><EFBFBD> Copyright Jeremy Siek 2000. 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.</p>
|
||
|
||
</body>
|
||
|
||
</html>
|