mirror of
https://github.com/boostorg/utility.git
synced 2025-05-09 15:04:00 +00:00
50bc75a802
(I left out the changes to the hash library). Merged via svnmerge from https://svn.boost.org/svn/boost/trunk ................ r44807 | danieljames | 2008-04-27 08:39:49 +0100 (Sun, 27 Apr 2008) | 78 lines Merge in documentation fixes. Apart from the change to optional's documenation Jamfile, which I included by mistake. I wrote about this at: http://lists.boost.org/Archives/boost/2008/04/136405.php Merged revisions 44585-44806 via svnmerge from https://svn.boost.org/svn/boost/branches/doc ........ r44585 | danieljames | 2008-04-19 16:25:27 +0100 (Sat, 19 Apr 2008) | 2 lines Fix broken link to vacpp in bjam docs. ........ r44586 | danieljames | 2008-04-19 16:27:36 +0100 (Sat, 19 Apr 2008) | 2 lines Fix broken link to bcpp in bjam docs. ........ r44587 | danieljames | 2008-04-19 16:33:58 +0100 (Sat, 19 Apr 2008) | 2 lines DateTime documentation - Fix a link to the serialization library. ........ r44588 | danieljames | 2008-04-19 16:35:36 +0100 (Sat, 19 Apr 2008) | 2 lines Fix some links in interprocess & intrusive. ........ r44589 | danieljames | 2008-04-19 16:37:39 +0100 (Sat, 19 Apr 2008) | 2 lines Fix some links in the python docs. ........ r44590 | danieljames | 2008-04-19 16:38:29 +0100 (Sat, 19 Apr 2008) | 2 lines Work around a quickbook bug which is affecting the python docs. ........ r44591 | danieljames | 2008-04-19 16:39:34 +0100 (Sat, 19 Apr 2008) | 2 lines Fix a broken link in the numeric conversion docs. ........ r44592 | danieljames | 2008-04-19 16:40:45 +0100 (Sat, 19 Apr 2008) | 2 lines Fix some links in the optional docs. ........ r44593 | danieljames | 2008-04-19 16:42:09 +0100 (Sat, 19 Apr 2008) | 2 lines Fix link to the hash documentation from bimap. ........ r44599 | danieljames | 2008-04-19 18:07:33 +0100 (Sat, 19 Apr 2008) | 2 lines Fix a typo in the format library. ........ r44600 | danieljames | 2008-04-19 19:20:59 +0100 (Sat, 19 Apr 2008) | 1 line Initialise svnmerge. ........ r44641 | danieljames | 2008-04-20 18:59:47 +0100 (Sun, 20 Apr 2008) | 2 lines Fix the lincense url in shared container iterator documentation. ........ r44642 | danieljames | 2008-04-20 19:00:00 +0100 (Sun, 20 Apr 2008) | 2 lines Fix image link in the mpi documentation. ........ r44643 | danieljames | 2008-04-20 19:00:11 +0100 (Sun, 20 Apr 2008) | 2 lines Fix a typo in the spirit docs. ........ r44644 | danieljames | 2008-04-20 19:00:23 +0100 (Sun, 20 Apr 2008) | 2 lines Escape the slash so that quickbook doesn't think it the start of an italic section, and mess up the link. Refs #1844 ........ r44647 | danieljames | 2008-04-20 19:39:47 +0100 (Sun, 20 Apr 2008) | 2 lines Fix another typo in spirit docs. ........ ................ r45232 | danieljames | 2008-05-08 22:50:19 +0100 (Thu, 08 May 2008) | 1 line Fix some invalid xml by replacing ampersands with character entities. ................ r45576 | danieljames | 2008-05-20 16:39:25 +0100 (Tue, 20 May 2008) | 20 lines Merge some small documentation fixes from the doc branch, and mark some previously merged changes as merged. Merged revisions 44811,45129,45142,45154,45281-45282,45365 via svnmerge from https://svn.boost.org/svn/boost/branches/doc ........ r45129 | danieljames | 2008-05-05 12:36:50 +0100 (Mon, 05 May 2008) | 2 lines Update navbar links in boostbook. ........ r45282 | danieljames | 2008-05-11 14:15:31 +0100 (Sun, 11 May 2008) | 2 lines Group functions in the hash header - requires Frank's free-function-group fix. (not included in release branch). ........ r45365 | danieljames | 2008-05-14 21:39:00 +0100 (Wed, 14 May 2008) | 2 lines Add boost.root to standalone hash documentation. (not included in release branch). ........ ................ [SVN r45622]
323 lines
10 KiB
HTML
323 lines
10 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="../../boost.png" alt="boost.png (6897 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 not be deleted until after all its iterators are
|
||
destroyed. The shared container iterator is typically used to
|
||
implement functions that return iterators over a range of objects that
|
||
only need to exist for the lifetime of the iterators. By returning a
|
||
pair of shared iterators from a function, the callee can return a
|
||
heap-allocated range of objects whose lifetime is automatically managed.
|
||
<p>
|
||
The shared container iterator augments an iterator over a shared
|
||
container. It maintains a reference count on the shared
|
||
container. If only shared container iterators hold references to
|
||
the container, the container's lifetime will end when the last shared
|
||
container iterator over it is destroyed. In any case, the shared
|
||
container is guaranteed to persist beyond the lifetime of all
|
||
the iterators. 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;
|
||
|
||
template <typename <a href="http://www.sgi.com/tech/stl/Container.html">Container</a>>
|
||
shared_container_iterator<Container>
|
||
make_shared_container_iterator(typename Container::iterator base,
|
||
boost::shared_ptr<Container> const& container);
|
||
|
||
std::pair<
|
||
typename shared_container_iterator<Container>,
|
||
typename shared_container_iterator<Container>
|
||
>
|
||
make_shared_container_range(boost::shared_ptr<Container> const& container);
|
||
}
|
||
</pre>
|
||
|
||
<hr>
|
||
|
||
<h2><a name="generator">The Shared Container Iterator Type</a></h2>
|
||
|
||
<pre>
|
||
template <typename Container> class shared_container_iterator;
|
||
</pre>
|
||
|
||
The class template <tt>shared_container_iterator</tt>
|
||
is the shared container iterator type. The <tt>Container</tt> template
|
||
type argument must model the
|
||
<a href="http://www.sgi.com/tech/stl/Container.html">Container</a>
|
||
concept.
|
||
|
||
<h3>Example</h3>
|
||
|
||
<p>
|
||
The following example illustrates how to create an iterator that
|
||
regulates the lifetime of a reference counted <tt>std::vector</tt>.
|
||
Though the original shared pointer <tt>ints</tt> ceases to exist
|
||
after <tt>set_range()</tt> returns, the
|
||
<tt>shared_counter_iterator</tt> objects maintain references to the
|
||
underlying vector and thereby extend the container's lifetime.
|
||
<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< std::vector<<B>int</B>> > 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 <tt>shared_container_iterator<Container></tt> type models the
|
||
same iterator concept as the base iterator
|
||
(<tt>Container::iterator</tt>).
|
||
|
||
<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(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>
|
||
shared_container_iterator<Container>
|
||
make_shared_container_iterator(Container::iterator base,
|
||
boost::shared_ptr<Container> const& container)
|
||
</pre>
|
||
|
||
This function provides an alternative to directly constructing a
|
||
shared container iterator. 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<
|
||
shared_container_iterator<Container>,
|
||
shared_container_iterator<Container>
|
||
>
|
||
make_shared_container_range(boost::shared_ptr<Container> const& container);
|
||
</pre>
|
||
|
||
Class <tt>shared_container_iterator</tt> is meant primarily to return,
|
||
using 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. It 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> objects.
|
||
|
||
|
||
<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< std::vector<<B>int</B>> > iterator;
|
||
|
||
std::pair<iterator,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() {
|
||
|
||
|
||
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: Mon Aug 11 11:27:03 EST 2003
|
||
<!-- hhmts end -->
|
||
<p><EFBFBD> Copyright 2003 The Trustees of Indiana University.
|
||
Use, modification and distribution is subject to the Boost Software
|
||
License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
|
||
http://www.boost.org/LICENSE_1_0.txt)</p>
|
||
|
||
</body>
|
||
|
||
</html>
|