mirror of
https://github.com/boostorg/utility.git
synced 2025-05-09 23:14:02 +00:00
333 lines
11 KiB
HTML
333 lines
11 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>Shared Container Iterator 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>Shared Container Iterator</h1>
|
||
|
||
Defined in header
|
||
<a href="../../boost/shared_container_iterator.hpp">boost/shared_container_iterator.hpp</a>
|
||
|
||
<p>
|
||
The purpose of the shared container iterator is to attach the lifetime
|
||
of a container to the lifetime of its iterators. In other words,
|
||
the container will be deleted after the last iterator is destroyed.
|
||
The shared container iterator is typically used to implement functions
|
||
that return iterators over a
|
||
range of objects that will only be needed for the lifetime of
|
||
the iterators. By returning a pair of shared iterators from a
|
||
function, the callee can ensure that the underlying container's
|
||
lifetime will be properly managed.
|
||
<p>
|
||
The shared container iterator augments an iterator into a shared
|
||
container with a reference counted pointer to the container.
|
||
Assuming no other references exist to the container, it will be
|
||
destroyed when the last shared container iterator is destroyed.
|
||
In all other ways, the shared container iterator
|
||
behaves the same as its base iterator.
|
||
|
||
|
||
<h2>Synopsis</h2>
|
||
|
||
<pre>
|
||
namespace boost {
|
||
template <typename <a href="http://www.sgi.com/tech/stl/Container.html">Container</a>>
|
||
class shared_container_iterator_generator;
|
||
|
||
template <typename <a href="http://www.sgi.com/tech/stl/Container.html">Container</a>>
|
||
typename shared_container_iterator_generator<Container>::type
|
||
make_shared_container_iterator(typename Container::iterator base,
|
||
boost::shared_ptr<Container> const& container);
|
||
|
||
std::pair<
|
||
typename shared_container_iterator_generator<Container>::type,
|
||
typename shared_container_iterator_generator<Container>::type
|
||
>
|
||
make_shared_container_range(boost::shared_ptr<Container> const& container);
|
||
|
||
}
|
||
</pre>
|
||
|
||
<hr>
|
||
|
||
<h2><a name="generator">The Shared Container Iterator Type Generator</a></h2>
|
||
|
||
The class <tt>shared_container_iterator_generator</tt> is a helper
|
||
class to construct a shared container iterator type. The template
|
||
parameter for this class is a type that models the
|
||
<a href="http://www.sgi.com/tech/stl/Container.html">Container</a>
|
||
concept.
|
||
|
||
<pre>
|
||
template <typename Container>
|
||
class shared_container_iterator_generator
|
||
{
|
||
public:
|
||
typedef <a href="./iterator_adaptors.htm#iterator_adaptor">iterator_adaptor</a><...> type;
|
||
};
|
||
</pre>
|
||
|
||
<h3>Example</h3>
|
||
|
||
<p>
|
||
The following example illustrates how to use the
|
||
<tt>shared_counter_iterator_generator</tt> to create an iterator that
|
||
regulates the lifetime of a reference counted <tt>std::vector</tt>.
|
||
Though the original <tt>shared_ptr</tt> to the vector ceases to exist, the
|
||
<tt>shared_counter_iterator</tt>s extend the lifetime of the container.
|
||
<p>
|
||
<a href="./shared_iterator_example1.cpp">shared_iterator_example1.cpp</a>:
|
||
<PRE>
|
||
<font color="#008040">#include "shared_container_iterator.hpp"</font>
|
||
<font color="#008040">#include "boost/shared_ptr.hpp"</font>
|
||
<font color="#008040">#include <algorithm></font>
|
||
<font color="#008040">#include <iostream></font>
|
||
<font color="#008040">#include <vector></font>
|
||
|
||
<B>typedef</B> boost::shared_container_iterator_generator< std::vector<<B>int</B>> >::type iterator;
|
||
|
||
|
||
<B>void</B> set_range(iterator& i, iterator& end) {
|
||
|
||
boost::shared_ptr< std::vector<<B>int</B>> > ints(<B>new</B> std::vector<<B>int</B>>());
|
||
|
||
ints->push_back(<font color="#0000A0">0</font>);
|
||
ints->push_back(<font color="#0000A0">1</font>);
|
||
ints->push_back(<font color="#0000A0">2</font>);
|
||
ints->push_back(<font color="#0000A0">3</font>);
|
||
ints->push_back(<font color="#0000A0">4</font>);
|
||
ints->push_back(<font color="#0000A0">5</font>);
|
||
|
||
i = iterator(ints->begin(),ints);
|
||
end = iterator(ints->end(),ints);
|
||
}
|
||
|
||
|
||
<B>int</B> main() {
|
||
|
||
iterator i,end;
|
||
|
||
set_range(i,end);
|
||
|
||
std::copy(i,end,std::ostream_iterator<<B>int</B>>(std::cout,<font color="#0000FF">","</font>));
|
||
std::cout.put(<font color="#0000FF">'\n'</font>);
|
||
|
||
<B>return</B> <font color="#0000A0">0</font>;
|
||
}
|
||
</PRE>
|
||
|
||
The output from this part is:
|
||
<pre>
|
||
0,1,2,3,4,5,
|
||
</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/Container.html"><tt>Container</tt></a></TD>
|
||
<TD>The type of the container that we wish to iterate over. It must be
|
||
a model of the
|
||
<a href="http://www.sgi.com/tech/stl/Container.html"><tt>Container</tt></a>
|
||
concept.
|
||
</TD>
|
||
</TR>
|
||
</Table>
|
||
|
||
<h3>Model of</h3>
|
||
|
||
The shared container iterator adaptor (the type
|
||
<tt>shared_container_iterator_generator<...>::type</tt>) models the
|
||
same iterator concept as the base iterator
|
||
(<tt>Container::iterator</tt>) up to
|
||
<a href="http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random
|
||
Access Iterator</a>.
|
||
|
||
<h3>Members</h3>
|
||
|
||
The shared container 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, though only operations defined for the base iterator will be valid.
|
||
In addition it has the following constructor:
|
||
|
||
<pre>
|
||
shared_container_iterator_generator::type(Container::iterator const& it,
|
||
boost::shared_ptr<Container> const& container)
|
||
</pre>
|
||
|
||
<p>
|
||
<hr>
|
||
<p>
|
||
|
||
|
||
<h2><a name="make_iterator">The Shared Container Iterator Object Generator</a></h2>
|
||
|
||
<pre>
|
||
template <typename Container>
|
||
typename shared_container_iterator_generator<AdaptableUnaryFunction,BaseIterator>::type
|
||
make_shared_container_iterator(Container::iterator base,
|
||
boost::shared_ptr<Container> const& container)
|
||
</pre>
|
||
|
||
This function provides an alternative to using the shared container
|
||
iterator type generator to create the iterator type before
|
||
construction. Using the object generator, a shared container iterator
|
||
can be created and passed to a function without explicitly specifying
|
||
its type.
|
||
|
||
<h3>Example</h3>
|
||
|
||
This example, similar to the previous, uses
|
||
<tt>make_shared_container_iterator()</tt> to create the iterators.
|
||
|
||
<p>
|
||
<a href="./shared_iterator_example2.cpp">shared_iterator_example2.cpp</a>:
|
||
|
||
<PRE>
|
||
<font color="#008040">#include "shared_container_iterator.hpp"</font>
|
||
<font color="#008040">#include "boost/shared_ptr.hpp"</font>
|
||
<font color="#008040">#include <algorithm></font>
|
||
<font color="#008040">#include <iterator></font>
|
||
<font color="#008040">#include <iostream></font>
|
||
<font color="#008040">#include <vector></font>
|
||
|
||
|
||
<B>template</B> <<B>typename</B> Iterator>
|
||
<B>void</B> print_range_nl (Iterator begin, Iterator end) {
|
||
<B>typedef</B> <B>typename</B> std::iterator_traits<Iterator>::value_type val;
|
||
std::copy(begin,end,std::ostream_iterator<val>(std::cout,<font color="#0000FF">","</font>));
|
||
std::cout.put(<font color="#0000FF">'\n'</font>);
|
||
}
|
||
|
||
|
||
<B>int</B> main() {
|
||
|
||
<B>typedef</B> boost::shared_ptr< std::vector<<B>int</B>> > ints_t;
|
||
{
|
||
ints_t ints(<B>new</B> std::vector<<B>int</B>>());
|
||
|
||
ints->push_back(<font color="#0000A0">0</font>);
|
||
ints->push_back(<font color="#0000A0">1</font>);
|
||
ints->push_back(<font color="#0000A0">2</font>);
|
||
ints->push_back(<font color="#0000A0">3</font>);
|
||
ints->push_back(<font color="#0000A0">4</font>);
|
||
ints->push_back(<font color="#0000A0">5</font>);
|
||
|
||
print_range_nl(boost::make_shared_container_iterator(ints->begin(),ints),
|
||
boost::make_shared_container_iterator(ints->end(),ints));
|
||
}
|
||
|
||
|
||
|
||
<B>return</B> <font color="#0000A0">0</font>;
|
||
}
|
||
</PRE>
|
||
|
||
Observe that the <tt>shared_container_iterator</tt> type is never
|
||
explicitly named. The output from this example is the same as the previous.
|
||
|
||
<h2><a name="make_range">The Shared Container Iterator Range Generator</a></h2>
|
||
|
||
<pre>
|
||
template <typename Container>
|
||
std::pair<
|
||
typename shared_container_iterator_generator<Container>::type,
|
||
typename shared_container_iterator_generator<Container>::type
|
||
>
|
||
make_shared_container_range(boost::shared_ptr<Container> const& container);
|
||
</pre>
|
||
|
||
Class <tt>shared_container_iterator</tt> is meant primarily to return
|
||
via iterators a range of values that we can guarantee will be alive as
|
||
long as the iterators are. This is a convenience
|
||
function to do just that. This function is equivalent to
|
||
|
||
<pre>
|
||
std::make_pair(make_shared_container_iterator(container->begin(),container),
|
||
make_shared_container_iterator(container->end(),container));
|
||
</pre>
|
||
|
||
<h3>Example</h3>
|
||
|
||
In the following example, a range of values is returned as a pair of
|
||
<tt>shared_container_iterator</tt>s.
|
||
|
||
|
||
<p>
|
||
<a href="./shared_iterator_example3.cpp">shared_iterator_example3.cpp</a>:
|
||
|
||
<PRE>
|
||
<font color="#008040">#include "shared_container_iterator.hpp"</font>
|
||
<font color="#008040">#include "boost/shared_ptr.hpp"</font>
|
||
<font color="#008040">#include "boost/tuple/tuple.hpp" // for boost::tie</font>
|
||
<font color="#008040">#include <algorithm> // for std::copy</font>
|
||
<font color="#008040">#include <iostream> </font>
|
||
<font color="#008040">#include <vector></font>
|
||
|
||
|
||
<B>typedef</B> boost::shared_container_iterator_generator< std::vector<<B>int</B>> >::type
|
||
function_iterator;
|
||
|
||
std::pair<function_iterator,function_iterator>
|
||
return_range() {
|
||
boost::shared_ptr< std::vector<<B>int</B>> > range(<B>new</B> std::vector<<B>int</B>>());
|
||
range->push_back(<font color="#0000A0">0</font>);
|
||
range->push_back(<font color="#0000A0">1</font>);
|
||
range->push_back(<font color="#0000A0">2</font>);
|
||
range->push_back(<font color="#0000A0">3</font>);
|
||
range->push_back(<font color="#0000A0">4</font>);
|
||
range->push_back(<font color="#0000A0">5</font>);
|
||
<B>return</B> boost::make_shared_container_range(range);
|
||
}
|
||
|
||
|
||
<B>int</B> main() {
|
||
|
||
|
||
function_iterator i,end;
|
||
|
||
boost::tie(i,end) = return_range();
|
||
|
||
std::copy(i,end,std::ostream_iterator<<B>int</B>>(std::cout,<font color="#0000FF">","</font>));
|
||
std::cout.put(<font color="#0000FF">'\n'</font>);
|
||
|
||
<B>return</B> <font color="#0000A0">0</font>;
|
||
}
|
||
</PRE>
|
||
|
||
Though the <tt>range</tt> object only lives for the duration of the
|
||
<tt>return_range</tt> call, the reference counted
|
||
<tt>std::vector</tt> will live until <tt>i</tt> and <tt>end</tt>
|
||
are both destroyed. The output from this example is the same as
|
||
the previous two.
|
||
|
||
|
||
<hr>
|
||
<!-- hhmts start -->
|
||
Last modified: Wed Sep 4 15:52:17 EST 2002
|
||
<!-- hhmts end -->
|
||
<p><EFBFBD> Copyright Ronald Garcia 2002. 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>
|