1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.3.9: http://docutils.sourceforge.net/" />
<title>Boost Pointer Container Library</title>
<link rel="stylesheet" href="default.css" type="text/css" />
</head>
<body>
<div class="document" id="boost-pointer-container-library">
<h1 class="title"><img alt="Boost" src="boost.png" /> Pointer Container Library</h1>
<h2 class="subtitle" id="examples">Examples</h2>
<p>Some examples are given here and in the accompanying test files:</p>
<div class="contents topic" id="contents">
<ul class="simple">
<li><a class="reference" href="#null-pointers-cannot-be-stored-in-the-containers" id="id1" name="id1">1. Null pointers cannot be stored in the containers</a></li>
<li><a class="reference" href="#iterators-and-other-operations-return-indirected-values" id="id2" name="id2">2. Iterators and other operations return indirected values</a></li>
<li><a class="reference" href="#copy-semantics-of-pointer-containers" id="id3" name="id3">3. Copy-semantics of pointer containers</a></li>
<li><a class="reference" href="#making-a-non-copyable-type-clonable" id="id4" name="id4">4. Making a non-copyable type Clonable</a></li>
<li><a class="reference" href="#objects-are-cloned-before-insertion-inserted-pointers-are-owned-by-the-container" id="id5" name="id5">5. Objects are cloned before insertion, inserted pointers are owned by the container</a></li>
<li><a class="reference" href="#transferring-ownership-of-a-single-element" id="id6" name="id6">6. Transferring ownership of a single element</a></li>
<li><a class="reference" href="#transferring-ownership-of-pointers-between-different-pointer-containers" id="id7" name="id7">7. Transferring ownership of pointers between different pointer containers</a></li>
<li><a class="reference" href="#selected-test-files" id="id8" name="id8">8. Selected test files</a></li>
</ul>
</div>
<span id="example-1"></span><div class="section" id="null-pointers-cannot-be-stored-in-the-containers">
<h1><a class="toc-backref" href="#id1" name="null-pointers-cannot-be-stored-in-the-containers">1. Null pointers cannot be stored in the containers</a></h1>
<pre class="literal-block">
my_container.push_back( 0 ); // throws bad_ptr
my_container.replace( an_iterator, 0 ); // throws bad_ptr
my_container.insert( an_iterator, 0 ); // throws bad_ptr
</pre>
</div>
<span id="example-2"></span><div class="section" id="iterators-and-other-operations-return-indirected-values">
<h1><a class="toc-backref" href="#id2" name="iterators-and-other-operations-return-indirected-values">2. Iterators and other operations return indirected values</a></h1>
<pre class="literal-block">
ptr_vector<X> pvec;
std::vector<X*> vec;
*vec.begin() = new X; // fine, memory leak
*pvec.begin() = new X; // compile time error
( *vec.begin() )->foo(); // call X::foo(), a bit clumsy
pvec.begin()->foo(); // no indirection needed
*vec.front() = X(); // overwrite first element
pvec.front() = X(); // no indirection needed
</pre>
</div>
<span id="example-3"></span><div class="section" id="copy-semantics-of-pointer-containers">
<h1><a class="toc-backref" href="#id3" name="copy-semantics-of-pointer-containers">3. Copy-semantics of pointer containers</a></h1>
<pre class="literal-block">
ptr_vector<T> vec1;
...
ptr_vector<T> vec2( vec1.clone() ); // deep copy objects of 'vec1' and use them to construct 'vec2', could be very expensive
vec2 = vec1.release(); // give up ownership of pointers in 'vec1' and pass the ownership to 'vec2', rather cheap
vec2.release(); // give up ownership; the objects will be deallocated if not assigned to another container
vec1 = vec2; // compile time error: 'operator=()' not defined
ptr_vector<T> vec3( vec1 ); // compile time error: copy-constructor not defined
</pre>
</div>
<span id="example-4"></span><div class="section" id="making-a-non-copyable-type-clonable">
<h1><a class="toc-backref" href="#id4" name="making-a-non-copyable-type-clonable">4. Making a non-copyable type Clonable</a></h1>
<pre class="literal-block">
// a class that has no normal copy semantics
class X : boost::noncopyable { public: X* clone() const; ... };
// this will be found by the library by argument dependent lookup
X* new_clone( const X& x )
{ return x.clone(); }
// we can now use the interface that requires clonability
ptr_vector<X> vec1, vec2;
...
vec2 = vec1.clone(); // 'clone()' requires cloning <g>
vec2.insert( vec2.end(), vec1.begin(), vec1.end() ); // inserting always means inserting clones
</pre>
</div>
<span id="example-5"></span><div class="section" id="objects-are-cloned-before-insertion-inserted-pointers-are-owned-by-the-container">
<h1><a class="toc-backref" href="#id5" name="objects-are-cloned-before-insertion-inserted-pointers-are-owned-by-the-container">5. Objects are cloned before insertion, inserted pointers are owned by the container</a></h1>
<pre class="literal-block">
class X { ... }; // assume 'X' is Clonable
X x; // and 'X' can be stack-allocated
ptr_list<X> list;
list.push_back( x ); // clone 'x' and then insert the resulting pointer
list.push_back( new_clone( x ); // do it manually
list.push_back( new X ); // always give the pointer directly to the container to avoid leaks
list.push_back( &x ); // don't do this!!!
</pre>
</div>
<span id="example-6"></span><div class="section" id="transferring-ownership-of-a-single-element">
<h1><a class="toc-backref" href="#id6" name="transferring-ownership-of-a-single-element">6. Transferring ownership of a single element</a></h1>
<pre class="literal-block">
ptr_deque<T> deq;
typedef ptr_deque<T>::auto_type auto_type;
// ... fill the container somehow
auto_type ptr = deq.release_back(); // remove back element from container and give up ownership
auto_type ptr2 = deq.release( deq.begin() + 2 ); // use an iterator to determine the element to release
ptr = deq.release_front(); // supported for 'ptr_list' and 'ptr_deque'
</pre>
</div>
<span id="example-7"></span><div class="section" id="transferring-ownership-of-pointers-between-different-pointer-containers">
<h1><a class="toc-backref" href="#id7" name="transferring-ownership-of-pointers-between-different-pointer-containers">7. Transferring ownership of pointers between different pointer containers</a></h1>
<pre class="literal-block">
ptr_list<X> list; ptr_vector<X> vec;
...
//
// note: no cloning happens in these examples
//
list.transfer( list.begin(), vec.begin(), vec ); // make the first element of 'vec' the first element of 'list'
vec.transfer( vec.end(), list.begin(), list.end(), list ); // put all the lists element into the vector
</pre>
</div>
<span id="example-8"></span><div class="section" id="selected-test-files">
<h1><a class="toc-backref" href="#id8" name="selected-test-files">8. Selected test files</a></h1>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name" colspan="2"><a class="reference" href="../test/incomplete_type_test.cpp">incomplete_type_test.cpp</a>:</th></tr>
<tr><td> </td><td class="field-body">Shows how to implement the Composite pattern.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2"><a class="reference" href="../test/simple_test.cpp">simple_test.cpp</a>:</th></tr>
<tr><td> </td><td class="field-body">Shows how the usage of pointer container compares with a
container of pointer pointers</td>
</tr>
<tr class="field"><th class="field-name" colspan="2"><a class="reference" href="../test/view_example.cpp">view_example.cpp</a>:</th></tr>
<tr><td> </td><td class="field-body">Shows how to use a pointer container as a view into other container</td>
</tr>
<tr class="field"><th class="field-name"><a class="reference" href="../test/tree_test.cpp">tree_test.cpp</a>:</th><td class="field-body">Shows how to make a tree-structure</td>
</tr>
<tr class="field"><th class="field-name"><a class="reference" href="../test/ptr_array.cpp">array_test.cpp</a>:</th><td class="field-body">Shows how to make an n-ary tree</td>
</tr>
</tbody>
</table>
<!-- 9. A large example
++++++++++++++++++
This examples shows many of the most common
features at work.
.. raw:: html
:file: tut1.html
10. Changing the Clone Allocator
++++++++++++++++++++++++++++++++
This example shows how we can change
the Clone Allocator to use the pointer containers
as view into other containers:
.. raw:: html
:file: tut2.html -->
<p><strong>Navigate:</strong></p>
<ul class="simple">
<li><a class="reference" href="ptr_container.html">home</a></li>
<li><a class="reference" href="reference.html">reference</a></li>
</ul>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">copyright:</th><td class="field-body">Thorsten Ottosen 2004-2005.</td>
</tr>
</tbody>
</table>
</div>
</div>
</body>
</html>
|
