Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/libs/ptr_container/doc/reference.html @ 20

Last change on this file since 20 was 12, checked in by landauf, 18 years ago

added boost
File size: 17.5 KB
Line 
1<?xml version="1.0" encoding="utf-8" ?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6<meta name="generator" content="Docutils 0.3.9: http://docutils.sourceforge.net/" />
7<title>Boost Pointer Container Library</title>
8<link rel="stylesheet" href="default.css" type="text/css" />
9</head>
10<body>
11<div class="document" id="boost-pointer-container-library">
12<h1 class="title"><img alt="Boost" src="boost.png" /> Pointer Container Library</h1>
13<h2 class="subtitle" id="reference">Reference</h2>
14<p>The documentation is divided into a an explanation for
15each container. All the common interface is explained only once,
16but links are always provided to the relevant links.
17Please make sure you understand
18the <a class="reference" href="reference.html#the-clonable-concept">Clonable</a> concept and
19the <a class="reference" href="reference.html#the-clone-allocator-concept">Clone Allocator</a> concept.</p>
20<ul class="simple">
21<li><a class="reference" href="conventions.html">Conventions</a></li>
22<li><a class="reference" href="#the-clonable-concept">The Clonable concept</a></li>
23<li><a class="reference" href="#the-clone-allocator-concept">The Clone Allocator concept</a></li>
24<li>Class <a class="reference" href="reversible_ptr_container.html">reversible_ptr_container</a></li>
25<li>Class <a class="reference" href="associative_ptr_container.html">associative_ptr_container</a></li>
26<li><a class="reference" href="#pointer-container-adapters">Pointer container adapters</a><ul>
27<li><a class="reference" href="ptr_sequence_adapter.html">ptr_sequence_adapter</a></li>
28<li><a class="reference" href="ptr_set_adapter.html">ptr_set_adapter</a></li>
29<li><a class="reference" href="ptr_multiset_adapter.html">ptr_multiset_adapter</a></li>
30<li><a class="reference" href="ptr_map_adapter.html">ptr_map_adapter</a></li>
31<li><a class="reference" href="ptr_multimap_adapter.html">ptr_multimap_adapter</a></li>
32</ul>
33</li>
34<li><a class="reference" href="#sequence-containers">Sequence containers</a><ul>
35<li><a class="reference" href="ptr_vector.html">ptr_vector</a></li>
36<li><a class="reference" href="ptr_deque.html">ptr_deque</a></li>
37<li><a class="reference" href="ptr_list.html">ptr_list</a></li>
38<li><a class="reference" href="ptr_array.html">ptr_array</a></li>
39</ul>
40</li>
41<li><a class="reference" href="#associative-containers">Associative containers</a><ul>
42<li><a class="reference" href="ptr_set.html">ptr_set</a></li>
43<li><a class="reference" href="ptr_multiset.html">ptr_multiset</a></li>
44<li><a class="reference" href="ptr_map.html">ptr_map</a></li>
45<li><a class="reference" href="ptr_multimap.html">ptr_multimap</a></li>
46</ul>
47</li>
48<li><a class="reference" href="#map-iterator-operations">Map iterator operations</a></li>
49<li><a class="reference" href="indirect_fun.html">Indirected functions</a></li>
50<li><a class="reference" href="#class-nullable">Class nullable</a></li>
51<li><a class="reference" href="#exception-classes">Exception classes</a></li>
52</ul>
53<div class="section" id="the-clonable-concept">
54<h1><a name="the-clonable-concept">The Clonable concept</a></h1>
55<p><strong>Refinement of</strong></p>
56<ul class="simple">
57<li>Copy Constructible</li>
58<li>Heap Allocable</li>
59<li>Heap Deallocable</li>
60</ul>
61<p>The Clonable concept is introduced to formalize the requirements for
62copying heap-allocated objects.  A type <tt class="docutils literal"><span class="pre">T</span></tt> might be Clonable even though it
63is not Assignable or Copy Constructible.  Notice that many operations on
64the containers does not even require the stored type to be Clonable.</p>
65<p><strong>Notation</strong></p>
66<table border="1" class="docutils">
67<colgroup>
68<col width="21%" />
69<col width="41%" />
70<col width="18%" />
71<col width="20%" />
72</colgroup>
73<tbody valign="top">
74<tr><td><strong>Type</strong></td>
75<td><strong>Object</strong> (<tt class="docutils literal"><span class="pre">const</span></tt> or non-<tt class="docutils literal"><span class="pre">const</span></tt>)</td>
76<td><strong>Pointer</strong></td>
77<td><strong>Describes</strong></td>
78</tr>
79<tr><td><tt class="docutils literal"><span class="pre">T</span></tt></td>
80<td><tt class="docutils literal"><span class="pre">a</span></tt></td>
81<td><tt class="docutils literal"><span class="pre">ptr</span></tt></td>
82<td>A Clonable type</td>
83</tr>
84</tbody>
85</table>
86<p><strong>Valid expressions</strong></p>
87<table border="1" class="docutils">
88<colgroup>
89<col width="24%" />
90<col width="18%" />
91<col width="58%" />
92</colgroup>
93<tbody valign="top">
94<tr><td><strong>Expression</strong></td>
95<td><strong>Type</strong></td>
96<td><strong>Semantics</strong></td>
97</tr>
98<tr><td><tt class="docutils literal"><span class="pre">new_clone(a);</span></tt></td>
99<td><tt class="docutils literal"><span class="pre">T*</span></tt></td>
100<td>Allocate a new object that can be considered equivalent to the <tt class="docutils literal"><span class="pre">a</span></tt> object</td>
101</tr>
102<tr><td><tt class="docutils literal"><span class="pre">delete_clone(ptr);</span></tt></td>
103<td><tt class="docutils literal"><span class="pre">void</span></tt></td>
104<td>Deallocate an object previously allocated with <tt class="docutils literal"><span class="pre">allocate_clone()</span></tt>. Must not throw</td>
105</tr>
106</tbody>
107</table>
108<div class="section" id="default-implementation">
109<h2><a name="default-implementation">Default implementation</a></h2>
110<p>In the <tt class="docutils literal"><span class="pre">&lt;boost/ptr_container/clone_allocator.hpp&gt;</span></tt> header a default implementation
111of the two functions is given:</p>
112<pre class="literal-block">
113namespace boost
114{
115    template&lt; class T &gt;
116    inline T* new_clone( const T&amp; t )
117    {
118        return new T( t );
119    }
120
121    template&lt; class T &gt;
122    void delete_clone( const T* t )
123    {
124        checked_delete( r );
125    }
126}
127</pre>
128<p>Notice that this implementation  makes normal Copy Constructible classes are automatically
129Clonable unless <tt class="docutils literal"><span class="pre">operator</span> <span class="pre">new()</span></tt> or <tt class="docutils literal"><span class="pre">operator</span> <span class="pre">delete()</span></tt> are hidden.</p>
130<p>The two functions represent a layer of indirection which is necessary to support
131classes that are not Copy Constructible by default.  Notice that the implementation
132relies on argument-dependent lookup (ADL) to find the right version of
133<tt class="docutils literal"><span class="pre">new_clone()</span></tt> and <tt class="docutils literal"><span class="pre">delete_clone()</span></tt>. This means that one does not need to overload or specialize
134the function is the boost namespace, but it can be placed together with
135the rest of the interface of the class.  If you are implementing a class
136inline in headers, remember to forward declare the functions.</p>
137</div>
138</div>
139<div class="section" id="the-clone-allocator-concept">
140<h1><a name="the-clone-allocator-concept">The Clone Allocator concept</a></h1>
141<p>The Clone Allocator concept is introduced to formalize the way
142pointer containers controls memory of
143the stored objects (and not the pointers to the stored objects).
144The clone allocator allows
145users to apply custom allocators/deallocators for the cloned objects.</p>
146<p>More information can be found below:</p>
147<div class="contents topic" id="contents">
148<ul class="simple">
149<li><a class="reference" href="#clone-allocator-requirements" id="id14" name="id14">Clone Allocator requirements</a></li>
150<li><a class="reference" href="#class-heap-clone-allocator" id="id15" name="id15">Class <tt class="docutils literal"><span class="pre">heap_clone_allocator</span></tt></a></li>
151<li><a class="reference" href="#class-view-clone-allocator" id="id16" name="id16">Class <tt class="docutils literal"><span class="pre">view_clone_allocator</span></tt></a></li>
152</ul>
153</div>
154<div class="section" id="clone-allocator-requirements">
155<h2><a class="toc-backref" href="#id14" name="clone-allocator-requirements">Clone Allocator requirements</a></h2>
156<p><strong>Notation</strong></p>
157<table border="1" class="docutils">
158<colgroup>
159<col width="18%" />
160<col width="39%" />
161<col width="43%" />
162</colgroup>
163<tbody valign="top">
164<tr><td><strong>Type</strong></td>
165<td><strong>Object</strong> (<tt class="docutils literal"><span class="pre">const</span></tt> or non-<tt class="docutils literal"><span class="pre">const</span></tt>)</td>
166<td><strong>Describes</strong></td>
167</tr>
168<tr><td><tt class="docutils literal"><span class="pre">T</span></tt></td>
169<td><tt class="docutils literal"><span class="pre">a</span></tt></td>
170<td>A type</td>
171</tr>
172<tr><td><tt class="docutils literal"><span class="pre">T*</span></tt></td>
173<td><tt class="docutils literal"><span class="pre">ptr</span></tt></td>
174<td>A pointer to <tt class="docutils literal"><span class="pre">T</span></tt></td>
175</tr>
176</tbody>
177</table>
178<p><strong>Valid expressions</strong></p>
179<table border="1" class="docutils">
180<colgroup>
181<col width="25%" />
182<col width="6%" />
183<col width="69%" />
184</colgroup>
185<tbody valign="top">
186<tr><td><strong>Expression</strong></td>
187<td><strong>Type</strong></td>
188<td><strong>Semantics</strong></td>
189</tr>
190<tr><td><tt class="docutils literal"><span class="pre">CloneAllocator::allocate_clone(a);</span></tt></td>
191<td><tt class="docutils literal"><span class="pre">T*</span></tt></td>
192<td>Allocate a new object that can be considered equivalent to the <tt class="docutils literal"><span class="pre">a</span></tt> object</td>
193</tr>
194<tr><td><tt class="docutils literal"><span class="pre">CloneAllocator::deallocate_clone(ptr);</span></tt></td>
195<td><tt class="docutils literal"><span class="pre">void</span></tt></td>
196<td>Deallocate an object previously allocated with <tt class="docutils literal"><span class="pre">CloneAllocator::allocate_clone()</span></tt> or a compatible allocator. Must not throw.</td>
197</tr>
198</tbody>
199</table>
200<p>The library comes with two predefined clone allocators.</p>
201</div>
202<div class="section" id="class-heap-clone-allocator">
203<h2><a class="toc-backref" href="#id15" name="class-heap-clone-allocator">Class <tt class="docutils literal docutils literal"><span class="pre">heap_clone_allocator</span></tt></a></h2>
204<p>This is the default clone allocator used by all pointer containers. For most
205purposes you will never have to change this default.</p>
206<p><strong>Definition</strong></p>
207<pre class="literal-block">
208namespace boost
209{       
210    struct heap_clone_allocator
211    {
212        template&lt; class U &gt;
213        static U* allocate_clone( const U&amp; r )
214        {
215            return new_clone( r );
216        }
217
218        template&lt; class U &gt;
219        static void deallocate_clone( const U* r ) const
220        {
221            delete_clone( r );
222        }
223    };
224}
225</pre>
226<p>Notice that the above definition allows you to support custom allocation
227schemes by relying on <tt class="docutils literal"><span class="pre">new_clone()</span></tt> and <tt class="docutils literal"><span class="pre">delete_clone()</span></tt>.</p>
228</div>
229<div class="section" id="class-view-clone-allocator">
230<h2><a class="toc-backref" href="#id16" name="class-view-clone-allocator">Class <tt class="docutils literal docutils literal"><span class="pre">view_clone_allocator</span></tt></a></h2>
231<p>This class provides a way to remove ownership properties of the
232pointer containers. As its name implies, this means that you can
233instead use the pointer containers as a view into an existing
234container.</p>
235<p><strong>Definition</strong></p>
236<pre class="literal-block">
237namespace boost
238{
239    struct view_clone_allocator
240    {
241        template&lt; class U &gt;
242        static U* allocate_clone( const U&amp; r )
243        {
244            return const_cast&lt;U*&gt;(&amp;r);
245        }
246
247        template&lt; class U &gt;
248        static void deallocate_clone( const U* )
249        {
250            // empty
251        }
252    };
253}
254</pre>
255<p><strong>See also</strong></p>
256<ul class="simple">
257<li><a class="reference" href="examples.html#changing-the-clone-allocator">Changing the clone allocator</a></li>
258</ul>
259</div>
260</div>
261<div class="section" id="pointer-container-adapters">
262<h1><a name="pointer-container-adapters">Pointer container adapters</a></h1>
263<p>The pointer container adapters are used when you
264want to make a pointer container starting from
265your own &quot;normal&quot; container. For example, you
266might have a map class that is extends <tt class="docutils literal"><span class="pre">std::map</span></tt>
267in some way; the adapter class then allows you
268to use your map class as a basis for a new
269pointer container.</p>
270<p>The library provides an adapter for each type
271of standard container:</p>
272<ul class="simple">
273<li><a class="reference" href="ptr_sequence_adapter.html">ptr_sequence_adapter</a></li>
274<li><a class="reference" href="ptr_set_adapter.html">ptr_set_adapter</a></li>
275<li><a class="reference" href="ptr_multiset_adapter.html">ptr_multiset_adapter</a></li>
276<li><a class="reference" href="ptr_map_adapter.html">ptr_map_adapter</a></li>
277<li><a class="reference" href="ptr_multimap_adapter.html">ptr_multimap_adapter</a></li>
278</ul>
279</div>
280<div class="section" id="pointer-containers">
281<h1><a name="pointer-containers">Pointer containers</a></h1>
282<p>The pointer containers of this library are all built using
283the <a class="reference" href="#pointer-container-adapters">pointer container adapters</a>. There is a pointer container
284for each type of &quot;normal&quot; standard container:</p>
285<div class="section" id="sequence-containers">
286<h2><a name="sequence-containers">Sequence containers</a></h2>
287<blockquote>
288<ul class="simple">
289<li><a class="reference" href="ptr_vector.html">ptr_vector</a></li>
290<li><a class="reference" href="ptr_deque.html">ptr_deque</a></li>
291<li><a class="reference" href="ptr_list.html">ptr_list</a></li>
292<li><a class="reference" href="ptr_array.html">ptr_array</a></li>
293</ul>
294</blockquote>
295</div>
296<div class="section" id="associative-containers">
297<h2><a name="associative-containers">Associative containers</a></h2>
298<blockquote>
299<ul class="simple">
300<li><a class="reference" href="ptr_set.html">ptr_set</a></li>
301<li><a class="reference" href="ptr_multiset.html">ptr_multiset</a></li>
302<li><a class="reference" href="ptr_map.html">ptr_map</a></li>
303<li><a class="reference" href="ptr_multimap.html">ptr_multimap</a></li>
304</ul>
305</blockquote>
306</div>
307</div>
308<div class="section" id="map-iterator-operations">
309<h1><a name="map-iterator-operations">Map iterator operations</a></h1>
310<p>The map iterators are a bit different compared to the normal ones.  The
311reason is that it is a bit clumsy to access the key and the mapped object
312through i-&gt;first and i-&gt;second, and one tends to forget what is what.
313Moreover, and more importantly, we also want to hide the pointer as much as possibble.
314The new style can be illustrated with a small example:</p>
315<pre class="literal-block">
316typedef ptr_map&lt;string,int&gt; map_t;
317map_t  m;
318m[ &quot;foo&quot; ] = 4; // insert pair
319m[ &quot;bar&quot; ] = 5; // ditto
320...
321for( map_t::iterator i = m.begin(); i != m.end(); ++i )
322{
323         *i += 42; // add 42 to each value
324         cout &lt;&lt; &quot;value=&quot; &lt;&lt; *i &lt;&lt; &quot;, key=&quot; &lt;&lt; i.key() &lt;&lt; &quot;n&quot;;
325}
326</pre>
327<p>So the difference from the normal map iterator is that</p>
328<ul class="simple">
329<li><tt class="docutils literal"><span class="pre">operator*()</span></tt> returns a reference to the mapped object (normally it returns a reference to a <tt class="docutils literal"><span class="pre">std::pair</span></tt>, and</li>
330<li>that the key can be accessed through the <tt class="docutils literal"><span class="pre">key()</span></tt> function.</li>
331</ul>
332</div>
333<div class="section" id="class-nullable">
334<h1><a name="class-nullable">Class <tt class="docutils literal"><span class="pre">nullable</span></tt></a></h1>
335<p>The purpose of the class is simply to tell the containers
336that null values should be allowed. Its definition is
337trivial:</p>
338<pre class="literal-block">
339namespace boost
340{
341    template&lt; class T &gt;
342    struct nullable
343    {
344        typedef T type;
345    }; 
346}
347</pre>
348<p>Please notice that <tt class="docutils literal"><span class="pre">nullable</span></tt> has no effect on the containers
349interface (except for <tt class="docutils literal"><span class="pre">is_null()</span></tt> functions). For example, it
350does not make sense to do</p>
351<pre class="literal-block">
352boost::ptr_vector&lt; boost::nullable&lt;T&gt; &gt; vec;
353vec.push_back( new boost::nullable&lt;T&gt; ); // no no
354boost::nullable&lt;T&gt;&amp; ref = vec[0];        // also no no
355</pre>
356</div>
357<div class="section" id="exception-classes">
358<h1><a name="exception-classes">Exception classes</a></h1>
359<p>There are three exceptions that are thrown by this library.  The exception
360hierarchy looks as follows:</p>
361<pre class="literal-block">
362namespace boost
363{
364    class bad_ptr_container_operation : public std::exception
365    {
366    public:
367        bad_ptr_container_operation( const char* what );
368    };
369   
370    class bad_index : public bad_ptr_container_operation
371    {
372    public:
373        bad_index( const char* what );
374    };
375
376    class bad_pointer : public bad_ptr_container_operation
377    {
378    public:
379        bad_pointer();
380        bad_pointer( const char* what );
381    };
382}
383</pre>
384<ul class="simple">
385<li><a class="reference" href="ptr_container.html">home</a></li>
386</ul>
387<table class="docutils field-list" frame="void" rules="none">
388<col class="field-name" />
389<col class="field-body" />
390<tbody valign="top">
391<tr class="field"><th class="field-name">copyright:</th><td class="field-body">Thorsten Ottosen 2004-2005.</td>
392</tr>
393</tbody>
394</table>
395</div>
396</div>
397</body>
398</html>
Note: See TracBrowser for help on using the repository browser.