mirror of
https://github.com/boostorg/utility.git
synced 2025-05-08 18:34:02 +00:00
190 lines
6.0 KiB
HTML
190 lines
6.0 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 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 <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>
|
|
|
|
<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 <class AdaptableUnaryFunction, class Iterator>
|
|
class transform_iterator_generator
|
|
{
|
|
public:
|
|
typedef <a href="./iterator_adaptor.htm">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.
|
|
|
|
<p>
|
|
<PRE>
|
|
#include <functional>
|
|
#include <iostream>
|
|
#include <boost/iterator_adaptors.hpp>
|
|
|
|
int
|
|
main(int, char*[])
|
|
{
|
|
int x[] = { 1, 2, 3, 4, 5, 6, 7, 8 };
|
|
|
|
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 + sizeof(x)/sizeof(int), 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;
|
|
|
|
// 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& it, const AdaptableUnaryFunction& f = AdaptableUnaryFunction())</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<p>
|
|
|
|
|
|
<h2><a name="make_transform_iterator">The Make Transform Iterator Function</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, 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.
|