PageRenderTime 57ms CodeModel.GetById 29ms RepoModel.GetById 1ms app.codeStats 0ms

/libs/ptr_container/doc/reference.html

https://github.com/ee2/boost-svn
HTML | 815 lines | 689 code | 77 blank | 49 comment | 0 complexity | 5e2c23eb95c6a20dc53ff0cfa680bd29 MD5 | raw file
  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. :Author: David Goodger
  11. :Contact: goodger@users.sourceforge.net
  12. :Date: $Date$
  13. :Revision: $Revision$
  14. :Copyright: This stylesheet has been placed in the public domain.
  15. Default cascading style sheet for the HTML output of Docutils.
  16. See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
  17. customize this style sheet.
  18. */
  19. /* "! important" is used here to override other ``margin-top`` and
  20. ``margin-bottom`` styles that are later in the stylesheet or
  21. more specific. See http://www.w3.org/TR/CSS1#the-cascade */
  22. .first {
  23. margin-top: 0 ! important }
  24. .last, .with-subtitle {
  25. margin-bottom: 0 ! important }
  26. .hidden {
  27. display: none }
  28. a.toc-backref {
  29. text-decoration: none ;
  30. color: black }
  31. blockquote.epigraph {
  32. margin: 2em 5em ; }
  33. dl.docutils dd {
  34. margin-bottom: 0.5em }
  35. /* Uncomment (and remove this text!) to get bold-faced definition list terms
  36. dl.docutils dt {
  37. font-weight: bold }
  38. */
  39. div.abstract {
  40. margin: 2em 5em }
  41. div.abstract p.topic-title {
  42. font-weight: bold ;
  43. text-align: center }
  44. div.admonition, div.attention, div.caution, div.danger, div.error,
  45. div.hint, div.important, div.note, div.tip, div.warning {
  46. margin: 2em ;
  47. border: medium outset ;
  48. padding: 1em }
  49. div.admonition p.admonition-title, div.hint p.admonition-title,
  50. div.important p.admonition-title, div.note p.admonition-title,
  51. div.tip p.admonition-title {
  52. font-weight: bold ;
  53. font-family: sans-serif }
  54. div.attention p.admonition-title, div.caution p.admonition-title,
  55. div.danger p.admonition-title, div.error p.admonition-title,
  56. div.warning p.admonition-title {
  57. color: red ;
  58. font-weight: bold ;
  59. font-family: sans-serif }
  60. /* Uncomment (and remove this text!) to get reduced vertical space in
  61. compound paragraphs.
  62. div.compound .compound-first, div.compound .compound-middle {
  63. margin-bottom: 0.5em }
  64. div.compound .compound-last, div.compound .compound-middle {
  65. margin-top: 0.5em }
  66. */
  67. div.dedication {
  68. margin: 2em 5em ;
  69. text-align: center ;
  70. font-style: italic }
  71. div.dedication p.topic-title {
  72. font-weight: bold ;
  73. font-style: normal }
  74. div.figure {
  75. margin-left: 2em }
  76. div.footer, div.header {
  77. clear: both;
  78. font-size: smaller }
  79. div.line-block {
  80. display: block ;
  81. margin-top: 1em ;
  82. margin-bottom: 1em }
  83. div.line-block div.line-block {
  84. margin-top: 0 ;
  85. margin-bottom: 0 ;
  86. margin-left: 1.5em }
  87. div.sidebar {
  88. margin-left: 1em ;
  89. border: medium outset ;
  90. padding: 1em ;
  91. background-color: #ffffee ;
  92. width: 40% ;
  93. float: right ;
  94. clear: right }
  95. div.sidebar p.rubric {
  96. font-family: sans-serif ;
  97. font-size: medium }
  98. div.system-messages {
  99. margin: 5em }
  100. div.system-messages h1 {
  101. color: red }
  102. div.system-message {
  103. border: medium outset ;
  104. padding: 1em }
  105. div.system-message p.system-message-title {
  106. color: red ;
  107. font-weight: bold }
  108. div.topic {
  109. margin: 2em }
  110. h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
  111. h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
  112. margin-top: 0.4em }
  113. h1.title {
  114. text-align: center }
  115. h2.subtitle {
  116. text-align: center }
  117. hr.docutils {
  118. width: 75% }
  119. img.align-left {
  120. clear: left }
  121. img.align-right {
  122. clear: right }
  123. img.borderless {
  124. border: 0 }
  125. ol.simple, ul.simple {
  126. margin-bottom: 1em }
  127. ol.arabic {
  128. list-style: decimal }
  129. ol.loweralpha {
  130. list-style: lower-alpha }
  131. ol.upperalpha {
  132. list-style: upper-alpha }
  133. ol.lowerroman {
  134. list-style: lower-roman }
  135. ol.upperroman {
  136. list-style: upper-roman }
  137. p.attribution {
  138. text-align: right ;
  139. margin-left: 50% }
  140. p.caption {
  141. font-style: italic }
  142. p.credits {
  143. font-style: italic ;
  144. font-size: smaller }
  145. p.label {
  146. white-space: nowrap }
  147. p.rubric {
  148. font-weight: bold ;
  149. font-size: larger ;
  150. color: maroon ;
  151. text-align: center }
  152. p.sidebar-title {
  153. font-family: sans-serif ;
  154. font-weight: bold ;
  155. font-size: larger }
  156. p.sidebar-subtitle {
  157. font-family: sans-serif ;
  158. font-weight: bold }
  159. p.topic-title {
  160. font-weight: bold }
  161. pre.address {
  162. margin-bottom: 0 ;
  163. margin-top: 0 ;
  164. font-family: serif ;
  165. font-size: 100% }
  166. pre.line-block {
  167. font-family: serif ;
  168. font-size: 100% }
  169. pre.literal-block, pre.doctest-block {
  170. margin-left: 2em ;
  171. margin-right: 2em ;
  172. background-color: #eeeeee }
  173. span.classifier {
  174. font-family: sans-serif ;
  175. font-style: oblique }
  176. span.classifier-delimiter {
  177. font-family: sans-serif ;
  178. font-weight: bold }
  179. span.interpreted {
  180. font-family: sans-serif }
  181. span.option {
  182. white-space: nowrap }
  183. span.pre {
  184. white-space: pre }
  185. span.problematic {
  186. color: red }
  187. span.section-subtitle {
  188. /* font-size relative to parent (h1..h6 element) */
  189. font-size: 80% }
  190. table.citation {
  191. border-left: solid thin gray }
  192. table.docinfo {
  193. margin: 2em 4em }
  194. table.docutils {
  195. margin-top: 0.5em ;
  196. margin-bottom: 0.5em }
  197. table.footnote {
  198. border-left: solid thin black }
  199. table.docutils td, table.docutils th,
  200. table.docinfo td, table.docinfo th {
  201. padding-left: 0.5em ;
  202. padding-right: 0.5em ;
  203. vertical-align: top }
  204. table.docutils th.field-name, table.docinfo th.docinfo-name {
  205. font-weight: bold ;
  206. text-align: left ;
  207. white-space: nowrap ;
  208. padding-left: 0 }
  209. h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
  210. h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
  211. font-size: 100% }
  212. tt.docutils {
  213. background-color: #eeeeee }
  214. ul.auto-toc {
  215. list-style-type: none }
  216. </style>
  217. </head>
  218. <body>
  219. <div class="document" id="boost-pointer-container-library">
  220. <h1 class="title"><img alt="Boost" src="boost.png" /> Pointer Container Library</h1>
  221. <h2 class="subtitle" id="reference">Reference</h2>
  222. <p>The documentation is divided into an explanation for
  223. each container. When containers have the same interface, that common interface is explained only once,
  224. but links are always provided to more relevant information.
  225. Please make sure you understand
  226. the <a class="reference" href="reference.html#the-Clonable-concept">Clonable</a> concept and
  227. the <a class="reference" href="reference.html#the-clone-allocator-concept">Clone Allocator</a> concept.</p>
  228. <ul class="simple">
  229. <li><a class="reference" href="conventions.html">Conventions</a></li>
  230. <li><a class="reference" href="#the-clonable-concept">The Clonable concept</a></li>
  231. <li><a class="reference" href="#the-clone-allocator-concept">The Clone Allocator concept</a></li>
  232. <li><a class="reference" href="#class-hierarchy">Class hierarchy</a>:<ul>
  233. <li><a class="reference" href="reversible_ptr_container.html">reversible_ptr_container</a><ul>
  234. <li><a class="reference" href="ptr_sequence_adapter.html">ptr_sequence_adapter</a><ul>
  235. <li><a class="reference" href="ptr_vector.html">ptr_vector</a></li>
  236. <li><a class="reference" href="ptr_list.html">ptr_list</a></li>
  237. <li><a class="reference" href="ptr_deque.html">ptr_deque</a></li>
  238. <li><a class="reference" href="ptr_array.html">ptr_array</a></li>
  239. </ul>
  240. </li>
  241. <li><a class="reference" href="associative_ptr_container.html">associative_ptr_container</a><ul>
  242. <li><a class="reference" href="ptr_set_adapter.html">ptr_set_adapter</a></li>
  243. <li><a class="reference" href="ptr_multiset_adapter.html">ptr_multiset_adapter</a></li>
  244. <li><a class="reference" href="ptr_map_adapter.html">ptr_map_adapter</a></li>
  245. <li><a class="reference" href="ptr_multimap_adapter.html">ptr_multi_map_adapter</a><ul>
  246. <li><a class="reference" href="ptr_set.html">ptr_set</a></li>
  247. <li><a class="reference" href="ptr_multiset.html">ptr_multi_set</a></li>
  248. <li><a class="reference" href="ptr_map.html">ptr_map</a></li>
  249. <li><a class="reference" href="ptr_multimap.html">ptr_multimap</a></li>
  250. </ul>
  251. </li>
  252. </ul>
  253. </li>
  254. </ul>
  255. </li>
  256. </ul>
  257. </li>
  258. <li><a class="reference" href="#serialization">Serialization</a></li>
  259. <li><a class="reference" href="indirect_fun.html">Indirected functions</a></li>
  260. <li><a class="reference" href="ptr_inserter.html">Insert iterators</a></li>
  261. <li><a class="reference" href="#class-nullable">Class nullable</a></li>
  262. <li><a class="reference" href="#exception-classes">Exception classes</a></li>
  263. <li><a class="reference" href="#disabling-the-use-of-exceptions">Disabling the use of exceptions</a></li>
  264. </ul>
  265. <!-- - Class `reversible_ptr_container <reversible_ptr_container.html>`_
  266. - Class `associative_ptr_container <associative_ptr_container.html>`_
  267. - `Pointer container adapters`_
  268. - `ptr_sequence_adapter <ptr_sequence_adapter.html>`_
  269. - `ptr_set_adapter <ptr_set_adapter.html>`_
  270. - `ptr_multiset_adapter <ptr_multiset_adapter.html>`_
  271. - `ptr_map_adapter <ptr_map_adapter.html>`_
  272. - `ptr_multimap_adapter <ptr_multimap_adapter.html>`_
  273. - `Sequence containers`_
  274. - `ptr_vector <ptr_vector.html>`_
  275. - `ptr_deque <ptr_deque.html>`_
  276. - `ptr_list <ptr_list.html>`_
  277. - `ptr_array <ptr_array.html>`_
  278. - `Associative containers`_
  279. - `ptr_set <ptr_set.html>`_
  280. - `ptr_multiset <ptr_multiset.html>`_
  281. - `ptr_map <ptr_map.html>`_
  282. - `ptr_multimap <ptr_multimap.html>`_ -->
  283. <div class="section">
  284. <h1><a id="the-clonable-concept" name="the-clonable-concept">The Clonable concept</a></h1>
  285. <p><strong>Refinement of</strong></p>
  286. <ul class="simple">
  287. <li>Heap Allocable</li>
  288. <li>Heap Deallocable</li>
  289. </ul>
  290. <p>The Clonable concept is introduced to formalize the requirements for
  291. copying heap-allocated objects. A type <tt class="docutils literal"><span class="pre">T</span></tt> might be Clonable even though it
  292. is not Assignable or Copy Constructible. Notice that many operations on
  293. the containers do not even require the stored type to be Clonable.</p>
  294. <p><strong>Notation</strong></p>
  295. <table border="1" class="docutils">
  296. <colgroup>
  297. <col width="21%" />
  298. <col width="41%" />
  299. <col width="18%" />
  300. <col width="20%" />
  301. </colgroup>
  302. <tbody valign="top">
  303. <tr><td><strong>Type</strong></td>
  304. <td><strong>Object</strong> (<tt class="docutils literal"><span class="pre">const</span></tt> or non-<tt class="docutils literal"><span class="pre">const</span></tt>)</td>
  305. <td><strong>Pointer</strong></td>
  306. <td><strong>Describes</strong></td>
  307. </tr>
  308. <tr><td><tt class="docutils literal"><span class="pre">T</span></tt></td>
  309. <td><tt class="docutils literal"><span class="pre">a</span></tt></td>
  310. <td><tt class="docutils literal"><span class="pre">ptr</span></tt></td>
  311. <td>A Clonable type</td>
  312. </tr>
  313. </tbody>
  314. </table>
  315. <p><strong>Valid expressions</strong></p>
  316. <table border="1" class="docutils">
  317. <colgroup>
  318. <col width="19%" />
  319. <col width="14%" />
  320. <col width="46%" />
  321. <col width="20%" />
  322. </colgroup>
  323. <tbody valign="top">
  324. <tr><td><strong>Expression</strong></td>
  325. <td><strong>Type</strong></td>
  326. <td><strong>Semantics</strong></td>
  327. <td><strong>Postcondition</strong></td>
  328. </tr>
  329. <tr><td><tt class="docutils literal"><span class="pre">new_clone(a);</span></tt></td>
  330. <td><tt class="docutils literal"><span class="pre">T*</span></tt></td>
  331. <td>Allocate a new object that can be considered equivalent to the <tt class="docutils literal"><span class="pre">a</span></tt> object</td>
  332. <td><tt class="docutils literal"><span class="pre">typeid(*new_clone(a))</span> <span class="pre">==</span> <span class="pre">typeid(a)</span></tt></td>
  333. </tr>
  334. <tr><td><tt class="docutils literal"><span class="pre">delete_clone(ptr);</span></tt></td>
  335. <td><tt class="docutils literal"><span class="pre">void</span></tt></td>
  336. <td>Deallocate an object previously allocated with <tt class="docutils literal"><span class="pre">allocate_clone()</span></tt>. Must not throw</td>
  337. <td>&nbsp;</td>
  338. </tr>
  339. </tbody>
  340. </table>
  341. <div class="section">
  342. <h2><a id="default-implementation" name="default-implementation">Default implementation</a></h2>
  343. <p>In the <tt class="docutils literal"><span class="pre">&lt;boost/ptr_container/clone_allocator.hpp&gt;</span></tt> header a default implementation
  344. of the two functions is given:</p>
  345. <pre class="literal-block">
  346. namespace boost
  347. {
  348. template&lt; class T &gt;
  349. inline T* new_clone( const T&amp; t )
  350. {
  351. return new T( t );
  352. }
  353. template&lt; class T &gt;
  354. void delete_clone( const T* t )
  355. {
  356. checked_delete( t );
  357. }
  358. }
  359. </pre>
  360. <p>Notice that this implementation makes normal Copy Constructible classes automatically
  361. Clonable unless <tt class="docutils literal"><span class="pre">operator</span> <span class="pre">new()</span></tt> or <tt class="docutils literal"><span class="pre">operator</span> <span class="pre">delete()</span></tt> are hidden.</p>
  362. <p>The two functions represent a layer of indirection which is necessary to support
  363. classes that are not Copy Constructible by default. Notice that the implementation
  364. relies on argument-dependent lookup (ADL) to find the right version of
  365. <tt class="docutils literal"><span class="pre">new_clone()</span></tt> and <tt class="docutils literal"><span class="pre">delete_clone()</span></tt>. This means that one does not need to overload or specialize
  366. the function in the boost namespace, but it can be placed together with
  367. the rest of the interface of the class. If you are implementing a class
  368. inline in headers, remember to forward declare the functions.</p>
  369. <p><strong>Warning: We are considering the removal of default implementation above. Therefore always make sure that you overload the functions for your types and do not rely on the defaults in any way.</strong></p>
  370. </div>
  371. </div>
  372. <div class="section">
  373. <h1><a id="the-clone-allocator-concept" name="the-clone-allocator-concept">The Clone Allocator concept</a></h1>
  374. <p>The Clone Allocator concept is introduced to formalize the way
  375. pointer containers control memory of
  376. the stored objects (and not the pointers to the stored objects).
  377. The clone allocator allows
  378. users to apply custom allocators/deallocators for the cloned objects.</p>
  379. <p>More information can be found below:</p>
  380. <div class="contents local topic">
  381. <ul class="simple">
  382. <li><a class="reference" href="#clone-allocator-requirements" id="id19" name="id19">Clone Allocator requirements</a></li>
  383. <li><a class="reference" href="#class-heap-clone-allocator" id="id20" name="id20">Class <tt class="docutils literal"><span class="pre">heap_clone_allocator</span></tt></a></li>
  384. <li><a class="reference" href="#class-view-clone-allocator" id="id21" name="id21">Class <tt class="docutils literal"><span class="pre">view_clone_allocator</span></tt></a></li>
  385. </ul>
  386. </div>
  387. <div class="section">
  388. <h2><a class="toc-backref" href="#id19" id="clone-allocator-requirements" name="clone-allocator-requirements">Clone Allocator requirements</a></h2>
  389. <p><strong>Notation</strong></p>
  390. <table border="1" class="docutils">
  391. <colgroup>
  392. <col width="18%" />
  393. <col width="39%" />
  394. <col width="43%" />
  395. </colgroup>
  396. <tbody valign="top">
  397. <tr><td><strong>Type</strong></td>
  398. <td><strong>Object</strong> (<tt class="docutils literal"><span class="pre">const</span></tt> or non-<tt class="docutils literal"><span class="pre">const</span></tt>)</td>
  399. <td><strong>Describes</strong></td>
  400. </tr>
  401. <tr><td><tt class="docutils literal"><span class="pre">T</span></tt></td>
  402. <td><tt class="docutils literal"><span class="pre">a</span></tt></td>
  403. <td>A type</td>
  404. </tr>
  405. <tr><td><tt class="docutils literal"><span class="pre">T*</span></tt></td>
  406. <td><tt class="docutils literal"><span class="pre">ptr</span></tt></td>
  407. <td>A pointer to <tt class="docutils literal"><span class="pre">T</span></tt></td>
  408. </tr>
  409. </tbody>
  410. </table>
  411. <p><strong>Valid expressions</strong></p>
  412. <table border="1" class="docutils">
  413. <colgroup>
  414. <col width="23%" />
  415. <col width="7%" />
  416. <col width="39%" />
  417. <col width="31%" />
  418. </colgroup>
  419. <tbody valign="top">
  420. <tr><td><strong>Expression</strong></td>
  421. <td><strong>Type</strong></td>
  422. <td><strong>Semantics</strong></td>
  423. <td><strong>Postcondition</strong></td>
  424. </tr>
  425. <tr><td><tt class="docutils literal"><span class="pre">CloneAllocator::allocate_clone(a);</span></tt></td>
  426. <td><tt class="docutils literal"><span class="pre">T*</span></tt></td>
  427. <td>Allocate a new object that can be considered equivalent to the
  428. <tt class="docutils literal"><span class="pre">a</span></tt> object</td>
  429. <td><tt class="docutils literal"><span class="pre">typeid(*CloneAllocator::allocate_clone(a))</span> <span class="pre">==</span> <span class="pre">typeid(a)</span></tt></td>
  430. </tr>
  431. <tr><td><tt class="docutils literal"><span class="pre">CloneAllocator::deallocate_clone(ptr);</span></tt></td>
  432. <td><tt class="docutils literal"><span class="pre">void</span></tt></td>
  433. <td>Deallocate an object previously allocated with
  434. <tt class="docutils literal"><span class="pre">CloneAllocator::allocate_clone()</span></tt> or a compatible allocator.
  435. Must not throw.</td>
  436. <td>&nbsp;</td>
  437. </tr>
  438. </tbody>
  439. </table>
  440. <p>The library comes with two predefined clone allocators.</p>
  441. </div>
  442. <div class="section">
  443. <h2><a class="toc-backref" href="#id20" id="class-heap-clone-allocator" name="class-heap-clone-allocator">Class <tt class="docutils literal docutils literal"><span class="pre">heap_clone_allocator</span></tt></a></h2>
  444. <p>This is the default clone allocator used by all pointer containers. For most
  445. purposes you will never have to change this default.</p>
  446. <p><strong>Definition</strong></p>
  447. <pre class="literal-block">
  448. namespace boost
  449. {
  450. struct heap_clone_allocator
  451. {
  452. template&lt; class U &gt;
  453. static U* allocate_clone( const U&amp; r )
  454. {
  455. return new_clone( r );
  456. }
  457. template&lt; class U &gt;
  458. static void deallocate_clone( const U* r )
  459. {
  460. delete_clone( r );
  461. }
  462. };
  463. }
  464. </pre>
  465. <p>Notice that the above definition allows you to support custom allocation
  466. schemes by relying on <tt class="docutils literal"><span class="pre">new_clone()</span></tt> and <tt class="docutils literal"><span class="pre">delete_clone()</span></tt>.</p>
  467. </div>
  468. <div class="section">
  469. <h2><a class="toc-backref" href="#id21" id="class-view-clone-allocator" name="class-view-clone-allocator">Class <tt class="docutils literal docutils literal"><span class="pre">view_clone_allocator</span></tt></a></h2>
  470. <p>This class provides a way to remove ownership properties of the
  471. pointer containers. As its name implies, this means that you can
  472. instead use the pointer containers as a view into an existing
  473. container.</p>
  474. <p><strong>Definition</strong></p>
  475. <pre class="literal-block">
  476. namespace boost
  477. {
  478. struct view_clone_allocator
  479. {
  480. template&lt; class U &gt;
  481. static U* allocate_clone( const U&amp; r )
  482. {
  483. return const_cast&lt;U*&gt;(&amp;r);
  484. }
  485. template&lt; class U &gt;
  486. static void deallocate_clone( const U* )
  487. {
  488. // empty
  489. }
  490. };
  491. }
  492. </pre>
  493. <!-- **See also**
  494. - `Changing the clone allocator <examples.html#changing-the-clone-allocator>`_ -->
  495. </div>
  496. </div>
  497. <div class="section">
  498. <h1><a id="class-hierarchy" name="class-hierarchy">Class hierarchy</a></h1>
  499. <p>The library consists of the following types of classes:</p>
  500. <ol class="arabic simple">
  501. <li>Pointer container adapters</li>
  502. </ol>
  503. <!-- -->
  504. <ol class="arabic simple" start="2">
  505. <li>Pointer containers</li>
  506. </ol>
  507. <p>The pointer container adapters are used when you
  508. want to make a pointer container starting from
  509. your own &quot;normal&quot; container. For example, you
  510. might have a map class that extends <tt class="docutils literal"><span class="pre">std::map</span></tt>
  511. in some way; the adapter class then allows you
  512. to use your map class as a basis for a new
  513. pointer container.</p>
  514. <p>The library provides an adapter for each type
  515. of standard container highlighted as links below:</p>
  516. <ul class="simple">
  517. <li><tt class="docutils literal"><span class="pre">reversible_ptr_container</span></tt><ul>
  518. <li><a class="reference" href="ptr_sequence_adapter.html">ptr_sequence_adapter</a><ul>
  519. <li><tt class="docutils literal"><span class="pre">ptr_vector</span></tt></li>
  520. <li><tt class="docutils literal"><span class="pre">ptr_list</span></tt></li>
  521. <li><tt class="docutils literal"><span class="pre">ptr_deque</span></tt></li>
  522. <li><tt class="docutils literal"><span class="pre">ptr_array</span></tt></li>
  523. </ul>
  524. </li>
  525. <li><tt class="docutils literal"><span class="pre">associative_ptr_container</span></tt><ul>
  526. <li><a class="reference" href="ptr_set_adapter.html">ptr_set_adapter</a></li>
  527. <li><a class="reference" href="ptr_multiset_adapter.html">ptr_multiset_adapter</a></li>
  528. <li><a class="reference" href="ptr_map_adapter.html">ptr_map_adapter</a></li>
  529. <li><a class="reference" href="ptr_multimap_adapter.html">ptr_multi_map_adapter</a><ul>
  530. <li><tt class="docutils literal"><span class="pre">ptr_set</span></tt></li>
  531. <li><tt class="docutils literal"><span class="pre">ptr_multi_set</span></tt></li>
  532. <li><tt class="docutils literal"><span class="pre">ptr_map</span></tt></li>
  533. <li><tt class="docutils literal"><span class="pre">ptr_multimap</span></tt></li>
  534. </ul>
  535. </li>
  536. </ul>
  537. </li>
  538. </ul>
  539. </li>
  540. </ul>
  541. <p>The pointer containers of this library are all built using
  542. the adapters. There is a pointer container
  543. for each type of &quot;normal&quot; standard container highlighted as links below.</p>
  544. <ul class="simple">
  545. <li><tt class="docutils literal"><span class="pre">reversible_ptr_container</span></tt><ul>
  546. <li><tt class="docutils literal"><span class="pre">ptr_sequence_adapter</span></tt><ul>
  547. <li><a class="reference" href="ptr_vector.html">ptr_vector</a></li>
  548. <li><a class="reference" href="ptr_list.html">ptr_list</a></li>
  549. <li><a class="reference" href="ptr_deque.html">ptr_deque</a></li>
  550. <li><a class="reference" href="ptr_array.html">ptr_array</a></li>
  551. </ul>
  552. </li>
  553. <li><tt class="docutils literal"><span class="pre">associative_ptr_container</span></tt><ul>
  554. <li><tt class="docutils literal"><span class="pre">ptr_set_adapter</span></tt></li>
  555. <li><tt class="docutils literal"><span class="pre">ptr_multiset_adapter</span></tt></li>
  556. <li><tt class="docutils literal"><span class="pre">ptr_map_adapter</span></tt></li>
  557. <li><tt class="docutils literal"><span class="pre">ptr_multi_map_adapter</span></tt><ul>
  558. <li><a class="reference" href="ptr_set.html">ptr_set</a></li>
  559. <li><a class="reference" href="ptr_multiset.html">ptr_multi_set</a></li>
  560. <li><a class="reference" href="ptr_map.html">ptr_map</a></li>
  561. <li><a class="reference" href="ptr_multimap.html">ptr_multimap</a></li>
  562. </ul>
  563. </li>
  564. </ul>
  565. </li>
  566. </ul>
  567. </li>
  568. </ul>
  569. </div>
  570. <div class="section">
  571. <h1><a id="serialization" name="serialization">Serialization</a></h1>
  572. <p>As of version 1.34.0 of Boost, the library supports
  573. serialization via <a class="reference" href="../../serialization/index.html">Boost.Serialization</a>.</p>
  574. <p>Of course, for serialization to work it is required
  575. that the stored type itself is serializable. For maps, both
  576. the key type and the mapped type must be serializable.</p>
  577. <p>When dealing with serialization (and serialization of polymophic objects in particular),
  578. pay special attention to these parts of Boost.Serialization:</p>
  579. <ol class="arabic">
  580. <li><p class="first">Output/saving requires a const-reference:</p>
  581. <pre class="literal-block">
  582. //
  583. // serialization helper: we can't save a non-const object
  584. //
  585. template&lt; class T &gt;
  586. inline T const&amp; as_const( T const&amp; r )
  587. {
  588. return r;
  589. }
  590. ...
  591. Container cont;
  592. std::ofstream ofs(&quot;filename&quot;);
  593. boost::archive::text_oarchive oa(ofs);
  594. oa &lt;&lt; as_const(cont);
  595. </pre>
  596. <p>See <a class="reference" href="../../serialization/doc/rationale.html#trap">Compile time trap when saving a non-const value</a> for
  597. details.</p>
  598. </li>
  599. </ol>
  600. <ol class="arabic" start="2">
  601. <li><p class="first">Derived classes need to call <tt class="docutils literal"><span class="pre">base_object()</span></tt> function:</p>
  602. <pre class="literal-block">
  603. struct Derived : Base
  604. {
  605. template&lt; class Archive &gt;
  606. void serialize( Archive&amp; ar, const unsigned int version )
  607. {
  608. ar &amp; boost::serialization::base_object&lt;Base&gt;( *this );
  609. ...
  610. }
  611. };
  612. </pre>
  613. <p>For details, see <a class="reference" href="../../serialization/doc/tutorial.html#derivedclasses">Derived Classes</a>.</p>
  614. </li>
  615. </ol>
  616. <ol class="arabic" start="3">
  617. <li><p class="first">You need to use <tt class="docutils literal"><span class="pre">BOOST_CLASS_EXPORT</span></tt> to register the
  618. derived classes in your class hierarchy:</p>
  619. <pre class="literal-block">
  620. BOOST_CLASS_EXPORT( Derived )
  621. </pre>
  622. <p>See <a class="reference" href="../../serialization/doc/traits.html#export">Export Key</a> and <a class="reference" href="../../serialization/doc/special.html">Object Tracking</a>
  623. for details.</p>
  624. </li>
  625. </ol>
  626. <p>Remember these three issues and it might save you some trouble.</p>
  627. <!-- Map iterator operations
  628. +++++++++++++++++++++++
  629. The map iterators are a bit different compared to the normal ones. The
  630. reason is that it is a bit clumsy to access the key and the mapped object
  631. through i->first and i->second, and one tends to forget what is what.
  632. Moreover, and more importantly, we also want to hide the pointer as much as possibble.
  633. The new style can be illustrated with a small example::
  634. typedef ptr_map<string,int> map_t;
  635. map_t m;
  636. m[ "foo" ] = 4; // insert pair
  637. m[ "bar" ] = 5; // ditto
  638. ...
  639. for( map_t::iterator i = m.begin(); i != m.end(); ++i )
  640. {
  641. *i += 42; // add 42 to each value
  642. cout << "value=" << *i << ", key=" << i.key() << "n";
  643. }
  644. So the difference from the normal map iterator is that
  645. - ``operator*()`` returns a reference to the mapped object (normally it returns a reference to a ``std::pair``, and
  646. - that the key can be accessed through the ``key()`` function. -->
  647. </div>
  648. <div class="section">
  649. <h1><a id="class-nullable" name="class-nullable">Class <tt class="docutils literal"><span class="pre">nullable</span></tt></a></h1>
  650. <p>The purpose of the class is simply to tell the containers
  651. that null values should be allowed. Its definition is
  652. trivial:</p>
  653. <pre class="literal-block">
  654. namespace boost
  655. {
  656. template&lt; class T &gt;
  657. struct nullable
  658. {
  659. typedef T type;
  660. };
  661. }
  662. </pre>
  663. <p>Please notice that <tt class="docutils literal"><span class="pre">nullable</span></tt> has no effect on the containers
  664. interface (except for <tt class="docutils literal"><span class="pre">is_null()</span></tt> functions). For example, it
  665. does not make sense to do</p>
  666. <pre class="literal-block">
  667. boost::ptr_vector&lt; boost::nullable&lt;T&gt; &gt; vec;
  668. vec.push_back( 0 ); // ok
  669. vec.push_back( new boost::nullable&lt;T&gt; ); // no no!
  670. boost::nullable&lt;T&gt;&amp; ref = vec[0]; // also no no!
  671. </pre>
  672. </div>
  673. <div class="section">
  674. <h1><a id="exception-classes" name="exception-classes">Exception classes</a></h1>
  675. <p>There are three exceptions that are thrown by this library. The exception
  676. hierarchy looks as follows:</p>
  677. <pre class="literal-block">
  678. namespace boost
  679. {
  680. class bad_ptr_container_operation : public std::exception
  681. {
  682. public:
  683. bad_ptr_container_operation( const char* what );
  684. };
  685. class bad_index : public bad_ptr_container_operation
  686. {
  687. public:
  688. bad_index( const char* what );
  689. };
  690. class bad_pointer : public bad_ptr_container_operation
  691. {
  692. public:
  693. bad_pointer();
  694. bad_pointer( const char* what );
  695. };
  696. }
  697. </pre>
  698. </div>
  699. <div class="section">
  700. <h1><a id="disabling-the-use-of-exceptions" name="disabling-the-use-of-exceptions">Disabling the use of exceptions</a></h1>
  701. <p>As of version 1.34.0 of Boost, the library allows you to disable exceptions
  702. completely. This means the library is more fit for domains where exceptions
  703. are not used. Furthermore, it also speeds up a operations a little. Instead
  704. of throwing an exception, the library simply calls <a class="reference" href="../../utility/assert.html">BOOST_ASSERT</a>.</p>
  705. <p>To disable exceptions, simply define this macro before including any header:</p>
  706. <pre class="literal-block">
  707. #define BOOST_PTR_CONTAINER_NO_EXCEPTIONS 1
  708. #include &lt;boost/ptr_container/ptr_vector.hpp&gt;
  709. </pre>
  710. <p>It is, however, recommended that you define the macro on the command-line, so
  711. you are absolutely certain that all headers are compiled the same way. Otherwise
  712. you might end up breaking the One Definition Rule.</p>
  713. <p>If <tt class="docutils literal"><span class="pre">BOOST_NO_EXCEPTIONS</span></tt> is defined, then <tt class="docutils literal"><span class="pre">BOOST_PTR_CONTAINER_NO_EXCEPTIONS</span></tt>
  714. is also defined.</p>
  715. <hr><p><strong>Navigate:</strong></p>
  716. <ul class="simple">
  717. <li><a class="reference" href="ptr_container.html">home</a></li>
  718. </ul>
  719. <hr><table class="docutils field-list" frame="void" rules="none">
  720. <col class="field-name" />
  721. <col class="field-body" />
  722. <tbody valign="top">
  723. <tr class="field"><th class="field-name">Copyright:</th><td class="field-body">Thorsten Ottosen 2004-2007. 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>
  724. </tr>
  725. </tbody>
  726. </table>
  727. </div>
  728. </div>
  729. </body>
  730. </html>