-
--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. -
-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. - - -
-namespace boost {
- template <typename Container>
- class shared_container_iterator;
-
- template <typename Container>
- 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);
-}
-
-
--template <typename Container> class shared_container_iterator; -- -The class template shared_container_iterator -is the shared container iterator type. The Container template -type argument must model the -Container -concept. - -
-The following example illustrates how to create an iterator that -regulates the lifetime of a reference counted std::vector. -Though the original shared pointer ints ceases to exist -after set_range() returns, the -shared_counter_iterator objects maintain references to the - underlying vector and thereby extend the container's lifetime. -
-shared_iterator_example1.cpp: -
-#include "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;
-}
-
-
-The output from this part is:
--0,1,2,3,4,5, -- -
| Parameter | Description | -
|---|---|
| Container | -The type of the container that we wish to iterate over. It must be -a model of the -Container -concept. - | -
-shared_container_iterator(Container::iterator const& it, - boost::shared_ptr<Container> const& container) -- -
-
- - -
-template <typename Container> -shared_container_iterator<Container> -make_shared_container_iterator(Container::iterator base, - boost::shared_ptr<Container> const& container) -- -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. - -
-shared_iterator_example2.cpp: - -
-#include "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;
-}
-
-
-Observe that the shared_container_iterator type is never
-explicitly named. The output from this example is the same as the previous.
-
--template <typename Container> -std::pair< - shared_container_iterator<Container>, - shared_container_iterator<Container> -> -make_shared_container_range(boost::shared_ptr<Container> const& container); -- -Class shared_container_iterator 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 - -
-std::make_pair(make_shared_container_iterator(container->begin(),container), - make_shared_container_iterator(container->end(),container)); -- -
-shared_iterator_example3.cpp: - -
-#include "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;
-}
-
-
-Though the range object only lives for the duration of the
-return_range call, the reference counted
-std::vector will live until i and end
-are both destroyed. The output from this example is the same as
-the previous two.
-
-
-© 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)
- - - - diff --git a/shared_iterator_example1.cpp b/shared_iterator_example1.cpp deleted file mode 100644 index f88e094..0000000 --- a/shared_iterator_example1.cpp +++ /dev/null @@ -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