ceph/src/boost/libs/ptr_container/doc/tutorial.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="tutorial">Tutorial</h2>
 293 <p>The tutorial shows you the most simple usage of the
 294 library. It is assumed that the reader is familiar
 295 with the use of standard containers. Although
 296 the tutorial is devided into sections, it is recommended
 297 that you read it all from top to bottom.</p>
 298 <ul class="simple">
 299 <li><a class="reference" href="#basic-usage">Basic usage</a></li>
 300 <li><a class="reference" href="#indirected-interface">Indirected interface</a></li>
 301 <li><a class="reference" href="#sequence-containers">Sequence containers</a></li>
 302 <li><a class="reference" href="#associative-containers">Associative containers</a></li>
 303 <li><a class="reference" href="#null-values">Null values</a></li>
 304 <li><a class="reference" href="#cloneability">Cloneability</a></li>
 305 <li><a class="reference" href="#new-functions">New functions</a></li>
 306 <li><a class="reference" href="#std-auto-ptr-u-overloads">std::auto_ptr&lt;U&gt; overloads</a></li>
 307 <li><a class="reference" href="#algorithms">Algorithms</a></li>
 308 </ul>
 309 <div class="section">
 310 <h1><a id="basic-usage" name="basic-usage">Basic usage</a></h1>
 311 <p>The most important aspect of a pointer container is that it manages
 312 memory for you. This means that you in most cases do not need to worry
 313 about deleting memory.</p>
 314 <p>Let us assume that we have an OO-hierarchy of animals</p>
 315 <pre class="literal-block">
 316 class animal : <a class="reference" href="http://www.boost.org/libs/utility/utility.htm#Class_noncopyable">boost::noncopyable</a>
 317 {
 318 public:
 319     virtual      ~animal()   {}
 320     virtual void eat()       = 0;
 321     virtual int  age() const = 0;
 322     // ...
 323 };
 324
 325 class mammal : public animal
 326 {
 327     // ...
 328 };
 329
 330 class bird : public animal
 331 {
 332     // ...
 333 };
 334 </pre>
 335 <p>Then the managing of the animals is straight-forward. Imagine a
 336 Zoo:</p>
 337 <pre class="literal-block">
 338 class zoo
 339 {
 340     boost::ptr_vector&lt;animal&gt; the_animals;
 341 public:
 342
 343     void add_animal( animal* a )
 344     {
 345         the_animals.push_back( a );
 346     }
 347 };
 348 </pre>
 349 <p>Notice how we just pass the class name to the container; there
 350 is no <tt class="docutils literal"><span class="pre">*</span></tt> to indicate it is a pointer.
 351 With this declaration we can now say:</p>
 352 <pre class="literal-block">
 353 zoo the_zoo;
 354 the_zoo.add_animal( new mammal(&quot;joe&quot;) );
 355 the_zoo.add_animal( new bird(&quot;dodo&quot;) );
 356 </pre>
 357 <p>Thus we heap-allocate all elements of the container
 358 and never rely on copy-semantics.</p>
 359 </div>
 360 <div class="section">
 361 <h1><a id="indirected-interface" name="indirected-interface">Indirected interface</a></h1>
 362 <p>A particular feature of the pointer containers is that
 363 the query interface is indirected. For example,</p>
 364 <pre class="literal-block">
 365 boost::ptr_vector&lt;animal&gt; vec;
 366 vec.push_back( new animal ); // you add it as pointer ...
 367 vec[0].eat();                // but get a reference back
 368 </pre>
 369 <p>This indirection also happens to iterators, so</p>
 370 <pre class="literal-block">
 371 typedef std::vector&lt;animal*&gt; std_vec;
 372 std_vec vec;
 373 ...
 374 std_vec::iterator i = vec.begin();
 375 (*i)-&gt;eat(); // '*' needed
 376 </pre>
 377 <p>now becomes</p>
 378 <pre class="literal-block">
 379 typedef boost::ptr_vector&lt;animal&gt;  ptr_vec;
 380 ptr_vec vec;
 381 ptr_vec::iterator i = vec.begin();
 382 i-&gt;eat(); // no indirection needed
 383 </pre>
 384 </div>
 385 <div class="section">
 386 <h1><a id="sequence-containers" name="sequence-containers">Sequence containers</a></h1>
 387 <p>The sequence containers are used when you do not need to
 388 keep an ordering on your elements. You can basically
 389 expect all operations of the normal standard containers
 390 to be available. So, for example, with a  <tt class="docutils literal"><span class="pre">ptr_deque</span></tt>
 391 and <tt class="docutils literal"><span class="pre">ptr_list</span></tt> object you can say:</p>
 392 <pre class="literal-block">
 393 boost::ptr_deque&lt;animal&gt; deq;
 394 deq.push_front( new animal );
 395 deq.pop_front();
 396 </pre>
 397 <p>because <tt class="docutils literal"><span class="pre">std::deque</span></tt> and <tt class="docutils literal"><span class="pre">std::list</span></tt> have <tt class="docutils literal"><span class="pre">push_front()</span></tt>
 398 and <tt class="docutils literal"><span class="pre">pop_front()</span></tt> members.</p>
 399 <p>If the standard sequence supports
 400 random access, so does the pointer container; for example:</p>
 401 <pre class="literal-block">
 402 for( boost::ptr_deque&lt;animal&gt;::size_type i = 0u;
 403      i != deq.size(); ++i )
 404      deq[i].eat();
 405 </pre>
 406 <p>The <tt class="docutils literal"><span class="pre">ptr_vector</span></tt> also allows you to specify the size of
 407 the buffer to allocate; for example</p>
 408 <pre class="literal-block">
 409 boost::ptr_vector&lt;animal&gt; animals( 10u );
 410 </pre>
 411 <p>will reserve room for 10 animals.</p>
 412 </div>
 413 <div class="section">
 414 <h1><a id="associative-containers" name="associative-containers">Associative containers</a></h1>
 415 <p>To keep an ordering on our animals, we could use a <tt class="docutils literal"><span class="pre">ptr_set</span></tt>:</p>
 416 <pre class="literal-block">
 417 boost::ptr_set&lt;animal&gt; set;
 418 set.insert( new monkey(&quot;bobo&quot;) );
 419 set.insert( new whale(&quot;anna&quot;) );
 420 ...
 421 </pre>
 422 <p>This requires that <tt class="docutils literal"><span class="pre">operator&lt;()</span></tt> is defined for animals. One
 423 way to do this could be</p>
 424 <pre class="literal-block">
 425 inline bool operator&lt;( const animal&amp; l, const animal&amp; r )
 426 {
 427     return l.name() &lt; r.name();
 428 }
 429 </pre>
 430 <p>if we wanted to keep the animals sorted by name.</p>
 431 <p>Maybe you want to keep all the animals in zoo ordered wrt.
 432 their name, but it so happens that many animals have the
 433 same name. We can then use a <tt class="docutils literal"><span class="pre">ptr_multimap</span></tt>:</p>
 434 <pre class="literal-block">
 435 typedef boost::ptr_multimap&lt;std::string,animal&gt; zoo_type;
 436 zoo_type zoo;
 437 std::string bobo = &quot;bobo&quot;,
 438             anna = &quot;anna&quot;;
 439 zoo.insert( bobo, new monkey(bobo) );
 440 zoo.insert( bobo, new elephant(bobo) );
 441 zoo.insert( anna, new whale(anna) );
 442 zoo.insert( anna, new emu(anna) );
 443 </pre>
 444 <p>Note that must create the key as an lvalue
 445 (due to exception-safety issues); the following would not
 446 have compiled</p>
 447 <pre class="literal-block">
 448 zoo.insert( &quot;bobo&quot;, // this is bad, but you get compile error
 449             new monkey(&quot;bobo&quot;) );
 450 </pre>
 451 <p>If a multimap is not needed, we can use <tt class="docutils literal"><span class="pre">operator[]()</span></tt>
 452 to avoid the clumsiness:</p>
 453 <pre class="literal-block">
 454 boost::ptr_map&lt;std::string,animal&gt; animals;
 455 animals[&quot;bobo&quot;].set_name(&quot;bobo&quot;);
 456 </pre>
 457 <p>This requires a default constructor for animals and
 458 a function to do the initialization, in this case <tt class="docutils literal"><span class="pre">set_name()</span></tt>.</p>
 459 <p>A better alternative is to use <a class="reference" href="../../assign/index.html">Boost.Assign</a>
 460 to help you out. In particular, consider</p>
 461 <ul class="simple">
 462 <li><a class="reference" href="../../assign/doc/index.html#ptr_push_back">ptr_push_back(), ptr_push_front(), ptr_insert() and ptr_map_insert()</a></li>
 463 <li><a class="reference" href="../../assign/doc/index.html#ptr_list_of">ptr_list_of()</a></li>
 464 </ul>
 465 <p>For example, the above insertion may now be written</p>
 466 <pre class="literal-block">
 467 boost::ptr_multimap&lt;std::string,animal&gt; animals;
 468
 469 using namespace boost::assign;
 470 ptr_map_insert&lt;monkey&gt;( animals )( &quot;bobo&quot;, &quot;bobo&quot; );
 471 ptr_map_insert&lt;elephant&gt;( animals )( &quot;bobo&quot;, &quot;bobo&quot; );
 472 ptr_map_insert&lt;whale&gt;( animals )( &quot;anna&quot;, &quot;anna&quot; );
 473 ptr_map_insert&lt;emu&gt;( animals )( &quot;anna&quot;, &quot;anna&quot; );
 474 </pre>
 475 </div>
 476 <div class="section">
 477 <h1><a id="null-values" name="null-values">Null values</a></h1>
 478 <p>By default, if you try to insert null into a container, an exception
 479 is thrown. If you want to allow nulls, then you must
 480 say so explicitly when declaring the container variable</p>
 481 <pre class="literal-block">
 482 boost::ptr_vector&lt; boost::nullable&lt;animal&gt; &gt; animals_type;
 483 animals_type animals;
 484 ...
 485 animals.insert( animals.end(), new dodo(&quot;fido&quot;) );
 486 animals.insert( animals.begin(), 0 ) // ok
 487 </pre>
 488 <p>Once you have inserted a null into the container, you must
 489 always check if the value is null before accessing the object</p>
 490 <pre class="literal-block">
 491 for( animals_type::iterator i = animals.begin();
 492      i != animals.end(); ++i )
 493 {
 494     if( !boost::is_null(i) ) // always check for validity
 495         i-&gt;eat();
 496 }
 497 </pre>
 498 <p>If the container support random access, you may also check this as</p>
 499 <pre class="literal-block">
 500 for( animals_type::size_type i = 0u;
 501      i != animals.size(); ++i )
 502 {
 503     if( !animals.is_null(i) )
 504          animals[i].eat();
 505 }
 506 </pre>
 507 <p>Note that it is meaningless to insert
 508 null into <tt class="docutils literal"><span class="pre">ptr_set</span></tt> and <tt class="docutils literal"><span class="pre">ptr_multiset</span></tt>.</p>
 509 </div>
 510 <div class="section">
 511 <h1><a id="cloneability" name="cloneability">Cloneability</a></h1>
 512 <p>In OO programming it is typical to prohibit copying of objects; the
 513 objects may sometimes be allowed to be Cloneable; for example,:</p>
 514 <pre class="literal-block">
 515 animal* animal::clone() const
 516 {
 517     return do_clone(); // implemented by private virtual function
 518 }
 519 </pre>
 520 <p>If the OO hierarchy thus allows cloning, we need to tell the
 521 pointer containers how cloning is to be done. This is simply
 522 done by defining a free-standing function, <tt class="docutils literal"><span class="pre">new_clone()</span></tt>,
 523 in the same namespace as
 524 the object hierarchy:</p>
 525 <pre class="literal-block">
 526 inline animal* new_clone( const animal&amp; a )
 527 {
 528     return a.clone();
 529 }
 530 </pre>
 531 <p>That is all, now a lot of functions in a pointer container
 532 can exploit the cloneability of the animal objects. For example</p>
 533 <pre class="literal-block">
 534 typedef boost::ptr_list&lt;animal&gt; zoo_type;
 535 zoo_type zoo, another_zoo;
 536 ...
 537 another_zoo.assign( zoo.begin(), zoo.end() );
 538 </pre>
 539 <p>will fill another zoo with clones of the first zoo. Similarly,
 540 <tt class="docutils literal"><span class="pre">insert()</span></tt> can now insert clones into your pointer container</p>
 541 <pre class="literal-block">
 542 another_zoo.insert( another_zoo.begin(), zoo.begin(), zoo.end() );
 543 </pre>
 544 <p>The whole container can now also be cloned</p>
 545 <pre class="literal-block">
 546 zoo_type yet_another_zoo = zoo.clone();
 547 </pre>
 548 <p>Copying or assigning the container has the same effect as cloning (though it is slightly cheaper):</p>
 549 <pre class="literal-block">
 550 zoo_type yet_another_zoo = zoo;
 551 </pre>
 552 <p>Copying also support derived-to-base class conversions:</p>
 553 <pre class="literal-block">
 554 boost::ptr_vector&lt;monkey&gt; monkeys = boost::assign::ptr_list_of&lt;monkey&gt;( &quot;bobo&quot; )( &quot;bebe&quot;)( &quot;uhuh&quot; );
 555 boost::ptr_vector&lt;animal&gt; animals = monkeys;
 556 </pre>
 557 <p>This also works for maps:</p>
 558 <pre class="literal-block">
 559 boost::ptr_map&lt;std::string,monkey&gt; monkeys = ...;
 560 boost::ptr_map&lt;std::string,animal&gt; animals = monkeys;
 561 </pre>
 562 </div>
 563 <div class="section">
 564 <h1><a id="new-functions" name="new-functions">New functions</a></h1>
 565 <p>Given that we know we are working with pointers, a few new functions
 566 make sense. For example, say you want to remove an
 567 animal from the zoo</p>
 568 <pre class="literal-block">
 569 zoo_type::auto_type the_animal = zoo.release( zoo.begin() );
 570 the_animal-&gt;eat();
 571 animal* the_animal_ptr = the_animal.release(); // now this is not deleted
 572 zoo.release(2); // for random access containers
 573 </pre>
 574 <p>You can think of <tt class="docutils literal"><span class="pre">auto_type</span></tt> as a non-copyable form of
 575 <tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt>. Notice that when you release an object, the
 576 pointer is removed from the container and the containers size
 577 shrinks. For containers that store nulls, we can exploit that
 578 <tt class="docutils literal"><span class="pre">auto_type</span></tt> is convertible to <tt class="docutils literal"><span class="pre">bool</span></tt>:</p>
 579 <pre class="literal-block">
 580 if( ptr_vector&lt; nullable&lt;T&gt; &gt;::auto_type r = vec.pop_back() )
 581 {
 582   ...
 583 }
 584 </pre>
 585 <p>You can also release the entire container if you
 586 want to return it from a function</p>
 587 <pre class="literal-block">
 588 std::auto_ptr&lt; boost::ptr_deque&lt;animal&gt; &gt; get_zoo()
 589 {
 590     boost::ptr_deque&lt;animal&gt;  result;
 591     ...
 592     return result.release(); // give up ownership
 593 }
 594 ...
 595 boost::ptr_deque&lt;animal&gt; animals = get_zoo();
 596 </pre>
 597 <p>Let us assume we want to move an animal object from
 598 one zoo to another. In other words, we want to move the
 599 animal and the responsibility of it to another zoo</p>
 600 <pre class="literal-block">
 601 another_zoo.transfer( another_zoo.end(), // insert before end
 602                       zoo.begin(),       // insert this animal ...
 603                       zoo );             // from this container
 604 </pre>
 605 <p>This kind of &quot;move-semantics&quot; is different from
 606 normal value-based containers. You can think of <tt class="docutils literal"><span class="pre">transfer()</span></tt>
 607 as the same as <tt class="docutils literal"><span class="pre">splice()</span></tt> on <tt class="docutils literal"><span class="pre">std::list</span></tt>.</p>
 608 <p>If you want to replace an element, you can easily do so</p>
 609 <pre class="literal-block">
 610 zoo_type::auto_type old_animal = zoo.replace( zoo.begin(), new monkey(&quot;bibi&quot;) );
 611 zoo.replace( 2, old_animal.release() ); // for random access containers
 612 </pre>
 613 <p>A map is slightly different to iterate over than standard maps.
 614 Now we say</p>
 615 <pre class="literal-block">
 616 typedef boost::ptr_map&lt;std::string, boost::nullable&lt;animal&gt; &gt; animal_map;
 617 animal_map map;
 618 ...
 619 for( animal_map::const_iterator i = map.begin(), e = map.end(); i != e; ++i )
 620 {
 621     std::cout &lt;&lt; &quot;\n key: &quot; &lt;&lt; i-&gt;first;
 622     std::cout &lt;&lt; &quot;\n age: &quot;;
 623
 624     if( boost::is_null(i) )
 625         std::cout &lt;&lt; &quot;unknown&quot;;
 626     else
 627         std::cout &lt;&lt; i-&gt;second-&gt;age();
 628  }
 629 </pre>
 630 <p>Except for the check for null, this looks like it would with a normal map. But if <tt class="docutils literal"><span class="pre">age()</span></tt> had
 631 not been a <tt class="docutils literal"><span class="pre">const</span></tt> member function,
 632 it would not have compiled.</p>
 633 <p>Maps can also be indexed with bounds-checking</p>
 634 <pre class="literal-block">
 635 try
 636 {
 637     animal&amp; bobo = map.at(&quot;bobo&quot;);
 638 }
 639 catch( boost::bad_ptr_container_operation&amp; e )
 640 {
 641     // &quot;bobo&quot; not found
 642 }
 643 </pre>
 644 </div>
 645 <div class="section">
 646 <h1><a id="std-auto-ptr-u-overloads" name="std-auto-ptr-u-overloads"><tt class="docutils literal"><span class="pre">std::auto_ptr&lt;U&gt;</span></tt> overloads</a></h1>
 647 <p>Every time there is a function that takes a <tt class="docutils literal"><span class="pre">T*</span></tt> parameter, there is
 648 also a function taking an <tt class="docutils literal"><span class="pre">std::auto_ptr&lt;U&gt;</span></tt> parameter. This is of course done
 649 to make the library intregrate seamlessly with <tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt>. For example</p>
 650 <pre class="literal-block">
 651 std::ptr_vector&lt;Base&gt; vec;
 652 vec.push_back( new Base );
 653 </pre>
 654 <p>is complemented by</p>
 655 <pre class="literal-block">
 656 std::auto_ptr&lt;Derived&gt; p( new Derived );
 657 vec.push_back( p );
 658 </pre>
 659 <p>Notice that the template argument for <tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt> does not need to
 660 follow the template argument for <tt class="docutils literal"><span class="pre">ptr_vector</span></tt> as long as <tt class="docutils literal"><span class="pre">Derived*</span></tt>
 661 can be implicitly converted to <tt class="docutils literal"><span class="pre">Base*</span></tt>.</p>
 662 </div>
 663 <div class="section">
 664 <h1><a id="algorithms" name="algorithms">Algorithms</a></h1>
 665 <p>Unfortunately it is not possible to use pointer containers with
 666 mutating algorithms from the standard library. However,
 667 the most useful ones
 668 are instead provided as member functions:</p>
 669 <pre class="literal-block">
 670 boost::ptr_vector&lt;animal&gt; zoo;
 671 ...
 672 zoo.sort();                               // assume 'bool operator&lt;( const animal&amp;, const animal&amp; )'
 673 zoo.sort( std::less&lt;animal&gt;() );          // the same, notice no '*' is present
 674 zoo.sort( zoo.begin(), zoo.begin() + 5 ); // sort selected range
 675 </pre>
 676 <p>Notice that predicates are automatically wrapped in an <a class="reference" href="indirect_fun.html">indirect_fun</a> object.</p>
 677 <p>You can remove equal and adjacent elements using <tt class="docutils literal"><span class="pre">unique()</span></tt>:</p>
 678 <pre class="literal-block">
 679 zoo.unique();                             // assume 'bool operator==( const animal&amp;, const animal&amp; )'
 680 zoo.unique( zoo.begin(), zoo.begin() + 5, my_comparison_predicate() );
 681 </pre>
 682 <p>If you just want to remove certain elements, use <tt class="docutils literal"><span class="pre">erase_if</span></tt>:</p>
 683 <pre class="literal-block">
 684 zoo.erase_if( my_predicate() );
 685 </pre>
 686 <p>Finally you may want to merge two sorted containers:</p>
 687 <pre class="literal-block">
 688 boost::ptr_vector&lt;animal&gt; another_zoo = ...;
 689 another_zoo.sort();                      // sorted wrt. to same order as 'zoo'
 690 zoo.merge( another_zoo );
 691 BOOST_ASSERT( another_zoo.empty() );
 692 </pre>
 693 <p>That is all; now you have learned all the basics!</p>
 694 <hr><p><strong>See also</strong></p>
 695 <ul class="simple">
 696 <li><a class="reference" href="guidelines.html">Usage guidelines</a></li>
 697 <li><a class="reference" href="../../conversion/cast.htm#Polymorphic_castl">Cast utilities</a></li>
 698 </ul>
 699 <p><strong>Navigate</strong></p>
 700 <ul class="simple">
 701 <li><a class="reference" href="ptr_container.html">home</a></li>
 702 <li><a class="reference" href="examples.html">examples</a></li>
 703 </ul>
 704 <hr><table class="docutils field-list" frame="void" rules="none">
 705 <col class="field-name" />
 706 <col class="field-body" />
 707 <tbody valign="top">
 708 <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>
 709 </tr>
 710 </tbody>
 711 </table>
 712 </div>
 713 </div>
 714 </body>
 715 </html>