| 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.9: http://docutils.sourceforge.net/" /> |
|---|
| 7 | <title>Boost Pointer Container Library</title> |
|---|
| 8 | <link rel="stylesheet" href="default.css" type="text/css" /> |
|---|
| 9 | </head> |
|---|
| 10 | <body> |
|---|
| 11 | <div class="document" id="boost-pointer-container-library"> |
|---|
| 12 | <h1 class="title"><img alt="Boost" src="boost.png" /> Pointer Container Library</h1> |
|---|
| 13 | <h2 class="subtitle" id="conventions">Conventions</h2> |
|---|
| 14 | <p>There are a few design decisions that will affect how the classes are |
|---|
| 15 | used. Besides these the classes are much like normal standard containers |
|---|
| 16 | and provides almost the same interface. The new conventions are:</p> |
|---|
| 17 | <div class="contents topic" id="contents"> |
|---|
| 18 | <ul class="simple"> |
|---|
| 19 | <li><a class="reference" href="#null-pointers-are-not-allowed-by-default" id="id3" name="id3">Null pointers are not allowed by default</a></li> |
|---|
| 20 | <li><a class="reference" href="#all-default-iterators-apply-an-extra-layer-of-indirection" id="id4" name="id4">All default iterators apply an extra layer of indirection</a></li> |
|---|
| 21 | <li><a class="reference" href="#all-comparison-operations-are-done-on-the-pointed-to-objects-and-not-at-the-pointer-level" id="id5" name="id5">All comparison operations are done on the pointed to objects and not at the pointer level</a></li> |
|---|
| 22 | <li><a class="reference" href="#the-containers-are-neither-copy-constructible-nor-assignable" id="id6" name="id6">The containers are neither Copy Constructible nor Assignable</a></li> |
|---|
| 23 | <li><a class="reference" href="#stored-elements-are-required-to-be-clonable-for-a-subset-of-the-operations" id="id7" name="id7">Stored elements are required to be Clonable for a subset of the operations</a></li> |
|---|
| 24 | <li><a class="reference" href="#whenever-objects-are-inserted-into-a-container-they-are-cloned-before-insertion" id="id8" name="id8">Whenever objects are inserted into a container, they are cloned before insertion</a></li> |
|---|
| 25 | <li><a class="reference" href="#whenever-pointers-are-inserted-into-a-container-ownership-is-transferred-to-the-container" id="id9" name="id9">Whenever pointers are inserted into a container, ownership is transferred to the container</a></li> |
|---|
| 26 | <li><a class="reference" href="#ownership-can-be-transferred-from-a-container-on-a-per-pointer-basis" id="id10" name="id10">Ownership can be transferred from a container on a per pointer basis</a></li> |
|---|
| 27 | <li><a class="reference" href="#ownership-can-be-transferred-from-a-container-to-another-container-on-a-per-iterator-range-basis" id="id11" name="id11">Ownership can be transferred from a container to another container on a per iterator range basis</a></li> |
|---|
| 28 | <li><a class="reference" href="#a-container-can-be-cheaply-returned-from-functions-either-by-making-a-clone-or-by-giving-up-ownership-of-the-container" id="id12" name="id12">A container can be cheaply returned from functions either by making a clone or by giving up ownership of the container</a></li> |
|---|
| 29 | <li><a class="reference" href="#iterators-are-invalidated-as-in-the-corresponding-standard-container" id="id13" name="id13">Iterators are invalidated as in the corresponding standard container</a></li> |
|---|
| 30 | </ul> |
|---|
| 31 | </div> |
|---|
| 32 | <div class="section" id="null-pointers-are-not-allowed-by-default"> |
|---|
| 33 | <h1><a class="toc-backref" href="#id3" name="null-pointers-are-not-allowed-by-default">Null pointers are not allowed by default</a></h1> |
|---|
| 34 | <p>If the user tries to insert the null pointer, the operation will throw a |
|---|
| 35 | <tt class="docutils literal"><span class="pre">bad_pointer</span></tt> exception (see <a class="reference" href="examples.html">Example 1</a>).</p> |
|---|
| 36 | <p>Use <a class="reference" href="reference.html#class-nullable">nullable</a> to allow null pointers.</p> |
|---|
| 37 | <p>Please notice that all preconditions of the form</p> |
|---|
| 38 | <pre class="literal-block"> |
|---|
| 39 | x != 0; |
|---|
| 40 | </pre> |
|---|
| 41 | <p>are not active when the you have instantiated a container |
|---|
| 42 | with <tt class="docutils literal"><span class="pre">nullable<T></span></tt> as in</p> |
|---|
| 43 | <pre class="literal-block"> |
|---|
| 44 | boost::ptr_vector< boost::nullable<animal> > vec; |
|---|
| 45 | vec.push_back( 0 ); // ok |
|---|
| 46 | </pre> |
|---|
| 47 | </div> |
|---|
| 48 | <div class="section" id="all-default-iterators-apply-an-extra-layer-of-indirection"> |
|---|
| 49 | <h1><a class="toc-backref" href="#id4" name="all-default-iterators-apply-an-extra-layer-of-indirection">All default iterators apply an extra layer of indirection</a></h1> |
|---|
| 50 | <p>This is done to |
|---|
| 51 | make the containers easier and safer to use. It promotes a kind of |
|---|
| 52 | pointer-less programming and the user of a class needs not worry about |
|---|
| 53 | pointers except when allocating them (see <a class="reference" href="examples.html">Example 2</a>). Iterators that |
|---|
| 54 | provide access to the naked pointers are also provided since they might be |
|---|
| 55 | useful in rare cases. For example, whenever <tt class="docutils literal"><span class="pre">begin()</span></tt> returns an iterator, |
|---|
| 56 | <tt class="docutils literal"><span class="pre">ptr_begin()</span></tt> will return an iterator that allows one to iterate over the |
|---|
| 57 | stored pointers.</p> |
|---|
| 58 | </div> |
|---|
| 59 | <div class="section" id="all-comparison-operations-are-done-on-the-pointed-to-objects-and-not-at-the-pointer-level"> |
|---|
| 60 | <h1><a class="toc-backref" href="#id5" name="all-comparison-operations-are-done-on-the-pointed-to-objects-and-not-at-the-pointer-level">All comparison operations are done on the pointed to objects and not at the pointer level</a></h1> |
|---|
| 61 | <p>For example, in <tt class="docutils literal"><span class="pre">ptr_set<T></span></tt> the ordering is by default done by |
|---|
| 62 | <tt class="docutils literal"><span class="pre">boost::ptr_less<T></span></tt> which compares the indirected pointers. |
|---|
| 63 | Similarly, <tt class="docutils literal"><span class="pre">operator==()</span></tt> for <tt class="docutils literal"><span class="pre">container<Foo></span></tt> compares all objects |
|---|
| 64 | with <tt class="docutils literal"><span class="pre">operator==(const</span> <span class="pre">Foo&,</span> <span class="pre">const</span> <span class="pre">Foo&)</span></tt>.</p> |
|---|
| 65 | </div> |
|---|
| 66 | <div class="section" id="the-containers-are-neither-copy-constructible-nor-assignable"> |
|---|
| 67 | <h1><a class="toc-backref" href="#id6" name="the-containers-are-neither-copy-constructible-nor-assignable">The containers are neither Copy Constructible nor Assignable</a></h1> |
|---|
| 68 | <p>This is |
|---|
| 69 | because cloning a lot of pointers can be a very expensive operation; |
|---|
| 70 | instead functions are provided to transfer ownership. If a deep-copy is |
|---|
| 71 | needed anyway, every container has a <tt class="docutils literal"><span class="pre">clone()</span></tt> member function |
|---|
| 72 | (see <a class="reference" href="examples.html">Example 3</a>).</p> |
|---|
| 73 | </div> |
|---|
| 74 | <div class="section" id="stored-elements-are-required-to-be-clonable-for-a-subset-of-the-operations"> |
|---|
| 75 | <h1><a name="stored-elements-are-required-to-be-clonable-for-a-subset-of-the-operations">Stored elements are required to be <a class="reference" href="reference.html#the-clonable-concept">Clonable</a> for a subset of the operations</a></h1> |
|---|
| 76 | <p>This is because most polymorphic objects cannot be copied directly, but |
|---|
| 77 | they can often be so by a use of a member function (see <a class="reference" href="examples.html">Example 4</a>). Often |
|---|
| 78 | it does not even make sense to clone an object in which case a large |
|---|
| 79 | subset of the operations are still workable.</p> |
|---|
| 80 | </div> |
|---|
| 81 | <div class="section" id="whenever-objects-are-inserted-into-a-container-they-are-cloned-before-insertion"> |
|---|
| 82 | <h1><a class="toc-backref" href="#id8" name="whenever-objects-are-inserted-into-a-container-they-are-cloned-before-insertion">Whenever objects are inserted into a container, they are cloned before insertion</a></h1> |
|---|
| 83 | <p>This is necessary because all pointer containers take ownerships of stored objects |
|---|
| 84 | (see <a class="reference" href="examples.html">Example 5</a>).</p> |
|---|
| 85 | </div> |
|---|
| 86 | <div class="section" id="whenever-pointers-are-inserted-into-a-container-ownership-is-transferred-to-the-container"> |
|---|
| 87 | <h1><a class="toc-backref" href="#id9" name="whenever-pointers-are-inserted-into-a-container-ownership-is-transferred-to-the-container">Whenever pointers are inserted into a container, ownership is transferred to the container</a></h1> |
|---|
| 88 | <p>All containers take ownership of the stored pointers and therefore a |
|---|
| 89 | container needs to have its own copies (see <a class="reference" href="examples.html">Example 5</a>).</p> |
|---|
| 90 | </div> |
|---|
| 91 | <div class="section" id="ownership-can-be-transferred-from-a-container-on-a-per-pointer-basis"> |
|---|
| 92 | <h1><a class="toc-backref" href="#id10" name="ownership-can-be-transferred-from-a-container-on-a-per-pointer-basis">Ownership can be transferred from a container on a per pointer basis</a></h1> |
|---|
| 93 | <p>This can of course also be convenient. Whenever it happens, an |
|---|
| 94 | <tt class="docutils literal"><span class="pre">SmartContainer::auto_type</span></tt> object is used to provide an exception-safe transfer |
|---|
| 95 | (see <a class="reference" href="examples.html">Example 6</a>).</p> |
|---|
| 96 | </div> |
|---|
| 97 | <div class="section" id="ownership-can-be-transferred-from-a-container-to-another-container-on-a-per-iterator-range-basis"> |
|---|
| 98 | <h1><a class="toc-backref" href="#id11" name="ownership-can-be-transferred-from-a-container-to-another-container-on-a-per-iterator-range-basis">Ownership can be transferred from a container to another container on a per iterator range basis</a></h1> |
|---|
| 99 | <p>This makes it possible to exchange data safely between different pointer |
|---|
| 100 | containers without cloning the objects again (see <a class="reference" href="examples.html">Example 7</a>).</p> |
|---|
| 101 | </div> |
|---|
| 102 | <div class="section" id="a-container-can-be-cheaply-returned-from-functions-either-by-making-a-clone-or-by-giving-up-ownership-of-the-container"> |
|---|
| 103 | <h1><a class="toc-backref" href="#id12" name="a-container-can-be-cheaply-returned-from-functions-either-by-making-a-clone-or-by-giving-up-ownership-of-the-container">A container can be cheaply returned from functions either by making a clone or by giving up ownership of the container</a></h1> |
|---|
| 104 | <p>Two special member functions, <tt class="docutils literal"><span class="pre">clone()</span></tt> and <tt class="docutils literal"><span class="pre">release()</span></tt>, both return an |
|---|
| 105 | <tt class="docutils literal"><span class="pre">auto_ptr<SmartContainer></span></tt> which can be assigned to another pointer container. This |
|---|
| 106 | effectively reduces the cost of returning a container to one |
|---|
| 107 | heap-allocation plus a call to <tt class="docutils literal"><span class="pre">swap()</span></tt> (see <a class="reference" href="examples.html">Example 3</a>).</p> |
|---|
| 108 | </div> |
|---|
| 109 | <div class="section" id="iterators-are-invalidated-as-in-the-corresponding-standard-container"> |
|---|
| 110 | <h1><a class="toc-backref" href="#id13" name="iterators-are-invalidated-as-in-the-corresponding-standard-container">Iterators are invalidated as in the corresponding standard container</a></h1> |
|---|
| 111 | <p>Because the containers in this library wrap standard containers, the |
|---|
| 112 | rules for invalidation of iterators are the same as the rules |
|---|
| 113 | of the corresponding standard container.</p> |
|---|
| 114 | <p>For example, for both <tt class="docutils literal"><span class="pre">boost::ptr_vector<T></span></tt> and <tt class="docutils literal"><span class="pre">std::vector<U></span></tt> |
|---|
| 115 | insertion and deletion only invalidates the deleted |
|---|
| 116 | element and elements following it; all elements before the inserted/deleted |
|---|
| 117 | element remain valid.</p> |
|---|
| 118 | <p><strong>Navigate:</strong></p> |
|---|
| 119 | <ul class="simple"> |
|---|
| 120 | <li><a class="reference" href="ptr_container.html">home</a></li> |
|---|
| 121 | <li><a class="reference" href="reference.html">reference</a></li> |
|---|
| 122 | </ul> |
|---|
| 123 | <table class="docutils field-list" frame="void" rules="none"> |
|---|
| 124 | <col class="field-name" /> |
|---|
| 125 | <col class="field-body" /> |
|---|
| 126 | <tbody valign="top"> |
|---|
| 127 | <tr class="field"><th class="field-name">copyright:</th><td class="field-body">Thorsten Ottosen 2004-2005.</td> |
|---|
| 128 | </tr> |
|---|
| 129 | </tbody> |
|---|
| 130 | </table> |
|---|
| 131 | </div> |
|---|
| 132 | </div> |
|---|
| 133 | </body> |
|---|
| 134 | </html> |
|---|
