libs/ptr_container/doc/reference.html

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