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">
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">
11 :Author: David Goodger
12 :Contact: goodger@users.sourceforge.net
15 :Copyright: This stylesheet has been placed in the public domain.
17 Default cascading style sheet for the HTML output of Docutils.
19 See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
20 customize this style sheet.
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 */
27 margin-top:
0 ! important }
29 .last, .with-subtitle {
30 margin-bottom:
0 ! important }
36 text-decoration: none ;
43 margin-bottom:
0.5em }
45 /* Uncomment (and remove this text!) to get bold-faced definition list terms
53 div.abstract p.topic-title {
57 div.admonition, div.attention, div.caution, div.danger, div.error,
58 div.hint, div.important, div.note, div.tip, div.warning {
60 border: medium outset ;
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 {
67 font-family: sans-serif }
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 {
74 font-family: sans-serif }
76 /* Uncomment (and remove this text!) to get reduced vertical space in
78 div.compound .compound-first, div.compound .compound-middle {
79 margin-bottom:
0.5em }
81 div.compound .compound-last, div.compound .compound-middle {
90 div.dedication p.topic-title {
97 div.footer, div.header {
106 div.line-block div.line-block {
113 border: medium outset ;
115 background-color: #ffffee ;
120 div.sidebar p.rubric {
121 font-family: sans-serif ;
124 div.system-messages {
127 div.system-messages h1 {
131 border: medium outset ;
134 div.system-message p.system-message-title {
141 h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
142 h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
163 ol.simple, ul.simple {
167 list-style: decimal }
170 list-style: lower-alpha }
173 list-style: upper-alpha }
176 list-style: lower-roman }
179 list-style: upper-roman }
193 white-space: nowrap }
202 font-family: sans-serif ;
207 font-family: sans-serif ;
223 pre.literal-block, pre.doctest-block {
226 background-color: #eeeeee }
229 font-family: sans-serif ;
230 font-style: oblique }
232 span.classifier-delimiter {
233 font-family: sans-serif ;
237 font-family: sans-serif }
240 white-space: nowrap }
248 span.section-subtitle {
249 /* font-size relative to parent (h1..h6 element) */
253 border-left: solid thin gray }
260 margin-bottom:
0.5em }
263 border-left: solid thin black }
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 }
271 table.docutils th.field-name, table.docinfo th.docinfo-name {
274 white-space: nowrap ;
277 h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
278 h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
282 background-color: #eeeeee }
285 list-style-type: none }
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">
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>
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
<T
> p(
0 );
314 my_container.push_back( p ); // throws bad_ptr
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
<X
> pvec;
321 std::vector
<X*
> vec;
322 *vec.begin() = new X; // fine, memory leak
323 *pvec.begin() = new X; // compile time error
324 ( *vec.begin() )-
>foo(); // call X::foo(), a bit clumsy
325 pvec.begin()-
>foo(); // no indirection needed
326 *vec.front() = X(); // overwrite first element
327 pvec.front() = X(); // no indirection needed
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
<T
> vec1;
335 ptr_vector
<T
> 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
<T
> vec3( vec1 ); // deep copy objects of 'vec1', could be very expensive
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; ... };
348 // this will be found by the library by argument dependent lookup (ADL)
349 X* new_clone( const X
& x )
350 { return x.clone(); }
352 // we can now use the interface that requires cloneability
353 ptr_vector
<X
> vec1, vec2;
355 vec2 = vec1.clone(); // 'clone()' requires cloning
<g
>
356 vec2.insert( vec2.end(), vec1.begin(), vec1.end() ); // inserting always means inserting clones
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
<X
> 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(
&x ); // don't do this!!!
368 std::auto_ptr
<X
> p( new X );
369 list.push_back( p ); // give up ownership
370 BOOST_ASSERT( p.get() ==
0 );
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
<T
> deq;
377 typedef ptr_deque
<T
>::auto_type auto_type;
379 // ... fill the container somehow
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'
385 deq.push_back( ptr.release() ); // give ownership back to the container
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
<X
> list; ptr_vector
<X
> vec;
394 // note: no cloning happens in these examples
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
399 <p>We can also transfer objects from
<tt class=
"docutils literal"><span class=
"pre">ptr_container
<Derived
></span></tt> to
<tt class=
"docutils literal"><span class=
"pre">ptr_container
<Base
></span></tt> without any problems.
</p>
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" />
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> </td><td class=
"field-body">Shows how to implement the Composite pattern.
</td>
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> </td><td class=
"field-body">Shows how the usage of pointer container compares with a
412 container of smart pointers
</td>
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> </td><td class=
"field-body">Shows how to use a pointer container as a view into other container
</td>
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>
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>
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>
431 <meta http-equiv=
"Content-Type" content=
"text/html; charset=ISO-8859-1">
433 <link rel=
"stylesheet" href=
"default.css" type=
"text/css">
437 <pre><span class=comment
>//
438 // Boost.Pointer Container
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)
445 // For more information, see http://www.boost.org/libs/ptr_container/
449 // This example is intended to get you started.
450 // Notice how the smart container
452 //
1. takes ownership of objects
453 //
2. transfers ownership
454 //
3. applies indirection to iterators
455 //
4. clones objects from other smart containers
459 // First we select which container to use.
461 <span class=preprocessor
>#include
</span> <span class=special
><</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
>></span>
463 <span class=comment
>//
464 // we need these later in the example
466 <span class=preprocessor
>#include
</span> <span class=special
><</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
>></span>
467 <span class=preprocessor
>#include
</span> <span class=special
><</span><span class=identifier
>string
</span><span class=special
>></span>
468 <span class=preprocessor
>#include
</span> <span class=special
><</span><span class=identifier
>exception
</span><span class=special
>></span>
471 <span class=comment
>//
472 // Then we define a small polymorphic class
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>
481 <span class=keyword
>protected
</span><span class=special
>:
</span>
482 <span class=comment
>//
483 // Animals cannot be copied...
485 <span class=identifier
>animal
</span><span class=special
>(
</span> <span class=keyword
>const
</span> <span class=identifier
>animal
</span><span class=special
>&</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
>&</span> <span class=special
>);
</span>
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!
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>
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
>&</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>
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>
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>
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>
515 <span class=comment
>//
516 // An animal is still not Clonable. We need this last hook.
518 // Notice that we pass the animal by const reference
519 // and return by pointer.
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
>&</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>
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()'.
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
>"Muuuh!
"</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
>"Oiiink
"</span><span class=special
>;
</span>
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>
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>
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
>&</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>
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>
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>
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
>&</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>
567 <span class=comment
>//
568 // Then we, of course, need a place to put all
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
577 <span class=keyword
>typedef
</span> <span class=identifier
>boost
</span><span class=special
>::
</span><span class=identifier
>ptr_deque
</span><span class=special
><</span><span class=identifier
>animal
</span><span class=special
>></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>
580 <span class=comment
>//
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>
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
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>
592 <span class=comment
>//
593 // We also need to count the farm's size...
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>
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
<T
>' ... this means you can expect
603 // T* operator-
>()
605 // deleting destructor
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>
611 <span class=comment
>//
612 // Create an empty farm.
614 <span class=identifier
>farm
</span><span class=special
>()
</span> <span class=special
>{
</span> <span class=special
>}
</span>
616 <span class=comment
>//
617 // We need a constructor that can make a new
618 // farm by cloning a range of animals.
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
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>
630 <span class=comment
>//
631 // ... so we need some other function too
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>
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>
644 <span class=comment
>//
645 // Here it is quite ok to have an 'animal*' argument.
646 // The smart container will handle all ownership
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>
654 <span class=comment
>//
655 // The farm can also be in economical trouble and
656 // therefore be in the need to sell animals.
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>
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
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>
672 <span class=comment
>//
673 // How big a farm do we have?
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>
680 <span class=comment
>//
681 // If things are bad, we might choose to sell all animals :-(
683 <span class=identifier
>std
</span><span class=special
>::
</span><span class=identifier
>auto_ptr
</span><span class=special
><</span><span class=identifier
>barn_type
</span><span class=special
>></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>
688 <span class=comment
>//
689 // However, if things are good, we might buy somebody
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
><</span><span class=identifier
>barn_type
</span><span class=special
>></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
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
704 // You might think you would have to do
708 // but '*other' is empty and can go out of scope as it wants
710 <span class=identifier
>BOOST_ASSERT
</span><span class=special
>(
</span> <span class=identifier
>other
</span><span class=special
>-
></span><span class=identifier
>empty
</span><span class=special
>()
</span> <span class=special
>);
</span>
711 <span class=special
>}
</span>
713 <span class=special
>};
</span> <span class=comment
>// class 'farm'.
</span>
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
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>
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
>"Betty
"</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
>"Benny
"</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
>"Jeltzin
"</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
>"Hanz
"</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
>"Mary
"</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
>"Frederik
"</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>
731 <span class=comment
>//
732 // Then we make another farm...it will actually contain
733 // a clone of the other farm.
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>
738 <span class=comment
>//
739 // Is it really clones in the new farm?
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
>()-
></span><span class=identifier
>name
</span><span class=special
>()
</span> <span class=special
>==
</span> <span class=string
>"Betty
"</span> <span class=special
>);
</span>
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 ...
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
>-
></span><span class=identifier
>name
</span><span class=special
>()
</span> <span class=special
>==
</span> <span class=string
>"Mary
"</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>
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>
763 <span class=keyword
>if
</span><span class=special
>(
</span> <span class=identifier
>mary
</span><span class=special
>-
></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
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.
773 <span class=special
>;
</span>
775 <span class=comment
>//
776 // Now we can observe some changes to the two farms...
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>
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...
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>
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>
794 <!-- 10. Changing the Clone Allocator
795 ++++++++++++++++++++++++++++++++
797 This example shows how we can change
798 the Clone Allocator to use the pointer containers
799 as view into other containers:
803 <hr><p><strong>Navigate:
</strong></p>
805 <li><a class=
"reference" href=
"ptr_container.html">home
</a></li>
806 <li><a class=
"reference" href=
"reference.html">reference
</a></li>
808 <hr><table class=
"docutils field-list" frame=
"void" rules=
"none">
809 <col class=
"field-name" />
810 <col class=
"field-body" />
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>