mirror of
https://github.com/boostorg/utility.git
synced 2025-07-29 20:37:32 +02:00
Remove shared_iterator files (they're in Iterator now)
This commit is contained in:
Peter Dimov
@ -1,322 +0,0 @@
|
||||
<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>
|
||||
@ -1,42 +0,0 @@
|
||||
// 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)
|
||||
|
||||
#include "boost/shared_container_iterator.hpp"
|
||||
#include "boost/shared_ptr.hpp"
|
||||
#include <algorithm>
|
||||
#include <iostream>
|
||||
#include <vector>
|
||||
|
||||
typedef boost::shared_container_iterator< std::vector<int> > iterator;
|
||||
|
||||
|
||||
void set_range(iterator& i, iterator& end) {
|
||||
|
||||
boost::shared_ptr< std::vector<int> > ints(new std::vector<int>());
|
||||
|
||||
ints->push_back(0);
|
||||
ints->push_back(1);
|
||||
ints->push_back(2);
|
||||
ints->push_back(3);
|
||||
ints->push_back(4);
|
||||
ints->push_back(5);
|
||||
|
||||
i = iterator(ints->begin(),ints);
|
||||
end = iterator(ints->end(),ints);
|
||||
}
|
||||
|
||||
|
||||
int main() {
|
||||
|
||||
iterator i,end;
|
||||
|
||||
set_range(i,end);
|
||||
|
||||
std::copy(i,end,std::ostream_iterator<int>(std::cout,","));
|
||||
std::cout.put('\n');
|
||||
|
||||
return 0;
|
||||
}
|
||||
@ -1,43 +0,0 @@
|
||||
// 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)
|
||||
|
||||
#include "boost/shared_container_iterator.hpp"
|
||||
#include "boost/shared_ptr.hpp"
|
||||
#include <algorithm>
|
||||
#include <iterator>
|
||||
#include <iostream>
|
||||
#include <vector>
|
||||
|
||||
|
||||
template <typename Iterator>
|
||||
void print_range_nl (Iterator begin, Iterator end) {
|
||||
typedef typename std::iterator_traits<Iterator>::value_type val;
|
||||
std::copy(begin,end,std::ostream_iterator<val>(std::cout,","));
|
||||
std::cout.put('\n');
|
||||
}
|
||||
|
||||
|
||||
int main() {
|
||||
|
||||
typedef boost::shared_ptr< std::vector<int> > ints_t;
|
||||
{
|
||||
ints_t ints(new std::vector<int>());
|
||||
|
||||
ints->push_back(0);
|
||||
ints->push_back(1);
|
||||
ints->push_back(2);
|
||||
ints->push_back(3);
|
||||
ints->push_back(4);
|
||||
ints->push_back(5);
|
||||
|
||||
print_range_nl(boost::make_shared_container_iterator(ints->begin(),ints),
|
||||
boost::make_shared_container_iterator(ints->end(),ints));
|
||||
}
|
||||
|
||||
|
||||
|
||||
return 0;
|
||||
}
|
||||
@ -1,41 +0,0 @@
|
||||
// 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)
|
||||
|
||||
#include "boost/shared_container_iterator.hpp"
|
||||
#include "boost/shared_ptr.hpp"
|
||||
#include "boost/tuple/tuple.hpp" // for boost::tie
|
||||
#include <algorithm> // for std::copy
|
||||
#include <iostream>
|
||||
#include <vector>
|
||||
|
||||
|
||||
typedef boost::shared_container_iterator< std::vector<int> > iterator;
|
||||
|
||||
std::pair<iterator,iterator>
|
||||
return_range() {
|
||||
boost::shared_ptr< std::vector<int> > range(new std::vector<int>());
|
||||
range->push_back(0);
|
||||
range->push_back(1);
|
||||
range->push_back(2);
|
||||
range->push_back(3);
|
||||
range->push_back(4);
|
||||
range->push_back(5);
|
||||
return boost::make_shared_container_range(range);
|
||||
}
|
||||
|
||||
|
||||
int main() {
|
||||
|
||||
|
||||
iterator i,end;
|
||||
|
||||
boost::tie(i,end) = return_range();
|
||||
|
||||
std::copy(i,end,std::ostream_iterator<int>(std::cout,","));
|
||||
std::cout.put('\n');
|
||||
|
||||
return 0;
|
||||
}
|
||||
@ -23,8 +23,6 @@ run operators_test.cpp ;
|
||||
|
||||
compile result_of_test.cpp ;
|
||||
|
||||
run shared_iterator_test.cpp ;
|
||||
|
||||
# compile-fail string_ref_from_rvalue.cpp ;
|
||||
run string_ref_test1.cpp ;
|
||||
run string_ref_test2.cpp ;
|
||||
|
||||
@ -1,64 +0,0 @@
|
||||
// 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)
|
||||
|
||||
// Shared container iterator adaptor
|
||||
// Author: Ronald Garcia
|
||||
// See http://boost.org/libs/utility/shared_container_iterator.html
|
||||
// for documentation.
|
||||
|
||||
//
|
||||
// shared_iterator_test.cpp - Regression tests for shared_container_iterator.
|
||||
//
|
||||
|
||||
|
||||
#include "boost/shared_container_iterator.hpp"
|
||||
#include "boost/shared_ptr.hpp"
|
||||
#include <vector>
|
||||
#include <cassert>
|
||||
|
||||
struct resource {
|
||||
static int count;
|
||||
resource() { ++count; }
|
||||
resource(resource const&) { ++count; }
|
||||
~resource() { --count; }
|
||||
};
|
||||
int resource::count = 0;
|
||||
|
||||
typedef std::vector<resource> resources_t;
|
||||
|
||||
typedef boost::shared_container_iterator< resources_t > iterator;
|
||||
|
||||
|
||||
void set_range(iterator& i, iterator& end) {
|
||||
|
||||
boost::shared_ptr< resources_t > objs(new resources_t());
|
||||
|
||||
for (int j = 0; j != 6; ++j)
|
||||
objs->push_back(resource());
|
||||
|
||||
i = iterator(objs->begin(),objs);
|
||||
end = iterator(objs->end(),objs);
|
||||
assert(resource::count == 6);
|
||||
}
|
||||
|
||||
|
||||
int main() {
|
||||
|
||||
assert(resource::count == 0);
|
||||
|
||||
{
|
||||
iterator i;
|
||||
{
|
||||
iterator end;
|
||||
set_range(i,end);
|
||||
assert(resource::count == 6);
|
||||
}
|
||||
assert(resource::count == 6);
|
||||
}
|
||||
assert(resource::count == 0);
|
||||
|
||||
return 0;
|
||||
}
|
||||
Reference in New Issue
Block a user