[ceph.git] / ceph / src / boost / libs / ptr_container / doc / faq.html

<?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>
<style type="text/css">

/*
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:Date: $Date$
:Revision: $Revision$
: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>
<h2 class="subtitle" id="faq">FAQ</h2>
<div class="contents local topic">
<ul class="simple">
<li><a class="reference" href="#calling-assign-is-very-costly-and-i-do-not-really-need-to-store-cloned-objects-i-merely-need-to-overwrite-the-existing-ones-what-do-i-do" id="id5" name="id5">Calling <tt class="docutils literal"><span class="pre">assign()</span></tt> is very costly and I do not really need to store cloned objects; I merely need to overwrite the existing ones; what do I do?</a></li>
<li><a class="reference" href="#which-mutating-algorithms-are-safe-to-use-with-pointers" id="id6" name="id6">Which mutating algorithms are safe to use with pointers?</a></li>
<li><a class="reference" href="#why-does-ptr-map-t-insert-replace-take-two-arguments-the-key-and-the-pointer-instead-of-one-std-pair-and-why-is-the-key-passed-by-non-const-reference" id="id7" name="id7">Why does <tt class="docutils literal"><span class="pre">ptr_map&lt;T&gt;::insert()/replace()</span></tt> take two arguments (the key and the pointer) instead of one <tt class="docutils literal"><span class="pre">std::pair</span></tt>? And why is the key passed by non-const reference?</a></li>
<li><a class="reference" href="#when-instantiating-a-pointer-container-with-a-type-t-is-t-then-allowed-to-be-incomplete-at-that-point" id="id8" name="id8">When instantiating a pointer container with a type <tt class="docutils literal"><span class="pre">T</span></tt>, is <tt class="docutils literal"><span class="pre">T</span></tt> then allowed to be incomplete at that point?</a></li>
<li><a class="reference" href="#why-do-iterator-range-inserts-give-the-strong-exception-safety-guarantee" id="id9" name="id9">Why do iterator-range inserts give the strong exception-safety guarantee?</a></li>
<li><a class="reference" href="#what-is-the-polymorphic-class-problem" id="id10" name="id10">What is the polymorphic class problem?</a></li>
<li><a class="reference" href="#are-the-pointer-containers-faster-and-do-they-have-a-better-memory-footprint-than-a-container-of-smart-pointers" id="id11" name="id11">Are the pointer containers faster and do they have a better memory  footprint than a container of smart pointers?</a></li>
<li><a class="reference" href="#when-the-stored-pointers-cannot-be-0-how-do-i-allow-this-empty-behavior-anyway" id="id12" name="id12">When the stored pointers cannot be <tt class="docutils literal"><span class="pre">0</span></tt>, how do I allow this &quot;empty&quot; behavior anyway?</a></li>
</ul>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id5" id="calling-assign-is-very-costly-and-i-do-not-really-need-to-store-cloned-objects-i-merely-need-to-overwrite-the-existing-ones-what-do-i-do" name="calling-assign-is-very-costly-and-i-do-not-really-need-to-store-cloned-objects-i-merely-need-to-overwrite-the-existing-ones-what-do-i-do">Calling <tt class="docutils literal docutils literal"><span class="pre">assign()</span></tt> is very costly and I do not really need to store cloned objects; I merely need to overwrite the existing ones; what do I do?</a></h1>
<p>Call <tt class="docutils literal"><span class="pre">std::copy(</span> <span class="pre">first,</span> <span class="pre">last,</span> <span class="pre">c.begin()</span> <span class="pre">);</span></tt>.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id6" id="which-mutating-algorithms-are-safe-to-use-with-pointers" name="which-mutating-algorithms-are-safe-to-use-with-pointers">Which mutating algorithms are safe to use with pointers?</a></h1>
<p>Any mutating algorithm that moves elements around by swapping them.  An 
important example is <tt class="docutils literal"><span class="pre">std::sort()</span></tt>; examples of unsafe algorithms are 
<tt class="docutils literal"><span class="pre">std::unique()</span></tt> and <tt class="docutils literal"><span class="pre">std::remove()</span></tt>.</p>
<!-- That is why these algorithms are 
provided as member functions.   -->
</div>
<div class="section">
<h1><a class="toc-backref" href="#id7" id="why-does-ptr-map-t-insert-replace-take-two-arguments-the-key-and-the-pointer-instead-of-one-std-pair-and-why-is-the-key-passed-by-non-const-reference" name="why-does-ptr-map-t-insert-replace-take-two-arguments-the-key-and-the-pointer-instead-of-one-std-pair-and-why-is-the-key-passed-by-non-const-reference">Why does <tt class="docutils literal docutils literal"><span class="pre">ptr_map&lt;T&gt;::insert()/replace()</span></tt> take two arguments (the key and the pointer) instead of one <tt class="docutils literal docutils literal"><span class="pre">std::pair</span></tt>? And why is the key passed by non-const reference?</a></h1>
<p>This is the only way the function can be implemented in an exception-safe 
manner; since the copy-constructor of the key might throw, and since 
function arguments are not guaranteed to be evaluated from left to right, 
we need to ensure that evaluating the first argument does not throw.  
Passing the key as a reference achieves just that.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id8" id="when-instantiating-a-pointer-container-with-a-type-t-is-t-then-allowed-to-be-incomplete-at-that-point" name="when-instantiating-a-pointer-container-with-a-type-t-is-t-then-allowed-to-be-incomplete-at-that-point">When instantiating a pointer container with a type <tt class="docutils literal docutils literal"><span class="pre">T</span></tt>, is <tt class="docutils literal docutils literal"><span class="pre">T</span></tt> then allowed to be incomplete at that point?</a></h1>
<p>No. This is a distinct property of <tt class="docutils literal"><span class="pre">shared_ptr</span></tt> which implies some overhead.</p>
<p>However, one can leave <tt class="docutils literal"><span class="pre">T</span></tt> incomplete in the header file:</p>
<pre class="literal-block">
// foo.hpp
class Foo { ... };
new_clone( const Foo&amp; ) { ... }
delete_clone( const Foo* )     { ... }

// x.hpp
class Foo; // Foo is incomplete here
class X { ptr_deque&lt;Foo&gt; container; ... }

// x.cpp
#include &lt;x.hpp&gt;
#include &lt;foo.hpp&gt; // now Foo is not incomplete anymore
...
</pre>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id9" id="why-do-iterator-range-inserts-give-the-strong-exception-safety-guarantee" name="why-do-iterator-range-inserts-give-the-strong-exception-safety-guarantee">Why do iterator-range inserts give the strong exception-safety guarantee?</a></h1>
<p>Is this not very inefficient?  It is because it is actually affordable to 
do so; the overhead is one heap-allocation which is relatively small 
compared to cloning N objects.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id10" id="what-is-the-polymorphic-class-problem" name="what-is-the-polymorphic-class-problem">What is the <span class="target" id="polymorphic-class-problem">polymorphic class problem</span>?</a></h1>
<p>The problem refers to the relatively troublesome way C++ supports Object 
Oriented programming in connection with containers of pointers to 
polymorphic objects.  In a language without garbage collection, you end up 
using either a container of smart pointers or a container that takes 
ownership of the pointers.  The hard part is to find a safe, fast and 
elegant solution.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id11" id="are-the-pointer-containers-faster-and-do-they-have-a-better-memory-footprint-than-a-container-of-smart-pointers" name="are-the-pointer-containers-faster-and-do-they-have-a-better-memory-footprint-than-a-container-of-smart-pointers">Are the pointer containers faster and do they have a better memory  footprint than a container of smart pointers?</a></h1>
<p>The short answer is yes: they are faster and they do use less memory; in 
fact, they are the only way to obtain the zero-overhead hallmark of C++.  
Smart pointers usually have one word or more of memory overhead per 
pointer because a reference count must be maintained.  And since the 
reference count must be maintained, there is also a runtime-overhead.  If 
your objects are big, then the memory overhead is often negligible, but if 
you have many small objects, it is not.  Further reading can be found in 
these references: <a class="reference" href="ptr_container.html#references">[11]</a> and <a class="reference" href="ptr_container.html#references">[12]</a>.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id12" id="when-the-stored-pointers-cannot-be-0-how-do-i-allow-this-empty-behavior-anyway" name="when-the-stored-pointers-cannot-be-0-how-do-i-allow-this-empty-behavior-anyway">When the stored pointers cannot be <tt class="docutils literal docutils literal"><span class="pre">0</span></tt>, how do I allow this &quot;empty&quot; behavior anyway?</a></h1>
<p>Storing a null-pointer among a list of pointers does not fit well into the Object Oriented paradigm. 
The most elegant design is to use the Null-Object Pattern where one basically makes a concrete
class with dummy implementations of the virtual functions. See <a class="reference" href="ptr_container.html#references">[13]</a> for details.</p>
<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. 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>
</div>
</body>
</html>
Commit	Line	Data
7c673cae FG	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="faq">FAQ</h2>
293	<div class="contents local topic">
294	<ul class="simple">
295	<li><a class="reference" href="#calling-assign-is-very-costly-and-i-do-not-really-need-to-store-cloned-objects-i-merely-need-to-overwrite-the-existing-ones-what-do-i-do" id="id5" name="id5">Calling <tt class="docutils literal"><span class="pre">assign()</span></tt> is very costly and I do not really need to store cloned objects; I merely need to overwrite the existing ones; what do I do?</a></li>
296	<li><a class="reference" href="#which-mutating-algorithms-are-safe-to-use-with-pointers" id="id6" name="id6">Which mutating algorithms are safe to use with pointers?</a></li>
297	<li><a class="reference" href="#why-does-ptr-map-t-insert-replace-take-two-arguments-the-key-and-the-pointer-instead-of-one-std-pair-and-why-is-the-key-passed-by-non-const-reference" id="id7" name="id7">Why does <tt class="docutils literal"><span class="pre">ptr_map<T>::insert()/replace()</span></tt> take two arguments (the key and the pointer) instead of one <tt class="docutils literal"><span class="pre">std::pair</span></tt>? And why is the key passed by non-const reference?</a></li>
298	<li><a class="reference" href="#when-instantiating-a-pointer-container-with-a-type-t-is-t-then-allowed-to-be-incomplete-at-that-point" id="id8" name="id8">When instantiating a pointer container with a type <tt class="docutils literal"><span class="pre">T</span></tt>, is <tt class="docutils literal"><span class="pre">T</span></tt> then allowed to be incomplete at that point?</a></li>
299	<li><a class="reference" href="#why-do-iterator-range-inserts-give-the-strong-exception-safety-guarantee" id="id9" name="id9">Why do iterator-range inserts give the strong exception-safety guarantee?</a></li>
300	<li><a class="reference" href="#what-is-the-polymorphic-class-problem" id="id10" name="id10">What is the polymorphic class problem?</a></li>
301	<li><a class="reference" href="#are-the-pointer-containers-faster-and-do-they-have-a-better-memory-footprint-than-a-container-of-smart-pointers" id="id11" name="id11">Are the pointer containers faster and do they have a better memory footprint than a container of smart pointers?</a></li>
302	<li><a class="reference" href="#when-the-stored-pointers-cannot-be-0-how-do-i-allow-this-empty-behavior-anyway" id="id12" name="id12">When the stored pointers cannot be <tt class="docutils literal"><span class="pre">0</span></tt>, how do I allow this "empty" behavior anyway?</a></li>
303	</ul>
304	</div>
305	<div class="section">
306	<h1><a class="toc-backref" href="#id5" id="calling-assign-is-very-costly-and-i-do-not-really-need-to-store-cloned-objects-i-merely-need-to-overwrite-the-existing-ones-what-do-i-do" name="calling-assign-is-very-costly-and-i-do-not-really-need-to-store-cloned-objects-i-merely-need-to-overwrite-the-existing-ones-what-do-i-do">Calling <tt class="docutils literal docutils literal"><span class="pre">assign()</span></tt> is very costly and I do not really need to store cloned objects; I merely need to overwrite the existing ones; what do I do?</a></h1>
307	<p>Call <tt class="docutils literal"><span class="pre">std::copy(</span> <span class="pre">first,</span> <span class="pre">last,</span> <span class="pre">c.begin()</span> <span class="pre">);</span></tt>.</p>
308	</div>
309	<div class="section">
310	<h1><a class="toc-backref" href="#id6" id="which-mutating-algorithms-are-safe-to-use-with-pointers" name="which-mutating-algorithms-are-safe-to-use-with-pointers">Which mutating algorithms are safe to use with pointers?</a></h1>
311	<p>Any mutating algorithm that moves elements around by swapping them. An
312	important example is <tt class="docutils literal"><span class="pre">std::sort()</span></tt>; examples of unsafe algorithms are
313	<tt class="docutils literal"><span class="pre">std::unique()</span></tt> and <tt class="docutils literal"><span class="pre">std::remove()</span></tt>.</p>
314	<!-- That is why these algorithms are
315	provided as member functions. -->
316	</div>
317	<div class="section">
318	<h1><a class="toc-backref" href="#id7" id="why-does-ptr-map-t-insert-replace-take-two-arguments-the-key-and-the-pointer-instead-of-one-std-pair-and-why-is-the-key-passed-by-non-const-reference" name="why-does-ptr-map-t-insert-replace-take-two-arguments-the-key-and-the-pointer-instead-of-one-std-pair-and-why-is-the-key-passed-by-non-const-reference">Why does <tt class="docutils literal docutils literal"><span class="pre">ptr_map<T>::insert()/replace()</span></tt> take two arguments (the key and the pointer) instead of one <tt class="docutils literal docutils literal"><span class="pre">std::pair</span></tt>? And why is the key passed by non-const reference?</a></h1>
319	<p>This is the only way the function can be implemented in an exception-safe
320	manner; since the copy-constructor of the key might throw, and since
321	function arguments are not guaranteed to be evaluated from left to right,
322	we need to ensure that evaluating the first argument does not throw.
323	Passing the key as a reference achieves just that.</p>
324	</div>
325	<div class="section">
326	<h1><a class="toc-backref" href="#id8" id="when-instantiating-a-pointer-container-with-a-type-t-is-t-then-allowed-to-be-incomplete-at-that-point" name="when-instantiating-a-pointer-container-with-a-type-t-is-t-then-allowed-to-be-incomplete-at-that-point">When instantiating a pointer container with a type <tt class="docutils literal docutils literal"><span class="pre">T</span></tt>, is <tt class="docutils literal docutils literal"><span class="pre">T</span></tt> then allowed to be incomplete at that point?</a></h1>
327	<p>No. This is a distinct property of <tt class="docutils literal"><span class="pre">shared_ptr</span></tt> which implies some overhead.</p>
328	<p>However, one can leave <tt class="docutils literal"><span class="pre">T</span></tt> incomplete in the header file:</p>
329	<pre class="literal-block">
330	// foo.hpp
331	class Foo { ... };
332	new_clone( const Foo& ) { ... }
333	delete_clone( const Foo* ) { ... }
334
335	// x.hpp
336	class Foo; // Foo is incomplete here
337	class X { ptr_deque<Foo> container; ... }
338
339	// x.cpp
340	#include <x.hpp>
341	#include <foo.hpp> // now Foo is not incomplete anymore
342	...
343	</pre>
344	</div>
345	<div class="section">
346	<h1><a class="toc-backref" href="#id9" id="why-do-iterator-range-inserts-give-the-strong-exception-safety-guarantee" name="why-do-iterator-range-inserts-give-the-strong-exception-safety-guarantee">Why do iterator-range inserts give the strong exception-safety guarantee?</a></h1>
347	<p>Is this not very inefficient? It is because it is actually affordable to
348	do so; the overhead is one heap-allocation which is relatively small
349	compared to cloning N objects.</p>
350	</div>
351	<div class="section">
352	<h1><a class="toc-backref" href="#id10" id="what-is-the-polymorphic-class-problem" name="what-is-the-polymorphic-class-problem">What is the <span class="target" id="polymorphic-class-problem">polymorphic class problem</span>?</a></h1>
353	<p>The problem refers to the relatively troublesome way C++ supports Object
354	Oriented programming in connection with containers of pointers to
355	polymorphic objects. In a language without garbage collection, you end up
356	using either a container of smart pointers or a container that takes
357	ownership of the pointers. The hard part is to find a safe, fast and
358	elegant solution.</p>
359	</div>
360	<div class="section">
361	<h1><a class="toc-backref" href="#id11" id="are-the-pointer-containers-faster-and-do-they-have-a-better-memory-footprint-than-a-container-of-smart-pointers" name="are-the-pointer-containers-faster-and-do-they-have-a-better-memory-footprint-than-a-container-of-smart-pointers">Are the pointer containers faster and do they have a better memory footprint than a container of smart pointers?</a></h1>
362	<p>The short answer is yes: they are faster and they do use less memory; in
363	fact, they are the only way to obtain the zero-overhead hallmark of C++.
364	Smart pointers usually have one word or more of memory overhead per
365	pointer because a reference count must be maintained. And since the
366	reference count must be maintained, there is also a runtime-overhead. If
367	your objects are big, then the memory overhead is often negligible, but if
368	you have many small objects, it is not. Further reading can be found in
369	these references: <a class="reference" href="ptr_container.html#references">[11]</a> and <a class="reference" href="ptr_container.html#references">[12]</a>.</p>
370	</div>
371	<div class="section">
372	<h1><a class="toc-backref" href="#id12" id="when-the-stored-pointers-cannot-be-0-how-do-i-allow-this-empty-behavior-anyway" name="when-the-stored-pointers-cannot-be-0-how-do-i-allow-this-empty-behavior-anyway">When the stored pointers cannot be <tt class="docutils literal docutils literal"><span class="pre">0</span></tt>, how do I allow this "empty" behavior anyway?</a></h1>
373	<p>Storing a null-pointer among a list of pointers does not fit well into the Object Oriented paradigm.
374	The most elegant design is to use the Null-Object Pattern where one basically makes a concrete
375	class with dummy implementations of the virtual functions. See <a class="reference" href="ptr_container.html#references">[13]</a> for details.</p>
376	<hr><table class="docutils field-list" frame="void" rules="none">
377	<col class="field-name" />
378	<col class="field-body" />
379	<tbody valign="top">
380	<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>
381	</tr>
382	</tbody>
383	</table>
384	</div>
385	</div>
386	</body>
387	</html>