ceph/src/boost/libs/ptr_container/doc/examples.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="examples">Examples</h2>
 293 <p>Some examples are given here and in the accompanying test files:</p>
 294 <div class="contents local topic">
 295 <ul class="simple">
 296 <li><a class="reference" href="#null-pointers-cannot-be-stored-in-the-containers" id="id2" name="id2">1. Null pointers cannot be stored in the containers</a></li>
 297 <li><a class="reference" href="#iterators-and-other-operations-return-indirected-values" id="id3" name="id3">2. Iterators and other operations return indirected values</a></li>
 298 <li><a class="reference" href="#copy-semantics-of-pointer-containers" id="id4" name="id4">3. Copy-semantics of pointer containers</a></li>
 299 <li><a class="reference" href="#making-a-non-copyable-type-cloneable" id="id5" name="id5">4. Making a non-copyable type Cloneable</a></li>
 300 <li><a class="reference" href="#objects-are-cloned-before-insertion-inserted-pointers-are-owned-by-the-container" id="id6" name="id6">5. Objects are cloned before insertion, inserted pointers are owned by the container</a></li>
 301 <li><a class="reference" href="#transferring-ownership-of-a-single-element" id="id7" name="id7">6. Transferring ownership of a single element</a></li>
 302 <li><a class="reference" href="#transferring-ownership-of-pointers-between-different-pointer-containers" id="id8" name="id8">7. Transferring ownership of pointers between different pointer containers</a></li>
 303 <li><a class="reference" href="#selected-test-files" id="id9" name="id9">8. Selected test files</a></li>
 304 <li><a class="reference" href="#a-large-example" id="id10" name="id10">9. A large example</a></li>
 305 </ul>
 306 </div>
 307 <div class="section">
 308 <h1><a class="toc-backref" href="#id2" id="null-pointers-cannot-be-stored-in-the-containers" name="null-pointers-cannot-be-stored-in-the-containers"><span id="example-1"></span>1. Null pointers cannot be stored in the containers</a></h1>
 309 <pre class="literal-block">
 310 my_container.push_back( 0 );            // throws bad_ptr
 311 my_container.replace( an_iterator, 0 ); // throws bad_ptr
 312 my_container.insert( an_iterator, 0 );  // throws bad_ptr
 313 std::auto_ptr&lt;T&gt; p( 0 );
 314 my_container.push_back( p );            // throws bad_ptr
 315 </pre>
 316 </div>
 317 <div class="section">
 318 <h1><a class="toc-backref" href="#id3" id="iterators-and-other-operations-return-indirected-values" name="iterators-and-other-operations-return-indirected-values"><span id="example-2"></span>2. Iterators and other operations return indirected values</a></h1>
 319 <pre class="literal-block">
 320 ptr_vector&lt;X&gt; pvec;
 321 std::vector&lt;X*&gt; vec;
 322 *vec.begin()  = new X;   // fine, memory leak
 323 *pvec.begin() = new X;   // compile time error
 324 ( *vec.begin() )-&gt;foo(); // call X::foo(), a bit clumsy
 325 pvec.begin()-&gt;foo();     // no indirection needed
 326 *vec.front()  = X();     // overwrite first element
 327 pvec.front()  = X();     // no indirection needed
 328 </pre>
 329 </div>
 330 <div class="section">
 331 <h1><a class="toc-backref" href="#id4" id="copy-semantics-of-pointer-containers" name="copy-semantics-of-pointer-containers"><span id="example-3"></span>3. Copy-semantics of pointer containers</a></h1>
 332 <pre class="literal-block">
 333 ptr_vector&lt;T&gt; vec1;
 334 ...
 335 ptr_vector&lt;T&gt; vec2( vec1.clone() ); // deep copy objects of 'vec1' and use them to construct 'vec2', could be very expensive
 336 vec2 = vec1.release();              // give up ownership of pointers in 'vec1' and pass the ownership to 'vec2', rather cheap
 337 vec2.release();                     // give up ownership; the objects will be deallocated if not assigned to another container
 338 vec1 = vec2;                        // deep copy objects of 'vec2' and assign them to 'vec1', could be very expensive
 339 ptr_vector&lt;T&gt; vec3( vec1 );         // deep copy objects of 'vec1', could be very expensive
 340 </pre>
 341 </div>
 342 <div class="section">
 343 <h1><a class="toc-backref" href="#id5" id="making-a-non-copyable-type-cloneable" name="making-a-non-copyable-type-cloneable"><span id="example-4"></span>4. Making a non-copyable type Cloneable</a></h1>
 344 <pre class="literal-block">
 345  // a class that has no normal copy semantics
 346 class X : boost::noncopyable { public: X* clone() const; ... };
 347
 348 // this will be found by the library by argument dependent lookup (ADL)
 349 X* new_clone( const X&amp; x )
 350 { return x.clone(); }
 351
 352 // we can now use the interface that requires cloneability
 353 ptr_vector&lt;X&gt; vec1, vec2;
 354 ...
 355 vec2 = vec1.clone();                                 // 'clone()' requires cloning &lt;g&gt;
 356 vec2.insert( vec2.end(), vec1.begin(), vec1.end() ); // inserting always means inserting clones
 357 </pre>
 358 </div>
 359 <div class="section">
 360 <h1><a class="toc-backref" href="#id6" id="objects-are-cloned-before-insertion-inserted-pointers-are-owned-by-the-container" name="objects-are-cloned-before-insertion-inserted-pointers-are-owned-by-the-container"><span id="example-5"></span>5. Objects are cloned before insertion, inserted pointers are owned by the container</a></h1>
 361 <pre class="literal-block">
 362 class X { ... };                     // assume 'X' is Cloneable
 363 X x;                                 // and 'X' can be stack-allocated
 364 ptr_list&lt;X&gt; list;
 365 list.push_back( new_clone( x ) );    // insert a clone
 366 list.push_back( new X );             // always give the pointer directly to the container to avoid leaks
 367 list.push_back( &amp;x );                // don't do this!!!
 368 std::auto_ptr&lt;X&gt; p( new X );
 369 list.push_back( p );                 // give up ownership
 370 BOOST_ASSERT( p.get() == 0 );
 371 </pre>
 372 </div>
 373 <div class="section">
 374 <h1><a class="toc-backref" href="#id7" id="transferring-ownership-of-a-single-element" name="transferring-ownership-of-a-single-element"><span id="example-6"></span>6. Transferring ownership of a single element</a></h1>
 375 <pre class="literal-block">
 376 ptr_deque&lt;T&gt;                    deq;
 377 typedef ptr_deque&lt;T&gt;::auto_type auto_type;
 378
 379 // ... fill the container somehow
 380
 381 auto_type ptr  = deq.pop_back();                 // remove back element from container and give up ownership
 382 auto_type ptr2 = deq.release( deq.begin() + 2 ); // use an iterator to determine the element to release
 383 ptr            = deq.pop_front();                // supported for 'ptr_list' and 'ptr_deque'
 384
 385 deq.push_back( ptr.release() );                  // give ownership back to the container
 386 </pre>
 387 </div>
 388 <div class="section">
 389 <h1><a class="toc-backref" href="#id8" id="transferring-ownership-of-pointers-between-different-pointer-containers" name="transferring-ownership-of-pointers-between-different-pointer-containers"><span id="example-7"></span>7. Transferring ownership of pointers between different pointer containers</a></h1>
 390 <pre class="literal-block">
 391 ptr_list&lt;X&gt; list; ptr_vector&lt;X&gt; vec;
 392 ...
 393 //
 394 // note: no cloning happens in these examples
 395 //
 396 list.transfer( list.begin(), vec.begin(), vec );           // make the first element of 'vec' the first element of 'list'
 397 vec.transfer( vec.end(), list.begin(), list.end(), list ); // put all the lists element into the vector
 398 </pre>
 399 <p>We can also transfer objects from <tt class="docutils literal"><span class="pre">ptr_container&lt;Derived&gt;</span></tt> to <tt class="docutils literal"><span class="pre">ptr_container&lt;Base&gt;</span></tt> without any problems.</p>
 400 </div>
 401 <div class="section">
 402 <h1><a class="toc-backref" href="#id9" id="selected-test-files" name="selected-test-files"><span id="example-8"></span>8. Selected test files</a></h1>
 403 <table class="docutils field-list" frame="void" rules="none">
 404 <col class="field-name" />
 405 <col class="field-body" />
 406 <tbody valign="top">
 407 <tr class="field"><th class="field-name" colspan="2"><a class="reference" href="../test/incomplete_type_test.cpp">incomplete_type_test.cpp</a>:</th></tr>
 408 <tr><td>&nbsp;</td><td class="field-body">Shows how to implement the Composite pattern.</td>
 409 </tr>
 410 <tr class="field"><th class="field-name" colspan="2"><a class="reference" href="../test/simple_test.cpp">simple_test.cpp</a>:</th></tr>
 411 <tr><td>&nbsp;</td><td class="field-body">Shows how the usage of pointer container compares with a
 412 container of smart pointers</td>
 413 </tr>
 414 <tr class="field"><th class="field-name" colspan="2"><a class="reference" href="../test/view_example.cpp">view_example.cpp</a>:</th></tr>
 415 <tr><td>&nbsp;</td><td class="field-body">Shows how to use a pointer container as a view into other container</td>
 416 </tr>
 417 <tr class="field"><th class="field-name"><a class="reference" href="../test/tree_test.cpp">tree_test.cpp</a>:</th><td class="field-body">Shows how to make a tree-structure</td>
 418 </tr>
 419 <tr class="field"><th class="field-name"><a class="reference" href="../test/ptr_array.cpp">array_test.cpp</a>:</th><td class="field-body">Shows how to make an n-ary tree</td>
 420 </tr>
 421 </tbody>
 422 </table>
 423 </div>
 424 <div class="section">
 425 <h1><a class="toc-backref" href="#id10" id="a-large-example" name="a-large-example">9. A large example</a></h1>
 426 <p>This example shows many of the most common
 427 features at work. The example provide lots of comments.
 428 The source code can also be found <a class="reference" href="../test/tut1.cpp">here</a>.</p>
 429 <html>
 430 <head>
 431 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
 432 <title> </title>
 433 <link rel="stylesheet" href="default.css" type="text/css">
 434 </head>
 435
 436 <body>
 437     <pre><span class=comment>//
 438 // Boost.Pointer Container
 439 //
 440 //  Copyright Thorsten Ottosen 2003-2005. Use, modification and
 441 //  distribution is subject to the Boost Software License, Version
 442 //  1.0. (See accompanying file LICENSE_1_0.txt or copy at
 443 //  http://www.boost.org/LICENSE_1_0.txt)
 444 //
 445 // For more information, see http://www.boost.org/libs/ptr_container/
 446 //
 447
 448 //
 449 // This example is intended to get you started.
 450 // Notice how the smart container
 451 //
 452 // 1. takes ownership of objects
 453 // 2. transfers ownership
 454 // 3. applies indirection to iterators
 455 // 4. clones objects from other smart containers
 456 //
 457
 458 //
 459 // First we select which container to use.
 460 //</span>
 461 <span class=preprocessor>#include</span> <span class=special>&lt;</span><span class=identifier>boost</span><span class=special>/</span><span class=identifier>ptr_container</span><span class=special>/</span><span class=identifier>ptr_deque</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt;</span>
 462
 463 <span class=comment>//
 464 // we need these later in the example
 465 //</span>
 466 <span class=preprocessor>#include</span> <span class=special>&lt;</span><span class=identifier>boost</span><span class=special>/</span><span class=identifier>assert</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt;</span>
 467 <span class=preprocessor>#include</span> <span class=special>&lt;</span><span class=identifier>string</span><span class=special>&gt;</span>
 468 <span class=preprocessor>#include</span> <span class=special>&lt;</span><span class=identifier>exception</span><span class=special>&gt;</span>
 469
 470
 471 <span class=comment>//
 472 // Then we define a small polymorphic class
 473 // hierarchy.
 474 //</span>
 475
 476 <span class=keyword>class</span> <span class=identifier>animal</span> <span class=special>:</span> <span class=identifier>boost</span><span class=special>::</span><span class=identifier>noncopyable</span>
 477 <span class=special>{</span>
 478     <span class=keyword>virtual</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span> <span class=identifier>do_speak</span><span class=special>()</span> <span class=keyword>const</span> <span class=special>=</span> <span class=number>0</span><span class=special>;</span>
 479     <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span> <span class=identifier>name_</span><span class=special>;</span>
 480
 481 <span class=keyword>protected</span><span class=special>:</span>
 482     <span class=comment>//
 483     // Animals cannot be copied...
 484     //</span>
 485     <span class=identifier>animal</span><span class=special>(</span> <span class=keyword>const</span> <span class=identifier>animal</span><span class=special>&amp;</span> <span class=identifier>r</span> <span class=special>)</span> <span class=special>:</span> <span class=identifier>name_</span><span class=special>(</span> <span class=identifier>r</span><span class=special>.</span><span class=identifier>name_</span> <span class=special>)</span>           <span class=special>{</span> <span class=special>}</span>
 486     <span class=keyword>void</span> <span class=keyword>operator</span><span class=special>=(</span> <span class=keyword>const</span> <span class=identifier>animal</span><span class=special>&amp;</span> <span class=special>);</span>
 487
 488 <span class=keyword>private</span><span class=special>:</span>
 489     <span class=comment>//
 490     // ...but due to advances in genetics, we can clone them!
 491     //</span>
 492
 493     <span class=keyword>virtual</span> <span class=identifier>animal</span><span class=special>*</span> <span class=identifier>do_clone</span><span class=special>()</span> <span class=keyword>const</span> <span class=special>=</span> <span class=number>0</span><span class=special>;</span>
 494
 495 <span class=keyword>public</span><span class=special>:</span>
 496     <span class=identifier>animal</span><span class=special>(</span> <span class=keyword>const</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span><span class=special>&amp;</span> <span class=identifier>name</span> <span class=special>)</span> <span class=special>:</span> <span class=identifier>name_</span><span class=special>(</span><span class=identifier>name</span><span class=special>)</span>        <span class=special>{</span> <span class=special>}</span>
 497     <span class=keyword>virtual</span> <span class=special>~</span><span class=identifier>animal</span><span class=special>()</span> <span class=keyword>throw</span><span class=special>()</span>                              <span class=special>{</span> <span class=special>}</span>
 498
 499     <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span> <span class=identifier>speak</span><span class=special>()</span> <span class=keyword>const</span>
 500     <span class=special>{</span>
 501         <span class=keyword>return</span> <span class=identifier>do_speak</span><span class=special>();</span>
 502     <span class=special>}</span>
 503
 504     <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span> <span class=identifier>name</span><span class=special>()</span> <span class=keyword>const</span>
 505     <span class=special>{</span>
 506         <span class=keyword>return</span> <span class=identifier>name_</span><span class=special>;</span>
 507     <span class=special>}</span>
 508
 509     <span class=identifier>animal</span><span class=special>*</span> <span class=identifier>clone</span><span class=special>()</span> <span class=keyword>const</span>
 510     <span class=special>{</span>
 511         <span class=keyword>return</span> <span class=identifier>do_clone</span><span class=special>();</span>
 512     <span class=special>}</span>
 513 <span class=special>};</span>
 514
 515 <span class=comment>//
 516 // An animal is still not Clonable. We need this last hook.
 517 //
 518 // Notice that we pass the animal by const reference
 519 // and return by pointer.
 520 //</span>
 521
 522 <span class=identifier>animal</span><span class=special>*</span> <span class=identifier>new_clone</span><span class=special>(</span> <span class=keyword>const</span> <span class=identifier>animal</span><span class=special>&amp;</span> <span class=identifier>a</span> <span class=special>)</span>
 523 <span class=special>{</span>
 524     <span class=keyword>return</span> <span class=identifier>a</span><span class=special>.</span><span class=identifier>clone</span><span class=special>();</span>
 525 <span class=special>}</span>
 526
 527 <span class=comment>//
 528 // We do not need to define 'delete_clone()' since
 529 // since the default is to call the default 'operator delete()'.
 530 //</span>
 531
 532 <span class=keyword>const</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span> <span class=identifier>muuuh</span> <span class=special>=</span> <span class=string>&quot;Muuuh!&quot;</span><span class=special>;</span>
 533 <span class=keyword>const</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span> <span class=identifier>oiink</span> <span class=special>=</span> <span class=string>&quot;Oiiink&quot;</span><span class=special>;</span>
 534
 535 <span class=keyword>class</span> <span class=identifier>cow</span> <span class=special>:</span> <span class=keyword>public</span> <span class=identifier>animal</span>
 536 <span class=special>{</span>
 537     <span class=keyword>virtual</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span> <span class=identifier>do_speak</span><span class=special>()</span> <span class=keyword>const</span>
 538     <span class=special>{</span>
 539         <span class=keyword>return</span> <span class=identifier>muuuh</span><span class=special>;</span>
 540     <span class=special>}</span>
 541
 542     <span class=keyword>virtual</span> <span class=identifier>animal</span><span class=special>*</span> <span class=identifier>do_clone</span><span class=special>()</span> <span class=keyword>const</span>
 543     <span class=special>{</span>
 544         <span class=keyword>return</span> <span class=keyword>new</span> <span class=identifier>cow</span><span class=special>(</span> <span class=special>*</span><span class=keyword>this</span> <span class=special>);</span>
 545     <span class=special>}</span>
 546
 547 <span class=keyword>public</span><span class=special>:</span>
 548     <span class=identifier>cow</span><span class=special>(</span> <span class=keyword>const</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span><span class=special>&amp;</span> <span class=identifier>name</span> <span class=special>)</span> <span class=special>:</span> <span class=identifier>animal</span><span class=special>(</span><span class=identifier>name</span><span class=special>)</span>          <span class=special>{</span> <span class=special>}</span>
 549 <span class=special>};</span>
 550
 551 <span class=keyword>class</span> <span class=identifier>pig</span> <span class=special>:</span> <span class=keyword>public</span> <span class=identifier>animal</span>
 552 <span class=special>{</span>
 553     <span class=keyword>virtual</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span> <span class=identifier>do_speak</span><span class=special>()</span> <span class=keyword>const</span>
 554     <span class=special>{</span>
 555         <span class=keyword>return</span> <span class=identifier>oiink</span><span class=special>;</span>
 556     <span class=special>}</span>
 557
 558     <span class=keyword>virtual</span> <span class=identifier>animal</span><span class=special>*</span> <span class=identifier>do_clone</span><span class=special>()</span> <span class=keyword>const</span>
 559     <span class=special>{</span>
 560         <span class=keyword>return</span> <span class=keyword>new</span> <span class=identifier>pig</span><span class=special>(</span> <span class=special>*</span><span class=keyword>this</span> <span class=special>);</span>
 561     <span class=special>}</span>
 562
 563 <span class=keyword>public</span><span class=special>:</span>
 564     <span class=identifier>pig</span><span class=special>(</span> <span class=keyword>const</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span><span class=special>&amp;</span> <span class=identifier>name</span> <span class=special>)</span> <span class=special>:</span> <span class=identifier>animal</span><span class=special>(</span><span class=identifier>name</span><span class=special>)</span>          <span class=special>{</span> <span class=special>}</span>
 565 <span class=special>};</span>
 566
 567 <span class=comment>//
 568 // Then we, of course, need a place to put all
 569 // those animals.
 570 //</span>
 571
 572 <span class=keyword>class</span> <span class=identifier>farm</span>
 573 <span class=special>{</span>
 574     <span class=comment>//
 575     // This is where the smart containers are handy
 576     //</span>
 577     <span class=keyword>typedef</span> <span class=identifier>boost</span><span class=special>::</span><span class=identifier>ptr_deque</span><span class=special>&lt;</span><span class=identifier>animal</span><span class=special>&gt;</span> <span class=identifier>barn_type</span><span class=special>;</span>
 578     <span class=identifier>barn_type</span>                        <span class=identifier>barn</span><span class=special>;</span>
 579
 580     <span class=comment>//
 581     // An error type
 582     //</span>
 583     <span class=keyword>struct</span> <span class=identifier>farm_trouble</span> <span class=special>:</span> <span class=keyword>public</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>exception</span>           <span class=special>{</span> <span class=special>};</span>
 584
 585 <span class=keyword>public</span><span class=special>:</span>
 586     <span class=comment>//
 587     // We would like to make it possible to
 588     // iterate over the animals in the farm
 589     //</span>
 590     <span class=keyword>typedef</span> <span class=identifier>barn_type</span><span class=special>::</span><span class=identifier>iterator</span>  <span class=identifier>animal_iterator</span><span class=special>;</span>
 591
 592     <span class=comment>//
 593     // We also need to count the farm's size...
 594     //</span>
 595     <span class=keyword>typedef</span> <span class=identifier>barn_type</span><span class=special>::</span><span class=identifier>size_type</span> <span class=identifier>size_type</span><span class=special>;</span>
 596
 597     <span class=comment>//
 598     // And we also want to transfer an animal
 599     // safely around. The easiest way to think
 600     // about '::auto_type' is to imagine a simplified
 601     // 'std::auto_ptr&lt;T&gt;' ... this means you can expect
 602     //
 603     //   T* operator-&gt;()
 604     //   T* release()
 605     //   deleting destructor
 606     //
 607     // but not more.
 608     //</span>
 609     <span class=keyword>typedef</span> <span class=identifier>barn_type</span><span class=special>::</span><span class=identifier>auto_type</span>  <span class=identifier>animal_transport</span><span class=special>;</span>
 610
 611     <span class=comment>//
 612     // Create an empty farm.
 613     //</span>
 614     <span class=identifier>farm</span><span class=special>()</span>                                                 <span class=special>{</span> <span class=special>}</span>
 615
 616     <span class=comment>//
 617     // We need a constructor that can make a new
 618     // farm by cloning a range of animals.
 619     //</span>
 620     <span class=identifier>farm</span><span class=special>(</span> <span class=identifier>animal_iterator</span> <span class=identifier>begin</span><span class=special>,</span> <span class=identifier>animal_iterator</span> <span class=identifier>end</span> <span class=special>)</span>
 621      <span class=special>:</span>
 622         <span class=comment>//
 623         // Objects are always cloned before insertion
 624         // unless we explicitly add a pointer or
 625         // use 'release()'. Therefore we actually
 626         // clone all animals in the range
 627         //</span>
 628         <span class=identifier>barn</span><span class=special>(</span> <span class=identifier>begin</span><span class=special>,</span> <span class=identifier>end</span> <span class=special>)</span>                               <span class=special>{</span> <span class=special>}</span>
 629
 630     <span class=comment>//
 631     // ... so we need some other function too
 632     //</span>
 633
 634     <span class=identifier>animal_iterator</span> <span class=identifier>begin</span><span class=special>()</span>
 635     <span class=special>{</span>
 636         <span class=keyword>return</span> <span class=identifier>barn</span><span class=special>.</span><span class=identifier>begin</span><span class=special>();</span>
 637     <span class=special>}</span>
 638
 639     <span class=identifier>animal_iterator</span> <span class=identifier>end</span><span class=special>()</span>
 640     <span class=special>{</span>
 641         <span class=keyword>return</span> <span class=identifier>barn</span><span class=special>.</span><span class=identifier>end</span><span class=special>();</span>
 642     <span class=special>}</span>
 643
 644     <span class=comment>//
 645     // Here it is quite ok to have an 'animal*' argument.
 646     // The smart container will handle all ownership
 647     // issues.
 648     //</span>
 649     <span class=keyword>void</span> <span class=identifier>buy_animal</span><span class=special>(</span> <span class=identifier>animal</span><span class=special>*</span> <span class=identifier>a</span> <span class=special>)</span>
 650     <span class=special>{</span>
 651         <span class=identifier>barn</span><span class=special>.</span><span class=identifier>push_back</span><span class=special>(</span> <span class=identifier>a</span> <span class=special>);</span>
 652     <span class=special>}</span>
 653
 654     <span class=comment>//
 655     // The farm can also be in economical trouble and
 656     // therefore be in the need to sell animals.
 657     //</span>
 658     <span class=identifier>animal_transport</span> <span class=identifier>sell_animal</span><span class=special>(</span> <span class=identifier>animal_iterator</span> <span class=identifier>to_sell</span> <span class=special>)</span>
 659     <span class=special>{</span>
 660         <span class=keyword>if</span><span class=special>(</span> <span class=identifier>to_sell</span> <span class=special>==</span> <span class=identifier>end</span><span class=special>()</span> <span class=special>)</span>
 661             <span class=keyword>throw</span> <span class=identifier>farm_trouble</span><span class=special>();</span>
 662
 663         <span class=comment>//
 664         // Here we remove the animal from the barn,
 665         // but the animal is not deleted yet...it's
 666         // up to the buyer to decide what
 667         // to do with it.
 668         //</span>
 669         <span class=keyword>return</span> <span class=identifier>barn</span><span class=special>.</span><span class=identifier>release</span><span class=special>(</span> <span class=identifier>to_sell</span> <span class=special>);</span>
 670     <span class=special>}</span>
 671
 672     <span class=comment>//
 673     // How big a farm do we have?
 674     //</span>
 675     <span class=identifier>size_type</span> <span class=identifier>size</span><span class=special>()</span> <span class=keyword>const</span>
 676     <span class=special>{</span>
 677         <span class=keyword>return</span> <span class=identifier>barn</span><span class=special>.</span><span class=identifier>size</span><span class=special>();</span>
 678     <span class=special>}</span>
 679
 680     <span class=comment>//
 681     // If things are bad, we might choose to sell all animals :-(
 682     //</span>
 683     <span class=identifier>std</span><span class=special>::</span><span class=identifier>auto_ptr</span><span class=special>&lt;</span><span class=identifier>barn_type</span><span class=special>&gt;</span> <span class=identifier>sell_farm</span><span class=special>()</span>
 684     <span class=special>{</span>
 685         <span class=keyword>return</span> <span class=identifier>barn</span><span class=special>.</span><span class=identifier>release</span><span class=special>();</span>
 686     <span class=special>}</span>
 687
 688     <span class=comment>//
 689     // However, if things are good, we might buy somebody
 690     // else's farm :-)
 691     //</span>
 692
 693     <span class=keyword>void</span> <span class=identifier>buy_farm</span><span class=special>(</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>auto_ptr</span><span class=special>&lt;</span><span class=identifier>barn_type</span><span class=special>&gt;</span> <span class=identifier>other</span> <span class=special>)</span>
 694     <span class=special>{</span>
 695         <span class=comment>//
 696         // This line inserts all the animals from 'other'
 697         // and is guaranteed either to succeed or to have no
 698         // effect
 699         //</span>
 700         <span class=identifier>barn</span><span class=special>.</span><span class=identifier>transfer</span><span class=special>(</span> <span class=identifier>barn</span><span class=special>.</span><span class=identifier>end</span><span class=special>(),</span> <span class=comment>// insert new animals at the end</span>
 701                          <span class=special>*</span><span class=identifier>other</span> <span class=special>);</span>     <span class=comment>// we want to transfer all animals,
 702                                        // so we use the whole container as argument
 703         //
 704         // You might think you would have to do
 705         //
 706         // other.release();
 707         //
 708         // but '*other' is empty and can go out of scope as it wants
 709         //</span>
 710         <span class=identifier>BOOST_ASSERT</span><span class=special>(</span> <span class=identifier>other</span><span class=special>-&gt;</span><span class=identifier>empty</span><span class=special>()</span> <span class=special>);</span>
 711     <span class=special>}</span>
 712
 713 <span class=special>};</span> <span class=comment>// class 'farm'.</span>
 714
 715 <span class=keyword>int</span> <span class=identifier>main</span><span class=special>()</span>
 716 <span class=special>{</span>
 717     <span class=comment>//
 718     // First we make a farm
 719     //</span>
 720     <span class=identifier>farm</span> <span class=identifier>animal_farm</span><span class=special>;</span>
 721     <span class=identifier>BOOST_ASSERT</span><span class=special>(</span> <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>size</span><span class=special>()</span> <span class=special>==</span> <span class=number>0u</span> <span class=special>);</span>
 722
 723     <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>buy_animal</span><span class=special>(</span> <span class=keyword>new</span> <span class=identifier>pig</span><span class=special>(</span><span class=string>&quot;Betty&quot;</span><span class=special>)</span> <span class=special>);</span>
 724     <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>buy_animal</span><span class=special>(</span> <span class=keyword>new</span> <span class=identifier>pig</span><span class=special>(</span><span class=string>&quot;Benny&quot;</span><span class=special>)</span> <span class=special>);</span>
 725     <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>buy_animal</span><span class=special>(</span> <span class=keyword>new</span> <span class=identifier>pig</span><span class=special>(</span><span class=string>&quot;Jeltzin&quot;</span><span class=special>)</span> <span class=special>);</span>
 726     <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>buy_animal</span><span class=special>(</span> <span class=keyword>new</span> <span class=identifier>cow</span><span class=special>(</span><span class=string>&quot;Hanz&quot;</span><span class=special>)</span> <span class=special>);</span>
 727     <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>buy_animal</span><span class=special>(</span> <span class=keyword>new</span> <span class=identifier>cow</span><span class=special>(</span><span class=string>&quot;Mary&quot;</span><span class=special>)</span> <span class=special>);</span>
 728     <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>buy_animal</span><span class=special>(</span> <span class=keyword>new</span> <span class=identifier>cow</span><span class=special>(</span><span class=string>&quot;Frederik&quot;</span><span class=special>)</span> <span class=special>);</span>
 729     <span class=identifier>BOOST_ASSERT</span><span class=special>(</span> <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>size</span><span class=special>()</span> <span class=special>==</span> <span class=number>6u</span> <span class=special>);</span>
 730
 731     <span class=comment>//
 732     // Then we make another farm...it will actually contain
 733     // a clone of the other farm.
 734     //</span>
 735     <span class=identifier>farm</span> <span class=identifier>new_farm</span><span class=special>(</span> <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>begin</span><span class=special>(),</span> <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>end</span><span class=special>()</span> <span class=special>);</span>
 736     <span class=identifier>BOOST_ASSERT</span><span class=special>(</span> <span class=identifier>new_farm</span><span class=special>.</span><span class=identifier>size</span><span class=special>()</span> <span class=special>==</span> <span class=number>6u</span> <span class=special>);</span>
 737
 738     <span class=comment>//
 739     // Is it really clones in the new farm?
 740     //</span>
 741     <span class=identifier>BOOST_ASSERT</span><span class=special>(</span> <span class=identifier>new_farm</span><span class=special>.</span><span class=identifier>begin</span><span class=special>()-&gt;</span><span class=identifier>name</span><span class=special>()</span> <span class=special>==</span> <span class=string>&quot;Betty&quot;</span> <span class=special>);</span>
 742
 743     <span class=comment>//
 744     // Then we search for an animal, Mary (the Crown Princess of Denmark),
 745     // because we would like to buy her ...
 746     //</span>
 747     <span class=keyword>typedef</span> <span class=identifier>farm</span><span class=special>::</span><span class=identifier>animal_iterator</span> <span class=identifier>iterator</span><span class=special>;</span>
 748     <span class=identifier>iterator</span> <span class=identifier>to_sell</span><span class=special>;</span>
 749     <span class=keyword>for</span><span class=special>(</span> <span class=identifier>iterator</span> <span class=identifier>i</span>   <span class=special>=</span> <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>begin</span><span class=special>(),</span>
 750                   <span class=identifier>end</span> <span class=special>=</span> <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>end</span><span class=special>();</span>
 751          <span class=identifier>i</span> <span class=special>!=</span> <span class=identifier>end</span><span class=special>;</span> <span class=special>++</span><span class=identifier>i</span> <span class=special>)</span>
 752     <span class=special>{</span>
 753         <span class=keyword>if</span><span class=special>(</span> <span class=identifier>i</span><span class=special>-&gt;</span><span class=identifier>name</span><span class=special>()</span> <span class=special>==</span> <span class=string>&quot;Mary&quot;</span> <span class=special>)</span>
 754         <span class=special>{</span>
 755             <span class=identifier>to_sell</span> <span class=special>=</span> <span class=identifier>i</span><span class=special>;</span>
 756             <span class=keyword>break</span><span class=special>;</span>
 757         <span class=special>}</span>
 758     <span class=special>}</span>
 759
 760     <span class=identifier>farm</span><span class=special>::</span><span class=identifier>animal_transport</span> <span class=identifier>mary</span> <span class=special>=</span> <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>sell_animal</span><span class=special>(</span> <span class=identifier>to_sell</span> <span class=special>);</span>
 761
 762
 763     <span class=keyword>if</span><span class=special>(</span> <span class=identifier>mary</span><span class=special>-&gt;</span><span class=identifier>speak</span><span class=special>()</span> <span class=special>==</span> <span class=identifier>muuuh</span> <span class=special>)</span>
 764         <span class=comment>//
 765         // Great, Mary is a cow, and she may live longer
 766         //</span>
 767         <span class=identifier>new_farm</span><span class=special>.</span><span class=identifier>buy_animal</span><span class=special>(</span> <span class=identifier>mary</span><span class=special>.</span><span class=identifier>release</span><span class=special>()</span> <span class=special>);</span>
 768     <span class=keyword>else</span>
 769         <span class=comment>//
 770         // Then the animal would be destroyed (!)
 771         // when we go out of scope.
 772         //</span>
 773         <span class=special>;</span>
 774
 775     <span class=comment>//
 776     // Now we can observe some changes to the two farms...
 777     //</span>
 778     <span class=identifier>BOOST_ASSERT</span><span class=special>(</span> <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>size</span><span class=special>()</span> <span class=special>==</span> <span class=number>5u</span> <span class=special>);</span>
 779     <span class=identifier>BOOST_ASSERT</span><span class=special>(</span> <span class=identifier>new_farm</span><span class=special>.</span><span class=identifier>size</span><span class=special>()</span>    <span class=special>==</span> <span class=number>7u</span> <span class=special>);</span>
 780
 781     <span class=comment>//
 782     // The new farm has however underestimated how much
 783     // it cost to feed Mary and its owner is forced to sell the farm...
 784     //</span>
 785     <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>buy_farm</span><span class=special>(</span> <span class=identifier>new_farm</span><span class=special>.</span><span class=identifier>sell_farm</span><span class=special>()</span> <span class=special>);</span>
 786
 787     <span class=identifier>BOOST_ASSERT</span><span class=special>(</span> <span class=identifier>new_farm</span><span class=special>.</span><span class=identifier>size</span><span class=special>()</span>    <span class=special>==</span> <span class=number>0u</span> <span class=special>);</span>
 788     <span class=identifier>BOOST_ASSERT</span><span class=special>(</span> <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>size</span><span class=special>()</span> <span class=special>==</span> <span class=number>12u</span> <span class=special>);</span>
 789 <span class=special>}</span>
 790 </pre>
 791 </body>
 792
 793 </html>
 794 <!-- 10. Changing the Clone Allocator
 795 ++++++++++++++++++++++++++++++++
 796
 797 This example shows how we can change
 798 the Clone Allocator to use the pointer containers
 799 as view into other containers:
 800
 801 .. raw:: html
 802         :file: tut2.html -->
 803 <hr><p><strong>Navigate:</strong></p>
 804 <ul class="simple">
 805 <li><a class="reference" href="ptr_container.html">home</a></li>
 806 <li><a class="reference" href="reference.html">reference</a></li>
 807 </ul>
 808 <hr><table class="docutils field-list" frame="void" rules="none">
 809 <col class="field-name" />
 810 <col class="field-body" />
 811 <tbody valign="top">
 812 <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>
 813 </tr>
 814 </tbody>
 815 </table>
 816 </div>
 817 </div>
 818 </body>
 819 </html>