Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/ptr_container/doc/reference.html @ 47

Last change on this file since 47 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 28.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.10: http://docutils.sourceforge.net/" />
7<title>Boost Pointer Container Library</title>
8<style type="text/css">
9
10/*
11:Author: David Goodger
12:Contact: goodger@users.sourceforge.net
13:Date: $Date: 2006/11/22 22:01:03 $
14:Revision: $Revision: 1.5.2.5 $
15:Copyright: This stylesheet has been placed in the public domain.
16
17Default cascading style sheet for the HTML output of Docutils.
18
19See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
20customize this style sheet.
21*/
22
23/* "! important" is used here to override other ``margin-top`` and
24   ``margin-bottom`` styles that are later in the stylesheet or
25   more specific.  See http://www.w3.org/TR/CSS1#the-cascade */
26.first {
27  margin-top: 0 ! important }
28
29.last, .with-subtitle {
30  margin-bottom: 0 ! important }
31
32.hidden {
33  display: none }
34
35a.toc-backref {
36  text-decoration: none ;
37  color: black }
38
39blockquote.epigraph {
40  margin: 2em 5em ; }
41
42dl.docutils dd {
43  margin-bottom: 0.5em }
44
45/* Uncomment (and remove this text!) to get bold-faced definition list terms
46dl.docutils dt {
47  font-weight: bold }
48*/
49
50div.abstract {
51  margin: 2em 5em }
52
53div.abstract p.topic-title {
54  font-weight: bold ;
55  text-align: center }
56
57div.admonition, div.attention, div.caution, div.danger, div.error,
58div.hint, div.important, div.note, div.tip, div.warning {
59  margin: 2em ;
60  border: medium outset ;
61  padding: 1em }
62
63div.admonition p.admonition-title, div.hint p.admonition-title,
64div.important p.admonition-title, div.note p.admonition-title,
65div.tip p.admonition-title {
66  font-weight: bold ;
67  font-family: sans-serif }
68
69div.attention p.admonition-title, div.caution p.admonition-title,
70div.danger p.admonition-title, div.error p.admonition-title,
71div.warning p.admonition-title {
72  color: red ;
73  font-weight: bold ;
74  font-family: sans-serif }
75
76/* Uncomment (and remove this text!) to get reduced vertical space in
77   compound paragraphs.
78div.compound .compound-first, div.compound .compound-middle {
79  margin-bottom: 0.5em }
80
81div.compound .compound-last, div.compound .compound-middle {
82  margin-top: 0.5em }
83*/
84
85div.dedication {
86  margin: 2em 5em ;
87  text-align: center ;
88  font-style: italic }
89
90div.dedication p.topic-title {
91  font-weight: bold ;
92  font-style: normal }
93
94div.figure {
95  margin-left: 2em }
96
97div.footer, div.header {
98  clear: both;
99  font-size: smaller }
100
101div.line-block {
102  display: block ;
103  margin-top: 1em ;
104  margin-bottom: 1em }
105
106div.line-block div.line-block {
107  margin-top: 0 ;
108  margin-bottom: 0 ;
109  margin-left: 1.5em }
110
111div.sidebar {
112  margin-left: 1em ;
113  border: medium outset ;
114  padding: 1em ;
115  background-color: #ffffee ;
116  width: 40% ;
117  float: right ;
118  clear: right }
119
120div.sidebar p.rubric {
121  font-family: sans-serif ;
122  font-size: medium }
123
124div.system-messages {
125  margin: 5em }
126
127div.system-messages h1 {
128  color: red }
129
130div.system-message {
131  border: medium outset ;
132  padding: 1em }
133
134div.system-message p.system-message-title {
135  color: red ;
136  font-weight: bold }
137
138div.topic {
139  margin: 2em }
140
141h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
142h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
143  margin-top: 0.4em }
144
145h1.title {
146  text-align: center }
147
148h2.subtitle {
149  text-align: center }
150
151hr.docutils {
152  width: 75% }
153
154img.align-left {
155  clear: left }
156
157img.align-right {
158  clear: right }
159
160img.borderless {
161  border: 0 }
162
163ol.simple, ul.simple {
164  margin-bottom: 1em }
165
166ol.arabic {
167  list-style: decimal }
168
169ol.loweralpha {
170  list-style: lower-alpha }
171
172ol.upperalpha {
173  list-style: upper-alpha }
174
175ol.lowerroman {
176  list-style: lower-roman }
177
178ol.upperroman {
179  list-style: upper-roman }
180
181p.attribution {
182  text-align: right ;
183  margin-left: 50% }
184
185p.caption {
186  font-style: italic }
187
188p.credits {
189  font-style: italic ;
190  font-size: smaller }
191
192p.label {
193  white-space: nowrap }
194
195p.rubric {
196  font-weight: bold ;
197  font-size: larger ;
198  color: maroon ;
199  text-align: center }
200
201p.sidebar-title {
202  font-family: sans-serif ;
203  font-weight: bold ;
204  font-size: larger }
205
206p.sidebar-subtitle {
207  font-family: sans-serif ;
208  font-weight: bold }
209
210p.topic-title {
211  font-weight: bold }
212
213pre.address {
214  margin-bottom: 0 ;
215  margin-top: 0 ;
216  font-family: serif ;
217  font-size: 100% }
218
219pre.line-block {
220  font-family: serif ;
221  font-size: 100% }
222
223pre.literal-block, pre.doctest-block {
224  margin-left: 2em ;
225  margin-right: 2em ;
226  background-color: #eeeeee }
227
228span.classifier {
229  font-family: sans-serif ;
230  font-style: oblique }
231
232span.classifier-delimiter {
233  font-family: sans-serif ;
234  font-weight: bold }
235
236span.interpreted {
237  font-family: sans-serif }
238
239span.option {
240  white-space: nowrap }
241
242span.pre {
243  white-space: pre }
244
245span.problematic {
246  color: red }
247
248span.section-subtitle {
249  /* font-size relative to parent (h1..h6 element) */
250  font-size: 80% }
251
252table.citation {
253  border-left: solid thin gray }
254
255table.docinfo {
256  margin: 2em 4em }
257
258table.docutils {
259  margin-top: 0.5em ;
260  margin-bottom: 0.5em }
261
262table.footnote {
263  border-left: solid thin black }
264
265table.docutils td, table.docutils th,
266table.docinfo td, table.docinfo th {
267  padding-left: 0.5em ;
268  padding-right: 0.5em ;
269  vertical-align: top }
270
271table.docutils th.field-name, table.docinfo th.docinfo-name {
272  font-weight: bold ;
273  text-align: left ;
274  white-space: nowrap ;
275  padding-left: 0 }
276
277h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
278h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
279  font-size: 100% }
280
281tt.docutils {
282  background-color: #eeeeee }
283
284ul.auto-toc {
285  list-style-type: none }
286
287</style>
288</head>
289<body>
290<div class="document" id="boost-pointer-container-library">
291<h1 class="title"><img alt="Boost" src="boost.png" /> Pointer Container Library</h1>
292<h2 class="subtitle" id="reference">Reference</h2>
293<p>The documentation is divided into a an explanation for
294each container. When containers have the same interface, that common interface is explained only once,
295but links are always provided to more relevant information.
296Please make sure you understand
297the <a class="reference" href="reference.html#the-clonable-concept">Clonable</a> concept and
298the <a class="reference" href="reference.html#the-clone-allocator-concept">Clone Allocator</a> concept.</p>
299<ul class="simple">
300<li><a class="reference" href="conventions.html">Conventions</a></li>
301<li><a class="reference" href="#the-clonable-concept">The Clonable concept</a></li>
302<li><a class="reference" href="#the-clone-allocator-concept">The Clone Allocator concept</a></li>
303<li><a class="reference" href="#class-hierarchy">Class hierarchy</a>:<ul>
304<li><a class="reference" href="reversible_ptr_container.html">reversible_ptr_container</a><ul>
305<li><a class="reference" href="ptr_sequence_adapter.html">ptr_sequence_adapter</a><ul>
306<li><a class="reference" href="ptr_vector.html">ptr_vector</a></li>
307<li><a class="reference" href="ptr_list.html">ptr_list</a></li>
308<li><a class="reference" href="ptr_deque.html">ptr_deque</a></li>
309<li><a class="reference" href="ptr_array.html">ptr_array</a></li>
310</ul>
311</li>
312<li><a class="reference" href="associative_ptr_container.html">associative_ptr_container</a><ul>
313<li><a class="reference" href="ptr_set_adapter.html">ptr_set_adapter</a></li>
314<li><a class="reference" href="ptr_multiset_adapter.html">ptr_multiset_adapter</a></li>
315<li><a class="reference" href="ptr_map_adapter.html">ptr_map_adapter</a></li>
316<li><a class="reference" href="ptr_multimap_adapter.html">ptr_multi_map_adapter</a><ul>
317<li><a class="reference" href="ptr_set.html">ptr_set</a></li>
318<li><a class="reference" href="ptr_multiset.html">ptr_multi_set</a></li>
319<li><a class="reference" href="ptr_map.html">ptr_map</a></li>
320<li><a class="reference" href="ptr_multimap.html">ptr_multimap</a></li>
321</ul>
322</li>
323</ul>
324</li>
325</ul>
326</li>
327</ul>
328</li>
329<li><a class="reference" href="#serialization">Serialization</a></li>
330<li><a class="reference" href="indirect_fun.html">Indirected functions</a></li>
331<li><a class="reference" href="#class-nullable">Class nullable</a></li>
332<li><a class="reference" href="#exception-classes">Exception classes</a></li>
333<li><a class="reference" href="#disabling-the-use-of-exceptions">Disabling the use of exceptions</a></li>
334</ul>
335<!-- - Class `reversible_ptr_container <reversible_ptr_container.html>`_
336- Class `associative_ptr_container <associative_ptr_container.html>`_
337- `Pointer container adapters`_
338
339  - `ptr_sequence_adapter <ptr_sequence_adapter.html>`_
340  - `ptr_set_adapter <ptr_set_adapter.html>`_
341  - `ptr_multiset_adapter <ptr_multiset_adapter.html>`_
342  - `ptr_map_adapter <ptr_map_adapter.html>`_
343  - `ptr_multimap_adapter <ptr_multimap_adapter.html>`_   
344- `Sequence containers`_
345
346  - `ptr_vector <ptr_vector.html>`_
347  - `ptr_deque <ptr_deque.html>`_
348  - `ptr_list <ptr_list.html>`_
349  - `ptr_array <ptr_array.html>`_
350- `Associative containers`_
351
352  - `ptr_set <ptr_set.html>`_
353  - `ptr_multiset <ptr_multiset.html>`_
354  - `ptr_map <ptr_map.html>`_
355  - `ptr_multimap <ptr_multimap.html>`_ -->
356<div class="section">
357<h1><a id="the-clonable-concept" name="the-clonable-concept">The Clonable concept</a></h1>
358<p><strong>Refinement of</strong></p>
359<ul class="simple">
360<li>Heap Allocable</li>
361<li>Heap Deallocable</li>
362</ul>
363<p>The Clonable concept is introduced to formalize the requirements for
364copying heap-allocated objects.  A type <tt class="docutils literal"><span class="pre">T</span></tt> might be Clonable even though it
365is not Assignable or Copy Constructible.  Notice that many operations on
366the containers does not even require the stored type to be Clonable.</p>
367<p><strong>Notation</strong></p>
368<table border="1" class="docutils">
369<colgroup>
370<col width="21%" />
371<col width="41%" />
372<col width="18%" />
373<col width="20%" />
374</colgroup>
375<tbody valign="top">
376<tr><td><strong>Type</strong></td>
377<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>
378<td><strong>Pointer</strong></td>
379<td><strong>Describes</strong></td>
380</tr>
381<tr><td><tt class="docutils literal"><span class="pre">T</span></tt></td>
382<td><tt class="docutils literal"><span class="pre">a</span></tt></td>
383<td><tt class="docutils literal"><span class="pre">ptr</span></tt></td>
384<td>A Clonable type</td>
385</tr>
386</tbody>
387</table>
388<p><strong>Valid expressions</strong></p>
389<table border="1" class="docutils">
390<colgroup>
391<col width="19%" />
392<col width="14%" />
393<col width="46%" />
394<col width="20%" />
395</colgroup>
396<tbody valign="top">
397<tr><td><strong>Expression</strong></td>
398<td><strong>Type</strong></td>
399<td><strong>Semantics</strong></td>
400<td><strong>Postcondition</strong></td>
401</tr>
402<tr><td><tt class="docutils literal"><span class="pre">new_clone(a);</span></tt></td>
403<td><tt class="docutils literal"><span class="pre">T*</span></tt></td>
404<td>Allocate a new object that can be considered equivalent to the <tt class="docutils literal"><span class="pre">a</span></tt> object</td>
405<td><tt class="docutils literal"><span class="pre">typeid(*new_clone(a))</span> <span class="pre">==</span> <span class="pre">typeid(a)</span></tt></td>
406</tr>
407<tr><td><tt class="docutils literal"><span class="pre">delete_clone(ptr);</span></tt></td>
408<td><tt class="docutils literal"><span class="pre">void</span></tt></td>
409<td>Deallocate an object previously allocated with <tt class="docutils literal"><span class="pre">allocate_clone()</span></tt>. Must not throw</td>
410<td>&nbsp;</td>
411</tr>
412</tbody>
413</table>
414<div class="section">
415<h2><a id="default-implementation" name="default-implementation">Default implementation</a></h2>
416<p>In the <tt class="docutils literal"><span class="pre">&lt;boost/ptr_container/clone_allocator.hpp&gt;</span></tt> header a default implementation
417of the two functions is given:</p>
418<pre class="literal-block">
419namespace boost
420{
421    template&lt; class T &gt;
422    inline T* new_clone( const T&amp; t )
423    {
424        return new T( t );
425    }
426
427    template&lt; class T &gt;
428    void delete_clone( const T* t )
429    {
430        checked_delete( r );
431    }
432}
433</pre>
434<p>Notice that this implementation  makes normal Copy Constructible classes are automatically
435Clonable 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>
436<p>The two functions represent a layer of indirection which is necessary to support
437classes that are not Copy Constructible by default.  Notice that the implementation
438relies on argument-dependent lookup (ADL) to find the right version of
439<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
440the function is the boost namespace, but it can be placed together with
441the rest of the interface of the class.  If you are implementing a class
442inline in headers, remember to forward declare the functions.</p>
443<p><strong>Warning: We are considering to remove the default implementation above. Therefore always make sure that you overload the functions for your types and do not rely on the defaults in any way.</strong></p>
444</div>
445</div>
446<div class="section">
447<h1><a id="the-clone-allocator-concept" name="the-clone-allocator-concept">The Clone Allocator concept</a></h1>
448<p>The Clone Allocator concept is introduced to formalize the way
449pointer containers controls memory of
450the stored objects (and not the pointers to the stored objects).
451The clone allocator allows
452users to apply custom allocators/deallocators for the cloned objects.</p>
453<p>More information can be found below:</p>
454<div class="contents local topic">
455<ul class="simple">
456<li><a class="reference" href="#clone-allocator-requirements" id="id19" name="id19">Clone Allocator requirements</a></li>
457<li><a class="reference" href="#class-heap-clone-allocator" id="id20" name="id20">Class <tt class="docutils literal"><span class="pre">heap_clone_allocator</span></tt></a></li>
458<li><a class="reference" href="#class-view-clone-allocator" id="id21" name="id21">Class <tt class="docutils literal"><span class="pre">view_clone_allocator</span></tt></a></li>
459</ul>
460</div>
461<div class="section">
462<h2><a class="toc-backref" href="#id19" id="clone-allocator-requirements" name="clone-allocator-requirements">Clone Allocator requirements</a></h2>
463<p><strong>Notation</strong></p>
464<table border="1" class="docutils">
465<colgroup>
466<col width="18%" />
467<col width="39%" />
468<col width="43%" />
469</colgroup>
470<tbody valign="top">
471<tr><td><strong>Type</strong></td>
472<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>
473<td><strong>Describes</strong></td>
474</tr>
475<tr><td><tt class="docutils literal"><span class="pre">T</span></tt></td>
476<td><tt class="docutils literal"><span class="pre">a</span></tt></td>
477<td>A type</td>
478</tr>
479<tr><td><tt class="docutils literal"><span class="pre">T*</span></tt></td>
480<td><tt class="docutils literal"><span class="pre">ptr</span></tt></td>
481<td>A pointer to <tt class="docutils literal"><span class="pre">T</span></tt></td>
482</tr>
483</tbody>
484</table>
485<p><strong>Valid expressions</strong></p>
486<table border="1" class="docutils">
487<colgroup>
488<col width="23%" />
489<col width="7%" />
490<col width="39%" />
491<col width="31%" />
492</colgroup>
493<tbody valign="top">
494<tr><td><strong>Expression</strong></td>
495<td><strong>Type</strong></td>
496<td><strong>Semantics</strong></td>
497<td><strong>Postcondition</strong></td>
498</tr>
499<tr><td><tt class="docutils literal"><span class="pre">CloneAllocator::allocate_clone(a);</span></tt></td>
500<td><tt class="docutils literal"><span class="pre">T*</span></tt></td>
501<td>Allocate a new object that can be considered equivalent to the
502<tt class="docutils literal"><span class="pre">a</span></tt> object</td>
503<td><tt class="docutils literal"><span class="pre">typeid(*CloneAllocator::allocate_clone(a))</span> <span class="pre">==</span> <span class="pre">typeid(a)</span></tt></td>
504</tr>
505<tr><td><tt class="docutils literal"><span class="pre">CloneAllocator::deallocate_clone(ptr);</span></tt></td>
506<td><tt class="docutils literal"><span class="pre">void</span></tt></td>
507<td>Deallocate an object previously allocated with
508<tt class="docutils literal"><span class="pre">CloneAllocator::allocate_clone()</span></tt> or a compatible allocator.
509Must not throw.</td>
510<td>&nbsp;</td>
511</tr>
512</tbody>
513</table>
514<p>The library comes with two predefined clone allocators.</p>
515</div>
516<div class="section">
517<h2><a class="toc-backref" href="#id20" id="class-heap-clone-allocator" name="class-heap-clone-allocator">Class <tt class="docutils literal docutils literal"><span class="pre">heap_clone_allocator</span></tt></a></h2>
518<p>This is the default clone allocator used by all pointer containers. For most
519purposes you will never have to change this default.</p>
520<p><strong>Definition</strong></p>
521<pre class="literal-block">
522namespace boost
523{       
524    struct heap_clone_allocator
525    {
526        template&lt; class U &gt;
527        static U* allocate_clone( const U&amp; r )
528        {
529            return new_clone( r );
530        }
531
532        template&lt; class U &gt;
533        static void deallocate_clone( const U* r ) const
534        {
535            delete_clone( r );
536        }
537    };
538}
539</pre>
540<p>Notice that the above definition allows you to support custom allocation
541schemes 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>
542</div>
543<div class="section">
544<h2><a class="toc-backref" href="#id21" id="class-view-clone-allocator" name="class-view-clone-allocator">Class <tt class="docutils literal docutils literal"><span class="pre">view_clone_allocator</span></tt></a></h2>
545<p>This class provides a way to remove ownership properties of the
546pointer containers. As its name implies, this means that you can
547instead use the pointer containers as a view into an existing
548container.</p>
549<p><strong>Definition</strong></p>
550<pre class="literal-block">
551namespace boost
552{
553    struct view_clone_allocator
554    {
555        template&lt; class U &gt;
556        static U* allocate_clone( const U&amp; r )
557        {
558            return const_cast&lt;U*&gt;(&amp;r);
559        }
560
561        template&lt; class U &gt;
562        static void deallocate_clone( const U* )
563        {
564            // empty
565        }
566    };
567}
568</pre>
569<!-- **See also**
570
571- `Changing the clone allocator <examples.html#changing-the-clone-allocator>`_ -->
572</div>
573</div>
574<div class="section">
575<h1><a id="class-hierarchy" name="class-hierarchy">Class hierarchy</a></h1>
576<p>The library consists of the following types of classes:</p>
577<ol class="arabic simple">
578<li>Pointer container adapters</li>
579</ol>
580<!--  -->
581<ol class="arabic simple" start="2">
582<li>Pointer containers</li>
583</ol>
584<p>The pointer container adapters are used when you
585want to make a pointer container starting from
586your own &quot;normal&quot; container. For example, you
587might have a map class that is extends <tt class="docutils literal"><span class="pre">std::map</span></tt>
588in some way; the adapter class then allows you
589to use your map class as a basis for a new
590pointer container.</p>
591<p>The library provides an adapter for each type
592of standard container highlighted as links below:</p>
593<ul class="simple">
594<li><tt class="docutils literal"><span class="pre">reversible_ptr_container</span></tt><ul>
595<li><a class="reference" href="ptr_sequence_adapter.html">ptr_sequence_adapter</a><ul>
596<li><tt class="docutils literal"><span class="pre">ptr_vector</span></tt></li>
597<li><tt class="docutils literal"><span class="pre">ptr_list</span></tt></li>
598<li><tt class="docutils literal"><span class="pre">ptr_deque</span></tt></li>
599<li><tt class="docutils literal"><span class="pre">ptr_array</span></tt></li>
600</ul>
601</li>
602<li><tt class="docutils literal"><span class="pre">associative_ptr_container</span></tt><ul>
603<li><a class="reference" href="ptr_set_adapter.html">ptr_set_adapter</a></li>
604<li><a class="reference" href="ptr_multiset_adapter.html">ptr_multiset_adapter</a></li>
605<li><a class="reference" href="ptr_map_adapter.html">ptr_map_adapter</a></li>
606<li><a class="reference" href="ptr_multimap_adapter.html">ptr_multi_map_adapter</a><ul>
607<li><tt class="docutils literal"><span class="pre">ptr_set</span></tt></li>
608<li><tt class="docutils literal"><span class="pre">ptr_multi_set</span></tt></li>
609<li><tt class="docutils literal"><span class="pre">ptr_map</span></tt></li>
610<li><tt class="docutils literal"><span class="pre">ptr_multimap</span></tt></li>
611</ul>
612</li>
613</ul>
614</li>
615</ul>
616</li>
617</ul>
618<p>The pointer containers of this library are all built using
619the adapters. There is a pointer container
620for each type of &quot;normal&quot; standard container highlighted as links below.</p>
621<ul class="simple">
622<li><tt class="docutils literal"><span class="pre">reversible_ptr_container</span></tt><ul>
623<li><tt class="docutils literal"><span class="pre">ptr_sequence_adapter</span></tt><ul>
624<li><a class="reference" href="ptr_vector.html">ptr_vector</a></li>
625<li><a class="reference" href="ptr_list.html">ptr_list</a></li>
626<li><a class="reference" href="ptr_deque.html">ptr_deque</a></li>
627<li><a class="reference" href="ptr_array.html">ptr_array</a></li>
628</ul>
629</li>
630<li><tt class="docutils literal"><span class="pre">associative_ptr_container</span></tt><ul>
631<li><tt class="docutils literal"><span class="pre">ptr_set_adapter</span></tt></li>
632<li><tt class="docutils literal"><span class="pre">ptr_multiset_adapter</span></tt></li>
633<li><tt class="docutils literal"><span class="pre">ptr_map_adapter</span></tt></li>
634<li><tt class="docutils literal"><span class="pre">ptr_multi_map_adapter</span></tt><ul>
635<li><a class="reference" href="ptr_set.html">ptr_set</a></li>
636<li><a class="reference" href="ptr_multiset.html">ptr_multi_set</a></li>
637<li><a class="reference" href="ptr_map.html">ptr_map</a></li>
638<li><a class="reference" href="ptr_multimap.html">ptr_multimap</a></li>
639</ul>
640</li>
641</ul>
642</li>
643</ul>
644</li>
645</ul>
646</div>
647<div class="section">
648<h1><a id="serialization" name="serialization">Serialization</a></h1>
649<p>As of version 1.34.0 of Boost, the library support
650serialization as defined by <a class="reference" href="../../serialization/index.html">Boost.Serialization</a>.</p>
651<p>Of course, for serialization to work it is required
652that the stored type itself is serializable. For maps, both
653the key type and the mapped type must be serializable.</p>
654<p>When dealing with serialization (and serialization of polymophic objects in particular),
655pay special attention to these parts of Boost.Serialization:</p>
656<ol class="arabic">
657<li><p class="first">Output/saving requires a const-reference:</p>
658<pre class="literal-block">
659//
660// serialization helper: we can't save a non-const object
661//
662template&lt; class T &gt;
663inline T const&amp; as_const( T const&amp; r )
664{
665    return r;
666}
667...
668Container cont;
669
670std::ofstream ofs(&quot;filename&quot;);
671boost::archive::text_oarchive oa(ofs);
672oa &lt;&lt; as_const(cont);
673</pre>
674<p>See <a class="reference" href="../../serialization/doc/rationale.html#trap">Compile time trap when saving a non-const value</a> for
675details.</p>
676</li>
677</ol>
678<ol class="arabic" start="2">
679<li><p class="first">Derived classes need to call <tt class="docutils literal"><span class="pre">base_object()</span></tt> function:</p>
680<pre class="literal-block">
681struct Derived : Base
682{
683    template&lt; class Archive &gt;
684    void serialize( Archive&amp; ar, const unsigned int version )
685    {
686        ar &amp; boost::serialization::base_object&lt;Base&gt;( *this );
687        ...
688    }   
689};
690</pre>
691<p>For details, see <a class="reference" href="../../serialization/doc/tutorial.html#derivedclasses">Derived Classes</a>.</p>
692</li>
693</ol>
694<ol class="arabic" start="3">
695<li><p class="first">You need to use <tt class="docutils literal"><span class="pre">BOOST_CLASS_EXPORT</span></tt> to register the
696derived classes in your class hierarchy:</p>
697<pre class="literal-block">
698BOOST_CLASS_EXPORT( Derived )
699</pre>
700<p>See <a class="reference" href="../../serialization/doc/traits.html#export">Export Key</a> and <a class="reference" href="../../serialization/doc/special.html">Object Tracking</a>
701for details.</p>
702</li>
703</ol>
704<p>Remember these three issues and it will save you a lot of trouble.</p>
705<!-- Map iterator operations
706+++++++++++++++++++++++
707
708The map iterators are a bit different compared to the normal ones.  The
709reason is that it is a bit clumsy to access the key and the mapped object
710through i->first and i->second, and one tends to forget what is what.
711Moreover, and more importantly, we also want to hide the pointer as much as possibble.
712The new style can be illustrated with a small example::
713
714    typedef ptr_map<string,int> map_t;
715    map_t  m;
716    m[ "foo" ] = 4; // insert pair
717    m[ "bar" ] = 5; // ditto
718    ...
719    for( map_t::iterator i = m.begin(); i != m.end(); ++i )
720    {
721             *i += 42; // add 42 to each value
722             cout << "value=" << *i << ", key=" << i.key() << "n";
723    }
724   
725So the difference from the normal map iterator is that
726
727- ``operator*()`` returns a reference to the mapped object (normally it returns a reference to a ``std::pair``, and
728- that the key can be accessed through the ``key()`` function.  -->
729</div>
730<div class="section">
731<h1><a id="class-nullable" name="class-nullable">Class <tt class="docutils literal"><span class="pre">nullable</span></tt></a></h1>
732<p>The purpose of the class is simply to tell the containers
733that null values should be allowed. Its definition is
734trivial:</p>
735<pre class="literal-block">
736namespace boost
737{
738    template&lt; class T &gt;
739    struct nullable
740    {
741        typedef T type;
742    }; 
743}
744</pre>
745<p>Please notice that <tt class="docutils literal"><span class="pre">nullable</span></tt> has no effect on the containers
746interface (except for <tt class="docutils literal"><span class="pre">is_null()</span></tt> functions). For example, it
747does not make sense to do</p>
748<pre class="literal-block">
749boost::ptr_vector&lt; boost::nullable&lt;T&gt; &gt; vec;
750vec.push_back( 0 );                      // ok
751vec.push_back( new boost::nullable&lt;T&gt; ); // no no!
752boost::nullable&lt;T&gt;&amp; ref = vec[0];        // also no no!
753</pre>
754</div>
755<div class="section">
756<h1><a id="exception-classes" name="exception-classes">Exception classes</a></h1>
757<p>There are three exceptions that are thrown by this library.  The exception
758hierarchy looks as follows:</p>
759<pre class="literal-block">
760namespace boost
761{
762    class bad_ptr_container_operation : public std::exception
763    {
764    public:
765        bad_ptr_container_operation( const char* what );
766    };
767   
768    class bad_index : public bad_ptr_container_operation
769    {
770    public:
771        bad_index( const char* what );
772    };
773
774    class bad_pointer : public bad_ptr_container_operation
775    {
776    public:
777        bad_pointer();
778        bad_pointer( const char* what );
779    };
780}
781</pre>
782</div>
783<div class="section">
784<h1><a id="disabling-the-use-of-exceptions" name="disabling-the-use-of-exceptions">Disabling the use of exceptions</a></h1>
785<p>As of version 1.34.0 of Boost, the library allows you to disable exceptions
786completely. This means the library is more fit for domains where exceptions
787are not used. Furthermore, it also speeds up a operations a little. Instead
788of throwing an exception, the library simply calls <a class="reference" href="../../utility/assert.html">BOOST_ASSERT</a>.</p>
789<p>To diable exceptions, simly define this macro before including any header:</p>
790<pre class="literal-block">
791#define BOOST_PTR_CONTAINER_NO_EXCEPTIONS 1
792#include &lt;boost/ptr_container/ptr_vector.hpp&gt;
793</pre>
794<p>It is, however, recommended that you define the macro on the command-line, so
795you are absolutely certain that all headers are compiled the same way. Otherwise
796you might end up breaking the One Definition Rule.</p>
797<p>If <tt class="docutils literal"><span class="pre">BOOST_NO_EXCEPTIONS</span></tt> is defined, then <tt class="docutils literal"><span class="pre">BOOST_PTR_CONTAINER_NO_EXCEPTIONS</span></tt>
798is also defined.</p>
799<hr><p><strong>Navigate:</strong></p>
800<ul class="simple">
801<li><a class="reference" href="ptr_container.html">home</a></li>
802</ul>
803<hr><table class="docutils field-list" frame="void" rules="none">
804<col class="field-name" />
805<col class="field-body" />
806<tbody valign="top">
807<tr class="field"><th class="field-name">Copyright:</th><td class="field-body">Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see <a class="reference" href="http://www.boost.org/LICENSE_1_0.txt">LICENSE_1_0.txt</a>).</td>
808</tr>
809</tbody>
810</table>
811</div>
812</div>
813</body>
814</html>
Note: See TracBrowser for help on using the repository browser.