File: ptr_container.html

package info (click to toggle)
boost 1.34.1-14
links: PTS
area: main
in suites: lenny
size: 116,412 kB
ctags: 259,566
sloc: cpp: 642,395; xml: 56,450; python: 17,612; ansic: 14,520; sh: 2,265; yacc: 858; perl: 481; makefile: 478; lex: 94; sql: 74; csh: 6
file content (569 lines) | stat: -rw-r--r-- 20,934 bytes
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.3.10: http://docutils.sourceforge.net/" />
<title>Boost Pointer Container Library</title>
<meta name="author" content="Thorsten Ottosen" />
<meta name="date" content="29th of April 2006" />
<meta name="copyright" content="Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt)." />
<style type="text/css">

/*
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:Date: $Date: 2006/11/22 22:01:00 $
:Revision: $Revision: 1.7.2.4 $
:Copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.

See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/

/* "! important" is used here to override other ``margin-top`` and
   ``margin-bottom`` styles that are later in the stylesheet or 
   more specific.  See http://www.w3.org/TR/CSS1#the-cascade */
.first {
  margin-top: 0 ! important }

.last, .with-subtitle {
  margin-bottom: 0 ! important }

.hidden {
  display: none }

a.toc-backref {
  text-decoration: none ;
  color: black }

blockquote.epigraph {
  margin: 2em 5em ; }

dl.docutils dd {
  margin-bottom: 0.5em }

/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
  font-weight: bold }
*/

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

/* Uncomment (and remove this text!) to get reduced vertical space in
   compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
  margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle {
  margin-top: 0.5em }
*/

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em }

div.footer, div.header {
  clear: both;
  font-size: smaller }

div.line-block {
  display: block ;
  margin-top: 1em ;
  margin-bottom: 1em }

div.line-block div.line-block {
  margin-top: 0 ;
  margin-bottom: 0 ;
  margin-left: 1.5em }

div.sidebar {
  margin-left: 1em ;
  border: medium outset ;
  padding: 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
  margin-top: 0.4em }

h1.title {
  text-align: center }

h2.subtitle {
  text-align: center }

hr.docutils {
  width: 75% }

img.align-left {
  clear: left }

img.align-right {
  clear: right }

img.borderless {
  border: 0 }

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font-family: serif ;
  font-size: 100% }

pre.line-block {
  font-family: serif ;
  font-size: 100% }

pre.literal-block, pre.doctest-block {
  margin-left: 2em ;
  margin-right: 2em ;
  background-color: #eeeeee }

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

span.section-subtitle {
  /* font-size relative to parent (h1..h6 element) */
  font-size: 80% }

table.citation {
  border-left: solid thin gray }

table.docinfo {
  margin: 2em 4em }

table.docutils {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.footnote {
  border-left: solid thin black }

table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

table.docutils th.field-name, table.docinfo th.docinfo-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap ;
  padding-left: 0 }

h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
  font-size: 100% }

tt.docutils {
  background-color: #eeeeee }

ul.auto-toc {
  list-style-type: none }

</style>
</head>
<body>
<div class="document" id="boost-pointer-container-library">
<h1 class="title"><img alt="Boost" src="boost.png" /> Pointer Container Library</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Thorsten Ottosen</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first reference" href="mailto:nesotto&#64;cs.aau.dk">nesotto&#64;cs.aau.dk</a> or <a class="last reference" href="mailto:tottosen&#64;dezide.com">tottosen&#64;dezide.com</a></td></tr>
<tr class="field"><th class="docinfo-name">Organizations:</th><td class="field-body"><a class="reference" href="http://www.cs.aau.dk">Department of Computer Science</a>, Aalborg University, and <a class="reference" href="http://www.dezide.com">Dezide Aps</a></td>
</tr>
<tr><th class="docinfo-name">Date:</th>
<td>29th of April 2006</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>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></tr>
</tbody>
</table>
<div class="section">
<h1><a id="overview" name="overview">Overview</a></h1>
<p>Boost.Pointer Container provides containers for holding heap-allocated
objects in an exception-safe manner and with minimal overhead.
The aim of the library is in particular to make OO programming
easier in C++ by establishing a standard set of classes, methods
and designs for dealing with OO specific problems</p>
<ul class="simple">
<li><a class="reference" href="#motivation">Motivation</a></li>
<li><a class="reference" href="tutorial.html">Tutorial</a></li>
<li><a class="reference" href="reference.html">Reference</a></li>
<li><a class="reference" href="guidelines.html">Usage guidelines</a></li>
<li><a class="reference" href="examples.html">Examples</a></li>
<li><a class="reference" href="headers.html">Library headers</a></li>
<li><a class="reference" href="faq.html">FAQ</a></li>
<li><a class="reference" href="#upgrading-from-boost-v-1-33">Upgrading from Boost v. 1.33.*</a></li>
<li><a class="reference" href="#acknowledgements">Acknowledgements</a></li>
<li><a class="reference" href="#references">References</a></li>
</ul>
<!-- - `Conventions <conventions.html>`_
- `The Clonable Concept <reference.html#the-clonable-concept>`_
- `The Clone Allocator Concept <reference.html#the-clone-allocator-concept>`_
- `Pointer container adapters <reference.html#pointer-container-adapters>`_
- `Sequence container classes <reference.html#sequence-containers>`_

  - `ptr_vector <ptr_vector.html>`_
  - `ptr_deque <ptr_deque.html>`_
  - `ptr_list <ptr_list.html>`_
  - `ptr_array <ptr_array.html>`_
- `Associative container classes  <reference.html#associative-containers>`_

  - `ptr_set <ptr_set.html>`_
  - `ptr_multiset <ptr_multiset.html>`_
  - `ptr_map <ptr_map.html>`_
  - `ptr_multimap <ptr_multimap.html>`_
- `Indirected functions <indirect_fun.html>`_
- `Class nullable <reference.html#class-nullable>`_
- `Exception classes <reference.html#exception-classes>`_ -->
</div>
<div class="section">
<h1><a id="motivation" name="motivation">Motivation</a></h1>
<p>Whenever a programmer wants to have a container of pointers to
heap-allocated objects, there is usually only one exception-safe way:
to make a container of smart pointers like <a class="reference" href="../../smart_ptr/shared_ptr.htm">boost::shared_ptr</a>
This approach is suboptimal if</p>
<ol class="arabic simple">
<li>the stored objects are not shared, but owned exclusively, or</li>
</ol>
<!--  -->
<ol class="arabic simple" start="2">
<li>the overhead implied by smart pointers is inappropriate</li>
</ol>
<p>This library therefore provides standard-like containers that are for storing
heap-allocated or <a class="reference" href="reference.html#the-clonable-concept">cloned</a> objects (or in case of a map, the mapped object must be
a heap-allocated or cloned object). For each of the standard
containers there is a pointer container equivalent that takes ownership of
the objects in an exception safe manner.  In this respect the library is intended
to solve the so-called
<a class="reference" href="faq.html#what-is-the-polymorphic-class-problem">polymorphic class problem</a>.</p>
<p>The advantages of pointer containers are</p>
<ol class="arabic simple">
<li>Exception-safe pointer storage and manipulation.</li>
</ol>
<!--  -->
<ol class="arabic simple" start="2">
<li>Notational convenience compared to the use of containers of pointers.</li>
</ol>
<!--  -->
<ol class="arabic simple" start="3">
<li>Can be used for types that are neither Assignable nor Copy Constructible.</li>
</ol>
<!--  -->
<ol class="arabic simple" start="4">
<li>No memory-overhead as containers of smart pointers can have (see <a class="footnote-reference" href="#id23" id="id2" name="id2">[11]</a> and <a class="footnote-reference" href="#id25" id="id3" name="id3">[12]</a>).</li>
</ol>
<!--  -->
<ol class="arabic simple" start="5">
<li>Usually faster than using containers of smart pointers (see <a class="footnote-reference" href="#id23" id="id4" name="id4">[11]</a> and <a class="footnote-reference" href="#id25" id="id5" name="id5">[12]</a>).</li>
</ol>
<!--  -->
<ol class="arabic simple" start="6">
<li>The interface is slightly changed towards the domain of pointers
instead of relying on the normal value-based interface. For example,
now it is possible for <tt class="docutils literal"><span class="pre">pop_back()</span></tt> to return the removed element.</li>
</ol>
<!--  -->
<ol class="arabic simple" start="7">
<li>Propagates constness s.t. one cannot modify the objects via a <tt class="docutils literal"><span class="pre">const_iterator</span></tt>.</li>
</ol>
<!--  -->
<ol class="arabic simple" start="8">
<li>Built-in support for deep-copy semantics via the <a class="reference" href="reference.html#the-clonable-concept">The Clobable Concept</a></li>
</ol>
<p>The disadvantages are</p>
<ol class="arabic simple">
<li>Less flexible than containers of smart pointers like <a class="reference" href="../../smart_ptr/shared_ptr.htm">boost::shared_ptr</a></li>
</ol>
<p>When you do need shared semantics, this library is not what you need.</p>
</div>
<div class="section">
<h1><a id="upgrading-from-boost-v-1-33" name="upgrading-from-boost-v-1-33">Upgrading from Boost v. <tt class="docutils literal"><span class="pre">1.33.*</span></tt></a></h1>
<p>If you upgrade from one of these versions of Boost, then there has been one
major interface change: map iterators now mimic iterators from <tt class="docutils literal"><span class="pre">std::map</span></tt>.
Previously you may have written</p>
<pre class="literal-block">
for( boost::ptr_map&lt;std::string,T&gt;::iterator i = m.begin(), e = m.end();
     i != e; ++i )
{
  std::cout &lt;&lt; &quot;key:&quot; &lt;&lt; i.key();
  std::cout &lt;&lt; &quot;value:&quot; &lt;&lt; *i;
  i-&gt;foo(); // call T::foo()
}
</pre>
<p>and this now needs to be converted into</p>
<pre class="literal-block">
for( boost::ptr_map&lt;std::string,T&gt;::iterator i = m.begin(), e = m.end();
     i != e; ++i )
{
  std::cout &lt;&lt; &quot;key:&quot; &lt;&lt; i-&gt;first;
  std::cout &lt;&lt; &quot;value:&quot; &lt;&lt; *i-&gt;second;
  i-&gt;second-&gt;foo(); // call T::foo()
}
</pre>
<p>Apart from the above change, the library now also introduces</p>
<ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">std::auto_ptr&lt;T&gt;</span></tt> overloads:</p>
<pre class="literal-block">
std::auto_ptr&lt;T&gt; p( new T );
container.push_back( p );
</pre>
</li>
<li><p class="first">Derived-to-Base conversion in <tt class="docutils literal"><span class="pre">transfer()</span></tt>:</p>
<pre class="literal-block">
boost::ptr_vector&lt;Base&gt;  vec;
boost::ptr_list&lt;Derived&gt; list;
...
vec.transfer( vec.begin(), list ); // now ok
</pre>
</li>
</ul>
<p>Also note that <a class="reference" href="../../assign/index.html">Boost.Assign</a> introduces better support
for pointer containers.</p>
</div>
<div class="section">
<h1><a id="acknowledgements" name="acknowledgements">Acknowledgements</a></h1>
<p>The following people have been very helpful:</p>
<ul class="simple">
<li>Bjørn D. Rasmussen for unintentionally motivating me to start this library</li>
<li>Pavel Vozenilek for asking me to make the adapters</li>
<li>David Abrahams for the <tt class="docutils literal"><span class="pre">indirect_fun</span></tt> design</li>
<li>Pavol Droba for being review manager</li>
<li>Ross Boylan for trying out a prototype for real</li>
<li>Felipe Magno de Almeida for giving fedback based on using the
library in production code even before the library was part of boost</li>
<li>Jonathan Turkanis for supplying his <tt class="docutils literal"><span class="pre">move_ptr</span></tt> framework
which is used internally</li>
<li>Stefan Slapeta and Howard Hinnant for Metrowerks support</li>
<li>Russell Hind for help with Borland compatibility</li>
<li>Jonathan Wakely for his great help with GCC compatibility and bug fixes</li>
<li>Pavel Chikulaev for comments and bug-fixes</li>
<li>Andreas Hommel for fixing the nasty Metrowerks bug</li>
</ul>
</div>
<div class="section">
<h1><a id="references" name="references">References</a></h1>
<table class="docutils footnote" frame="void" id="id8" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id8">[1]</a></td><td>Matt Austern: <a class="reference" href="http://www.cuj.com/documents/s=7990/cujcexp1910austern/">&quot;The Standard Librarian: Containers of Pointers&quot;</a> , C/C++ Users Journal Experts Forum.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id10" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id10">[2]</a></td><td>Bjarne Stroustrup, &quot;The C++ Programming Language&quot;, <a class="reference" href="http://www.research.att.com/~bs/3rd_safe.pdf">Appendix E: &quot;Standard-Library Exception Safety&quot;</a></td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id12" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id12">[3]</a></td><td>Herb Sutter, &quot;Exceptional C++&quot;.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id13" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id13">[4]</a></td><td>Herb Sutter, &quot;More Exceptional C++&quot;.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id14" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id14">[5]</a></td><td>Kevlin Henney: <a class="reference" href="http://www.cuj.com/documents/s=7986/cujcexp2002henney/henney.htm">&quot;From Mechanism to Method: The Safe Stacking of Cats&quot;</a> , C++ Experts Forum, February 2002.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id16" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id16">[6]</a></td><td>Some of the few earlier attempts of pointer containers I have seen are the rather interesting <a class="reference" href="http://www.ntllib.org/asp.html">NTL</a> and the 
<a class="reference" href="http://ootips.org/yonat/4dev/pointainer.h">pointainer</a>. 
As of this writing both libraries are not exceptions-safe and can leak.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id17" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id17">[7]</a></td><td>INTERNATIONAL STANDARD, Programming languages --- C++, ISO/IEC 14882, 1998. See section 23 in particular.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id18" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id18">[8]</a></td><td>C++ Standard Library Closed Issues List (Revision 27), 
Item 218, <a class="reference" href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-closed.html#218">Algorithms do not use binary predicate objects for default comparisons</a>.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id20" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id20">[9]</a></td><td>C++ Standard Library Active Issues List (Revision 27), 
Item 226, <a class="reference" href="http://gcc.gnu.org/onlinedocs/libstdc++/ext/lwg-active.html#226">User supplied specializations or overloads of namespace std function templates</a>.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id22" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id22">[10]</a></td><td>Harald Nowak, &quot;A remove_if for vector&quot;, C/C++ Users Journal, July 2001.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id23" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id23">[11]</a></td><td><em>(<a class="fn-backref" href="#id2">1</a>, <a class="fn-backref" href="#id4">2</a>)</em> Boost smart pointer <a class="reference" href="http://www.boost.org/libs/smart_ptr/smarttests.htm">timings</a></td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id25" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id25">[12]</a></td><td><em>(<a class="fn-backref" href="#id3">1</a>, <a class="fn-backref" href="#id5">2</a>)</em> <a class="reference" href="http://www.ntllib.org/asp.html">NTL</a>: Array vs std::vector and boost::shared_ptr</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id26" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id26">[13]</a></td><td>Kevlin Henney, <a class="reference" href="http://www.two-sdg.demon.co.uk/curbralan/papers/europlop/NullObject.pdf">Null Object</a>, 2002.</td></tr>
</tbody>
</table>
<hr><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Copyright:</th><td class="field-body">Thorsten Ottosen 2004-2006.</td>
</tr>
</tbody>
</table>
</div>
</div>
</body>
</html>