Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/ptr_container/doc/guidelines.html @ 47

Last change on this file since 47 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 14.4 KB
Line 
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: 2006/11/22 22:01:00 $
14:Revision: $Revision: 1.4.2.5 $
15:Copyright: This stylesheet has been placed in the public domain.
16
17Default cascading style sheet for the HTML output of Docutils.
18
19See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
20customize 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
35a.toc-backref {
36  text-decoration: none ;
37  color: black }
38
39blockquote.epigraph {
40  margin: 2em 5em ; }
41
42dl.docutils dd {
43  margin-bottom: 0.5em }
44
45/* Uncomment (and remove this text!) to get bold-faced definition list terms
46dl.docutils dt {
47  font-weight: bold }
48*/
49
50div.abstract {
51  margin: 2em 5em }
52
53div.abstract p.topic-title {
54  font-weight: bold ;
55  text-align: center }
56
57div.admonition, div.attention, div.caution, div.danger, div.error,
58div.hint, div.important, div.note, div.tip, div.warning {
59  margin: 2em ;
60  border: medium outset ;
61  padding: 1em }
62
63div.admonition p.admonition-title, div.hint p.admonition-title,
64div.important p.admonition-title, div.note p.admonition-title,
65div.tip p.admonition-title {
66  font-weight: bold ;
67  font-family: sans-serif }
68
69div.attention p.admonition-title, div.caution p.admonition-title,
70div.danger p.admonition-title, div.error p.admonition-title,
71div.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.
78div.compound .compound-first, div.compound .compound-middle {
79  margin-bottom: 0.5em }
80
81div.compound .compound-last, div.compound .compound-middle {
82  margin-top: 0.5em }
83*/
84
85div.dedication {
86  margin: 2em 5em ;
87  text-align: center ;
88  font-style: italic }
89
90div.dedication p.topic-title {
91  font-weight: bold ;
92  font-style: normal }
93
94div.figure {
95  margin-left: 2em }
96
97div.footer, div.header {
98  clear: both;
99  font-size: smaller }
100
101div.line-block {
102  display: block ;
103  margin-top: 1em ;
104  margin-bottom: 1em }
105
106div.line-block div.line-block {
107  margin-top: 0 ;
108  margin-bottom: 0 ;
109  margin-left: 1.5em }
110
111div.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
120div.sidebar p.rubric {
121  font-family: sans-serif ;
122  font-size: medium }
123
124div.system-messages {
125  margin: 5em }
126
127div.system-messages h1 {
128  color: red }
129
130div.system-message {
131  border: medium outset ;
132  padding: 1em }
133
134div.system-message p.system-message-title {
135  color: red ;
136  font-weight: bold }
137
138div.topic {
139  margin: 2em }
140
141h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
142h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
143  margin-top: 0.4em }
144
145h1.title {
146  text-align: center }
147
148h2.subtitle {
149  text-align: center }
150
151hr.docutils {
152  width: 75% }
153
154img.align-left {
155  clear: left }
156
157img.align-right {
158  clear: right }
159
160img.borderless {
161  border: 0 }
162
163ol.simple, ul.simple {
164  margin-bottom: 1em }
165
166ol.arabic {
167  list-style: decimal }
168
169ol.loweralpha {
170  list-style: lower-alpha }
171
172ol.upperalpha {
173  list-style: upper-alpha }
174
175ol.lowerroman {
176  list-style: lower-roman }
177
178ol.upperroman {
179  list-style: upper-roman }
180
181p.attribution {
182  text-align: right ;
183  margin-left: 50% }
184
185p.caption {
186  font-style: italic }
187
188p.credits {
189  font-style: italic ;
190  font-size: smaller }
191
192p.label {
193  white-space: nowrap }
194
195p.rubric {
196  font-weight: bold ;
197  font-size: larger ;
198  color: maroon ;
199  text-align: center }
200
201p.sidebar-title {
202  font-family: sans-serif ;
203  font-weight: bold ;
204  font-size: larger }
205
206p.sidebar-subtitle {
207  font-family: sans-serif ;
208  font-weight: bold }
209
210p.topic-title {
211  font-weight: bold }
212
213pre.address {
214  margin-bottom: 0 ;
215  margin-top: 0 ;
216  font-family: serif ;
217  font-size: 100% }
218
219pre.line-block {
220  font-family: serif ;
221  font-size: 100% }
222
223pre.literal-block, pre.doctest-block {
224  margin-left: 2em ;
225  margin-right: 2em ;
226  background-color: #eeeeee }
227
228span.classifier {
229  font-family: sans-serif ;
230  font-style: oblique }
231
232span.classifier-delimiter {
233  font-family: sans-serif ;
234  font-weight: bold }
235
236span.interpreted {
237  font-family: sans-serif }
238
239span.option {
240  white-space: nowrap }
241
242span.pre {
243  white-space: pre }
244
245span.problematic {
246  color: red }
247
248span.section-subtitle {
249  /* font-size relative to parent (h1..h6 element) */
250  font-size: 80% }
251
252table.citation {
253  border-left: solid thin gray }
254
255table.docinfo {
256  margin: 2em 4em }
257
258table.docutils {
259  margin-top: 0.5em ;
260  margin-bottom: 0.5em }
261
262table.footnote {
263  border-left: solid thin black }
264
265table.docutils td, table.docutils th,
266table.docinfo td, table.docinfo th {
267  padding-left: 0.5em ;
268  padding-right: 0.5em ;
269  vertical-align: top }
270
271table.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
277h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
278h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
279  font-size: 100% }
280
281tt.docutils {
282  background-color: #eeeeee }
283
284ul.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="usage-guidelines">Usage Guidelines</h2>
293<div class="contents local topic">
294<ul class="simple">
295<li><a class="reference" href="#choosing-the-right-container" id="id8" name="id8">Choosing the right container</a></li>
296<li><a class="reference" href="#recommended-practice-for-object-oriented-programming" id="id9" name="id9">Recommended practice for Object-Oriented Programming</a><ul>
297<li><a class="reference" href="#make-base-classes-abstract-and-without-data" id="id10" name="id10">1. Make base classes abstract and without data</a></li>
298<li><a class="reference" href="#make-virtual-functions-private-and-provide-a-non-virtual-public-forwarding-function" id="id11" name="id11">2. Make virtual functions private and provide a non-virtual public forwarding function</a></li>
299<li><a class="reference" href="#derive-your-base-class-from-boost-noncopyable" id="id12" name="id12">3. Derive your base class from <tt class="docutils literal"><span class="pre">boost::noncopyable</span></tt></a></li>
300<li><a class="reference" href="#avoid-null-pointers-in-containers-if-possible" id="id13" name="id13">4. Avoid null-pointers in containers (if possible)</a></li>
301</ul>
302</li>
303</ul>
304</div>
305<div class="section">
306<h1><a class="toc-backref" href="#id8" id="choosing-the-right-container" name="choosing-the-right-container">Choosing the right container</a></h1>
307<p>The recommended usage pattern of the container classes are the same as the
308for normal standard containers.</p>
309<p><tt class="docutils literal"><span class="pre">ptr_vector</span></tt>, <tt class="docutils literal"><span class="pre">ptr_list</span></tt> and <tt class="docutils literal"><span class="pre">ptr_deque</span></tt> offer the programmer different
310complexity tradeoffs and should be used accordingly.  <tt class="docutils literal"><span class="pre">ptr_vector</span></tt> is the
311type of sequence that should be used by default.  <tt class="docutils literal"><span class="pre">ptr_list</span></tt> should be used
312when there are frequent insertions and deletions from the middle of the
313sequence and if the container is fairly large (eg.  more than 100
314elements).  <tt class="docutils literal"><span class="pre">ptr_deque</span></tt> is the data structure of choice when most insertions
315and deletions take place at the beginning or at the end of the sequence. 
316The special container <tt class="docutils literal"><span class="pre">ptr_array</span></tt> may be used when the size of the container is invariant
317and known at compile time.</p>
318<p>An associative container supports unique keys if it may contain at most
319one element for each key. Otherwise, it supports equivalent keys. 
320<tt class="docutils literal"><span class="pre">ptr_set</span></tt> and <tt class="docutils literal"><span class="pre">ptr_map</span></tt> support unique keys. 
321<tt class="docutils literal"><span class="pre">ptr_multiset</span></tt> and <tt class="docutils literal"><span class="pre">ptr_multimap</span></tt> 
322support equivalent keys.</p>
323</div>
324<div class="section">
325<h1><a class="toc-backref" href="#id9" id="recommended-practice-for-object-oriented-programming" name="recommended-practice-for-object-oriented-programming">Recommended practice for Object-Oriented Programming</a></h1>
326<p>Idiomtic Object-Oriented Programming in C++ looks a bit different from
327the way it is done in other languages. This is partly because C++
328has both value and reference semantics, and partly because C++ is more flexible
329than other languages. Below is a list of recommendations that you are
330encouraged to follow:</p>
331<div class="section">
332<h2><a class="toc-backref" href="#id10" id="make-base-classes-abstract-and-without-data" name="make-base-classes-abstract-and-without-data">1. Make base classes abstract and without data</a></h2>
333<p>The has the following advantages:</p>
334<blockquote>
335<ol class="loweralpha simple">
336<li>It reduces <em>coupling</em> because you do not have to maintain or update state</li>
337</ol>
338<!--  -->
339<ol class="loweralpha simple" start="2">
340<li>It helps you to avoid <em>slicing</em></li>
341</ol>
342<!--  -->
343<ol class="loweralpha simple" start="3">
344<li>It ensures you <em>override</em> the right function</li>
345</ol>
346</blockquote>
347<p>You might also want to read the following articles:</p>
348<ul class="simple">
349<li>Kevlin Henney's <a class="reference" href="http://www.two-sdg.demon.co.uk/curbralan/papers/SixOfTheBest.pdf">Six of the best</a></li>
350</ul>
351<ul class="simple">
352<li>Jack Reeves' <a class="reference" href="http://www.ddj.com/documents/s=10011/q=1/cuj0602reeves/0602reeves.html">Multiple Inheritance Considered Useful</a></li>
353</ul>
354</div>
355<div class="section">
356<h2><a class="toc-backref" href="#id11" id="make-virtual-functions-private-and-provide-a-non-virtual-public-forwarding-function" name="make-virtual-functions-private-and-provide-a-non-virtual-public-forwarding-function">2. Make virtual functions private and provide a non-virtual public forwarding function</a></h2>
357<p>In code:</p>
358<pre class="literal-block">
359class Polymorphic
360{
361private:
362    virtual int do_foo() = 0;
363   
364public:
365    int foo()
366    {
367        return do_foo();
368    }
369    ...
370};     
371</pre>
372<p>This has the following advantages:</p>
373<blockquote>
374<ol class="loweralpha simple">
375<li>It makes sure all calls to the virtual function always goes through one place in your code</li>
376</ol>
377<!--  -->
378<ol class="loweralpha simple" start="2">
379<li>It enables you to check preconditions and postconditions inside the forwarding function</li>
380</ol>
381</blockquote>
382<p>You might also want to read Herb Sutter's article <a class="reference" href="http://www.gotw.ca/publications/mill18.htm">Virtuality</a>.</p>
383</div>
384<div class="section">
385<h2><a class="toc-backref" href="#id12" id="derive-your-base-class-from-boost-noncopyable" name="derive-your-base-class-from-boost-noncopyable">3. Derive your base class from <tt class="docutils literal docutils literal"><span class="pre">boost::noncopyable</span></tt></a></h2>
386<p>Having an abstact base class prevents slicing when the base class is involved, but
387it does not prevent it for classes further down the hierarchy. This is where
388<a class="reference" href="http://www.boost.org/libs/utility/utility.htm#Class_noncopyable">boost::noncopyable</a> is handy to use:</p>
389<pre class="literal-block">
390class Polymorphic : boost::noncopyable
391{
392  ...
393};
394</pre>
395</div>
396<div class="section">
397<h2><a class="toc-backref" href="#id13" id="avoid-null-pointers-in-containers-if-possible" name="avoid-null-pointers-in-containers-if-possible">4. Avoid null-pointers in containers (if possible)</a></h2>
398<p>By default the pointer containers do not allow you to store null-pointer in them.
399As you might know, this behavior can be changed explicitly with the use
400of <a class="reference" href="reference.html#class-nullable">boost::nullable</a>.</p>
401<p>The primary reason to avoid null-pointers
402is that you have to check for null-pointers every time the container is
403used. This extra checking is easy to forget, and it is somewhat contradictory to
404the spirit of OO where you replace special cases with dynamic dispatch.</p>
405<p>Often, however, you need to place some special object in the container because you
406do not have enough information to construct a full object. In that case
407you might be able to use the Null Object pattern which simply dictates that
408you implement virtual functions from the abstract base-class
409as empty functions or with dummy return values. This means that
410your OO-code still does not need to worry about null-pointers.</p>
411<p>You might want to read</p>
412<ul class="simple">
413<li>Kevlin Henney's <a class="reference" href="http://www.two-sdg.demon.co.uk/curbralan/papers/europlop/NullObject.pdf">Null Object - Something for Nothing</a></li>
414</ul>
415<p>Finally you might end up in a situation where not even the Null Object can help
416you. That is when you truly need <tt class="docutils literal"><span class="pre">container&lt;</span> <span class="pre">nullable&lt;T&gt;</span> <span class="pre">&gt;</span></tt>.</p>
417<hr><p><strong>Navigate:</strong></p>
418<ul class="simple">
419<li><a class="reference" href="ptr_container.html">home</a></li>
420<li><a class="reference" href="reference.html">reference</a></li>
421</ul>
422<hr><table class="docutils field-list" frame="void" rules="none">
423<col class="field-name" />
424<col class="field-body" />
425<tbody valign="top">
426<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>
427</tr>
428</tbody>
429</table>
430</div>
431</div>
432</div>
433</body>
434</html>
Note: See TracBrowser for help on using the repository browser.