1++++++++++++++++++++++++++++++++++ 2 |Boost| Pointer Container Library 3++++++++++++++++++++++++++++++++++ 4 5.. |Boost| image:: boost.png 6 7======== 8Examples 9======== 10 11Some examples are given here and in the accompanying test files: 12 13.. contents:: :local: 14 15 16.. _`Example 1`: 17 181. Null pointers cannot be stored in the containers 19+++++++++++++++++++++++++++++++++++++++++++++++++++ 20 21:: 22 23 my_container.push_back( 0 ); // throws bad_ptr 24 my_container.replace( an_iterator, 0 ); // throws bad_ptr 25 my_container.insert( an_iterator, 0 ); // throws bad_ptr 26 std::auto_ptr<T> p( 0 ); 27 my_container.push_back( p ); // throws bad_ptr 28 29.. _`Example 2`: 30 312. Iterators and other operations return indirected values 32++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 33 34:: 35 36 ptr_vector<X> pvec; 37 std::vector<X*> vec; 38 *vec.begin() = new X; // fine, memory leak 39 *pvec.begin() = new X; // compile time error 40 ( *vec.begin() )->foo(); // call X::foo(), a bit clumsy 41 pvec.begin()->foo(); // no indirection needed 42 *vec.front() = X(); // overwrite first element 43 pvec.front() = X(); // no indirection needed 44 45 46.. _`Example 3`: 47 483. Copy-semantics of pointer containers 49+++++++++++++++++++++++++++++++++++++++ 50 51:: 52 53 ptr_vector<T> vec1; 54 ... 55 ptr_vector<T> vec2( vec1.clone() ); // deep copy objects of 'vec1' and use them to construct 'vec2', could be very expensive 56 vec2 = vec1.release(); // give up ownership of pointers in 'vec1' and pass the ownership to 'vec2', rather cheap 57 vec2.release(); // give up ownership; the objects will be deallocated if not assigned to another container 58 vec1 = vec2; // deep copy objects of 'vec2' and assign them to 'vec1', could be very expensive 59 ptr_vector<T> vec3( vec1 ); // deep copy objects of 'vec1', could be very expensive 60 61 62.. _`Example 4`: 63 644. Making a non-copyable type Cloneable 65+++++++++++++++++++++++++++++++++++++++ 66 67:: 68 69 // a class that has no normal copy semantics 70 class X : boost::noncopyable { public: X* clone() const; ... }; 71 72 // this will be found by the library by argument dependent lookup (ADL) 73 X* new_clone( const X& x ) 74 { return x.clone(); } 75 76 // we can now use the interface that requires cloneability 77 ptr_vector<X> vec1, vec2; 78 ... 79 vec2 = vec1.clone(); // 'clone()' requires cloning <g> 80 vec2.insert( vec2.end(), vec1.begin(), vec1.end() ); // inserting always means inserting clones 81 82 83.. _`Example 5`: 84 855. Objects are cloned before insertion, inserted pointers are owned by the container 86++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 87 88:: 89 90 class X { ... }; // assume 'X' is Cloneable 91 X x; // and 'X' can be stack-allocated 92 ptr_list<X> list; 93 list.push_back( new_clone( x ) ); // insert a clone 94 list.push_back( new X ); // always give the pointer directly to the container to avoid leaks 95 list.push_back( &x ); // don't do this!!! 96 std::auto_ptr<X> p( new X ); 97 list.push_back( p ); // give up ownership 98 BOOST_ASSERT( p.get() == 0 ); 99 100 101.. _`Example 6`: 102 1036. Transferring ownership of a single element 104+++++++++++++++++++++++++++++++++++++++++++++ 105 106:: 107 108 ptr_deque<T> deq; 109 typedef ptr_deque<T>::auto_type auto_type; 110 111 // ... fill the container somehow 112 113 auto_type ptr = deq.release_back(); // remove back element from container and give up ownership 114 auto_type ptr2 = deq.release( deq.begin() + 2 ); // use an iterator to determine the element to release 115 ptr = deq.release_front(); // supported for 'ptr_list' and 'ptr_deque' 116 117 deq.push_back( ptr.release() ); // give ownership back to the container 118 119 120.. _`Example 7`: 121 1227. Transferring ownership of pointers between different pointer containers 123++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 124 125:: 126 127 128 ptr_list<X> list; ptr_vector<X> vec; 129 ... 130 // 131 // note: no cloning happens in these examples 132 // 133 list.transfer( list.begin(), vec.begin(), vec ); // make the first element of 'vec' the first element of 'list' 134 vec.transfer( vec.end(), list.begin(), list.end(), list ); // put all the lists element into the vector 135 136We can also transfer objects from ``ptr_container<Derived>`` to ``ptr_container<Base>`` without any problems. 137 138.. _`Example 8`: 139 140 141 1428. Selected test files 143++++++++++++++++++++++ 144 145:incomplete_type_test.cpp_: Shows how to implement the Composite pattern. 146:simple_test.cpp_: Shows how the usage of pointer container compares with a 147 container of smart pointers 148:view_example.cpp_: Shows how to use a pointer container as a view into other container 149:tree_test.cpp_: Shows how to make a tree-structure 150:array_test.cpp_: Shows how to make an n-ary tree 151 152.. _incomplete_type_test.cpp : ../test/incomplete_type_test.cpp 153.. _simple_test.cpp : ../test/simple_test.cpp 154.. _view_example.cpp : ../test/view_example.cpp 155.. _tree_test.cpp : ../test/tree_test.cpp 156.. _array_test.cpp : ../test/ptr_array.cpp 157 158 159 1609. A large example 161++++++++++++++++++ 162 163This example shows many of the most common 164features at work. The example provide lots of comments. 165The source code can also be found `here <../test/tut1.cpp>`_. 166 167.. raw:: html 168 :file: tutorial_example.html 169 170.. 171 10. Changing the Clone Allocator 172 ++++++++++++++++++++++++++++++++ 173 174 This example shows how we can change 175 the Clone Allocator to use the pointer containers 176 as view into other containers: 177 178 .. raw:: html 179 :file: tut2.html 180 181.. raw:: html 182 183 <hr> 184 185**Navigate:** 186 187- `home <ptr_container.html>`_ 188- `reference <reference.html>`_ 189 190.. raw:: html 191 192 <hr> 193 194:Copyright: Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). 195 196__ http://www.boost.org/LICENSE_1_0.txt 197 198 199