| <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>© 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> |