diff options
| author | Anas Nashif <anas.nashif@intel.com> | 2012-10-30 12:57:26 -0700 |
|---|---|---|
| committer | Anas Nashif <anas.nashif@intel.com> | 2012-10-30 12:57:26 -0700 |
| commit | 1a78a62555be32868418fe52f8e330c9d0f95d5a (patch) | |
| tree | d3765a80e7d3b9640ec2e930743630cd6b9fce2b /libs/ptr_container | |
| download | boost-1a78a62555be32868418fe52f8e330c9d0f95d5a.tar.gz boost-1a78a62555be32868418fe52f8e330c9d0f95d5a.tar.bz2 boost-1a78a62555be32868418fe52f8e330c9d0f95d5a.zip | |
Imported Upstream version 1.49.0upstream/1.49.0
Diffstat (limited to 'libs/ptr_container')
113 files changed, 23931 insertions, 0 deletions
diff --git a/libs/ptr_container/doc/Jamfile.v2 b/libs/ptr_container/doc/Jamfile.v2 new file mode 100644 index 0000000000..4bb6cf591f --- /dev/null +++ b/libs/ptr_container/doc/Jamfile.v2 @@ -0,0 +1,20 @@ +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +project boost/ptr_container/doc ; + +import boostbook : boostbook ; +import doxygen ; + +boostbook doc : ptr_container.xml ; + + + diff --git a/libs/ptr_container/doc/associative_ptr_container.html b/libs/ptr_container/doc/associative_ptr_container.html new file mode 100644 index 0000000000..b20fa227c7 --- /dev/null +++ b/libs/ptr_container/doc/associative_ptr_container.html @@ -0,0 +1,544 @@ +<?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: 2006-11-22 17:01:03 -0500 (Wed, 22 Nov 2006) $ +:Revision: $Revision: 36152 $ +: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> +<div class="section"> +<h1><a id="class-associative-ptr-container" name="class-associative-ptr-container">Class <tt class="docutils literal"><span class="pre">associative_ptr_container</span></tt></a></h1> +<p>This section describes all the common operations for all associative +pointer containers (in addition to <tt class="docutils literal"><span class="pre">reversible_ptr_container</span></tt>).</p> +<p><strong>Hierarchy:</strong></p> +<ul class="simple"> +<li><a class="reference" href="reversible_ptr_container.html">reversible_ptr_container</a><ul> +<li><tt class="docutils literal"><span class="pre">associative_ptr_container</span></tt><ul> +<li><a class="reference" href="ptr_set_adapter.html">ptr_set_adapter</a></li> +<li><a class="reference" href="ptr_multiset_adapter.html">ptr_multiset_adapter</a></li> +<li><a class="reference" href="ptr_map_adapter.html">ptr_map_adapter</a></li> +<li><a class="reference" href="ptr_multimap_adapter.html">ptr_multi_map_adapter</a><ul> +<li><a class="reference" href="ptr_set.html">ptr_set</a></li> +<li><a class="reference" href="ptr_multiset.html">ptr_multi_set</a></li> +<li><a class="reference" href="ptr_map.html">ptr_map</a></li> +<li><a class="reference" href="ptr_multimap.html">ptr_multimap</a></li> +</ul> +</li> +</ul> +</li> +</ul> +</li> +</ul> +<p><strong>See also:</strong></p> +<ul class="simple"> +<li><a class="reference" href="http://www.boost.org/libs/range/doc/utility_class.html#iter_range">iterator_range</a></li> +</ul> +<p><strong>Navigate:</strong></p> +<ul class="simple"> +<li><a class="reference" href="ptr_container.html">home</a></li> +<li><a class="reference" href="reference.html">reference</a></li> +</ul> +<p><strong>Synopsis:</strong></p> +<pre class="literal-block"> +namespace boost +{ + template + < + class Key, + class CloneAllocator = heap_clone_allocator + > + class associative_ptr_container + { + public: // <a class="reference" href="#typedefs">typedefs</a> + typedef ... key_type; + typedef ... key_compare; + typedef ... value_compare; + + public: // <a class="reference" href="#observers">observers</a> + key_compare key_comp() const; + value_compare value_comp() const; + + public: // <a class="reference" href="#modifiers">modifiers</a> + template< typename InputIterator > + void insert( InputIterator first, InputIterator last ); + template< class InputRange > + void insert( const InputRange& r ); + void erase( iterator position ); + size_type erase( const key_type& x ); + template< class Range > + void erase( const Range& r ); + void erase( iterator first, iterator last ); + + public: // <a class="reference" href="#algorithms">algorithms</a> + iterator find( const key_type& x ); + const_iterator find( const key_type& x ) const; + size_type count( const key_type& x ) const; + iterator lower_bound( const key_type& x ); + const_iterator lower_bound( const key_type& x ) const; + iterator upper_bound( const key_type& x ); + const_iterator upper_bound( const key_type& x ) const; + iterator_range<iterator> equal_range( const key_type& x ); + iterator_range<const_iterator> equal_range( const key_type& x ) const; + + }; // class 'associative_ptr_container' + +} // namespace 'boost' +</pre> +</div> +<div class="section"> +<h1><a id="semantics" name="semantics">Semantics</a></h1> +<div class="section"> +<h2><a id="semantics-typedefs" name="semantics-typedefs"><span id="typedefs"></span>Semantics: typedefs</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">...</span> <span class="pre">key_type;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>if we are dealing with a map, then simply the key type</li> +<li>if we are dealing with a set, then the <em>indirected</em> key type, that is, +given <tt class="docutils literal"><span class="pre">ptr_set<T></span></tt>, <tt class="docutils literal"><span class="pre">key_type*</span></tt> will be <tt class="docutils literal"><span class="pre">T*</span></tt>.</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">...</span> <span class="pre">key_compare;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>comparison object type that determines the order of elements in the container</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">...</span> <span class="pre">value_compare;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>comparison object type that determines the order of elements in the container</li> +<li>if we are dealing with a map, then this comparison simply forwards to the <tt class="docutils literal"><span class="pre">key_compare</span></tt> comparison operation</li> +</ul> +</blockquote> +</li> +</ul> +</div> +<div class="section"> +<h2><a id="semantics-observers" name="semantics-observers"><span id="observers"></span>Semantics: observers</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">key_compare</span> <span class="pre">key_comp()</span> <span class="pre">const;</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">value_compare</span> <span class="pre">value_comp()</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>returns copies of objects used to determine the order of elements</li> +</ul> +</blockquote> +</li> +</ul> +</div> +<div class="section"> +<h2><a id="semantics-modifiers" name="semantics-modifiers"><span id="modifiers"></span>Semantics: modifiers</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">typename</span> <span class="pre">InputIterator</span> <span class="pre">></span> +<span class="pre">void</span> <span class="pre">insert(</span> <span class="pre">InputIterator</span> <span class="pre">first,</span> <span class="pre">InputIterator</span> <span class="pre">last</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">[first,last)</span></tt> is a valid range</li> +<li>Effects: Inserts a cloned range</li> +<li>Exception safety: Basic guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">InputRange</span> <span class="pre">></span> +<span class="pre">void</span> <span class="pre">insert(</span> <span class="pre">const</span> <span class="pre">InputRange&</span> <span class="pre">r</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: <tt class="docutils literal"><span class="pre">insert(</span> <span class="pre">boost::begin(r),</span> <span class="pre">boost::end(r)</span> <span class="pre">);</span></tt></li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">erase(</span> <span class="pre">iterator</span> <span class="pre">position</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">position</span></tt> is a valid iterator from the container</li> +<li>Effects: Removes the element defined by <tt class="docutils literal"><span class="pre">position</span></tt>.</li> +<li>Throws: Nothing</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">size_type</span> <span class="pre">erase(</span> <span class="pre">const</span> <span class="pre">key_type&</span> <span class="pre">x</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Removes all the elements in the container with a key equivalent to <tt class="docutils literal"><span class="pre">x</span></tt> and returns the number of erased elements.</li> +<li>Throws: Nothing</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">erase(</span> <span class="pre">iterator</span> <span class="pre">first,</span> <span class="pre">iterator</span> <span class="pre">last</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">[first,last)</span></tt> is a valid range</li> +<li>Effects: Removes the range of elements defined by <tt class="docutils literal"><span class="pre">[first,last)</span></tt>.</li> +<li>Throws: Nothing</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">Range</span> <span class="pre">></span> <span class="pre">void</span> <span class="pre">erase(</span> <span class="pre">const</span> <span class="pre">Range&</span> <span class="pre">r</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: <tt class="docutils literal"><span class="pre">erase(</span> <span class="pre">boost::begin(r),</span> <span class="pre">boost::end(r)</span> <span class="pre">);</span></tt></li> +</ul> +</blockquote> +</li> +</ul> +</div> +<div class="section"> +<h2><a id="semantics-algorithms" name="semantics-algorithms"><span id="algorithms"></span>Semantics: algorithms</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">iterator</span> <span class="pre">find(</span> <span class="pre">const</span> <span class="pre">Key&</span> <span class="pre">x</span> <span class="pre">);</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">const_iterator</span> <span class="pre">find(</span> <span class="pre">const</span> <span class="pre">Key&</span> <span class="pre">x</span> <span class="pre">)</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Searches for the key and returns <tt class="docutils literal"><span class="pre">end()</span></tt> on failure.</li> +<li>Complexity: Logarithmic</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">size_type</span> <span class="pre">count(</span> <span class="pre">const</span> <span class="pre">Key&</span> <span class="pre">x</span> <span class="pre">)</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Counts the elements with a key equivalent to <tt class="docutils literal"><span class="pre">x</span></tt></li> +<li>Complexity: Logarithmic</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">iterator</span> <span class="pre">lower_bound(</span> <span class="pre">const</span> <span class="pre">Key&</span> <span class="pre">x</span> <span class="pre">);</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">const_iterator</span> <span class="pre">lower_bound(</span> <span class="pre">const</span> <span class="pre">Key&</span> <span class="pre">x</span> <span class="pre">)</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Returns an iterator pointing to the first element with a key not less than <tt class="docutils literal"><span class="pre">x</span></tt></li> +<li>Complexity: Logarithmic</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">iterator</span> <span class="pre">upper_bound(</span> <span class="pre">const</span> <span class="pre">Key&</span> <span class="pre">x</span> <span class="pre">);</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">const_iterator</span> <span class="pre">upper_bound(</span> <span class="pre">const</span> <span class="pre">Key&</span> <span class="pre">x</span> <span class="pre">)</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Returns an iterator pointing to the first element with a key greater than <tt class="docutils literal"><span class="pre">x</span></tt></li> +<li>Complexity: Logarithmic</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">iterator_range<iterator></span> <span class="pre">equal_range(</span> <span class="pre">const</span> <span class="pre">Key&</span> <span class="pre">x</span> <span class="pre">);</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">iterator_range<const_iterator></span> <span class="pre">equal_range(</span> <span class="pre">const</span> <span class="pre">Key&</span> <span class="pre">x</span> <span class="pre">)</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: <tt class="docutils literal"><span class="pre">return</span> <span class="pre">boost::make_iterator_range(</span> <span class="pre">lower_bound(</span> <span class="pre">x</span> <span class="pre">),</span> <span class="pre">upper_bound(</span> <span class="pre">x</span> <span class="pre">)</span> <span class="pre">);</span></tt></li> +<li>Complexity: Logarithmic</li> +</ul> +</blockquote> +</li> +</ul> +<!-- - ``reference at( const key_type& key );`` +- ``const_reference at( const key_type& key ) const;`` + +- Requirements: the key exists + +- Effects: returns the object with key ``key`` + +- Throws: ``bad_ptr_container_operation`` if the key does not exist --> +<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> +</div> +</body> +</html> diff --git a/libs/ptr_container/doc/associative_ptr_container.rst b/libs/ptr_container/doc/associative_ptr_container.rst new file mode 100644 index 0000000000..b9b8d45ab8 --- /dev/null +++ b/libs/ptr_container/doc/associative_ptr_container.rst @@ -0,0 +1,224 @@ +++++++++++++++++++++++++++++++++++ + |Boost| Pointer Container Library +++++++++++++++++++++++++++++++++++ + +.. |Boost| image:: boost.png + +Class ``associative_ptr_container`` +------------------------------------- + +This section describes all the common operations for all associative +pointer containers (in addition to ``reversible_ptr_container``). + +**Hierarchy:** + +- `reversible_ptr_container <reversible_ptr_container.html>`_ + + - ``associative_ptr_container`` + + - `ptr_set_adapter <ptr_set_adapter.html>`_ + - `ptr_multiset_adapter <ptr_multiset_adapter.html>`_ + - `ptr_map_adapter <ptr_map_adapter.html>`_ + - `ptr_multi_map_adapter <ptr_multimap_adapter.html>`_ + + - `ptr_set <ptr_set.html>`_ + - `ptr_multi_set <ptr_multiset.html>`_ + - `ptr_map <ptr_map.html>`_ + - `ptr_multimap <ptr_multimap.html>`_ + +**See also:** + +- `iterator_range <http://www.boost.org/libs/range/doc/utility_class.html#iter_range>`_ + +**Navigate:** + +- `home <ptr_container.html>`_ +- `reference <reference.html>`_ + +**Synopsis:** + +.. parsed-literal:: + + namespace boost + { + template + < + class Key, + class CloneAllocator = heap_clone_allocator + > + class associative_ptr_container + { + public: // typedefs_ + typedef ... key_type; + typedef ... key_compare; + typedef ... value_compare; + + public: // `observers`_ + key_compare key_comp() const; + value_compare value_comp() const; + + public: // `modifiers`_ + template< typename InputIterator > + void insert( InputIterator first, InputIterator last ); + template< class InputRange > + void insert( const InputRange& r ); + void erase( iterator position ); + size_type erase( const key_type& x ); + template< class Range > + void erase( const Range& r ); + void erase( iterator first, iterator last ); + + public: // `algorithms`_ + iterator find( const key_type& x ); + const_iterator find( const key_type& x ) const; + size_type count( const key_type& x ) const; + iterator lower_bound( const key_type& x ); + const_iterator lower_bound( const key_type& x ) const; + iterator upper_bound( const key_type& x ); + const_iterator upper_bound( const key_type& x ) const; + iterator_range<iterator> equal_range( const key_type& x ); + iterator_range<const_iterator> equal_range( const key_type& x ) const; + + }; // class 'associative_ptr_container' + + } // namespace 'boost' + + +Semantics +--------- + +.. _typedefs: + +Semantics: typedefs +^^^^^^^^^^^^^^^^^^^ + +- ``typedef ... key_type;`` + + - if we are dealing with a map, then simply the key type + - if we are dealing with a set, then the *indirected* key type, that is, + given ``ptr_set<T>``, ``key_type*`` will be ``T*``. + +- ``typedef ... key_compare;`` + + - comparison object type that determines the order of elements in the container + +- ``typedef ... value_compare;`` + + - comparison object type that determines the order of elements in the container + - if we are dealing with a map, then this comparison simply forwards to the ``key_compare`` comparison operation + +.. _`observers`: + +Semantics: observers +^^^^^^^^^^^^^^^^^^^^ + +- ``key_compare key_comp() const;`` +- ``value_compare value_comp() const;`` + + - returns copies of objects used to determine the order of elements + +.. _`modifiers`: + +Semantics: modifiers +^^^^^^^^^^^^^^^^^^^^ + +- ``template< typename InputIterator > + void insert( InputIterator first, InputIterator last );`` + + - Requirements: ``[first,last)`` is a valid range + + - Effects: Inserts a cloned range + + - Exception safety: Basic guarantee + +- ``template< class InputRange > + void insert( const InputRange& r );`` + + - Effects: ``insert( boost::begin(r), boost::end(r) );`` + +- ``void erase( iterator position );`` + + - Requirements: ``position`` is a valid iterator from the container + + - Effects: Removes the element defined by ``position``. + + - Throws: Nothing + +- ``size_type erase( const key_type& x );`` + + - Effects: Removes all the elements in the container with a key equivalent to ``x`` and returns the number of erased elements. + + - Throws: Nothing + +- ``void erase( iterator first, iterator last );`` + + - Requirements: ``[first,last)`` is a valid range + + - Effects: Removes the range of elements defined by ``[first,last)``. + + - Throws: Nothing + +- ``template< class Range > void erase( const Range& r );`` + + - Effects: ``erase( boost::begin(r), boost::end(r) );`` + +.. _`algorithms`: + +Semantics: algorithms +^^^^^^^^^^^^^^^^^^^^^ + +- ``iterator find( const Key& x );`` +- ``const_iterator find( const Key& x ) const;`` + + - Effects: Searches for the key and returns ``end()`` on failure. + + - Complexity: Logarithmic + +- ``size_type count( const Key& x ) const;`` + + - Effects: Counts the elements with a key equivalent to ``x`` + + - Complexity: Logarithmic + +- ``iterator lower_bound( const Key& x );`` +- ``const_iterator lower_bound( const Key& x ) const;`` + + - Effects: Returns an iterator pointing to the first element with a key not less than ``x`` + + - Complexity: Logarithmic + +- ``iterator upper_bound( const Key& x );`` +- ``const_iterator upper_bound( const Key& x ) const;`` + + - Effects: Returns an iterator pointing to the first element with a key greater than ``x`` + + - Complexity: Logarithmic + +- ``iterator_range<iterator> equal_range( const Key& x );`` +- ``iterator_range<const_iterator> equal_range( const Key& x ) const;`` + + - Effects: ``return boost::make_iterator_range( lower_bound( x ), upper_bound( x ) );`` + + - Complexity: Logarithmic + +.. + - ``reference at( const key_type& key );`` + - ``const_reference at( const key_type& key ) const;`` + + - Requirements: the key exists + + - Effects: returns the object with key ``key`` + + - Throws: ``bad_ptr_container_operation`` if the key does not exist + + +.. _`pointer container requirements`: + +.. raw:: html + + <hr> + +:Copyright: Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). + +__ http://www.boost.org/LICENSE_1_0.txt + diff --git a/libs/ptr_container/doc/boost.png b/libs/ptr_container/doc/boost.png Binary files differnew file mode 100644 index 0000000000..b4d51fcd5c --- /dev/null +++ b/libs/ptr_container/doc/boost.png diff --git a/libs/ptr_container/doc/comp.sh b/libs/ptr_container/doc/comp.sh new file mode 100644 index 0000000000..2e6eb2deb1 --- /dev/null +++ b/libs/ptr_container/doc/comp.sh @@ -0,0 +1,17 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2005. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +sh comp_ptr_container.sh +sh comp_reversible_ptr_container.sh +sh comp_ptr_sequence_adapter.sh +sh comp_associative_ptr_container.sh +sh comp_ptr_set_adapter.sh + diff --git a/libs/ptr_container/doc/comp_all.sh b/libs/ptr_container/doc/comp_all.sh new file mode 100644 index 0000000000..f609839db7 --- /dev/null +++ b/libs/ptr_container/doc/comp_all.sh @@ -0,0 +1,37 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2005. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +sh comp_ptr_container.sh +sh comp_reference.sh +sh comp_faq.sh +sh comp_tutorial.sh +sh comp_guidelines.sh +sh comp_headers.sh +sh comp_examples.sh +sh comp_conventions.sh +sh comp_rever_ptr_container.sh +sh comp_ptr_sequence_adapter.sh +sh comp_assoc_ptr_container.sh +sh comp_ptr_set_adapter.sh +sh comp_ptr_multiset_adapter.sh +sh comp_ptr_map_adapter.sh +sh comp_ptr_multimap_adapter.sh +sh comp_ptr_array.sh +sh comp_ptr_vector.sh +sh comp_ptr_deque.sh +sh comp_ptr_list.sh +sh comp_ptr_map.sh +sh comp_ptr_multimap.sh +sh comp_ptr_set.sh +sh comp_ptr_multiset.sh +sh comp_indirect_fun.sh + + diff --git a/libs/ptr_container/doc/comp_assoc_ptr_container.sh b/libs/ptr_container/doc/comp_assoc_ptr_container.sh new file mode 100644 index 0000000000..fec3b3bf8e --- /dev/null +++ b/libs/ptr_container/doc/comp_assoc_ptr_container.sh @@ -0,0 +1,13 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2005. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +rst2html.py associative_ptr_container.rst > associative_ptr_container.html + diff --git a/libs/ptr_container/doc/comp_conventions.sh b/libs/ptr_container/doc/comp_conventions.sh new file mode 100644 index 0000000000..7b008c8563 --- /dev/null +++ b/libs/ptr_container/doc/comp_conventions.sh @@ -0,0 +1,12 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2005. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +rst2html.py conventions.rst > conventions.html diff --git a/libs/ptr_container/doc/comp_examples.sh b/libs/ptr_container/doc/comp_examples.sh new file mode 100644 index 0000000000..5b695c29e7 --- /dev/null +++ b/libs/ptr_container/doc/comp_examples.sh @@ -0,0 +1,13 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2005. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +rst2html.py examples.rst > examples.html + diff --git a/libs/ptr_container/doc/comp_faq.sh b/libs/ptr_container/doc/comp_faq.sh new file mode 100644 index 0000000000..6c5e2e9405 --- /dev/null +++ b/libs/ptr_container/doc/comp_faq.sh @@ -0,0 +1,13 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2005. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +rst2html.py faq.rst > faq.html + diff --git a/libs/ptr_container/doc/comp_guidelines.sh b/libs/ptr_container/doc/comp_guidelines.sh new file mode 100644 index 0000000000..420820f12c --- /dev/null +++ b/libs/ptr_container/doc/comp_guidelines.sh @@ -0,0 +1,13 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2005. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +rst2html.py guidelines.rst > guidelines.html + diff --git a/libs/ptr_container/doc/comp_headers.sh b/libs/ptr_container/doc/comp_headers.sh new file mode 100644 index 0000000000..84b8e8b169 --- /dev/null +++ b/libs/ptr_container/doc/comp_headers.sh @@ -0,0 +1,13 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2005. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +rst2html.py headers.rst > headers.html + diff --git a/libs/ptr_container/doc/comp_indirect_fun.sh b/libs/ptr_container/doc/comp_indirect_fun.sh new file mode 100644 index 0000000000..1632ee8d15 --- /dev/null +++ b/libs/ptr_container/doc/comp_indirect_fun.sh @@ -0,0 +1,13 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2005. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +rst2html.py indirect_fun.rst > indirect_fun.html + diff --git a/libs/ptr_container/doc/comp_ptr_array.sh b/libs/ptr_container/doc/comp_ptr_array.sh new file mode 100644 index 0000000000..e625d6717c --- /dev/null +++ b/libs/ptr_container/doc/comp_ptr_array.sh @@ -0,0 +1,13 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2005. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +rst2html.py ptr_array.rst > ptr_array.html + diff --git a/libs/ptr_container/doc/comp_ptr_container.sh b/libs/ptr_container/doc/comp_ptr_container.sh new file mode 100644 index 0000000000..781867feed --- /dev/null +++ b/libs/ptr_container/doc/comp_ptr_container.sh @@ -0,0 +1,13 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2005. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +rst2html.py ptr_container.rst > ptr_container.html + diff --git a/libs/ptr_container/doc/comp_ptr_deque.sh b/libs/ptr_container/doc/comp_ptr_deque.sh new file mode 100644 index 0000000000..0b7d51a635 --- /dev/null +++ b/libs/ptr_container/doc/comp_ptr_deque.sh @@ -0,0 +1,13 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2005. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +rst2html.py ptr_deque.rst > ptr_deque.html + diff --git a/libs/ptr_container/doc/comp_ptr_inserter.sh b/libs/ptr_container/doc/comp_ptr_inserter.sh new file mode 100644 index 0000000000..f91c532c71 --- /dev/null +++ b/libs/ptr_container/doc/comp_ptr_inserter.sh @@ -0,0 +1,13 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2005. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +rst2html.py ptr_inserter.rst > ptr_inserter.html + diff --git a/libs/ptr_container/doc/comp_ptr_list.sh b/libs/ptr_container/doc/comp_ptr_list.sh new file mode 100644 index 0000000000..0d579da38a --- /dev/null +++ b/libs/ptr_container/doc/comp_ptr_list.sh @@ -0,0 +1,13 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2005. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +rst2html.py ptr_list.rst > ptr_list.html + diff --git a/libs/ptr_container/doc/comp_ptr_map.sh b/libs/ptr_container/doc/comp_ptr_map.sh new file mode 100644 index 0000000000..0fbd2fe158 --- /dev/null +++ b/libs/ptr_container/doc/comp_ptr_map.sh @@ -0,0 +1,13 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2005. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +rst2html.py ptr_map.rst > ptr_map.html + diff --git a/libs/ptr_container/doc/comp_ptr_map_adapter.sh b/libs/ptr_container/doc/comp_ptr_map_adapter.sh new file mode 100644 index 0000000000..b5bffa43f8 --- /dev/null +++ b/libs/ptr_container/doc/comp_ptr_map_adapter.sh @@ -0,0 +1,13 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2005. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +rst2html.py ptr_map_adapter.rst > ptr_map_adapter.html + diff --git a/libs/ptr_container/doc/comp_ptr_multimap.sh b/libs/ptr_container/doc/comp_ptr_multimap.sh new file mode 100644 index 0000000000..2a385702dd --- /dev/null +++ b/libs/ptr_container/doc/comp_ptr_multimap.sh @@ -0,0 +1,13 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2005. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +rst2html.py ptr_multimap.rst > ptr_multimap.html + diff --git a/libs/ptr_container/doc/comp_ptr_multimap_adapter.sh b/libs/ptr_container/doc/comp_ptr_multimap_adapter.sh new file mode 100644 index 0000000000..1d86e07bdb --- /dev/null +++ b/libs/ptr_container/doc/comp_ptr_multimap_adapter.sh @@ -0,0 +1,13 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2005. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +rst2html.py ptr_multimap_adapter.rst > ptr_multimap_adapter.html + diff --git a/libs/ptr_container/doc/comp_ptr_multiset.sh b/libs/ptr_container/doc/comp_ptr_multiset.sh new file mode 100644 index 0000000000..3695a2d62f --- /dev/null +++ b/libs/ptr_container/doc/comp_ptr_multiset.sh @@ -0,0 +1,13 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2005. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +rst2html.py ptr_multiset.rst > ptr_multiset.html + diff --git a/libs/ptr_container/doc/comp_ptr_multiset_adapter.sh b/libs/ptr_container/doc/comp_ptr_multiset_adapter.sh new file mode 100644 index 0000000000..75478dc196 --- /dev/null +++ b/libs/ptr_container/doc/comp_ptr_multiset_adapter.sh @@ -0,0 +1,13 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2005. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +rst2html.py ptr_multiset_adapter.rst > ptr_multiset_adapter.html + diff --git a/libs/ptr_container/doc/comp_ptr_sequence_adapter.sh b/libs/ptr_container/doc/comp_ptr_sequence_adapter.sh new file mode 100644 index 0000000000..649356707e --- /dev/null +++ b/libs/ptr_container/doc/comp_ptr_sequence_adapter.sh @@ -0,0 +1,13 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2005. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +rst2html.py ptr_sequence_adapter.rst > ptr_sequence_adapter.html + diff --git a/libs/ptr_container/doc/comp_ptr_set.sh b/libs/ptr_container/doc/comp_ptr_set.sh new file mode 100644 index 0000000000..d94a39a64e --- /dev/null +++ b/libs/ptr_container/doc/comp_ptr_set.sh @@ -0,0 +1,13 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2005. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +rst2html.py ptr_set.rst > ptr_set.html + diff --git a/libs/ptr_container/doc/comp_ptr_set_adapter.sh b/libs/ptr_container/doc/comp_ptr_set_adapter.sh new file mode 100644 index 0000000000..699615d14e --- /dev/null +++ b/libs/ptr_container/doc/comp_ptr_set_adapter.sh @@ -0,0 +1,13 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2005. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +rst2html.py ptr_set_adapter.rst > ptr_set_adapter.html + diff --git a/libs/ptr_container/doc/comp_ptr_vector.sh b/libs/ptr_container/doc/comp_ptr_vector.sh new file mode 100644 index 0000000000..ce9e7bc984 --- /dev/null +++ b/libs/ptr_container/doc/comp_ptr_vector.sh @@ -0,0 +1,13 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2005. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +rst2html.py ptr_vector.rst > ptr_vector.html + diff --git a/libs/ptr_container/doc/comp_reference.sh b/libs/ptr_container/doc/comp_reference.sh new file mode 100644 index 0000000000..e8c163eb70 --- /dev/null +++ b/libs/ptr_container/doc/comp_reference.sh @@ -0,0 +1,12 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2005. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +rst2html.py reference.rst > reference.html diff --git a/libs/ptr_container/doc/comp_rever_ptr_container.sh b/libs/ptr_container/doc/comp_rever_ptr_container.sh new file mode 100644 index 0000000000..83964629fd --- /dev/null +++ b/libs/ptr_container/doc/comp_rever_ptr_container.sh @@ -0,0 +1,13 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2005. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +rst2html.py reversible_ptr_container.rst > reversible_ptr_container.html + diff --git a/libs/ptr_container/doc/comp_tutorial.sh b/libs/ptr_container/doc/comp_tutorial.sh new file mode 100644 index 0000000000..6216477b20 --- /dev/null +++ b/libs/ptr_container/doc/comp_tutorial.sh @@ -0,0 +1,13 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2005. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +rst2html.py tutorial.rst > tutorial.html + diff --git a/libs/ptr_container/doc/conventions.html b/libs/ptr_container/doc/conventions.html new file mode 100644 index 0000000000..3d9dd3e9b7 --- /dev/null +++ b/libs/ptr_container/doc/conventions.html @@ -0,0 +1,404 @@ +<?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: 2007-11-25 13:38:02 -0500 (Sun, 25 Nov 2007) $ +:Revision: $Revision: 41370 $ +: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="conventions">Conventions</h2> +<p>There are a few design decisions that will affect how the classes are +used. Besides these the classes are much like normal standard containers +and provides almost the same interface. The new conventions are:</p> +<div class="contents local topic"> +<ul class="simple"> +<li><a class="reference" href="#null-pointers-are-not-allowed-by-default" id="id3" name="id3">Null pointers are not allowed by default</a></li> +<li><a class="reference" href="#all-default-iterators-apply-an-extra-layer-of-indirection" id="id4" name="id4">All default iterators apply an extra layer of indirection</a></li> +<li><a class="reference" href="#all-comparison-operations-are-done-on-the-pointed-to-objects-and-not-at-the-pointer-level" id="id5" name="id5">All comparison operations are done on the pointed to objects and not at the pointer level</a></li> +<li><a class="reference" href="#stored-elements-are-required-to-be-cloneable-for-a-subset-of-the-operations" id="id6" name="id6">Stored elements are required to be Cloneable for a subset of the operations</a></li> +<li><a class="reference" href="#whenever-objects-are-inserted-into-a-container-they-are-cloned-before-insertion" id="id7" name="id7">Whenever objects are inserted into a container, they are cloned before insertion</a></li> +<li><a class="reference" href="#whenever-pointers-are-inserted-into-a-container-ownership-is-transferred-to-the-container" id="id8" name="id8">Whenever pointers are inserted into a container, ownership is transferred to the container</a></li> +<li><a class="reference" href="#ownership-can-be-transferred-from-a-container-on-a-per-pointer-basis" id="id9" name="id9">Ownership can be transferred from a container on a per pointer basis</a></li> +<li><a class="reference" href="#ownership-can-be-transferred-from-a-container-to-another-container-on-a-per-iterator-range-basis" id="id10" name="id10">Ownership can be transferred from a container to another container on a per iterator range basis</a></li> +<li><a class="reference" href="#a-container-can-be-cheaply-returned-from-functions-either-by-making-a-clone-or-by-giving-up-ownership-of-the-container" id="id11" name="id11">A container can be cheaply returned from functions either by making a clone or by giving up ownership of the container</a></li> +<li><a class="reference" href="#iterators-are-invalidated-as-in-the-corresponding-standard-container" id="id12" name="id12">Iterators are invalidated as in the corresponding standard container</a></li> +</ul> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id3" id="null-pointers-are-not-allowed-by-default" name="null-pointers-are-not-allowed-by-default">Null pointers are not allowed by default</a></h1> +<p>If the user tries to insert the null pointer, the operation will throw a +<tt class="docutils literal"><span class="pre">bad_pointer</span></tt> exception (see <a class="reference" href="examples.html">Example 1</a>).</p> +<p>Use <a class="reference" href="reference.html#class-nullable">nullable</a> to allow null pointers.</p> +<p>Please notice that all preconditions of the form</p> +<pre class="literal-block"> +x != 0; +</pre> +<p>are not active when the you have instantiated a container +with <tt class="docutils literal"><span class="pre">nullable<T></span></tt> as in</p> +<pre class="literal-block"> +boost::ptr_vector< boost::nullable<animal> > vec; +vec.push_back( 0 ); // ok +</pre> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id4" id="all-default-iterators-apply-an-extra-layer-of-indirection" name="all-default-iterators-apply-an-extra-layer-of-indirection">All default iterators apply an extra layer of indirection</a></h1> +<p>This is done to +make the containers easier and safer to use. It promotes a kind of +pointer-less programming and the user of a class needs not worry about +pointers except when allocating them (see <a class="reference" href="examples.html">Example 2</a>). Iterators that +provide access to the naked pointers are also provided since they might be +useful in rare cases. For example, whenever <tt class="docutils literal"><span class="pre">begin()</span></tt> returns an iterator, +<tt class="docutils literal"><span class="pre">ptr_begin()</span></tt> will return an iterator that allows one to iterate over the +stored pointers.</p> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id5" id="all-comparison-operations-are-done-on-the-pointed-to-objects-and-not-at-the-pointer-level" name="all-comparison-operations-are-done-on-the-pointed-to-objects-and-not-at-the-pointer-level">All comparison operations are done on the pointed to objects and not at the pointer level</a></h1> +<p>For example, in <tt class="docutils literal"><span class="pre">ptr_set<T></span></tt> the ordering is by default done by +<tt class="docutils literal"><span class="pre">boost::ptr_less<T></span></tt> which compares the indirected pointers. +Similarly, <tt class="docutils literal"><span class="pre">operator==()</span></tt> for <tt class="docutils literal"><span class="pre">container<Foo></span></tt> compares all objects +with <tt class="docutils literal"><span class="pre">operator==(const</span> <span class="pre">Foo&,</span> <span class="pre">const</span> <span class="pre">Foo&)</span></tt>.</p> +</div> +<div class="section"> +<h1><a id="stored-elements-are-required-to-be-cloneable-for-a-subset-of-the-operations" name="stored-elements-are-required-to-be-cloneable-for-a-subset-of-the-operations">Stored elements are required to be <a class="reference" href="reference.html#the-Cloneable-concept">Cloneable</a> for a subset of the operations</a></h1> +<p>This is because most polymorphic objects cannot be copied directly, but +they can often be so by a use of a member function (see <a class="reference" href="examples.html">Example 4</a>). Often +it does not even make sense to clone an object in which case a large +subset of the operations are still workable.</p> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id7" id="whenever-objects-are-inserted-into-a-container-they-are-cloned-before-insertion" name="whenever-objects-are-inserted-into-a-container-they-are-cloned-before-insertion">Whenever objects are inserted into a container, they are cloned before insertion</a></h1> +<p>This is necessary because all pointer containers take ownerships of stored objects +(see <a class="reference" href="examples.html">Example 5</a>).</p> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id8" id="whenever-pointers-are-inserted-into-a-container-ownership-is-transferred-to-the-container" name="whenever-pointers-are-inserted-into-a-container-ownership-is-transferred-to-the-container">Whenever pointers are inserted into a container, ownership is transferred to the container</a></h1> +<p>All containers take ownership of the stored pointers and therefore a +container needs to have its own copies (see <a class="reference" href="examples.html">Example 5</a>).</p> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id9" id="ownership-can-be-transferred-from-a-container-on-a-per-pointer-basis" name="ownership-can-be-transferred-from-a-container-on-a-per-pointer-basis">Ownership can be transferred from a container on a per pointer basis</a></h1> +<p>This can of course also be convenient. Whenever it happens, an +<tt class="docutils literal"><span class="pre">SmartContainer::auto_type</span></tt> object is used to provide an exception-safe transfer +(see <a class="reference" href="examples.html">Example 6</a>).</p> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id10" id="ownership-can-be-transferred-from-a-container-to-another-container-on-a-per-iterator-range-basis" name="ownership-can-be-transferred-from-a-container-to-another-container-on-a-per-iterator-range-basis">Ownership can be transferred from a container to another container on a per iterator range basis</a></h1> +<p>This makes it possible to exchange data safely between different pointer +containers without cloning the objects again (see <a class="reference" href="examples.html">Example 7</a>).</p> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id11" id="a-container-can-be-cheaply-returned-from-functions-either-by-making-a-clone-or-by-giving-up-ownership-of-the-container" name="a-container-can-be-cheaply-returned-from-functions-either-by-making-a-clone-or-by-giving-up-ownership-of-the-container">A container can be cheaply returned from functions either by making a clone or by giving up ownership of the container</a></h1> +<p>Two special member functions, <tt class="docutils literal"><span class="pre">clone()</span></tt> and <tt class="docutils literal"><span class="pre">release()</span></tt>, both return an +<tt class="docutils literal"><span class="pre">auto_ptr<SmartContainer></span></tt> which can be assigned to another pointer container. This +effectively reduces the cost of returning a container to one +heap-allocation plus a call to <tt class="docutils literal"><span class="pre">swap()</span></tt> (see <a class="reference" href="examples.html">Example 3</a>).</p> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id12" id="iterators-are-invalidated-as-in-the-corresponding-standard-container" name="iterators-are-invalidated-as-in-the-corresponding-standard-container">Iterators are invalidated as in the corresponding standard container</a></h1> +<p>Because the containers in this library wrap standard containers, the +rules for invalidation of iterators are the same as the rules +of the corresponding standard container.</p> +<p>For example, for both <tt class="docutils literal"><span class="pre">boost::ptr_vector<T></span></tt> and <tt class="docutils literal"><span class="pre">std::vector<U></span></tt> +insertion and deletion only invalidates the deleted +element and elements following it; all elements before the inserted/deleted +element remain valid.</p> +<hr><p><strong>Navigate:</strong></p> +<ul class="simple"> +<li><a class="reference" href="ptr_container.html">home</a></li> +<li><a class="reference" href="reference.html">reference</a></li> +</ul> +<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> diff --git a/libs/ptr_container/doc/conventions.rst b/libs/ptr_container/doc/conventions.rst new file mode 100644 index 0000000000..6d12017496 --- /dev/null +++ b/libs/ptr_container/doc/conventions.rst @@ -0,0 +1,125 @@ +++++++++++++++++++++++++++++++++++ + |Boost| Pointer Container Library +++++++++++++++++++++++++++++++++++ + +.. |Boost| image:: boost.png + +Conventions ++++++++++++ + +There are a few design decisions that will affect how the classes are +used. Besides these the classes are much like normal standard containers +and provides almost the same interface. The new conventions are: + +.. contents:: :local: + +Null pointers are not allowed by default +---------------------------------------- + +If the user tries to insert the null pointer, the operation will throw a +``bad_pointer`` exception (see `Example 1 <examples.html>`_). + +Use `nullable <reference.html#class-nullable>`_ to allow null pointers. + +Please notice that all preconditions of the form :: + + x != 0; + +are not active when the you have instantiated a container +with ``nullable<T>`` as in :: + + boost::ptr_vector< boost::nullable<animal> > vec; + vec.push_back( 0 ); // ok + +All default iterators apply an extra layer of indirection +--------------------------------------------------------- + +This is done to +make the containers easier and safer to use. It promotes a kind of +pointer-less programming and the user of a class needs not worry about +pointers except when allocating them (see `Example 2 <examples.html>`_). Iterators that +provide access to the naked pointers are also provided since they might be +useful in rare cases. For example, whenever ``begin()`` returns an iterator, +``ptr_begin()`` will return an iterator that allows one to iterate over the +stored pointers. + +All comparison operations are done on the pointed to objects and not at the pointer level +----------------------------------------------------------------------------------------- + +For example, in ``ptr_set<T>`` the ordering is by default done by +``boost::ptr_less<T>`` which compares the indirected pointers. +Similarly, ``operator==()`` for ``container<Foo>`` compares all objects +with ``operator==(const Foo&, const Foo&)``. + + +Stored elements are required to be `Cloneable <reference.html#the-Cloneable-concept>`_ for a subset of the operations +--------------------------------------------------------------------------------------------------------------------- + +This is because most polymorphic objects cannot be copied directly, but +they can often be so by a use of a member function (see `Example 4 <examples.html>`_). Often +it does not even make sense to clone an object in which case a large +subset of the operations are still workable. + +Whenever objects are inserted into a container, they are cloned before insertion +-------------------------------------------------------------------------------- + +This is necessary because all pointer containers take ownerships of stored objects +(see `Example 5 <examples.html>`_). + +Whenever pointers are inserted into a container, ownership is transferred to the container +------------------------------------------------------------------------------------------ + +All containers take ownership of the stored pointers and therefore a +container needs to have its own copies (see `Example 5 <examples.html>`_). + +Ownership can be transferred from a container on a per pointer basis +-------------------------------------------------------------------- + +This can of course also be convenient. Whenever it happens, an +``SmartContainer::auto_type`` object is used to provide an exception-safe transfer +(see `Example 6 <examples.html>`_). + +Ownership can be transferred from a container to another container on a per iterator range basis +------------------------------------------------------------------------------------------------ + +This makes it possible to exchange data safely between different pointer +containers without cloning the objects again (see `Example 7 <examples.html>`_). + +A container can be cheaply returned from functions either by making a clone or by giving up ownership of the container +---------------------------------------------------------------------------------------------------------------------- + +Two special member functions, ``clone()`` and ``release()``, both return an +``auto_ptr<SmartContainer>`` which can be assigned to another pointer container. This +effectively reduces the cost of returning a container to one +heap-allocation plus a call to ``swap()`` (see `Example 3 <examples.html>`_). + +Iterators are invalidated as in the corresponding standard container +-------------------------------------------------------------------- + +Because the containers in this library wrap standard containers, the +rules for invalidation of iterators are the same as the rules +of the corresponding standard container. + +For example, for both ``boost::ptr_vector<T>`` and ``std::vector<U>`` +insertion and deletion only invalidates the deleted +element and elements following it; all elements before the inserted/deleted +element remain valid. + +.. raw:: html + + <hr> + +**Navigate:** + +- `home <ptr_container.html>`_ +- `reference <reference.html>`_ + +.. raw:: html + + <hr> + +:Copyright: Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). + +__ http://www.boost.org/LICENSE_1_0.txt + + diff --git a/libs/ptr_container/doc/default.css b/libs/ptr_container/doc/default.css new file mode 100644 index 0000000000..d7ffe81822 --- /dev/null +++ b/libs/ptr_container/doc/default.css @@ -0,0 +1,250 @@ +/* +boostinspect:nolicense + +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:date: $Date: 2008-03-22 17:45:55 -0400 (Sat, 22 Mar 2008) $ +:version: $Revision: 43798 $ +:copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. +*/ + +.first { + margin-top: 0 } + +.last { + margin-bottom: 0 } + +a.toc-backref { + text-decoration: none ; + color: black } + +dd { + margin-bottom: 0.5em } + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.attention, div.caution, div.danger, div.error, div.hint, +div.important, div.note, div.tip, div.warning, div.admonition { + margin: 2em ; + border: medium outset ; + padding: 1em } + +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 } + +div.hint p.admonition-title, div.important p.admonition-title, +div.note p.admonition-title, div.tip p.admonition-title, +div.admonition p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +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 { + font-size: smaller } + +div.sidebar { + margin-left: 1em ; + border: medium outset ; + padding: 0em 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.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr { + width: 75% } + +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.option-argument { + font-style: italic } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +table { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.citation { + border-left: solid thin gray ; + padding-left: 0.5ex } + +table.docinfo { + margin: 2em 4em } + +table.footnote { + border-left: solid thin black ; + padding-left: 0.5ex } + +td, th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +th.docinfo-name, th.field-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap } + +h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { + font-size: 100% } + +tt { + background-color: #eeeeee } + +ul.auto-toc { + list-style-type: none } + +pre{ + BORDER-RIGHT: gray 1pt solid; + PADDING-RIGHT: 2pt; + BORDER-TOP: gray 1pt solid; + DISPLAY: block; + PADDING-LEFT: 2pt; + PADDING-BOTTOM: 2pt; + BORDER-LEFT: gray 1pt solid; + MARGIN-RIGHT: 32pt; + PADDING-TOP: 2pt; + BORDER-BOTTOM: gray 1pt solid; + FONT-FAMILY: "Courier New", Courier, mono; + background-color: #EEEEEE; +} + + +.keyword{color: #0000FF;} +.identifier{} +.comment{font-style: italic; color: #008000;} +.special{color: #800040;} +.preprocessor{color: #3F007F;} +.string{font-style: italic; color: #666666;} +.literal{/*font-style: italic;*/ color: #000000;} diff --git a/libs/ptr_container/doc/examples.html b/libs/ptr_container/doc/examples.html new file mode 100644 index 0000000000..36b9c706c4 --- /dev/null +++ b/libs/ptr_container/doc/examples.html @@ -0,0 +1,819 @@ +<?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: 2009-04-05 16:10:44 -0400 (Sun, 05 Apr 2009) $ +:Revision: $Revision: 52198 $ +: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="examples">Examples</h2> +<p>Some examples are given here and in the accompanying test files:</p> +<div class="contents local topic"> +<ul class="simple"> +<li><a class="reference" href="#null-pointers-cannot-be-stored-in-the-containers" id="id2" name="id2">1. Null pointers cannot be stored in the containers</a></li> +<li><a class="reference" href="#iterators-and-other-operations-return-indirected-values" id="id3" name="id3">2. Iterators and other operations return indirected values</a></li> +<li><a class="reference" href="#copy-semantics-of-pointer-containers" id="id4" name="id4">3. Copy-semantics of pointer containers</a></li> +<li><a class="reference" href="#making-a-non-copyable-type-cloneable" id="id5" name="id5">4. Making a non-copyable type Cloneable</a></li> +<li><a class="reference" href="#objects-are-cloned-before-insertion-inserted-pointers-are-owned-by-the-container" id="id6" name="id6">5. Objects are cloned before insertion, inserted pointers are owned by the container</a></li> +<li><a class="reference" href="#transferring-ownership-of-a-single-element" id="id7" name="id7">6. Transferring ownership of a single element</a></li> +<li><a class="reference" href="#transferring-ownership-of-pointers-between-different-pointer-containers" id="id8" name="id8">7. Transferring ownership of pointers between different pointer containers</a></li> +<li><a class="reference" href="#selected-test-files" id="id9" name="id9">8. Selected test files</a></li> +<li><a class="reference" href="#a-large-example" id="id10" name="id10">9. A large example</a></li> +</ul> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id2" id="null-pointers-cannot-be-stored-in-the-containers" name="null-pointers-cannot-be-stored-in-the-containers"><span id="example-1"></span>1. Null pointers cannot be stored in the containers</a></h1> +<pre class="literal-block"> +my_container.push_back( 0 ); // throws bad_ptr +my_container.replace( an_iterator, 0 ); // throws bad_ptr +my_container.insert( an_iterator, 0 ); // throws bad_ptr +std::auto_ptr<T> p( 0 ); +my_container.push_back( p ); // throws bad_ptr +</pre> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id3" id="iterators-and-other-operations-return-indirected-values" name="iterators-and-other-operations-return-indirected-values"><span id="example-2"></span>2. Iterators and other operations return indirected values</a></h1> +<pre class="literal-block"> +ptr_vector<X> pvec; +std::vector<X*> vec; +*vec.begin() = new X; // fine, memory leak +*pvec.begin() = new X; // compile time error +( *vec.begin() )->foo(); // call X::foo(), a bit clumsy +pvec.begin()->foo(); // no indirection needed +*vec.front() = X(); // overwrite first element +pvec.front() = X(); // no indirection needed +</pre> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id4" id="copy-semantics-of-pointer-containers" name="copy-semantics-of-pointer-containers"><span id="example-3"></span>3. Copy-semantics of pointer containers</a></h1> +<pre class="literal-block"> +ptr_vector<T> vec1; +... +ptr_vector<T> vec2( vec1.clone() ); // deep copy objects of 'vec1' and use them to construct 'vec2', could be very expensive +vec2 = vec1.release(); // give up ownership of pointers in 'vec1' and pass the ownership to 'vec2', rather cheap +vec2.release(); // give up ownership; the objects will be deallocated if not assigned to another container +vec1 = vec2; // deep copy objects of 'vec2' and assign them to 'vec1', could be very expensive +ptr_vector<T> vec3( vec1 ); // deep copy objects of 'vec1', could be very expensive +</pre> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id5" id="making-a-non-copyable-type-cloneable" name="making-a-non-copyable-type-cloneable"><span id="example-4"></span>4. Making a non-copyable type Cloneable</a></h1> +<pre class="literal-block"> + // a class that has no normal copy semantics +class X : boost::noncopyable { public: X* clone() const; ... }; + +// this will be found by the library by argument dependent lookup (ADL) +X* new_clone( const X& x ) +{ return x.clone(); } + +// we can now use the interface that requires cloneability +ptr_vector<X> vec1, vec2; +... +vec2 = vec1.clone(); // 'clone()' requires cloning <g> +vec2.insert( vec2.end(), vec1.begin(), vec1.end() ); // inserting always means inserting clones +</pre> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id6" id="objects-are-cloned-before-insertion-inserted-pointers-are-owned-by-the-container" name="objects-are-cloned-before-insertion-inserted-pointers-are-owned-by-the-container"><span id="example-5"></span>5. Objects are cloned before insertion, inserted pointers are owned by the container</a></h1> +<pre class="literal-block"> +class X { ... }; // assume 'X' is Cloneable +X x; // and 'X' can be stack-allocated +ptr_list<X> list; +list.push_back( new_clone( x ) ); // insert a clone +list.push_back( new X ); // always give the pointer directly to the container to avoid leaks +list.push_back( &x ); // don't do this!!! +std::auto_ptr<X> p( new X ); +list.push_back( p ); // give up ownership +BOOST_ASSERT( p.get() == 0 ); +</pre> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id7" id="transferring-ownership-of-a-single-element" name="transferring-ownership-of-a-single-element"><span id="example-6"></span>6. Transferring ownership of a single element</a></h1> +<pre class="literal-block"> +ptr_deque<T> deq; +typedef ptr_deque<T>::auto_type auto_type; + +// ... fill the container somehow + +auto_type ptr = deq.pop_back(); // remove back element from container and give up ownership +auto_type ptr2 = deq.release( deq.begin() + 2 ); // use an iterator to determine the element to release +ptr = deq.pop_front(); // supported for 'ptr_list' and 'ptr_deque' + +deq.push_back( ptr.release() ); // give ownership back to the container +</pre> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id8" id="transferring-ownership-of-pointers-between-different-pointer-containers" name="transferring-ownership-of-pointers-between-different-pointer-containers"><span id="example-7"></span>7. Transferring ownership of pointers between different pointer containers</a></h1> +<pre class="literal-block"> +ptr_list<X> list; ptr_vector<X> vec; +... +// +// note: no cloning happens in these examples +// +list.transfer( list.begin(), vec.begin(), vec ); // make the first element of 'vec' the first element of 'list' +vec.transfer( vec.end(), list.begin(), list.end(), list ); // put all the lists element into the vector +</pre> +<p>We can also transfer objects from <tt class="docutils literal"><span class="pre">ptr_container<Derived></span></tt> to <tt class="docutils literal"><span class="pre">ptr_container<Base></span></tt> without any problems.</p> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id9" id="selected-test-files" name="selected-test-files"><span id="example-8"></span>8. Selected test files</a></h1> +<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" colspan="2"><a class="reference" href="../test/incomplete_type_test.cpp">incomplete_type_test.cpp</a>:</th></tr> +<tr><td> </td><td class="field-body">Shows how to implement the Composite pattern.</td> +</tr> +<tr class="field"><th class="field-name" colspan="2"><a class="reference" href="../test/simple_test.cpp">simple_test.cpp</a>:</th></tr> +<tr><td> </td><td class="field-body">Shows how the usage of pointer container compares with a +container of smart pointers</td> +</tr> +<tr class="field"><th class="field-name" colspan="2"><a class="reference" href="../test/view_example.cpp">view_example.cpp</a>:</th></tr> +<tr><td> </td><td class="field-body">Shows how to use a pointer container as a view into other container</td> +</tr> +<tr class="field"><th class="field-name"><a class="reference" href="../test/tree_test.cpp">tree_test.cpp</a>:</th><td class="field-body">Shows how to make a tree-structure</td> +</tr> +<tr class="field"><th class="field-name"><a class="reference" href="../test/ptr_array.cpp">array_test.cpp</a>:</th><td class="field-body">Shows how to make an n-ary tree</td> +</tr> +</tbody> +</table> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id10" id="a-large-example" name="a-large-example">9. A large example</a></h1> +<p>This example shows many of the most common +features at work. The example provide lots of comments. +The source code can also be found <a class="reference" href="../test/tut1.cpp">here</a>.</p> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title> </title> +<link rel="stylesheet" href="default.css" type="text/css"> +</head> + +<body> + <pre><span class=comment>// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +// +// This example is intended to get you started. +// Notice how the smart container +// +// 1. takes ownership of objects +// 2. transfers ownership +// 3. applies indirection to iterators +// 4. clones objects from other smart containers +// + +// +// First we select which container to use. +//</span> +<span class=preprocessor>#include</span> <span class=special><</span><span class=identifier>boost</span><span class=special>/</span><span class=identifier>ptr_container</span><span class=special>/</span><span class=identifier>ptr_deque</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>></span> + +<span class=comment>// +// we need these later in the example +//</span> +<span class=preprocessor>#include</span> <span class=special><</span><span class=identifier>boost</span><span class=special>/</span><span class=identifier>assert</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>></span> +<span class=preprocessor>#include</span> <span class=special><</span><span class=identifier>string</span><span class=special>></span> +<span class=preprocessor>#include</span> <span class=special><</span><span class=identifier>exception</span><span class=special>></span> + + +<span class=comment>// +// Then we define a small polymorphic class +// hierarchy. +//</span> + +<span class=keyword>class</span> <span class=identifier>animal</span> <span class=special>:</span> <span class=identifier>boost</span><span class=special>::</span><span class=identifier>noncopyable</span> +<span class=special>{</span> + <span class=keyword>virtual</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span> <span class=identifier>do_speak</span><span class=special>()</span> <span class=keyword>const</span> <span class=special>=</span> <span class=number>0</span><span class=special>;</span> + <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span> <span class=identifier>name_</span><span class=special>;</span> + +<span class=keyword>protected</span><span class=special>:</span> + <span class=comment>// + // Animals cannot be copied... + //</span> + <span class=identifier>animal</span><span class=special>(</span> <span class=keyword>const</span> <span class=identifier>animal</span><span class=special>&</span> <span class=identifier>r</span> <span class=special>)</span> <span class=special>:</span> <span class=identifier>name_</span><span class=special>(</span> <span class=identifier>r</span><span class=special>.</span><span class=identifier>name_</span> <span class=special>)</span> <span class=special>{</span> <span class=special>}</span> + <span class=keyword>void</span> <span class=keyword>operator</span><span class=special>=(</span> <span class=keyword>const</span> <span class=identifier>animal</span><span class=special>&</span> <span class=special>);</span> + +<span class=keyword>private</span><span class=special>:</span> + <span class=comment>// + // ...but due to advances in genetics, we can clone them! + //</span> + + <span class=keyword>virtual</span> <span class=identifier>animal</span><span class=special>*</span> <span class=identifier>do_clone</span><span class=special>()</span> <span class=keyword>const</span> <span class=special>=</span> <span class=number>0</span><span class=special>;</span> + +<span class=keyword>public</span><span class=special>:</span> + <span class=identifier>animal</span><span class=special>(</span> <span class=keyword>const</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span><span class=special>&</span> <span class=identifier>name</span> <span class=special>)</span> <span class=special>:</span> <span class=identifier>name_</span><span class=special>(</span><span class=identifier>name</span><span class=special>)</span> <span class=special>{</span> <span class=special>}</span> + <span class=keyword>virtual</span> <span class=special>~</span><span class=identifier>animal</span><span class=special>()</span> <span class=keyword>throw</span><span class=special>()</span> <span class=special>{</span> <span class=special>}</span> + + <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span> <span class=identifier>speak</span><span class=special>()</span> <span class=keyword>const</span> + <span class=special>{</span> + <span class=keyword>return</span> <span class=identifier>do_speak</span><span class=special>();</span> + <span class=special>}</span> + + <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span> <span class=identifier>name</span><span class=special>()</span> <span class=keyword>const</span> + <span class=special>{</span> + <span class=keyword>return</span> <span class=identifier>name_</span><span class=special>;</span> + <span class=special>}</span> + + <span class=identifier>animal</span><span class=special>*</span> <span class=identifier>clone</span><span class=special>()</span> <span class=keyword>const</span> + <span class=special>{</span> + <span class=keyword>return</span> <span class=identifier>do_clone</span><span class=special>();</span> + <span class=special>}</span> +<span class=special>};</span> + +<span class=comment>// +// An animal is still not Clonable. We need this last hook. +// +// Notice that we pass the animal by const reference +// and return by pointer. +//</span> + +<span class=identifier>animal</span><span class=special>*</span> <span class=identifier>new_clone</span><span class=special>(</span> <span class=keyword>const</span> <span class=identifier>animal</span><span class=special>&</span> <span class=identifier>a</span> <span class=special>)</span> +<span class=special>{</span> + <span class=keyword>return</span> <span class=identifier>a</span><span class=special>.</span><span class=identifier>clone</span><span class=special>();</span> +<span class=special>}</span> + +<span class=comment>// +// We do not need to define 'delete_clone()' since +// since the default is to call the default 'operator delete()'. +//</span> + +<span class=keyword>const</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span> <span class=identifier>muuuh</span> <span class=special>=</span> <span class=string>"Muuuh!"</span><span class=special>;</span> +<span class=keyword>const</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span> <span class=identifier>oiink</span> <span class=special>=</span> <span class=string>"Oiiink"</span><span class=special>;</span> + +<span class=keyword>class</span> <span class=identifier>cow</span> <span class=special>:</span> <span class=keyword>public</span> <span class=identifier>animal</span> +<span class=special>{</span> + <span class=keyword>virtual</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span> <span class=identifier>do_speak</span><span class=special>()</span> <span class=keyword>const</span> + <span class=special>{</span> + <span class=keyword>return</span> <span class=identifier>muuuh</span><span class=special>;</span> + <span class=special>}</span> + + <span class=keyword>virtual</span> <span class=identifier>animal</span><span class=special>*</span> <span class=identifier>do_clone</span><span class=special>()</span> <span class=keyword>const</span> + <span class=special>{</span> + <span class=keyword>return</span> <span class=keyword>new</span> <span class=identifier>cow</span><span class=special>(</span> <span class=special>*</span><span class=keyword>this</span> <span class=special>);</span> + <span class=special>}</span> + +<span class=keyword>public</span><span class=special>:</span> + <span class=identifier>cow</span><span class=special>(</span> <span class=keyword>const</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span><span class=special>&</span> <span class=identifier>name</span> <span class=special>)</span> <span class=special>:</span> <span class=identifier>animal</span><span class=special>(</span><span class=identifier>name</span><span class=special>)</span> <span class=special>{</span> <span class=special>}</span> +<span class=special>};</span> + +<span class=keyword>class</span> <span class=identifier>pig</span> <span class=special>:</span> <span class=keyword>public</span> <span class=identifier>animal</span> +<span class=special>{</span> + <span class=keyword>virtual</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span> <span class=identifier>do_speak</span><span class=special>()</span> <span class=keyword>const</span> + <span class=special>{</span> + <span class=keyword>return</span> <span class=identifier>oiink</span><span class=special>;</span> + <span class=special>}</span> + + <span class=keyword>virtual</span> <span class=identifier>animal</span><span class=special>*</span> <span class=identifier>do_clone</span><span class=special>()</span> <span class=keyword>const</span> + <span class=special>{</span> + <span class=keyword>return</span> <span class=keyword>new</span> <span class=identifier>pig</span><span class=special>(</span> <span class=special>*</span><span class=keyword>this</span> <span class=special>);</span> + <span class=special>}</span> + +<span class=keyword>public</span><span class=special>:</span> + <span class=identifier>pig</span><span class=special>(</span> <span class=keyword>const</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span><span class=special>&</span> <span class=identifier>name</span> <span class=special>)</span> <span class=special>:</span> <span class=identifier>animal</span><span class=special>(</span><span class=identifier>name</span><span class=special>)</span> <span class=special>{</span> <span class=special>}</span> +<span class=special>};</span> + +<span class=comment>// +// Then we, of course, need a place to put all +// those animals. +//</span> + +<span class=keyword>class</span> <span class=identifier>farm</span> +<span class=special>{</span> + <span class=comment>// + // This is where the smart containers are handy + //</span> + <span class=keyword>typedef</span> <span class=identifier>boost</span><span class=special>::</span><span class=identifier>ptr_deque</span><span class=special><</span><span class=identifier>animal</span><span class=special>></span> <span class=identifier>barn_type</span><span class=special>;</span> + <span class=identifier>barn_type</span> <span class=identifier>barn</span><span class=special>;</span> + + <span class=comment>// + // An error type + //</span> + <span class=keyword>struct</span> <span class=identifier>farm_trouble</span> <span class=special>:</span> <span class=keyword>public</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>exception</span> <span class=special>{</span> <span class=special>};</span> + +<span class=keyword>public</span><span class=special>:</span> + <span class=comment>// + // We would like to make it possible to + // iterate over the animals in the farm + //</span> + <span class=keyword>typedef</span> <span class=identifier>barn_type</span><span class=special>::</span><span class=identifier>iterator</span> <span class=identifier>animal_iterator</span><span class=special>;</span> + + <span class=comment>// + // We also need to count the farm's size... + //</span> + <span class=keyword>typedef</span> <span class=identifier>barn_type</span><span class=special>::</span><span class=identifier>size_type</span> <span class=identifier>size_type</span><span class=special>;</span> + + <span class=comment>// + // And we also want to transfer an animal + // safely around. The easiest way to think + // about '::auto_type' is to imagine a simplified + // 'std::auto_ptr<T>' ... this means you can expect + // + // T* operator->() + // T* release() + // deleting destructor + // + // but not more. + //</span> + <span class=keyword>typedef</span> <span class=identifier>barn_type</span><span class=special>::</span><span class=identifier>auto_type</span> <span class=identifier>animal_transport</span><span class=special>;</span> + + <span class=comment>// + // Create an empty farm. + //</span> + <span class=identifier>farm</span><span class=special>()</span> <span class=special>{</span> <span class=special>}</span> + + <span class=comment>// + // We need a constructor that can make a new + // farm by cloning a range of animals. + //</span> + <span class=identifier>farm</span><span class=special>(</span> <span class=identifier>animal_iterator</span> <span class=identifier>begin</span><span class=special>,</span> <span class=identifier>animal_iterator</span> <span class=identifier>end</span> <span class=special>)</span> + <span class=special>:</span> + <span class=comment>// + // Objects are always cloned before insertion + // unless we explicitly add a pointer or + // use 'release()'. Therefore we actually + // clone all animals in the range + //</span> + <span class=identifier>barn</span><span class=special>(</span> <span class=identifier>begin</span><span class=special>,</span> <span class=identifier>end</span> <span class=special>)</span> <span class=special>{</span> <span class=special>}</span> + + <span class=comment>// + // ... so we need some other function too + //</span> + + <span class=identifier>animal_iterator</span> <span class=identifier>begin</span><span class=special>()</span> + <span class=special>{</span> + <span class=keyword>return</span> <span class=identifier>barn</span><span class=special>.</span><span class=identifier>begin</span><span class=special>();</span> + <span class=special>}</span> + + <span class=identifier>animal_iterator</span> <span class=identifier>end</span><span class=special>()</span> + <span class=special>{</span> + <span class=keyword>return</span> <span class=identifier>barn</span><span class=special>.</span><span class=identifier>end</span><span class=special>();</span> + <span class=special>}</span> + + <span class=comment>// + // Here it is quite ok to have an 'animal*' argument. + // The smart container will handle all ownership + // issues. + //</span> + <span class=keyword>void</span> <span class=identifier>buy_animal</span><span class=special>(</span> <span class=identifier>animal</span><span class=special>*</span> <span class=identifier>a</span> <span class=special>)</span> + <span class=special>{</span> + <span class=identifier>barn</span><span class=special>.</span><span class=identifier>push_back</span><span class=special>(</span> <span class=identifier>a</span> <span class=special>);</span> + <span class=special>}</span> + + <span class=comment>// + // The farm can also be in economical trouble and + // therefore be in the need to sell animals. + //</span> + <span class=identifier>animal_transport</span> <span class=identifier>sell_animal</span><span class=special>(</span> <span class=identifier>animal_iterator</span> <span class=identifier>to_sell</span> <span class=special>)</span> + <span class=special>{</span> + <span class=keyword>if</span><span class=special>(</span> <span class=identifier>to_sell</span> <span class=special>==</span> <span class=identifier>end</span><span class=special>()</span> <span class=special>)</span> + <span class=keyword>throw</span> <span class=identifier>farm_trouble</span><span class=special>();</span> + + <span class=comment>// + // Here we remove the animal from the barn, + // but the animal is not deleted yet...it's + // up to the buyer to decide what + // to do with it. + //</span> + <span class=keyword>return</span> <span class=identifier>barn</span><span class=special>.</span><span class=identifier>release</span><span class=special>(</span> <span class=identifier>to_sell</span> <span class=special>);</span> + <span class=special>}</span> + + <span class=comment>// + // How big a farm do we have? + //</span> + <span class=identifier>size_type</span> <span class=identifier>size</span><span class=special>()</span> <span class=keyword>const</span> + <span class=special>{</span> + <span class=keyword>return</span> <span class=identifier>barn</span><span class=special>.</span><span class=identifier>size</span><span class=special>();</span> + <span class=special>}</span> + + <span class=comment>// + // If things are bad, we might choose to sell all animals :-( + //</span> + <span class=identifier>std</span><span class=special>::</span><span class=identifier>auto_ptr</span><span class=special><</span><span class=identifier>barn_type</span><span class=special>></span> <span class=identifier>sell_farm</span><span class=special>()</span> + <span class=special>{</span> + <span class=keyword>return</span> <span class=identifier>barn</span><span class=special>.</span><span class=identifier>release</span><span class=special>();</span> + <span class=special>}</span> + + <span class=comment>// + // However, if things are good, we might buy somebody + // else's farm :-) + //</span> + + <span class=keyword>void</span> <span class=identifier>buy_farm</span><span class=special>(</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>auto_ptr</span><span class=special><</span><span class=identifier>barn_type</span><span class=special>></span> <span class=identifier>other</span> <span class=special>)</span> + <span class=special>{</span> + <span class=comment>// + // This line inserts all the animals from 'other' + // and is guaranteed either to succeed or to have no + // effect + //</span> + <span class=identifier>barn</span><span class=special>.</span><span class=identifier>transfer</span><span class=special>(</span> <span class=identifier>barn</span><span class=special>.</span><span class=identifier>end</span><span class=special>(),</span> <span class=comment>// insert new animals at the end</span> + <span class=special>*</span><span class=identifier>other</span> <span class=special>);</span> <span class=comment>// we want to transfer all animals, + // so we use the whole container as argument + // + // You might think you would have to do + // + // other.release(); + // + // but '*other' is empty and can go out of scope as it wants + //</span> + <span class=identifier>BOOST_ASSERT</span><span class=special>(</span> <span class=identifier>other</span><span class=special>-></span><span class=identifier>empty</span><span class=special>()</span> <span class=special>);</span> + <span class=special>}</span> + +<span class=special>};</span> <span class=comment>// class 'farm'.</span> + +<span class=keyword>int</span> <span class=identifier>main</span><span class=special>()</span> +<span class=special>{</span> + <span class=comment>// + // First we make a farm + //</span> + <span class=identifier>farm</span> <span class=identifier>animal_farm</span><span class=special>;</span> + <span class=identifier>BOOST_ASSERT</span><span class=special>(</span> <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>size</span><span class=special>()</span> <span class=special>==</span> <span class=number>0u</span> <span class=special>);</span> + + <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>buy_animal</span><span class=special>(</span> <span class=keyword>new</span> <span class=identifier>pig</span><span class=special>(</span><span class=string>"Betty"</span><span class=special>)</span> <span class=special>);</span> + <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>buy_animal</span><span class=special>(</span> <span class=keyword>new</span> <span class=identifier>pig</span><span class=special>(</span><span class=string>"Benny"</span><span class=special>)</span> <span class=special>);</span> + <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>buy_animal</span><span class=special>(</span> <span class=keyword>new</span> <span class=identifier>pig</span><span class=special>(</span><span class=string>"Jeltzin"</span><span class=special>)</span> <span class=special>);</span> + <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>buy_animal</span><span class=special>(</span> <span class=keyword>new</span> <span class=identifier>cow</span><span class=special>(</span><span class=string>"Hanz"</span><span class=special>)</span> <span class=special>);</span> + <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>buy_animal</span><span class=special>(</span> <span class=keyword>new</span> <span class=identifier>cow</span><span class=special>(</span><span class=string>"Mary"</span><span class=special>)</span> <span class=special>);</span> + <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>buy_animal</span><span class=special>(</span> <span class=keyword>new</span> <span class=identifier>cow</span><span class=special>(</span><span class=string>"Frederik"</span><span class=special>)</span> <span class=special>);</span> + <span class=identifier>BOOST_ASSERT</span><span class=special>(</span> <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>size</span><span class=special>()</span> <span class=special>==</span> <span class=number>6u</span> <span class=special>);</span> + + <span class=comment>// + // Then we make another farm...it will actually contain + // a clone of the other farm. + //</span> + <span class=identifier>farm</span> <span class=identifier>new_farm</span><span class=special>(</span> <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>begin</span><span class=special>(),</span> <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>end</span><span class=special>()</span> <span class=special>);</span> + <span class=identifier>BOOST_ASSERT</span><span class=special>(</span> <span class=identifier>new_farm</span><span class=special>.</span><span class=identifier>size</span><span class=special>()</span> <span class=special>==</span> <span class=number>6u</span> <span class=special>);</span> + + <span class=comment>// + // Is it really clones in the new farm? + //</span> + <span class=identifier>BOOST_ASSERT</span><span class=special>(</span> <span class=identifier>new_farm</span><span class=special>.</span><span class=identifier>begin</span><span class=special>()-></span><span class=identifier>name</span><span class=special>()</span> <span class=special>==</span> <span class=string>"Betty"</span> <span class=special>);</span> + + <span class=comment>// + // Then we search for an animal, Mary (the Crown Princess of Denmark), + // because we would like to buy her ... + //</span> + <span class=keyword>typedef</span> <span class=identifier>farm</span><span class=special>::</span><span class=identifier>animal_iterator</span> <span class=identifier>iterator</span><span class=special>;</span> + <span class=identifier>iterator</span> <span class=identifier>to_sell</span><span class=special>;</span> + <span class=keyword>for</span><span class=special>(</span> <span class=identifier>iterator</span> <span class=identifier>i</span> <span class=special>=</span> <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>begin</span><span class=special>(),</span> + <span class=identifier>end</span> <span class=special>=</span> <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>end</span><span class=special>();</span> + <span class=identifier>i</span> <span class=special>!=</span> <span class=identifier>end</span><span class=special>;</span> <span class=special>++</span><span class=identifier>i</span> <span class=special>)</span> + <span class=special>{</span> + <span class=keyword>if</span><span class=special>(</span> <span class=identifier>i</span><span class=special>-></span><span class=identifier>name</span><span class=special>()</span> <span class=special>==</span> <span class=string>"Mary"</span> <span class=special>)</span> + <span class=special>{</span> + <span class=identifier>to_sell</span> <span class=special>=</span> <span class=identifier>i</span><span class=special>;</span> + <span class=keyword>break</span><span class=special>;</span> + <span class=special>}</span> + <span class=special>}</span> + + <span class=identifier>farm</span><span class=special>::</span><span class=identifier>animal_transport</span> <span class=identifier>mary</span> <span class=special>=</span> <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>sell_animal</span><span class=special>(</span> <span class=identifier>to_sell</span> <span class=special>);</span> + + + <span class=keyword>if</span><span class=special>(</span> <span class=identifier>mary</span><span class=special>-></span><span class=identifier>speak</span><span class=special>()</span> <span class=special>==</span> <span class=identifier>muuuh</span> <span class=special>)</span> + <span class=comment>// + // Great, Mary is a cow, and she may live longer + //</span> + <span class=identifier>new_farm</span><span class=special>.</span><span class=identifier>buy_animal</span><span class=special>(</span> <span class=identifier>mary</span><span class=special>.</span><span class=identifier>release</span><span class=special>()</span> <span class=special>);</span> + <span class=keyword>else</span> + <span class=comment>// + // Then the animal would be destroyed (!) + // when we go out of scope. + //</span> + <span class=special>;</span> + + <span class=comment>// + // Now we can observe some changes to the two farms... + //</span> + <span class=identifier>BOOST_ASSERT</span><span class=special>(</span> <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>size</span><span class=special>()</span> <span class=special>==</span> <span class=number>5u</span> <span class=special>);</span> + <span class=identifier>BOOST_ASSERT</span><span class=special>(</span> <span class=identifier>new_farm</span><span class=special>.</span><span class=identifier>size</span><span class=special>()</span> <span class=special>==</span> <span class=number>7u</span> <span class=special>);</span> + + <span class=comment>// + // The new farm has however underestimated how much + // it cost to feed Mary and its owner is forced to sell the farm... + //</span> + <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>buy_farm</span><span class=special>(</span> <span class=identifier>new_farm</span><span class=special>.</span><span class=identifier>sell_farm</span><span class=special>()</span> <span class=special>);</span> + + <span class=identifier>BOOST_ASSERT</span><span class=special>(</span> <span class=identifier>new_farm</span><span class=special>.</span><span class=identifier>size</span><span class=special>()</span> <span class=special>==</span> <span class=number>0u</span> <span class=special>);</span> + <span class=identifier>BOOST_ASSERT</span><span class=special>(</span> <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>size</span><span class=special>()</span> <span class=special>==</span> <span class=number>12u</span> <span class=special>);</span> +<span class=special>}</span> +</pre> +</body> + +</html> +<!-- 10. Changing the Clone Allocator +++++++++++++++++++++++++++++++++ + +This example shows how we can change +the Clone Allocator to use the pointer containers +as view into other containers: + +.. raw:: html + :file: tut2.html --> +<hr><p><strong>Navigate:</strong></p> +<ul class="simple"> +<li><a class="reference" href="ptr_container.html">home</a></li> +<li><a class="reference" href="reference.html">reference</a></li> +</ul> +<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> diff --git a/libs/ptr_container/doc/examples.rst b/libs/ptr_container/doc/examples.rst new file mode 100644 index 0000000000..e0cf1af716 --- /dev/null +++ b/libs/ptr_container/doc/examples.rst @@ -0,0 +1,198 @@ +++++++++++++++++++++++++++++++++++ + |Boost| Pointer Container Library +++++++++++++++++++++++++++++++++++ + +.. |Boost| image:: boost.png + +======== +Examples +======== + +Some examples are given here and in the accompanying test files: + +.. contents:: :local: + + +.. _`Example 1`: + +1. Null pointers cannot be stored in the containers ++++++++++++++++++++++++++++++++++++++++++++++++++++ + +:: + + my_container.push_back( 0 ); // throws bad_ptr + my_container.replace( an_iterator, 0 ); // throws bad_ptr + my_container.insert( an_iterator, 0 ); // throws bad_ptr + std::auto_ptr<T> p( 0 ); + my_container.push_back( p ); // throws bad_ptr + +.. _`Example 2`: + +2. Iterators and other operations return indirected values +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +:: + + ptr_vector<X> pvec; + std::vector<X*> vec; + *vec.begin() = new X; // fine, memory leak + *pvec.begin() = new X; // compile time error + ( *vec.begin() )->foo(); // call X::foo(), a bit clumsy + pvec.begin()->foo(); // no indirection needed + *vec.front() = X(); // overwrite first element + pvec.front() = X(); // no indirection needed + + +.. _`Example 3`: + +3. Copy-semantics of pointer containers ++++++++++++++++++++++++++++++++++++++++ + +:: + + ptr_vector<T> vec1; + ... + ptr_vector<T> vec2( vec1.clone() ); // deep copy objects of 'vec1' and use them to construct 'vec2', could be very expensive + vec2 = vec1.release(); // give up ownership of pointers in 'vec1' and pass the ownership to 'vec2', rather cheap + vec2.release(); // give up ownership; the objects will be deallocated if not assigned to another container + vec1 = vec2; // deep copy objects of 'vec2' and assign them to 'vec1', could be very expensive + ptr_vector<T> vec3( vec1 ); // deep copy objects of 'vec1', could be very expensive + + +.. _`Example 4`: + +4. Making a non-copyable type Cloneable ++++++++++++++++++++++++++++++++++++++++ + +:: + + // a class that has no normal copy semantics + class X : boost::noncopyable { public: X* clone() const; ... }; + + // this will be found by the library by argument dependent lookup (ADL) + X* new_clone( const X& x ) + { return x.clone(); } + + // we can now use the interface that requires cloneability + ptr_vector<X> vec1, vec2; + ... + vec2 = vec1.clone(); // 'clone()' requires cloning <g> + vec2.insert( vec2.end(), vec1.begin(), vec1.end() ); // inserting always means inserting clones + + +.. _`Example 5`: + +5. Objects are cloned before insertion, inserted pointers are owned by the container +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +:: + + class X { ... }; // assume 'X' is Cloneable + X x; // and 'X' can be stack-allocated + ptr_list<X> list; + list.push_back( new_clone( x ) ); // insert a clone + list.push_back( new X ); // always give the pointer directly to the container to avoid leaks + list.push_back( &x ); // don't do this!!! + std::auto_ptr<X> p( new X ); + list.push_back( p ); // give up ownership + BOOST_ASSERT( p.get() == 0 ); + + +.. _`Example 6`: + +6. Transferring ownership of a single element ++++++++++++++++++++++++++++++++++++++++++++++ + +:: + + ptr_deque<T> deq; + typedef ptr_deque<T>::auto_type auto_type; + + // ... fill the container somehow + + auto_type ptr = deq.release_back(); // remove back element from container and give up ownership + auto_type ptr2 = deq.release( deq.begin() + 2 ); // use an iterator to determine the element to release + ptr = deq.release_front(); // supported for 'ptr_list' and 'ptr_deque' + + deq.push_back( ptr.release() ); // give ownership back to the container + + +.. _`Example 7`: + +7. Transferring ownership of pointers between different pointer containers +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +:: + + + ptr_list<X> list; ptr_vector<X> vec; + ... + // + // note: no cloning happens in these examples + // + list.transfer( list.begin(), vec.begin(), vec ); // make the first element of 'vec' the first element of 'list' + vec.transfer( vec.end(), list.begin(), list.end(), list ); // put all the lists element into the vector + +We can also transfer objects from ``ptr_container<Derived>`` to ``ptr_container<Base>`` without any problems. + +.. _`Example 8`: + + + +8. Selected test files +++++++++++++++++++++++ + +:incomplete_type_test.cpp_: Shows how to implement the Composite pattern. +:simple_test.cpp_: Shows how the usage of pointer container compares with a + container of smart pointers +:view_example.cpp_: Shows how to use a pointer container as a view into other container +:tree_test.cpp_: Shows how to make a tree-structure +:array_test.cpp_: Shows how to make an n-ary tree + +.. _incomplete_type_test.cpp : ../test/incomplete_type_test.cpp +.. _simple_test.cpp : ../test/simple_test.cpp +.. _view_example.cpp : ../test/view_example.cpp +.. _tree_test.cpp : ../test/tree_test.cpp +.. _array_test.cpp : ../test/ptr_array.cpp + + + +9. A large example +++++++++++++++++++ + +This example shows many of the most common +features at work. The example provide lots of comments. +The source code can also be found `here <../test/tut1.cpp>`_. + +.. raw:: html + :file: tutorial_example.html + +.. + 10. Changing the Clone Allocator + ++++++++++++++++++++++++++++++++ + + This example shows how we can change + the Clone Allocator to use the pointer containers + as view into other containers: + + .. raw:: html + :file: tut2.html + +.. raw:: html + + <hr> + +**Navigate:** + +- `home <ptr_container.html>`_ +- `reference <reference.html>`_ + +.. raw:: html + + <hr> + +:Copyright: Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). + +__ http://www.boost.org/LICENSE_1_0.txt + + diff --git a/libs/ptr_container/doc/faq.html b/libs/ptr_container/doc/faq.html new file mode 100644 index 0000000000..9b04b046d8 --- /dev/null +++ b/libs/ptr_container/doc/faq.html @@ -0,0 +1,387 @@ +<?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: 2007-11-25 13:38:02 -0500 (Sun, 25 Nov 2007) $ +:Revision: $Revision: 41370 $ +: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<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> +<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 "empty" 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<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> +<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& ) { ... } +delete_clone( const Foo* ) { ... } + +// x.hpp +class Foo; // Foo is incomplete here +class X { ptr_deque<Foo> container; ... } + +// x.cpp +#include <x.hpp> +#include <foo.hpp> // 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 "empty" 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> diff --git a/libs/ptr_container/doc/faq.rst b/libs/ptr_container/doc/faq.rst new file mode 100644 index 0000000000..40c8eb2d3c --- /dev/null +++ b/libs/ptr_container/doc/faq.rst @@ -0,0 +1,104 @@ +++++++++++++++++++++++++++++++++++ + |Boost| Pointer Container Library +++++++++++++++++++++++++++++++++++ + +.. |Boost| image:: boost.png + + +FAQ +=== + +.. contents:: :local: + +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? ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Call ``std::copy( first, last, c.begin() );``. + +Which mutating algorithms are safe to use with pointers? +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Any mutating algorithm that moves elements around by swapping them. An +important example is ``std::sort()``; examples of unsafe algorithms are +``std::unique()`` and ``std::remove()``. + +.. That is why these algorithms are + provided as member functions. + +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? +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +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. + +When instantiating a pointer container with a type ``T``, is ``T`` then allowed to be incomplete at that point? ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +No. This is a distinct property of ``shared_ptr`` which implies some overhead. + +However, one can leave ``T`` incomplete in the header file:: + + // foo.hpp + class Foo { ... }; + new_clone( const Foo& ) { ... } + delete_clone( const Foo* ) { ... } + + // x.hpp + class Foo; // Foo is incomplete here + class X { ptr_deque<Foo> container; ... } + + // x.cpp + #include <x.hpp> + #include <foo.hpp> // now Foo is not incomplete anymore + ... + + + +Why do iterator-range inserts give the strong exception-safety guarantee? ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +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. + +What is the _`polymorphic class problem`? ++++++++++++++++++++++++++++++++++++++++++ + +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. + +Are the pointer containers faster and do they have a better memory footprint than a container of smart pointers? ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +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: `[11] <ptr_container.html#references>`_ and `[12] <ptr_container.html#references>`_. + +When the stored pointers cannot be ``0``, how do I allow this "empty" behavior anyway? +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +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 `[13] <ptr_container.html#references>`_ for details. + +.. raw:: html + + <hr> + +:Copyright: Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). + +__ http://www.boost.org/LICENSE_1_0.txt + + diff --git a/libs/ptr_container/doc/guidelines.html b/libs/ptr_container/doc/guidelines.html new file mode 100644 index 0000000000..80cd01aa6b --- /dev/null +++ b/libs/ptr_container/doc/guidelines.html @@ -0,0 +1,434 @@ +<?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: 2008-07-16 17:03:47 -0400 (Wed, 16 Jul 2008) $ +:Revision: $Revision: 47494 $ +: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="usage-guidelines">Usage Guidelines</h2> +<div class="contents local topic"> +<ul class="simple"> +<li><a class="reference" href="#choosing-the-right-container" id="id8" name="id8">Choosing the right container</a></li> +<li><a class="reference" href="#recommended-practice-for-object-oriented-programming" id="id9" name="id9">Recommended practice for Object-Oriented Programming</a><ul> +<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> +<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> +<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> +<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> +</ul> +</li> +</ul> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id8" id="choosing-the-right-container" name="choosing-the-right-container">Choosing the right container</a></h1> +<p>The recommended usage pattern of the container classes is the same as +for normal standard containers.</p> +<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 +complexity tradeoffs and should be used accordingly. <tt class="docutils literal"><span class="pre">ptr_vector</span></tt> is the +type of sequence that should be used by default. <tt class="docutils literal"><span class="pre">ptr_list</span></tt> should be used +when there are frequent insertions and deletions from the middle of the +sequence and if the container is fairly large (eg. more than 100 +elements). <tt class="docutils literal"><span class="pre">ptr_deque</span></tt> is the data structure of choice when most insertions +and deletions take place at the beginning or at the end of the sequence. +The special container <tt class="docutils literal"><span class="pre">ptr_array</span></tt> may be used when the size of the container is invariant +and known at compile time.</p> +<p>An associative container supports unique keys if it may contain at most +one element for each key. Otherwise, it supports equivalent keys. +<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. +<tt class="docutils literal"><span class="pre">ptr_multiset</span></tt> and <tt class="docutils literal"><span class="pre">ptr_multimap</span></tt> +support equivalent keys.</p> +</div> +<div class="section"> +<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> +<p>Idiomatic Object-Oriented Programming in C++ looks a bit different from +the way it is done in other languages. This is partly because C++ +has both value and reference semantics, and partly because C++ is more flexible +than other languages. Below is a list of recommendations that you are +encouraged to follow:</p> +<div class="section"> +<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> +<p>This has the following advantages:</p> +<blockquote> +<ol class="loweralpha simple"> +<li>It reduces <em>coupling</em> because you do not have to maintain or update state</li> +</ol> +<!-- --> +<ol class="loweralpha simple" start="2"> +<li>It helps you to avoid <em>slicing</em></li> +</ol> +<!-- --> +<ol class="loweralpha simple" start="3"> +<li>It ensures you <em>override</em> the right function</li> +</ol> +</blockquote> +<p>You might also want to read the following articles:</p> +<ul class="simple"> +<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> +</ul> +<ul class="simple"> +<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> +</ul> +</div> +<div class="section"> +<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> +<p>In code:</p> +<pre class="literal-block"> +class Polymorphic +{ +private: + virtual int do_foo() = 0; + +public: + int foo() + { + return do_foo(); + } + ... +}; +</pre> +<p>This has the following advantages:</p> +<blockquote> +<ol class="loweralpha simple"> +<li>It makes sure all calls to the virtual function always goes through one place in your code</li> +</ol> +<!-- --> +<ol class="loweralpha simple" start="2"> +<li>It enables you to check preconditions and postconditions inside the forwarding function</li> +</ol> +</blockquote> +<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> +</div> +<div class="section"> +<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> +<p>Having an abstact base class prevents slicing when the base class is involved, but +it does not prevent it for classes further down the hierarchy. This is where +<a class="reference" href="http://www.boost.org/libs/utility/utility.htm#Class_noncopyable">boost::noncopyable</a> is handy to use:</p> +<pre class="literal-block"> +class Polymorphic : boost::noncopyable +{ + ... +}; +</pre> +</div> +<div class="section"> +<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> +<p>By default the pointer containers do not allow you to store null-pointer in them. +As you might know, this behavior can be changed explicitly with the use +of <a class="reference" href="reference.html#class-nullable">boost::nullable</a>.</p> +<p>The primary reason to avoid null-pointers +is that you have to check for null-pointers every time the container is +used. This extra checking is easy to forget, and it is somewhat contradictory to +the spirit of OO where you replace special cases with dynamic dispatch.</p> +<p>Often, however, you need to place some special object in the container because you +do not have enough information to construct a full object. In that case +you might be able to use the Null Object pattern which simply dictates that +you implement virtual functions from the abstract base-class +as empty functions or with dummy return values. This means that +your OO-code still does not need to worry about null-pointers.</p> +<p>You might want to read</p> +<ul class="simple"> +<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> +</ul> +<p>Finally you might end up in a situation where not even the Null Object can help +you. That is when you truly need <tt class="docutils literal"><span class="pre">container<</span> <span class="pre">nullable<T></span> <span class="pre">></span></tt>.</p> +<hr><p><strong>Navigate:</strong></p> +<ul class="simple"> +<li><a class="reference" href="ptr_container.html">home</a></li> +<li><a class="reference" href="reference.html">reference</a></li> +</ul> +<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> +</div> +</body> +</html> diff --git a/libs/ptr_container/doc/guidelines.rst b/libs/ptr_container/doc/guidelines.rst new file mode 100644 index 0000000000..1c39c7ba71 --- /dev/null +++ b/libs/ptr_container/doc/guidelines.rst @@ -0,0 +1,162 @@ +++++++++++++++++++++++++++++++++++ + |Boost| Pointer Container Library +++++++++++++++++++++++++++++++++++ + +.. |Boost| image:: boost.png + +================ +Usage Guidelines +================ + +.. contents:: :local: + +Choosing the right container +---------------------------- + +The recommended usage pattern of the container classes is the same as +for normal standard containers. + +``ptr_vector``, ``ptr_list`` and ``ptr_deque`` offer the programmer different +complexity tradeoffs and should be used accordingly. ``ptr_vector`` is the +type of sequence that should be used by default. ``ptr_list`` should be used +when there are frequent insertions and deletions from the middle of the +sequence and if the container is fairly large (eg. more than 100 +elements). ``ptr_deque`` is the data structure of choice when most insertions +and deletions take place at the beginning or at the end of the sequence. +The special container ``ptr_array`` may be used when the size of the container is invariant +and known at compile time. + +An associative container supports unique keys if it may contain at most +one element for each key. Otherwise, it supports equivalent keys. +``ptr_set`` and ``ptr_map`` support unique keys. +``ptr_multiset`` and ``ptr_multimap`` +support equivalent keys. + +Recommended practice for Object-Oriented Programming +---------------------------------------------------- + +Idiomatic Object-Oriented Programming in C++ looks a bit different from +the way it is done in other languages. This is partly because C++ +has both value and reference semantics, and partly because C++ is more flexible +than other languages. Below is a list of recommendations that you are +encouraged to follow: + +1. Make base classes abstract and without data +++++++++++++++++++++++++++++++++++++++++++++++ + +This has the following advantages: + + a. It reduces *coupling* because you do not have to maintain or update state + + .. + + b. It helps you to avoid *slicing* + + .. + + c. It ensures you *override* the right function + +You might also want to read the following articles: + +- Kevlin Henney's `Six of the best`__ + +.. __: http://www.two-sdg.demon.co.uk/curbralan/papers/SixOfTheBest.pdf + +- Jack Reeves' `Multiple Inheritance Considered Useful`__ + +.. __: http://www.ddj.com/documents/s=10011/q=1/cuj0602reeves/0602reeves.html + + +2. Make virtual functions private and provide a non-virtual public forwarding function +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +In code:: + + class Polymorphic + { + private: + virtual int do_foo() = 0; + + public: + int foo() + { + return do_foo(); + } + ... + }; + +This has the following advantages: + + a. It makes sure all calls to the virtual function always goes through one place in your code + + .. + + b. It enables you to check preconditions and postconditions inside the forwarding function + +You might also want to read Herb Sutter's article `Virtuality`__. + +.. __: http://www.gotw.ca/publications/mill18.htm + +3. Derive your base class from ``boost::noncopyable`` ++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Having an abstact base class prevents slicing when the base class is involved, but +it does not prevent it for classes further down the hierarchy. This is where +`boost::noncopyable`__ is handy to use:: + + class Polymorphic : boost::noncopyable + { + ... + }; + +.. __ : http://www.boost.org/libs/utility/utility.htm#Class_noncopyable + + +4. Avoid null-pointers in containers (if possible) +++++++++++++++++++++++++++++++++++++++++++++++++++ + +By default the pointer containers do not allow you to store null-pointer in them. +As you might know, this behavior can be changed explicitly with the use +of `boost::nullable`__. + +The primary reason to avoid null-pointers +is that you have to check for null-pointers every time the container is +used. This extra checking is easy to forget, and it is somewhat contradictory to +the spirit of OO where you replace special cases with dynamic dispatch. + +.. __: reference.html#class-nullable + +Often, however, you need to place some special object in the container because you +do not have enough information to construct a full object. In that case +you might be able to use the Null Object pattern which simply dictates that +you implement virtual functions from the abstract base-class +as empty functions or with dummy return values. This means that +your OO-code still does not need to worry about null-pointers. + +You might want to read + +- Kevlin Henney's `Null Object - Something for Nothing`__ + +.. __: http://www.two-sdg.demon.co.uk/curbralan/papers/europlop/NullObject.pdf + +Finally you might end up in a situation where not even the Null Object can help +you. That is when you truly need ``container< nullable<T> >``. + +.. raw:: html + + <hr> + +**Navigate:** + +- `home <ptr_container.html>`_ +- `reference <reference.html>`_ + +.. raw:: html + + <hr> + +:Copyright: Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). + +__ http://www.boost.org/LICENSE_1_0.txt + + diff --git a/libs/ptr_container/doc/headers.html b/libs/ptr_container/doc/headers.html new file mode 100644 index 0000000000..67439af1c7 --- /dev/null +++ b/libs/ptr_container/doc/headers.html @@ -0,0 +1,388 @@ +<?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: 2008-07-16 17:03:47 -0400 (Wed, 16 Jul 2008) $ +:Revision: $Revision: 47494 $ +: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="library-headers">Library headers</h2> +<table border="1" class="docutils"> +<colgroup> +<col width="29%" /> +<col width="71%" /> +</colgroup> +<tbody valign="top"> +<tr><td><strong>Header</strong></td> +<td><strong>Includes</strong></td> +</tr> +<tr><td><tt class="docutils literal"><span class="pre"><boost/ptr_container/clone_allocator.hpp></span></tt></td> +<td>classes <a class="reference" href="reference.html#the-clone-allocator-concept">heap_clone_allocator</a> and <a class="reference" href="reference.html#the-clone-allocator-concept">view_clone_allocator</a> +and functions <tt class="docutils literal"><span class="pre">new_clone()</span></tt> and <tt class="docutils literal"><span class="pre">delete_clone()</span></tt></td> +</tr> +<tr><td><tt class="docutils literal"><span class="pre"><boost/ptr_container/ptr_deque.hpp></span></tt></td> +<td>class <a class="reference" href="ptr_deque.html">ptr_deque</a> (and <tt class="docutils literal"><span class="pre">std::deque</span></tt>)</td> +</tr> +<tr><td><tt class="docutils literal"><span class="pre"><boost/ptr_container/ptr_list.hpp></span></tt></td> +<td>class <a class="reference" href="ptr_list.html">ptr_list</a> (and <tt class="docutils literal"><span class="pre">std::list</span></tt>)</td> +</tr> +<tr><td><tt class="docutils literal"><span class="pre"><boost/ptr_container/ptr_vector.hpp></span></tt></td> +<td>class <a class="reference" href="ptr_vector.html">ptr_vector</a> (and <tt class="docutils literal"><span class="pre">std::vector</span></tt>)</td> +</tr> +<tr><td><tt class="docutils literal"><span class="pre"><boost/ptr_container/ptr_array.hpp></span></tt></td> +<td>class <a class="reference" href="ptr_array.html">ptr_array</a> (and <tt class="docutils literal"><span class="pre">boost::array</span></tt>)</td> +</tr> +<tr><td><tt class="docutils literal"><span class="pre"><boost/ptr_container/ptr_set.hpp></span></tt></td> +<td>classes <a class="reference" href="ptr_set.html">ptr_set</a> and <a class="reference" href="ptr_multiset.html">ptr_multiset</a> +(and <tt class="docutils literal"><span class="pre">std::set</span></tt> and <tt class="docutils literal"><span class="pre">std::multiset</span></tt>)</td> +</tr> +<tr><td><tt class="docutils literal"><span class="pre"><boost/ptr_container/ptr_map.hpp></span></tt></td> +<td>classes <a class="reference" href="ptr_map.html">ptr_map</a> and <a class="reference" href="ptr_multimap.html">ptr_multimap</a> +(and <tt class="docutils literal"><span class="pre">std::map</span></tt> and <tt class="docutils literal"><span class="pre">std::multimap</span></tt>)</td> +</tr> +<tr><td><tt class="docutils literal"><span class="pre"><boost/ptr_container/ptr_inserter.hpp></span></tt></td> +<td>functions <a class="reference" href="ptr_inserter.html">ptr_back_inserter</a>, <a class="reference" href="ptr_inserter.html">ptr_front_inserter</a> and <a class="reference" href="ptr_inserter.html">ptr_inserter</a></td> +</tr> +<tr><td><tt class="docutils literal"><span class="pre"><boost/ptr_container/ptr_container.hpp></span></tt></td> +<td>all classes</td> +</tr> +<tr><td><tt class="docutils literal"><span class="pre"><boost/ptr_container/ptr_sequence_adapter.hpp></span></tt></td> +<td>class <a class="reference" href="ptr_sequence_adapter.html">ptr_sequence_adapter</a></td> +</tr> +<tr><td><tt class="docutils literal"><span class="pre"><boost/ptr_container/ptr_set_adapter.hpp></span></tt></td> +<td>classes <a class="reference" href="ptr_set_adapter.html">ptr_set_adapter</a> and <a class="reference" href="ptr_multiset_adapter.html">ptr_multiset_adapter</a></td> +</tr> +<tr><td><tt class="docutils literal"><span class="pre"><boost/ptr_container/ptr_map_adapter.hpp></span></tt></td> +<td>classes <a class="reference" href="ptr_map_adapter.html">ptr_map_adapter</a> and <a class="reference" href="ptr_multimap_adapter.html">ptr_multimap_adapter</a></td> +</tr> +<tr><td><tt class="docutils literal"><span class="pre"><boost/ptr_container/exception.hpp></span></tt></td> +<td>classes <a class="reference" href="reference.html#exception-classes">bad_ptr_container_operation</a>, <a class="reference" href="reference.html#exception-classes">bad_index</a> and <a class="reference" href="reference.html#exception-classes">bad_pointer</a></td> +</tr> +<tr><td><tt class="docutils literal"><span class="pre"><boost/ptr_container/indirect_fun.hpp></span></tt></td> +<td>class <a class="reference" href="indirect_fun.html">indirect_fun</a></td> +</tr> +<tr><td><tt class="docutils literal"><span class="pre"><boost/ptr_container/nullable.hpp></span></tt></td> +<td>class <a class="reference" href="reference.html#class-nullable">nullable</a></td> +</tr> +<tr><td><tt class="docutils literal"><span class="pre"><boost/ptr_container/serialize_ptr_deque.hpp></span></tt></td> +<td>class <a class="reference" href="ptr_deque.html">ptr_deque</a> with serialization support</td> +</tr> +<tr><td><tt class="docutils literal"><span class="pre"><boost/ptr_container/serialize_ptr_list.hpp></span></tt></td> +<td>class <a class="reference" href="ptr_list.html">ptr_list</a> with serialization support</td> +</tr> +<tr><td><tt class="docutils literal"><span class="pre"><boost/ptr_container/serialize_ptr_vector.hpp></span></tt></td> +<td>class <a class="reference" href="ptr_vector.html">ptr_vector</a> with serialization support</td> +</tr> +<tr><td><tt class="docutils literal"><span class="pre"><boost/ptr_container/serialize_ptr_array.hpp></span></tt></td> +<td>class <a class="reference" href="ptr_array.html">ptr_array</a> with serialization support</td> +</tr> +<tr><td><tt class="docutils literal"><span class="pre"><boost/ptr_container/serialize_ptr_set.hpp></span></tt></td> +<td>classes <a class="reference" href="ptr_set.html">ptr_set</a> and <a class="reference" href="ptr_multiset.html">ptr_multiset</a> with serialization support</td> +</tr> +<tr><td><tt class="docutils literal"><span class="pre"><boost/ptr_container/serialize_ptr_map.hpp></span></tt></td> +<td>classes <a class="reference" href="ptr_map.html">ptr_map</a> and <a class="reference" href="ptr_multimap.html">ptr_multimap</a> with serialization support</td> +</tr> +<tr><td><tt class="docutils literal"><span class="pre"><boost/ptr_container/serialize_ptr_container.hpp></span></tt></td> +<td>all classes with serialization support</td> +</tr> +</tbody> +</table> +<p><strong>Navigate:</strong></p> +<ul class="simple"> +<li><a class="reference" href="ptr_container.html">home</a></li> +<li><a class="reference" href="reference.html">reference</a></li> +</ul> +<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> +</body> +</html> diff --git a/libs/ptr_container/doc/headers.rst b/libs/ptr_container/doc/headers.rst new file mode 100644 index 0000000000..befcbb55ec --- /dev/null +++ b/libs/ptr_container/doc/headers.rst @@ -0,0 +1,84 @@ +++++++++++++++++++++++++++++++++++ + |Boost| Pointer Container Library +++++++++++++++++++++++++++++++++++ + +.. |Boost| image:: boost.png + +=============== +Library headers +=============== + +======================================================= ============================================================= + **Header** **Includes** + +``<boost/ptr_container/clone_allocator.hpp>`` classes heap_clone_allocator_ and view_clone_allocator_ + and functions ``new_clone()`` and ``delete_clone()`` + +``<boost/ptr_container/ptr_deque.hpp>`` class `ptr_deque <ptr_deque.html>`_ (and ``std::deque``) + +``<boost/ptr_container/ptr_list.hpp>`` class `ptr_list <ptr_list.html>`_ (and ``std::list``) + +``<boost/ptr_container/ptr_vector.hpp>`` class `ptr_vector <ptr_vector.html>`_ (and ``std::vector``) + +``<boost/ptr_container/ptr_array.hpp>`` class `ptr_array <ptr_array.html>`_ (and ``boost::array``) + +``<boost/ptr_container/ptr_set.hpp>`` classes `ptr_set <ptr_set.html>`_ and `ptr_multiset <ptr_multiset.html>`_ + (and ``std::set`` and ``std::multiset``) + +``<boost/ptr_container/ptr_map.hpp>`` classes `ptr_map <ptr_map.html>`_ and `ptr_multimap <ptr_multimap.html>`_ + (and ``std::map`` and ``std::multimap``) + +``<boost/ptr_container/ptr_inserter.hpp>`` functions `ptr_back_inserter <ptr_inserter.html>`_, `ptr_front_inserter <ptr_inserter.html>`_ and `ptr_inserter <ptr_inserter.html>`_ + +``<boost/ptr_container/ptr_container.hpp>`` all classes + +``<boost/ptr_container/ptr_sequence_adapter.hpp>`` class `ptr_sequence_adapter <ptr_sequence_adapter.html>`_ + +``<boost/ptr_container/ptr_set_adapter.hpp>`` classes `ptr_set_adapter <ptr_set_adapter.html>`_ and `ptr_multiset_adapter <ptr_multiset_adapter.html>`_ + +``<boost/ptr_container/ptr_map_adapter.hpp>`` classes `ptr_map_adapter <ptr_map_adapter.html>`_ and `ptr_multimap_adapter <ptr_multimap_adapter.html>`_ + +``<boost/ptr_container/exception.hpp>`` classes `bad_ptr_container_operation`_, `bad_index`_ and `bad_pointer`_ +``<boost/ptr_container/indirect_fun.hpp>`` class `indirect_fun`_ + +``<boost/ptr_container/nullable.hpp>`` class `nullable`_ + +``<boost/ptr_container/serialize_ptr_deque.hpp>`` class `ptr_deque <ptr_deque.html>`_ with serialization support + +``<boost/ptr_container/serialize_ptr_list.hpp>`` class `ptr_list <ptr_list.html>`_ with serialization support + +``<boost/ptr_container/serialize_ptr_vector.hpp>`` class `ptr_vector <ptr_vector.html>`_ with serialization support + +``<boost/ptr_container/serialize_ptr_array.hpp>`` class `ptr_array <ptr_array.html>`_ with serialization support + +``<boost/ptr_container/serialize_ptr_set.hpp>`` classes `ptr_set <ptr_set.html>`_ and `ptr_multiset <ptr_multiset.html>`_ with serialization support + +``<boost/ptr_container/serialize_ptr_map.hpp>`` classes `ptr_map <ptr_map.html>`_ and `ptr_multimap <ptr_multimap.html>`_ with serialization support + +``<boost/ptr_container/serialize_ptr_container.hpp>`` all classes with serialization support + +======================================================= ============================================================= + +.. _`heap_clone_allocator`: reference.html#the-clone-allocator-concept +.. _`view_clone_allocator`: reference.html#the-clone-allocator-concept +.. _`bad_ptr_container_operation`: reference.html#exception-classes +.. _`bad_index`: reference.html#exception-classes +.. _`bad_pointer`: reference.html#exception-classes +.. _`nullable`: reference.html#class-nullable +.. _`indirect_fun`: indirect_fun.html + + +**Navigate:** + +- `home <ptr_container.html>`_ +- `reference <reference.html>`_ + +.. raw:: html + + <hr> + +:Copyright: Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). + +__ http://www.boost.org/LICENSE_1_0.txt + + diff --git a/libs/ptr_container/doc/indirect_fun.html b/libs/ptr_container/doc/indirect_fun.html new file mode 100644 index 0000000000..c4673585b4 --- /dev/null +++ b/libs/ptr_container/doc/indirect_fun.html @@ -0,0 +1,414 @@ +<?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: 2006-11-22 17:01:03 -0500 (Wed, 22 Nov 2006) $ +:Revision: $Revision: 36152 $ +: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="indirected-functions">Indirected functions</h2> +<p>It is quite common that we have two pointers and what to compare the +pointed to objects. Also, we have usually already defined how +to compare the objects. So to avoid some tedious boiler-plate code +this library defines predicates that apply an indirection before comparing.</p> +<p>When the container uses <tt class="docutils literal"><span class="pre">void*</span></tt> internally, we can use the +class <tt class="docutils literal"><span class="pre">void_ptr_indirect_fun</span></tt>; otherwise we use the class +<tt class="docutils literal"><span class="pre">indirect_fun</span></tt>.</p> +<p><strong>Example:</strong></p> +<pre class="literal-block"> +std::string* bar = new std::string("bar"); +std::string* foo = new std::string("foo"); +BOOST_ASSERT( indirect_fun< std::less<std::string> >()( bar, foo ) == true ); +BOOST_ASSERT( make_indirect_fun( std::less<std::string>() )( foo, bar ) == false ); + +void* vptr1 = ptr1; +void* vptr2 = ptr2; +void_ptr_indirect_fun< std::less<std::string>, std::string> cast_fun; +BOOST_CHECK( cast_fun( vptr1, vptr2 ) == true ); +</pre> +<p><strong>See also:</strong></p> +<ul class="simple"> +<li><a class="reference" href="http://www.boost.org/libs/utility/utility.htm#result_of">result_of</a></li> +<li><a class="reference" href="http://www.boost.org/libs/iterator/doc/pointee.html">pointee</a></li> +<li><a class="reference" href="ptr_set.html">ptr_set</a></li> +<li><a class="reference" href="ptr_multiset.html">ptr_multiset</a></li> +</ul> +<p><strong>Navigate</strong></p> +<ul class="simple"> +<li><a class="reference" href="ptr_container.html">home</a></li> +<li><a class="reference" href="reference.html">reference</a></li> +</ul> +<p><strong>Remarks:</strong></p> +<p>The class <tt class="docutils literal"><span class="pre">indirect_fun</span></tt> will work with smart pointers such as <a class="reference" href="http://www.boost.org/libs/smart_ptr/shared_ptr.htm">boost::shared_ptr<T></a> +because of the type traits <tt class="docutils literal"><span class="pre">pointee<T>::type</span></tt> from the header <tt class="docutils literal"><span class="pre"><boost/pointee.hpp></span></tt>.</p> +<p><strong>Synopsis:</strong></p> +<p>Since the definition of the predicates is somewhat trivial, only the +first operation is expanded inline.</p> +<pre class="literal-block"> +namespace boost +{ + + template< class Fun > + struct indirect_fun + { + indirect_fun() : fun(Fun()) + { } + + indirect_fun( Fun f ) : fun(f) + { } + + template< class T > + typename result_of< Fun( typename pointee<T>::type ) >::type + operator()( const T& r ) const + { + return fun( *r ); + } + + template< class T, class U > + typename result_of< Fun( typename pointee<T>::type, + typename pointee<U>::type ) >::type + operator()( const T& r, const U& r2 ) const + { + return fun( *r, *r2 ); + } + + private: + Fun fun; + }; + + template< class Fun > + inline indirect_fun<Fun> make_indirect_fun( Fun f ) + { + return indirect_fun<Fun>( f ); + } + + + + template< class Fun, class Arg1, class Arg2 = Arg1 > + struct void_ptr_indirect_fun + { + void_ptr_indirect_fun() : fun(Fun()) + { } + + void_ptr_indirect_fun( Fun f ) : fun(f) + { } + + typename result_of< Fun( Arg1 ) >::type + operator()( const void* r ) const + { + return fun( * static_cast<const Arg1*>( r ) ); + } + + typename result_of< Fun( Arg1, Arg2 ) >::type + operator()( const void* l, const void* r ) const + { + return fun( * static_cast<const Arg1*>( l ), * static_cast<const Arg2*>( r ) ); + } + + private: + Fun fun; + }; + + template< class Fun, class Arg > + inline void_ptr_indirect_fun<Fun,Arg> + make_void_ptr_indirect_fun( Fun f ) + { + return void_ptr_indirect_fun<Fun,Arg>( f ); + } + +} // namespace 'boost' +</pre> +<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> +</body> +</html> diff --git a/libs/ptr_container/doc/indirect_fun.rst b/libs/ptr_container/doc/indirect_fun.rst new file mode 100644 index 0000000000..5fd13df2c7 --- /dev/null +++ b/libs/ptr_container/doc/indirect_fun.rst @@ -0,0 +1,136 @@ +++++++++++++++++++++++++++++++++++ + |Boost| Pointer Container Library +++++++++++++++++++++++++++++++++++ + +.. |Boost| image:: boost.png + +Indirected functions +-------------------- + +It is quite common that we have two pointers and what to compare the +pointed to objects. Also, we have usually already defined how +to compare the objects. So to avoid some tedious boiler-plate code +this library defines predicates that apply an indirection before comparing. + +When the container uses ``void*`` internally, we can use the +class ``void_ptr_indirect_fun``; otherwise we use the class +``indirect_fun``. + +**Example:** :: + + std::string* bar = new std::string("bar"); + std::string* foo = new std::string("foo"); + BOOST_ASSERT( indirect_fun< std::less<std::string> >()( bar, foo ) == true ); + BOOST_ASSERT( make_indirect_fun( std::less<std::string>() )( foo, bar ) == false ); + + void* vptr1 = ptr1; + void* vptr2 = ptr2; + void_ptr_indirect_fun< std::less<std::string>, std::string> cast_fun; + BOOST_CHECK( cast_fun( vptr1, vptr2 ) == true ); + +**See also:** + +- `result_of <http://www.boost.org/libs/utility/utility.htm#result_of>`_ +- `pointee <http://www.boost.org/libs/iterator/doc/pointee.html>`_ +- `ptr_set <ptr_set.html>`_ +- `ptr_multiset <ptr_multiset.html>`_ + +**Navigate** + +- `home <ptr_container.html>`_ +- `reference <reference.html>`_ + +**Remarks:** + +The class ``indirect_fun`` will work with smart pointers such as `boost::shared_ptr<T> <http://www.boost.org/libs/smart_ptr/shared_ptr.htm>`_ +because of the type traits ``pointee<T>::type`` from the header ``<boost/pointee.hpp>``. + +**Synopsis:** + +Since the definition of the predicates is somewhat trivial, only the +first operation is expanded inline. + +:: + + namespace boost + { + + template< class Fun > + struct indirect_fun + { + indirect_fun() : fun(Fun()) + { } + + indirect_fun( Fun f ) : fun(f) + { } + + template< class T > + typename result_of< Fun( typename pointee<T>::type ) >::type + operator()( const T& r ) const + { + return fun( *r ); + } + + template< class T, class U > + typename result_of< Fun( typename pointee<T>::type, + typename pointee<U>::type ) >::type + operator()( const T& r, const U& r2 ) const + { + return fun( *r, *r2 ); + } + + private: + Fun fun; + }; + + template< class Fun > + inline indirect_fun<Fun> make_indirect_fun( Fun f ) + { + return indirect_fun<Fun>( f ); + } + + + + template< class Fun, class Arg1, class Arg2 = Arg1 > + struct void_ptr_indirect_fun + { + void_ptr_indirect_fun() : fun(Fun()) + { } + + void_ptr_indirect_fun( Fun f ) : fun(f) + { } + + typename result_of< Fun( Arg1 ) >::type + operator()( const void* r ) const + { + return fun( * static_cast<const Arg1*>( r ) ); + } + + typename result_of< Fun( Arg1, Arg2 ) >::type + operator()( const void* l, const void* r ) const + { + return fun( * static_cast<const Arg1*>( l ), * static_cast<const Arg2*>( r ) ); + } + + private: + Fun fun; + }; + + template< class Fun, class Arg > + inline void_ptr_indirect_fun<Fun,Arg> + make_void_ptr_indirect_fun( Fun f ) + { + return void_ptr_indirect_fun<Fun,Arg>( f ); + } + + } // namespace 'boost' + +.. raw:: html + + <hr> + +:Copyright: Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). + +__ http://www.boost.org/LICENSE_1_0.txt + + diff --git a/libs/ptr_container/doc/intro.xml b/libs/ptr_container/doc/intro.xml new file mode 100644 index 0000000000..69815fb950 --- /dev/null +++ b/libs/ptr_container/doc/intro.xml @@ -0,0 +1,91 @@ +<!-- +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// +--> +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" +"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> +<section id="ptr_container.intro" last-revision="$Date: 2008-02-07 03:44:10 -0500 (Thu, 07 Feb 2008) $"> + <title>Introduction</title> + + <para> + This library provides standard-like containers that are suitable + for storing pointers to both polymorphic and non-polymorphic objects. + For each of the standard containers there is a pointer container + equivalent that takes ownership of the stored pointers in an exception + safe manner. In this respect it is intended to solve + the so-called <emphasis>polymorphic class problem. </emphasis> + </para> + <para> + The main advantages are + <itemizedlist> + <listitem> Exception-safe and fool proof pointer storage and manipulation.</listitem>. + <listitem> Exception-guarantees are generally much better than with standard containers (at least the strong guarantee</listitem> + <listitem> Notational convinience compared to the use of containers of smart pointers.</listitem> + <listitem> Iterators are automatically indirected so the comparison operations can be kept + on object basis instead of making/adding pointer based variants.</listitem> + <listitem> No memory-overhead as containers of smart_pointers can have.</listitem> + <listitem> Faster than using containers of smart pointers.</listitem> + <listitem> Provides an elegant solution to <code> vector< vector<T> > </code> performance + problems; simply use <code>ptr_vector< vector<T> ></code></listtem> + </para> + <para> + Below is given some example that show how the usage compares to a container of smart pointers: + <programlisting> + using namespace boost; + using namespace std; + + class Poly + { + public: + virtual ~Poly() {} + void foo() { doFoo(); } + private: + virtual void doFoo() + { + int i; + ++i; + } + }; + + // + // one doesn't need to introduce new names or live with long ones + // + typedef shared_ptr<Poly> PolyPtr; + + // + // one doesn't need to write this anymore + // + struct PolyPtrOps + { + void operator()( const PolyPtr & a ) + { a->foo(); } + }; + + int main() + { + enum { size = 2000000 }; + vector<PolyPtr> svec + ptr_vector<Poly> pvec; + + for( int i = 0; i < size; ++i ) + { + svec.push_back( PolyPtr( new Poly ) ); + pvec.push_back( new Poly ); // no extra syntax + } + + for_each( svec.begin(), svec.end(), PolyPtrOps() ); + + for_each( pvec.begin(), pvec.end(), mem_fun_ref( &Poly::foo ) ); + } + </programlisting> + </para> +</section> diff --git a/libs/ptr_container/doc/ptr_array.html b/libs/ptr_container/doc/ptr_array.html new file mode 100644 index 0000000000..6ff6a32f2c --- /dev/null +++ b/libs/ptr_container/doc/ptr_array.html @@ -0,0 +1,601 @@ +<?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: 2007-11-25 13:38:02 -0500 (Sun, 25 Nov 2007) $ +:Revision: $Revision: 41370 $ +: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> +<div class="section"> +<h1><a id="class-ptr-array" name="class-ptr-array">Class <tt class="docutils literal"><span class="pre">ptr_array</span></tt></a></h1> +<p>A <tt class="docutils literal"><span class="pre">ptr_array<T,size></span></tt> is a pointer container that uses an underlying <tt class="docutils literal"><span class="pre">boost::array<void*,size></span></tt> +to store the pointers. The class is useful when there is no requirement +of dynamic expansion and when no overhead is tolerable.</p> +<p><strong>Hierarchy:</strong></p> +<ul class="simple"> +<li><a class="reference" href="reversible_ptr_container.html">reversible_ptr_container</a><ul> +<li><a class="reference" href="ptr_sequence_adapter.html">ptr_sequence_adapter</a><ul> +<li><a class="reference" href="ptr_vector.html">ptr_vector</a></li> +<li><a class="reference" href="ptr_list.html">ptr_list</a></li> +<li><a class="reference" href="ptr_deque.html">ptr_deque</a></li> +<li><tt class="docutils literal"><span class="pre">ptr_array</span></tt></li> +</ul> +</li> +</ul> +</li> +</ul> +<p><strong>Navigate:</strong></p> +<ul class="simple"> +<li><a class="reference" href="ptr_container.html">home</a></li> +<li><a class="reference" href="reference.html">reference</a></li> +</ul> +<p><strong>Synopsis:</strong></p> +<pre class="literal-block"> +namespace boost +{ + + template + < + class T, + size_t N, + CloneAllocator = heap_clone_allocator + > + class ptr_array : public <em>implementation-defined</em> + { + public: // <a class="reference" href="#construct-copy-destroy">construct/copy/destroy</a> + ptr_array(); + explicit ptr_array( const ptr_array& r ); + template< class U > + explicit ptr_array( const ptr_array<U,N>& r ); + explicit ptr_array( std::auto_ptr<ptr_array>& r ); + + ptr_array& operator=( const ptr_array& r ); + template< class U > + ptr_array& operator=( const ptr_array<U,N>& r ); + ptr_array& operator=( std::auto_ptr<this_type> r ); + + public: // <a class="reference" href="reversible_ptr_container.html#iterators">iterators</a> + + public: // <a class="reference" href="reversible_ptr_container.html#capacity">capacity</a> + + public: // <a class="reference" href="#element-access">element access</a> + T& front(); + const T& front() const; + T& back(); + const T& back() const; + + template< size_t idx > + T& at(); + template< size_t idx > + const T& at() const; + T& at( size_t ); + const T& at( size_t ); + + T& operator[]( size_t ); + const T& operator[]( size_t ) const; + + public: // <a class="reference" href="#modifiers">modifiers</a> + void swap( ptr_array& r ); + + template< size_t idx > + auto_type replace( T* r ); + template< size_t idx, class U > + auto_type replace( std::auto_ptr<U> r ); + auto_type replace( size_t idx, T* r ); + template< class U > + auto_type replace( size_t idx, std::auto_ptr<U> r ); + + public: // <a class="reference" href="#pointer-container-requirements">pointer container requirements</a> + std::auto_ptr<ptr_array> clone() const; + std::auto_ptr<ptr_array> release(); + template< size_t idx > + bool is_null() const; + bool is_null( size_t idx ) const; + + }; // class 'ptr_sequence_adapter' + +} // namespace 'boost' +</pre> +</div> +<div class="section"> +<h1><a id="semantics" name="semantics">Semantics</a></h1> +<div class="section"> +<h2><a id="semantics-construct-copy-destroy" name="semantics-construct-copy-destroy"><span id="construct-copy-destroy"></span>Semantics: construct/copy/destroy</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">ptr_array();</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: constructs array where each element is null</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">explicit</span> <span class="pre">ptr_array(</span> <span class="pre">const</span> <span class="pre">ptr_array&</span> <span class="pre">r</span> <span class="pre">);</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">U</span> <span class="pre">></span> +<span class="pre">explicit</span> <span class="pre">ptr_array(</span> <span class="pre">const</span> <span class="pre">ptr_array<U,N>&</span> <span class="pre">r</span> <span class="pre">);</span></tt></p> +<ul class="simple"> +<li>Effects: Constructs array by cloning <tt class="docutils literal"><span class="pre">r</span></tt></li> +</ul> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">ptr_array(</span> <span class="pre">std::auto_ptr<ptr_array>&</span> <span class="pre">r</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: take ownership of the supplied pointers</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">ptr_array&</span> <span class="pre">operator=(</span> <span class="pre">const</span> <span class="pre">ptr_array&</span> <span class="pre">r</span> <span class="pre">);</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">U</span> <span class="pre">></span> <span class="pre">ptr_array&</span> <span class="pre">operator=(</span> <span class="pre">const</span> <span class="pre">ptr_array<U,N>&</span> <span class="pre">r</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Assigns a clone of <tt class="docutils literal"><span class="pre">r</span></tt></li> +<li>Exception safety: Strong guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">ptr_array&</span> <span class="pre">operator=(</span> <span class="pre">std::auto_ptr<this_type></span> <span class="pre">r</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: take ownership of the supplied pointers</li> +<li>Throws: Nothing</li> +</ul> +</blockquote> +</li> +</ul> +</div> +<div class="section"> +<h2><a id="semantics-element-access" name="semantics-element-access"><span id="element-access"></span>Semantics: element access</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">T&</span> <span class="pre">front();</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">const</span> <span class="pre">T&</span> <span class="pre">front()</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">not</span> <span class="pre">empty();</span></tt></li> +<li>Effects: <tt class="docutils literal"><span class="pre">return</span> <span class="pre">*begin();</span></tt></li> +<li>Throws: <tt class="docutils literal"><span class="pre">bad_ptr_container_operation</span></tt> if <tt class="docutils literal"><span class="pre">empty()</span> <span class="pre">==</span> <span class="pre">true</span></tt></li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">T&</span> <span class="pre">back();</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">const</span> <span class="pre">T&</span> <span class="pre">back()</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">not</span> <span class="pre">empty();</span></tt></li> +<li>Effects: <tt class="docutils literal"><span class="pre">return</span> <span class="pre">*--end();</span></tt></li> +<li>Throws: <tt class="docutils literal"><span class="pre">bad_ptr_container_operation</span></tt> if <tt class="docutils literal"><span class="pre">empty()</span> <span class="pre">==</span> <span class="pre">true</span></tt></li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">size_t</span> <span class="pre">idx</span> <span class="pre">></span> <span class="pre">T&</span> <span class="pre">at(</span> <span class="pre">size_type</span> <span class="pre">n</span> <span class="pre">);</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">size_t</span> <span class="pre">idx</span> <span class="pre">></span> <span class="pre">const</span> <span class="pre">T&</span> <span class="pre">at(</span> <span class="pre">size_type</span> <span class="pre">n</span> <span class="pre">)</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">idx</span> <span class="pre"><</span> <span class="pre">size()</span></tt> (compile-time enforced)</li> +<li>Effects: Returns a reference to the <tt class="docutils literal"><span class="pre">n</span></tt>'th element</li> +<li>Throws: nothing</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">T&</span> <span class="pre">at(</span> <span class="pre">size_type</span> <span class="pre">n</span> <span class="pre">);</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">const</span> <span class="pre">T&</span> <span class="pre">at(</span> <span class="pre">size_type</span> <span class="pre">n</span> <span class="pre">)</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">n</span> <span class="pre"><</span> <span class="pre">size()</span></tt></li> +<li>Effects: Returns a reference to the <tt class="docutils literal"><span class="pre">n</span></tt>'th element</li> +<li>Throws: <tt class="docutils literal"><span class="pre">bad_index</span></tt> if <tt class="docutils literal"><span class="pre">n</span> <span class="pre">>=size()</span></tt></li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">T&</span> <span class="pre">operator[](</span> <span class="pre">size_type</span> <span class="pre">n</span> <span class="pre">);</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">const</span> <span class="pre">T&</span> <span class="pre">operator[](</span> <span class="pre">size_type</span> <span class="pre">n</span> <span class="pre">)</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">n</span> <span class="pre"><</span> <span class="pre">size()</span></tt></li> +<li>Effects: Returns a reference to the <tt class="docutils literal"><span class="pre">n</span></tt>'th element</li> +<li>Throws: Nothing</li> +</ul> +</blockquote> +</li> +</ul> +</div> +<div class="section"> +<h2><a id="semantics-modifiers" name="semantics-modifiers"><span id="modifiers"></span>Semantics: modifiers</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">swap(</span> <span class="pre">ptr_array&</span> <span class="pre">r</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: swaps the two arrays</li> +<li>Complexity: Linear</li> +<li>Throws: nothing</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">size_t</span> <span class="pre">idx</span> <span class="pre">></span> <span class="pre">auto_type</span> <span class="pre">replace(</span> <span class="pre">T*</span> <span class="pre">r</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul> +<li><p class="first">Requirements:</p> +<blockquote> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">idx</span> <span class="pre"><</span> <span class="pre">size()</span></tt> (compile-time enforced)</li> +<li><tt class="docutils literal"><span class="pre">r</span> <span class="pre">!=</span> <span class="pre">0</span></tt></li> +</ul> +</blockquote> +</li> +<li><p class="first">Effects: returns the object indexed by <tt class="docutils literal"><span class="pre">idx</span></tt> and replaces it with <tt class="docutils literal"><span class="pre">r</span></tt>.</p> +</li> +<li><p class="first">Throws: <tt class="docutils literal"><span class="pre">bad_pointer</span></tt> if <tt class="docutils literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">0</span></tt>.</p> +</li> +<li><p class="first">Exception safety: Strong guarantee</p> +</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">size_t</span> <span class="pre">idx,</span> <span class="pre">class</span> <span class="pre">U</span> <span class="pre">></span> <span class="pre">auto_type</span> <span class="pre">replace(</span> <span class="pre">std::auto_ptr<U></span> <span class="pre">r</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: <tt class="docutils literal"><span class="pre">return</span> <span class="pre">replace<idx>(</span> <span class="pre">r.release()</span> <span class="pre">);</span></tt></li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">auto_type</span> <span class="pre">replace(</span> <span class="pre">size_t</span> <span class="pre">idx,</span> <span class="pre">T*</span> <span class="pre">r</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: `` x != 0 and idx < size()``</li> +<li>Effects: returns the object indexed by <tt class="docutils literal"><span class="pre">idx</span></tt> and replaces it with <tt class="docutils literal"><span class="pre">x</span></tt>.</li> +<li>Throws: <tt class="docutils literal"><span class="pre">bad_index</span></tt> if <tt class="docutils literal"><span class="pre">idx</span> <span class="pre">>=</span> <span class="pre">size()</span></tt> and <tt class="docutils literal"><span class="pre">bad_pointer</span></tt> if <tt class="docutils literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">0</span></tt>.</li> +<li>Exception safety: Strong guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">U</span> <span class="pre">></span> <span class="pre">auto_type</span> <span class="pre">replace(</span> <span class="pre">size_t</span> <span class="pre">idx,</span> <span class="pre">std::auto_ptr<U></span> <span class="pre">r</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: <tt class="docutils literal"><span class="pre">return</span> <span class="pre">replace(</span> <span class="pre">idx,</span> <span class="pre">r.release()</span> <span class="pre">);</span></tt></li> +</ul> +</blockquote> +</li> +</ul> +</div> +<div class="section"> +<h2><a id="semantics-pointer-container-requirements" name="semantics-pointer-container-requirements"><span id="pointer-container-requirements"></span>Semantics: pointer container requirements</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">std::auto_ptr<ptr_array></span> <span class="pre">clone()</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Returns a deep copy of the container</li> +<li>Throws: <tt class="docutils literal"><span class="pre">std::bad_alloc</span></tt> if there is not enough memory to make a clone of the container</li> +<li>Complexity: Linear</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">std::auto_ptr<ptr_array></span> <span class="pre">release();</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Releases ownership of the container. This is a useful way of returning a container from a function.</li> +<li>Postconditions: <tt class="docutils literal"><span class="pre">empty()</span> <span class="pre">==</span> <span class="pre">true</span></tt> and all pointers are null</li> +<li>Throws: <tt class="docutils literal"><span class="pre">std::bad_alloc</span></tt> if the return value cannot be allocated</li> +<li>Exception safety: Strong guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">size_t</span> <span class="pre">idx</span> <span class="pre">></span> <span class="pre">bool</span> <span class="pre">is_null()</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">idx</span> <span class="pre"><</span> <span class="pre">size()</span></tt> (compile-time enforced)</li> +<li>Effects: returns whether the pointer at index <tt class="docutils literal"><span class="pre">idx</span></tt> is null</li> +<li>Exception safety: Nothrow guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">is_null(</span> <span class="pre">size_type</span> <span class="pre">idx</span> <span class="pre">)</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">idx</span> <span class="pre"><</span> <span class="pre">size()</span></tt></li> +<li>Effects: returns whether the pointer at index <tt class="docutils literal"><span class="pre">idx</span></tt> is null</li> +<li>Exception safety: Nothrow guarantee</li> +</ul> +</blockquote> +</li> +</ul> +<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> +</div> +</body> +</html> diff --git a/libs/ptr_container/doc/ptr_array.rst b/libs/ptr_container/doc/ptr_array.rst new file mode 100644 index 0000000000..ff288f2316 --- /dev/null +++ b/libs/ptr_container/doc/ptr_array.rst @@ -0,0 +1,290 @@ +++++++++++++++++++++++++++++++++++ + |Boost| Pointer Container Library +++++++++++++++++++++++++++++++++++ + +.. |Boost| image:: boost.png + +Class ``ptr_array`` +------------------- + +A ``ptr_array<T,size>`` is a pointer container that uses an underlying ``boost::array<void*,size>`` +to store the pointers. The class is useful when there is no requirement +of dynamic expansion and when no overhead is tolerable. + +**Hierarchy:** + +- `reversible_ptr_container <reversible_ptr_container.html>`_ + + - `ptr_sequence_adapter <ptr_sequence_adapter.html>`_ + + - `ptr_vector <ptr_vector.html>`_ + - `ptr_list <ptr_list.html>`_ + - `ptr_deque <ptr_deque.html>`_ + - ``ptr_array`` + +**Navigate:** + +- `home <ptr_container.html>`_ +- `reference <reference.html>`_ + + + +**Synopsis:** + +.. parsed-literal:: + + namespace boost + { + + template + < + class T, + size_t N, + CloneAllocator = heap_clone_allocator + > + class ptr_array : public *implementation-defined* + { + public: // `construct/copy/destroy`_ + ptr_array(); + explicit ptr_array( const ptr_array& r ); + template< class U > + explicit ptr_array( const ptr_array<U,N>& r ); + explicit ptr_array( std::auto_ptr<ptr_array>& r ); + + ptr_array& operator=( const ptr_array& r ); + template< class U > + ptr_array& operator=( const ptr_array<U,N>& r ); + ptr_array& operator=( std::auto_ptr<this_type> r ); + + public: // `iterators`_ + + public: // `capacity`_ + + public: // `element access`_ + T& front(); + const T& front() const; + T& back(); + const T& back() const; + + template< size_t idx > + T& at(); + template< size_t idx > + const T& at() const; + T& at( size_t ); + const T& at( size_t ); + + T& operator[]( size_t ); + const T& operator[]( size_t ) const; + + public: // `modifiers`_ + void swap( ptr_array& r ); + + template< size_t idx > + auto_type replace( T* r ); + template< size_t idx, class U > + auto_type replace( std::auto_ptr<U> r ); + auto_type replace( size_t idx, T* r ); + template< class U > + auto_type replace( size_t idx, std::auto_ptr<U> r ); + + public: // `pointer container requirements`_ + std::auto_ptr<ptr_array> clone() const; + std::auto_ptr<ptr_array> release(); + template< size_t idx > + bool is_null() const; + bool is_null( size_t idx ) const; + + }; // class 'ptr_sequence_adapter' + + } // namespace 'boost' + +.. _iterators: reversible_ptr_container.html#iterators + +.. _capacity: reversible_ptr_container.html#capacity + +.. _`inherited element access`: reversible_ptr_container.html#element-access + +Semantics +--------- + +.. _`construct/copy/destroy`: + +Semantics: construct/copy/destroy +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``ptr_array();`` + + - Effects: constructs array where each element is null + +- ``explicit ptr_array( const ptr_array& r );`` +- ``template< class U > + explicit ptr_array( const ptr_array<U,N>& r );`` + + - Effects: Constructs array by cloning ``r`` + +- ``ptr_array( std::auto_ptr<ptr_array>& r );`` + + - Effects: take ownership of the supplied pointers + +- ``ptr_array& operator=( const ptr_array& r );`` + +- ``template< class U > ptr_array& operator=( const ptr_array<U,N>& r );`` + + - Effects: Assigns a clone of ``r`` + + - Exception safety: Strong guarantee + +- ``ptr_array& operator=( std::auto_ptr<this_type> r );`` + + - Effects: take ownership of the supplied pointers + + - Throws: Nothing + +.. _`element access`: + +Semantics: element access +^^^^^^^^^^^^^^^^^^^^^^^^^ + + +- ``T& front();`` +- ``const T& front() const;`` + + - Requirements: ``not empty();`` + + - Effects: ``return *begin();`` + + - Throws: ``bad_ptr_container_operation`` if ``empty() == true`` + + +- ``T& back();`` +- ``const T& back() const;`` + + - Requirements: ``not empty();`` + + - Effects: ``return *--end();`` + + - Throws: ``bad_ptr_container_operation`` if ``empty() == true`` + +- ``template< size_t idx > T& at( size_type n );`` +- ``template< size_t idx > const T& at( size_type n ) const;`` + + - Requirements: ``idx < size()`` (compile-time enforced) + + - Effects: Returns a reference to the ``n``'th element + + - Throws: nothing + +- ``T& at( size_type n );`` +- ``const T& at( size_type n ) const;`` + + - Requirements: ``n < size()`` + + - Effects: Returns a reference to the ``n``'th element + + - Throws: ``bad_index`` if ``n >=size()`` + + +- ``T& operator[]( size_type n );`` +- ``const T& operator[]( size_type n ) const;`` + + - Requirements: ``n < size()`` + + - Effects: Returns a reference to the ``n``'th element + + - Throws: Nothing + + +.. _`modifiers`: + +Semantics: modifiers +^^^^^^^^^^^^^^^^^^^^ + +- ``void swap( ptr_array& r );`` + + - Effects: swaps the two arrays + + - Complexity: Linear + + - Throws: nothing + +- ``template< size_t idx > auto_type replace( T* r );`` + + - Requirements: + + - ``idx < size()`` (compile-time enforced) + - ``r != 0`` + + - Effects: returns the object indexed by ``idx`` and replaces it with ``r``. + + - Throws: ``bad_pointer`` if ``x == 0``. + + - Exception safety: Strong guarantee + +- ``template< size_t idx, class U > auto_type replace( std::auto_ptr<U> r );`` + + - Effects: ``return replace<idx>( r.release() );`` + +- ``auto_type replace( size_t idx, T* r );`` + + - Requirements: `` x != 0 and idx < size()`` + + - Effects: returns the object indexed by ``idx`` and replaces it with ``x``. + + - Throws: ``bad_index`` if ``idx >= size()`` and ``bad_pointer`` if ``x == 0``. + + - Exception safety: Strong guarantee + +- ``template< class U > auto_type replace( size_t idx, std::auto_ptr<U> r );`` + + - Effects: ``return replace( idx, r.release() );`` + +.. _`pointer container requirements`: + +Semantics: pointer container requirements +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``std::auto_ptr<ptr_array> clone() const;`` + + - Effects: Returns a deep copy of the container + + - Throws: ``std::bad_alloc`` if there is not enough memory to make a clone of the container + + - Complexity: Linear + + +- ``std::auto_ptr<ptr_array> release();`` + + - Effects: Releases ownership of the container. This is a useful way of returning a container from a function. + + - Postconditions: ``empty() == true`` and all pointers are null + + - Throws: ``std::bad_alloc`` if the return value cannot be allocated + + - Exception safety: Strong guarantee + + +- ``template< size_t idx > bool is_null() const;`` + + - Requirements: ``idx < size()`` (compile-time enforced) + + - Effects: returns whether the pointer at index ``idx`` is null + + - Exception safety: Nothrow guarantee + +- ``bool is_null( size_type idx ) const;`` + + - Requirements: ``idx < size()`` + + - Effects: returns whether the pointer at index ``idx`` is null + + - Exception safety: Nothrow guarantee + +.. raw:: html + + <hr> + +:Copyright: Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). + +__ http://www.boost.org/LICENSE_1_0.txt + + diff --git a/libs/ptr_container/doc/ptr_container.html b/libs/ptr_container/doc/ptr_container.html new file mode 100644 index 0000000000..50b60977a2 --- /dev/null +++ b/libs/ptr_container/doc/ptr_container.html @@ -0,0 +1,643 @@ +<?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="27th of October 2007" /> +<meta name="copyright" content="Thorsten Ottosen 2004-2007. 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: 2008-07-16 17:03:47 -0400 (Wed, 16 Jul 2008) $ +:Revision: $Revision: 47494 $ +: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@cs.aau.dk">nesotto@cs.aau.dk</a> or <a class="last reference" href="mailto:tottosen@dezide.com">tottosen@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>27th of October 2007</td></tr> +<tr><th class="docinfo-name">Copyright:</th> +<td>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></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="#upgrading-from-boost-v-1-34">Upgrading from Boost v. 1.34.*</a></li> +<li><a class="reference" href="#upgrading-from-boost-v-1-35">Upgrading from Boost v. 1.35.*</a></li> +<li><a class="reference" href="#future-developments">Future Developments</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 such that 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 Clonable 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<std::string,T>::iterator i = m.begin(), e = m.end(); + i != e; ++i ) +{ + std::cout << "key:" << i.key(); + std::cout << "value:" << *i; + i->foo(); // call T::foo() +} +</pre> +<p>and this now needs to be converted into</p> +<pre class="literal-block"> +for( boost::ptr_map<std::string,T>::iterator i = m.begin(), e = m.end(); + i != e; ++i ) +{ + std::cout << "key:" << i->first; + std::cout << "value:" << *i->second; + i->second->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<T></span></tt> overloads:</p> +<pre class="literal-block"> +std::auto_ptr<T> 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<Base> vec; +boost::ptr_list<Derived> 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="upgrading-from-boost-v-1-34" name="upgrading-from-boost-v-1-34">Upgrading from Boost v. <tt class="docutils literal"><span class="pre">1.34.*</span></tt></a></h1> +<p>Serialization has now been made optional thanks to Sebastian Ramacher. +You simply include <tt class="docutils literal"><span class="pre"><boost/ptr_container/serialize.hpp></span></tt> or perhaps +just one of the more specialized headers.</p> +<p>All containers are now copy-constructible and assignable. So you can e.g. now +do:</p> +<pre class="literal-block"> +boost::ptr_vector<Derived> derived = ...; +boost::ptr_vector<Base> base( derived ); +base = derived; +</pre> +<p>As the example shows, derived-to-base class conversions are also allowed.</p> +<p>A few general functions have been added:</p> +<pre class="literal-block"> +VoidPtrContainer& base(); +const VoidPtrContainer& base() const; +</pre> +<p>These allow direct access to the wrapped container which is +sometimes needed when you want to provide extra functionality.</p> +<p>A few new functions have been added to sequences:</p> +<pre class="literal-block"> +void resize( size_type size ); +void resize( size_type size, T* to_clone ); +</pre> +<p><tt class="docutils literal"><span class="pre">ptr_vector<T></span></tt> has a few new helper functions to integrate better with C-arrays:</p> +<pre class="literal-block"> +void transfer( iterator before, T** from, size_type size, bool delete_from = true ); +T** c_array(); +</pre> +<p>Finally, you can now also "copy" and "assign" an <tt class="docutils literal"><span class="pre">auto_type</span></tt> ptr by calling <tt class="docutils literal"><span class="pre">move()</span></tt>:</p> +<pre class="literal-block"> +boost::ptr_vector<T>::auto_type move_ptr = ...; +return boost::ptr_container::move( move_ptr ); +</pre> +</div> +<div class="section"> +<h1><a id="upgrading-from-boost-v-1-35" name="upgrading-from-boost-v-1-35">Upgrading from Boost v. <tt class="docutils literal"><span class="pre">1.35.*</span></tt></a></h1> +<p>The library has been fairly stable, but a few new containers have been supported:</p> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">boost::ptr_unordered_set<T></span></tt> in <tt class="docutils literal"><span class="pre"><boost/ptr_container/ptr_unordered_set.hpp></span></tt></li> +<li><tt class="docutils literal"><span class="pre">boost::ptr_unordered_map<Key,T></span></tt> in <tt class="docutils literal"><span class="pre"><boost/ptr_container/ptr_unordered_map.hpp></span></tt></li> +<li><tt class="docutils literal"><span class="pre">boost::ptr_circular_buffer<T></span></tt> in <tt class="docutils literal"><span class="pre"><boost/ptr_container/ptr_circular_buffer.hpp></span></tt></li> +</ul> +<p>There are no docs for these classes yet, but they are almost identical to +<tt class="docutils literal"><span class="pre">boost::ptr_set<T></span></tt>, <tt class="docutils literal"><span class="pre">boost::ptr_map<Key,T></span></tt> and <tt class="docutils literal"><span class="pre">boost::ptr_array<T,N></span></tt>, respectively. +The underlying containers stem from the two boost libraries</p> +<ul class="simple"> +<li><a class="reference" href="../../unordered/index.html">Boost.Unordered</a></li> +<li><a class="reference" href="../../circular_buffer/index.html">Boost.Circular Buffer</a></li> +</ul> +<p>Furthermore, <a class="reference" href="ptr_inserter.html">insert iterators</a> have been added.</p> +</div> +<div class="section"> +<h1><a id="future-developments" name="future-developments">Future Developments</a></h1> +<p>There are indications that the <tt class="docutils literal"><span class="pre">void*</span></tt> implementation has a slight +performance overhead compared to a <tt class="docutils literal"><span class="pre">T*</span></tt> based implementation. Furthermore, a +<tt class="docutils literal"><span class="pre">T*</span></tt> based implementation is so much easier to use type-safely +with algorithms. Therefore I anticipate to move to a <tt class="docutils literal"><span class="pre">T*</span></tt> based implementation.</p> +<p>Furthermore, the clone allocator might be allowed to have state. +This design requires some thought, so if you have good ideas and use-cases' +for this, please don't hesitate to contact me.</p> +<p>Also, support for Boost.Interprocess is on the todo list.</p> +<p>There has been a few request for <tt class="docutils literal"><span class="pre">boost::ptr_multi_index_container<T,...></span></tt>. +I investigated how difficult it would be, and it did turn out to be difficult, albeit +not impossible. But I don't have the resources to implement this beast +for years to come, so if someone really needs this container, I suggest that they +talk with me in private about how it can be done.</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> +<li>Charles Brockman for his many comments on the documentation</li> +<li>Sebastian Ramacher for implementing the optional serialization support</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/">"The Standard Librarian: Containers of Pointers"</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, "The C++ Programming Language", <a class="reference" href="http://www.research.att.com/~bs/3rd_safe.pdf">Appendix E: "Standard-Library Exception Safety"</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, "Exceptional C++".</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, "More Exceptional C++".</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">"From Mechanism to Method: The Safe Stacking of Cats"</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, "A remove_if for vector", 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> diff --git a/libs/ptr_container/doc/ptr_container.rst b/libs/ptr_container/doc/ptr_container.rst new file mode 100644 index 0000000000..73370e1b89 --- /dev/null +++ b/libs/ptr_container/doc/ptr_container.rst @@ -0,0 +1,349 @@ + +++++++++++++++++++++++++++++++++++ + |Boost| Pointer Container Library +++++++++++++++++++++++++++++++++++ + +.. |Boost| image:: boost.png + + + +:Authors: Thorsten Ottosen +:Contact: nesotto@cs.aau.dk or tottosen@dezide.com +:Organizations: `Department of Computer Science`_, Aalborg University, and `Dezide Aps`_ +:date: 27th of October 2007 +:Copyright: Thorsten Ottosen 2004-2007. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). + +__ http://www.boost.org/LICENSE_1_0.txt + +.. _`Department of Computer Science`: http://www.cs.aau.dk +.. _`Dezide Aps`: http://www.dezide.com + +======== +Overview +======== + +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 + +* Motivation_ +* Tutorial_ +* Reference_ +* `Usage guidelines`_ +* Examples_ +* `Library headers`_ +* FAQ_ +* `Upgrading from Boost v. 1.33.*`_ +* `Upgrading from Boost v. 1.34.*`_ +* `Upgrading from Boost v. 1.35.*`_ +* `Future Developments`_ +* Acknowledgements_ +* References_ + +.. + - `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>`_ + + + +.. _Tutorial: tutorial.html + + +.. _Reference: reference.html + +.. _`Usage guidelines`: guidelines.html + +.. _Examples: examples.html + +.. _`Library headers`: headers.html + +.. _FAQ: faq.html + + +========== +Motivation +========== + +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 `boost::shared_ptr <../../smart_ptr/shared_ptr.htm>`_ +This approach is suboptimal if + +1. the stored objects are not shared, but owned exclusively, or + +.. + +2. the overhead implied by smart pointers is inappropriate + +This library therefore provides standard-like containers that are for storing +heap-allocated or `cloned <reference.html#the-clonable-concept>`_ 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 +`polymorphic class problem <faq.html#what-is-the-polymorphic-class-problem>`_. + + +The advantages of pointer containers are + +1. Exception-safe pointer storage and manipulation. + +.. + +2. Notational convenience compared to the use of containers of pointers. + +.. + +3. Can be used for types that are neither Assignable nor Copy Constructible. + +.. + +4. No memory-overhead as containers of smart pointers can have (see [11]_ and [12]_). + +.. + +5. Usually faster than using containers of smart pointers (see [11]_ and [12]_). + +.. + +6. 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 ``pop_back()`` to return the removed element. + +.. + +7. Propagates constness such that one cannot modify the objects via a ``const_iterator``. + +.. + +8. Built-in support for deep-copy semantics via the `the Clonable concept`__ + +.. __: reference.html#the-clonable-concept + +The disadvantages are + +1. Less flexible than containers of smart pointers like `boost::shared_ptr <../../smart_ptr/shared_ptr.htm>`_ + +When you do need shared semantics, this library is not what you need. + +==================================== + Upgrading from Boost v. ``1.33.*`` +==================================== + +If you upgrade from one of these versions of Boost, then there has been one +major interface change: map iterators now mimic iterators from ``std::map``. +Previously you may have written :: + + for( boost::ptr_map<std::string,T>::iterator i = m.begin(), e = m.end(); + i != e; ++i ) + { + std::cout << "key:" << i.key(); + std::cout << "value:" << *i; + i->foo(); // call T::foo() + } + +and this now needs to be converted into :: + + for( boost::ptr_map<std::string,T>::iterator i = m.begin(), e = m.end(); + i != e; ++i ) + { + std::cout << "key:" << i->first; + std::cout << "value:" << *i->second; + i->second->foo(); // call T::foo() + } + +Apart from the above change, the library now also introduces + +- ``std::auto_ptr<T>`` overloads:: + + std::auto_ptr<T> p( new T ); + container.push_back( p ); + +- Derived-to-Base conversion in ``transfer()``:: + + boost::ptr_vector<Base> vec; + boost::ptr_list<Derived> list; + ... + vec.transfer( vec.begin(), list ); // now ok + +Also note that `Boost.Assign <../../assign/index.html>`_ introduces better support +for pointer containers. + +==================================== + Upgrading from Boost v. ``1.34.*`` +==================================== + +Serialization has now been made optional thanks to Sebastian Ramacher. +You simply include ``<boost/ptr_container/serialize.hpp>`` or perhaps +just one of the more specialized headers. + +All containers are now copy-constructible and assignable. So you can e.g. now +do:: + + boost::ptr_vector<Derived> derived = ...; + boost::ptr_vector<Base> base( derived ); + base = derived; + +As the example shows, derived-to-base class conversions are also allowed. + +A few general functions have been added:: + + VoidPtrContainer& base(); + const VoidPtrContainer& base() const; + +These allow direct access to the wrapped container which is +sometimes needed when you want to provide extra functionality. + +A few new functions have been added to sequences:: + + void resize( size_type size ); + void resize( size_type size, T* to_clone ); + +``ptr_vector<T>`` has a few new helper functions to integrate better with C-arrays:: + + void transfer( iterator before, T** from, size_type size, bool delete_from = true ); + T** c_array(); + +Finally, you can now also "copy" and "assign" an ``auto_type`` ptr by calling ``move()``:: + + boost::ptr_vector<T>::auto_type move_ptr = ...; + return boost::ptr_container::move( move_ptr ); + +==================================== + Upgrading from Boost v. ``1.35.*`` +==================================== + +The library has been fairly stable, but a few new containers have been supported: + +- ``boost::ptr_unordered_set<T>`` in ``<boost/ptr_container/ptr_unordered_set.hpp>`` + +- ``boost::ptr_unordered_map<Key,T>`` in ``<boost/ptr_container/ptr_unordered_map.hpp>`` + +- ``boost::ptr_circular_buffer<T>`` in ``<boost/ptr_container/ptr_circular_buffer.hpp>`` + +There are no docs for these classes yet, but they are almost identical to +``boost::ptr_set<T>``, ``boost::ptr_map<Key,T>`` and ``boost::ptr_array<T,N>``, respectively. +The underlying containers stem from the two boost libraries + +- `Boost.Unordered <../../unordered/index.html>`_ + +- `Boost.Circular Buffer <../../circular_buffer/index.html>`_ + +Furthermore, `insert iterators <ptr_inserter.html>`_ have been added. + +===================== + Future Developments +===================== + +There are indications that the ``void*`` implementation has a slight +performance overhead compared to a ``T*`` based implementation. Furthermore, a +``T*`` based implementation is so much easier to use type-safely +with algorithms. Therefore I anticipate to move to a ``T*`` based implementation. + +Furthermore, the clone allocator might be allowed to have state. +This design requires some thought, so if you have good ideas and use-cases' +for this, please don't hesitate to contact me. + +Also, support for Boost.Interprocess is on the todo list. + +There has been a few request for ``boost::ptr_multi_index_container<T,...>``. +I investigated how difficult it would be, and it did turn out to be difficult, albeit +not impossible. But I don't have the resources to implement this beast +for years to come, so if someone really needs this container, I suggest that they +talk with me in private about how it can be done. + +================ +Acknowledgements +================ + +The following people have been very helpful: + +- Bjørn D. Rasmussen for unintentionally motivating me to start this library +- Pavel Vozenilek for asking me to make the adapters +- David Abrahams for the ``indirect_fun`` design +- Pavol Droba for being review manager +- Ross Boylan for trying out a prototype for real +- Felipe Magno de Almeida for giving fedback based on using the + library in production code even before the library was part of boost +- Jonathan Turkanis for supplying his ``move_ptr`` framework + which is used internally +- Stefan Slapeta and Howard Hinnant for Metrowerks support +- Russell Hind for help with Borland compatibility +- Jonathan Wakely for his great help with GCC compatibility and bug fixes +- Pavel Chikulaev for comments and bug-fixes +- Andreas Hommel for fixing the nasty Metrowerks bug +- Charles Brockman for his many comments on the documentation +- Sebastian Ramacher for implementing the optional serialization support + +========== +References +========== + +.. [1] Matt Austern: `"The Standard Librarian: Containers of Pointers"`__ , C/C++ Users Journal Experts Forum. + +__ http://www.cuj.com/documents/s=7990/cujcexp1910austern/ + +.. [2] Bjarne Stroustrup, "The C++ Programming Language", `Appendix E: "Standard-Library Exception Safety"`__ + +__ http://www.research.att.com/~bs/3rd_safe.pdf + +.. [3] Herb Sutter, "Exceptional C++". +.. [4] Herb Sutter, "More Exceptional C++". +.. [5] Kevlin Henney: `"From Mechanism to Method: The Safe Stacking of Cats"`__ , C++ Experts Forum, February 2002. + +__ http://www.cuj.com/documents/s=7986/cujcexp2002henney/henney.htm + +.. [6] Some of the few earlier attempts of pointer containers I have seen are the rather interesting NTL_ and the + pointainer_. + As of this writing both libraries are not exceptions-safe and can leak. + +.. [7] INTERNATIONAL STANDARD, Programming languages --- C++, ISO/IEC 14882, 1998. See section 23 in particular. +.. [8] C++ Standard Library Closed Issues List (Revision 27), + Item 218, `Algorithms do not use binary predicate objects for default comparisons`__. + +__ http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-closed.html#218 + +.. [9] C++ Standard Library Active Issues List (Revision 27), + Item 226, `User supplied specializations or overloads of namespace std function templates`__. + +__ http://gcc.gnu.org/onlinedocs/libstdc++/ext/lwg-active.html#226 + +.. [10] Harald Nowak, "A remove_if for vector", C/C++ Users Journal, July 2001. +.. [11] Boost smart pointer timings__ + +__ http://www.boost.org/libs/smart_ptr/smarttests.htm + +.. [12] NTL_: Array vs std::vector and boost::shared_ptr +.. [13] Kevlin Henney, `Null Object`__, 2002. + +__ http://www.two-sdg.demon.co.uk/curbralan/papers/europlop/NullObject.pdf + +.. _NTL: http://www.ntllib.org/asp.html +.. _pointainer: http://ootips.org/yonat/4dev/pointainer.h + + +.. raw:: html + + <hr> + +:Copyright: Thorsten Ottosen 2004-2006. + diff --git a/libs/ptr_container/doc/ptr_container.xml b/libs/ptr_container/doc/ptr_container.xml new file mode 100644 index 0000000000..fb6eb4255c --- /dev/null +++ b/libs/ptr_container/doc/ptr_container.xml @@ -0,0 +1,55 @@ +<!-- +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// +--> +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" +"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> +<boostbook xmlns:xi="http://www.w3.org/2001/XInclude" + last-revision="$Date: 2008-02-07 03:44:10 -0500 (Thu, 07 Feb 2008) $"> +<library name="Pointer Container" dirname="ptr_container" xmlns:xi="http://www.w3.org/2001/XInclude" + id="ptr_container" last-revision="$Date: 2008-02-07 03:44:10 -0500 (Thu, 07 Feb 2008) $"> + <libraryinfo> + <author> + <firstname>Thorsten</firstname> + <surname>Ottosen</surname> + </author> + + <copyright> + <year>2003</year> + <holder>Thorsten Ottosen</holder> + </copyright> + + <legalnotice> + <para>Permission to copy, use, sell and distribute this software + is granted provided this copyright notice appears in all copies. + Permission to modify the code and to distribute modified code is + granted provided this copyright notice appears in all copies, and + a notice that the code was modified is included with the copyright + notice. </para> + + <para> This software is provided "as is" without express or + implied warranty, and with no claim as to its suitability for any + purpose. </para> + </legalnotice> + + <librarypurpose> + This library provides standard-like containers that are suitable + for storing pointers to both polymorphic and non-polymorphic objects. + </librarypurpose> + <librarycategory name="category:containers"/> + </libraryinfo> + + <title>Boost Pointer Container Library</title> + <xi:include href="intro.xml"/> +</library> +</boostbook> + diff --git a/libs/ptr_container/doc/ptr_deque.html b/libs/ptr_container/doc/ptr_deque.html new file mode 100644 index 0000000000..334ee451c4 --- /dev/null +++ b/libs/ptr_container/doc/ptr_deque.html @@ -0,0 +1,467 @@ +<?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: 2006-11-22 17:01:03 -0500 (Wed, 22 Nov 2006) $ +:Revision: $Revision: 36152 $ +: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> +<div class="section"> +<h1><a id="class-ptr-deque" name="class-ptr-deque">Class <tt class="docutils literal"><span class="pre">ptr_deque</span></tt></a></h1> +<p>A <tt class="docutils literal"><span class="pre">ptr_deque<T></span></tt> is a pointer container that uses an underlying <tt class="docutils literal"><span class="pre">std:deque<void*></span></tt> +to store the pointers.</p> +<p><strong>Hierarchy:</strong></p> +<ul class="simple"> +<li><a class="reference" href="reversible_ptr_container.html">reversible_ptr_container</a><ul> +<li><a class="reference" href="ptr_sequence_adapter.html">ptr_sequence_adapter</a><ul> +<li><a class="reference" href="ptr_vector.html">ptr_vector</a></li> +<li><a class="reference" href="ptr_list.html">ptr_list</a></li> +<li><tt class="docutils literal"><span class="pre">ptr_deque</span></tt></li> +<li><a class="reference" href="ptr_array.html">ptr_array</a></li> +</ul> +</li> +</ul> +</li> +</ul> +<p><strong>Navigate:</strong></p> +<ul class="simple"> +<li><a class="reference" href="ptr_container.html">home</a></li> +<li><a class="reference" href="reference.html">reference</a></li> +</ul> +<p><strong>Synopsis:</strong></p> +<pre class="literal-block"> +namespace boost +{ + + template + < + class T, + class CloneAllocator = heap_clone_allocator + class Allocator = std::allocator<void*> + > + class ptr_deque : public ptr_sequence_adapter + < + T, + std::deque<void*,Allocator>, + CloneAllocator + > + { + + public: // <a class="reference" href="#element-access">element access</a> + T& operator[]( size_type n ); + const T& operator[]( size_type n ) const; + T& at( size_type n ); + const T& at( size_type n ) const; + + public: // <a class="reference" href="#modifiers">modifiers</a> + void push_front( T* x ); + template< class U > + void push_front( std::auto_ptr<U> x ); + auto_type pop_front(); + + public: // <a class="reference" href="#pointer-container-requirements">pointer container requirements</a> + auto_type replace( size_type idx, T* x ); + template< class U > + auto_type replace( size_type idx, std::auto_ptr<U> x ); + bool is_null( size_type idx ) const; + + }; + +} // namespace 'boost' +</pre> +</div> +<div class="section"> +<h1><a id="semantics" name="semantics">Semantics</a></h1> +<div class="section"> +<h2><a id="semantics-modifiers" name="semantics-modifiers"><span id="modifiers"></span>Semantics: modifiers</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">push_front(</span> <span class="pre">T*</span> <span class="pre">x</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">x</span> <span class="pre">!=</span> <span class="pre">0</span></tt></li> +<li>Effects: Inserts the pointer into container and takes ownership of it</li> +<li>Throws: <tt class="docutils literal"><span class="pre">bad_pointer</span></tt> if <tt class="docutils literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">0</span></tt></li> +<li>Exception safety: Strong guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">U</span> <span class="pre">></span> <span class="pre">void</span> <span class="pre">push_front(</span> <span class="pre">std::auto_ptr<U></span> <span class="pre">x</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: <tt class="docutils literal"><span class="pre">push_front(</span> <span class="pre">x.release()</span> <span class="pre">);</span></tt></li> +</ul> +</blockquote> +</li> +</ul> +<!-- - ``void push_front( const T& x );`` + +- Effects: push_front( allocate_clone( x ) ); + +- Exception safety: Strong guarantee --> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">auto_type</span> <span class="pre">pop_front():</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements:<tt class="docutils literal"><span class="pre">not</span> <span class="pre">empty()</span></tt></li> +<li>Effects: Removes the first element in the container</li> +<li>Postconditions: <tt class="docutils literal"><span class="pre">size()</span></tt> is one less</li> +<li>Throws: <tt class="docutils literal"><span class="pre">bad_ptr_container_operation</span></tt> if <tt class="docutils literal"><span class="pre">empty()</span> <span class="pre">==</span> <span class="pre">true</span></tt></li> +<li>Exception safety: Strong guarantee</li> +</ul> +</blockquote> +</li> +</ul> +</div> +<div class="section"> +<h2><a id="semantics-element-access" name="semantics-element-access"><span id="element-access"></span>Semantics: element access</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">T&</span> <span class="pre">operator[](</span> <span class="pre">size_type</span> <span class="pre">n</span> <span class="pre">);</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">const</span> <span class="pre">T&</span> <span class="pre">operator[](</span> <span class="pre">size_type</span> <span class="pre">n</span> <span class="pre">)</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">n</span> <span class="pre"><</span> <span class="pre">size()</span></tt></li> +<li>Effects: Returns a reference to the <tt class="docutils literal"><span class="pre">n</span></tt>'th element</li> +<li>Throws: Nothing</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">T&</span> <span class="pre">at(</span> <span class="pre">size_type</span> <span class="pre">n</span> <span class="pre">);</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">const</span> <span class="pre">T&</span> <span class="pre">at(</span> <span class="pre">size_type</span> <span class="pre">n</span> <span class="pre">)</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">n</span> <span class="pre"><</span> <span class="pre">size()</span></tt></li> +<li>Effects: Returns a reference to the <tt class="docutils literal"><span class="pre">n</span></tt>'th element</li> +<li>Throws: <tt class="docutils literal"><span class="pre">bad_index</span></tt> if <tt class="docutils literal"><span class="pre">n</span> <span class="pre">>=size()</span></tt></li> +</ul> +</blockquote> +</li> +</ul> +</div> +<div class="section"> +<h2><a id="semantics-pointer-container-requirements" name="semantics-pointer-container-requirements"><span id="pointer-container-requirements"></span>Semantics: pointer container requirements</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">auto_type</span> <span class="pre">replace(</span> <span class="pre">size_type</span> <span class="pre">idx,</span> <span class="pre">T*</span> <span class="pre">x</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: `` x != 0 and idx < size()``</li> +<li>Effects: returns the object indexed by <tt class="docutils literal"><span class="pre">idx</span></tt> and replaces it with <tt class="docutils literal"><span class="pre">x</span></tt>.</li> +<li>Throws: <tt class="docutils literal"><span class="pre">bad_index</span></tt> if <tt class="docutils literal"><span class="pre">idx</span> <span class="pre">>=</span> <span class="pre">size()</span></tt> and <tt class="docutils literal"><span class="pre">bad_pointer</span></tt> if <tt class="docutils literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">0</span></tt>.</li> +<li>Exception safety: Strong guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">U</span> <span class="pre">></span> <span class="pre">auto_type</span> <span class="pre">replace(</span> <span class="pre">size_type</span> <span class="pre">idx,</span> <span class="pre">std::auto_ptr<U></span> <span class="pre">x</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: <tt class="docutils literal"><span class="pre">return</span> <span class="pre">replace(</span> <span class="pre">idx,</span> <span class="pre">x.release()</span> <span class="pre">);</span></tt></li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">is_null(</span> <span class="pre">size_type</span> <span class="pre">idx</span> <span class="pre">)</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">idx</span> <span class="pre"><</span> <span class="pre">size()</span></tt></li> +<li>Effects: returns whether the pointer at index <tt class="docutils literal"><span class="pre">idx</span></tt> is null</li> +<li>Exception safety: Nothrow guarantee</li> +</ul> +</blockquote> +</li> +</ul> +<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> +</div> +</body> +</html> diff --git a/libs/ptr_container/doc/ptr_deque.rst b/libs/ptr_container/doc/ptr_deque.rst new file mode 100644 index 0000000000..7d0b7364b9 --- /dev/null +++ b/libs/ptr_container/doc/ptr_deque.rst @@ -0,0 +1,179 @@ +++++++++++++++++++++++++++++++++++ + |Boost| Pointer Container Library +++++++++++++++++++++++++++++++++++ + +.. |Boost| image:: boost.png + +Class ``ptr_deque`` +-------------------- + +A ``ptr_deque<T>`` is a pointer container that uses an underlying ``std:deque<void*>`` +to store the pointers. + +**Hierarchy:** + +- `reversible_ptr_container <reversible_ptr_container.html>`_ + + - `ptr_sequence_adapter <ptr_sequence_adapter.html>`_ + + - `ptr_vector <ptr_vector.html>`_ + - `ptr_list <ptr_list.html>`_ + - ``ptr_deque`` + - `ptr_array <ptr_array.html>`_ + +**Navigate:** + +- `home <ptr_container.html>`_ +- `reference <reference.html>`_ + + +**Synopsis:** + +.. parsed-literal:: + + namespace boost + { + + template + < + class T, + class CloneAllocator = heap_clone_allocator + class Allocator = std::allocator<void*> + > + class ptr_deque : public ptr_sequence_adapter + < + T, + std::deque<void*,Allocator>, + CloneAllocator + > + { + + public: // `element access`_ + T& operator[]( size_type n ); + const T& operator[]( size_type n ) const; + T& at( size_type n ); + const T& at( size_type n ) const; + + public: // modifiers_ + void push_front( T* x ); + template< class U > + void push_front( std::auto_ptr<U> x ); + auto_type pop_front(); + + public: // `pointer container requirements`_ + auto_type replace( size_type idx, T* x ); + template< class U > + auto_type replace( size_type idx, std::auto_ptr<U> x ); + bool is_null( size_type idx ) const; + + }; + + } // namespace 'boost' + + +.. _`reversible_ptr_container`: reversible_ptr_container.html + +.. _`ptr_sequence_adapter`: ptr_sequence_adapter.html + +Semantics +--------- + +.. _modifiers: + +Semantics: modifiers +^^^^^^^^^^^^^^^^^^^^ + +- ``void push_front( T* x );`` + + - Requirements: ``x != 0`` + + - Effects: Inserts the pointer into container and takes ownership of it + + - Throws: ``bad_pointer`` if ``x == 0`` + + - Exception safety: Strong guarantee + +- ``template< class U > void push_front( std::auto_ptr<U> x );`` + + - Effects: ``push_front( x.release() );`` + +.. + - ``void push_front( const T& x );`` + + - Effects: push_front( allocate_clone( x ) ); + + - Exception safety: Strong guarantee + +- ``auto_type pop_front():`` + + - Requirements:``not empty()`` + + - Effects: Removes the first element in the container + + - Postconditions: ``size()`` is one less + + - Throws: ``bad_ptr_container_operation`` if ``empty() == true`` + + - Exception safety: Strong guarantee + + +.. _`element access`: + +Semantics: element access +^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``T& operator[]( size_type n );`` +- ``const T& operator[]( size_type n ) const;`` + + - Requirements: ``n < size()`` + + - Effects: Returns a reference to the ``n``'th element + + - Throws: Nothing + +- ``T& at( size_type n );`` +- ``const T& at( size_type n ) const;`` + + - Requirements: ``n < size()`` + + - Effects: Returns a reference to the ``n``'th element + + - Throws: ``bad_index`` if ``n >=size()`` + + +.. _`pointer container requirements`: + +Semantics: pointer container requirements +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``auto_type replace( size_type idx, T* x );`` + + - Requirements: `` x != 0 and idx < size()`` + + - Effects: returns the object indexed by ``idx`` and replaces it with ``x``. + + - Throws: ``bad_index`` if ``idx >= size()`` and ``bad_pointer`` if ``x == 0``. + + - Exception safety: Strong guarantee + +- ``template< class U > auto_type replace( size_type idx, std::auto_ptr<U> x );`` + + - Effects: ``return replace( idx, x.release() );`` + +- ``bool is_null( size_type idx ) const;`` + + - Requirements: ``idx < size()`` + + - Effects: returns whether the pointer at index ``idx`` is null + + - Exception safety: Nothrow guarantee + +.. raw:: html + + <hr> + +:Copyright: Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). + +__ http://www.boost.org/LICENSE_1_0.txt + + diff --git a/libs/ptr_container/doc/ptr_inserter.html b/libs/ptr_container/doc/ptr_inserter.html new file mode 100644 index 0000000000..9fb05a8a9c --- /dev/null +++ b/libs/ptr_container/doc/ptr_inserter.html @@ -0,0 +1,361 @@ +<?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: 2005-09-25 17:49:54 +0200 (Sun, 25 Sep 2005) $ +:Revision: $Revision: 3901 $ +: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="insert-iterators">Insert Iterators</h2> +<p>When you work with normal value-based containers and algorithms, you often +use insert iterators</p> +<pre class="literal-block"> +std::list<int> coll1; +// ... +std::vector<int> coll2; +std::copy( coll1.begin(), coll1.end(), + back_inserter(coll2) ); +</pre> +<p>With the special insert iterators for pointer containers, +you can do exactly the same</p> +<pre class="literal-block"> +boost::ptr_list<Base> coll1; +// ... +boost::ptr_vector<Base> coll2; +std::copy( coll1.begin(), coll1.end(), + boost::ptr_container::ptr_back_inserter(coll2) ); +</pre> +<p>Each element is cloned and inserted into the container. Furthermore, +if the source range iterates over pointers +instead of references, <tt class="docutils literal"><span class="pre">NULL</span></tt> pointers +can be transfered as well.</p> +<p><strong>Navigate</strong></p> +<ul class="simple"> +<li><a class="reference" href="ptr_container.html">home</a></li> +<li><a class="reference" href="reference.html">reference</a></li> +</ul> +<p><strong>Synopsis:</strong></p> +<pre class="literal-block"> +namespace boost +{ + namespace ptr_container + { + + template< class PtrContainer > + class ptr_back_insert_iterator; + + template< class PtrContainer > + class ptr_front_insert_iterator; + + template< class PtrContainer > + class ptr_insert_iterator; + + template< class PtrContainer > + ptr_back_insert_iterator<PtrContainer> + ptr_back_inserter( PtrContainer& cont ); + + template< class PtrContainer > + ptr_front_insert_iterator<PtrContainer> + ptr_front_inserter( PtrContainer& cont ); + + template< class PtrContainer > + ptr_insert_iterator<PtrContainer> + ptr_inserter( PtrContainer& cont, typename PtrContainer::iterator before ); + + } // namespace 'ptr_container' +} // namespace 'boost' +</pre> +<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 2008. 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> +</body> +</html> diff --git a/libs/ptr_container/doc/ptr_inserter.rst b/libs/ptr_container/doc/ptr_inserter.rst new file mode 100644 index 0000000000..574bbdad76 --- /dev/null +++ b/libs/ptr_container/doc/ptr_inserter.rst @@ -0,0 +1,79 @@ +++++++++++++++++++++++++++++++++++ + |Boost| Pointer Container Library +++++++++++++++++++++++++++++++++++ + +.. |Boost| image:: boost.png + +Insert Iterators +---------------- + +When you work with normal value-based containers and algorithms, you often +use insert iterators :: + + std::list<int> coll1; + // ... + std::vector<int> coll2; + std::copy( coll1.begin(), coll1.end(), + back_inserter(coll2) ); + +With the special insert iterators for pointer containers, +you can do exactly the same :: + + boost::ptr_list<Base> coll1; + // ... + boost::ptr_vector<Base> coll2; + std::copy( coll1.begin(), coll1.end(), + boost::ptr_container::ptr_back_inserter(coll2) ); + +Each element is cloned and inserted into the container. Furthermore, +if the source range iterates over pointers +instead of references, ``NULL`` pointers +can be transfered as well. + +**Navigate** + +- `home <ptr_container.html>`_ +- `reference <reference.html>`_ + +**Synopsis:** + +:: + + namespace boost + { + namespace ptr_container + { + + template< class PtrContainer > + class ptr_back_insert_iterator; + + template< class PtrContainer > + class ptr_front_insert_iterator; + + template< class PtrContainer > + class ptr_insert_iterator; + + template< class PtrContainer > + ptr_back_insert_iterator<PtrContainer> + ptr_back_inserter( PtrContainer& cont ); + + template< class PtrContainer > + ptr_front_insert_iterator<PtrContainer> + ptr_front_inserter( PtrContainer& cont ); + + template< class PtrContainer > + ptr_insert_iterator<PtrContainer> + ptr_inserter( PtrContainer& cont, typename PtrContainer::iterator before ); + + } // namespace 'ptr_container' + } // namespace 'boost' + +.. raw:: html + + <hr> + +:Copyright: Thorsten Ottosen 2008. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). + +__ http://www.boost.org/LICENSE_1_0.txt + + diff --git a/libs/ptr_container/doc/ptr_list.html b/libs/ptr_container/doc/ptr_list.html new file mode 100644 index 0000000000..1b8b77b41f --- /dev/null +++ b/libs/ptr_container/doc/ptr_list.html @@ -0,0 +1,441 @@ +<?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: 2006-11-22 17:01:03 -0500 (Wed, 22 Nov 2006) $ +:Revision: $Revision: 36152 $ +: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> +<div class="section"> +<h1><a id="class-ptr-list" name="class-ptr-list">Class <tt class="docutils literal"><span class="pre">ptr_list</span></tt></a></h1> +<p>A <tt class="docutils literal"><span class="pre">ptr_list<T></span></tt> is a pointer container that uses an underlying <tt class="docutils literal"><span class="pre">std:list<void*></span></tt> +to store the pointers.</p> +<p><strong>Hierarchy:</strong></p> +<ul class="simple"> +<li><a class="reference" href="reversible_ptr_container.html">reversible_ptr_container</a><ul> +<li><a class="reference" href="ptr_sequence_adapter.html">ptr_sequence_adapter</a><ul> +<li><a class="reference" href="ptr_vector.html">ptr_vector</a></li> +<li><tt class="docutils literal"><span class="pre">ptr_list</span></tt></li> +<li><a class="reference" href="ptr_deque.html">ptr_deque</a></li> +<li><a class="reference" href="ptr_array.html">ptr_array</a></li> +</ul> +</li> +</ul> +</li> +</ul> +<p><strong>Navigate:</strong></p> +<ul class="simple"> +<li><a class="reference" href="ptr_container.html">home</a></li> +<li><a class="reference" href="reference.html">reference</a></li> +</ul> +<p><strong>Synopsis:</strong></p> +<pre class="literal-block"> +namespace boost +{ + + template + < + class T, + class CloneAllocator = heap_clone_allocator, + class Allocator = std::allocator<void*> + > + class ptr_list : public ptr_sequence_adapter + < + T, + std::list<void*,Allocator>, + CloneAllocator + > + { + + public: // <a class="reference" href="#modifiers">modifiers</a> + void push_front( T* x ); + template< class U > + void push_front( std::auto_ptr<U> x ); + auto_type pop_front(); + + public: // <a class="reference" href="#list-operations">list operations</a> + void reverse(); + + }; // class 'ptr_list' + +} // namespace 'boost' +</pre> +</div> +<div class="section"> +<h1><a id="semantics" name="semantics">Semantics</a></h1> +<div class="section"> +<h2><a id="semantics-modifiers" name="semantics-modifiers"><span id="modifiers"></span>Semantics: modifiers</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">push_front(</span> <span class="pre">T*</span> <span class="pre">x</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">x</span> <span class="pre">!=</span> <span class="pre">0</span></tt></li> +<li>Effects: Inserts the pointer into container and takes ownership of it</li> +<li>Throws: <tt class="docutils literal"><span class="pre">bad_pointer</span></tt> if <tt class="docutils literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">0</span></tt></li> +<li>Exception safety: Strong guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">U</span> <span class="pre">></span> <span class="pre">void</span> <span class="pre">push_front(</span> <span class="pre">std::auto_ptr<U></span> <span class="pre">x</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: <tt class="docutils literal"><span class="pre">push_front(</span> <span class="pre">x.release()</span> <span class="pre">);</span></tt></li> +</ul> +</blockquote> +</li> +</ul> +<!-- - ``void push_front( const T& x );`` + + - Effects: push_front( allocate_clone( x ) ); + + - Exception safety: Strong guarantee --> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">auto_type</span> <span class="pre">pop_front():</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements:<tt class="docutils literal"><span class="pre">not</span> <span class="pre">empty()</span></tt></li> +<li>Effects: Removes the first element in the container</li> +<li>Postconditions: <tt class="docutils literal"><span class="pre">size()</span></tt> is one less</li> +<li>Throws: <tt class="docutils literal"><span class="pre">bad_ptr_container_operation</span></tt> if <tt class="docutils literal"><span class="pre">empty()</span> <span class="pre">==</span> <span class="pre">true</span></tt></li> +<li>Exception safety: Strong guarantee</li> +</ul> +</blockquote> +</li> +</ul> +</div> +<div class="section"> +<h2><a id="semantics-list-operations" name="semantics-list-operations"><span id="list-operations"></span>Semantics: list operations</a></h2> +<!-- - ``void splice( iterator before, ptr_list& x );`` + + - Requirements:``&x != this`` + + - Effects: inserts the all of ``x``'s elements before ``before`` + + - Postconditions: ``x.empty()`` + + - Throws: nothing + + - Remark: prefer this to ``transfer( before, x );`` + +- ``void splice( iterator before, ptr_list& x, iterator i );`` + + - Not ready yet + +- ``void splice( iterator before, ptr_list& x, iterator first, iterator last );`` + + - Not ready yet + +- ``void merge( ptr_list& x );`` + + - Not ready yet + +- ``template< typename Compare > + void merge( ptr_list& x, Compare comp );`` + + - Not ready yet --> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">reverse();</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: reverses the underlying sequence</li> +<li>Throws: nothing</li> +</ul> +</blockquote> +</li> +</ul> +<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> +</div> +</body> +</html> diff --git a/libs/ptr_container/doc/ptr_list.rst b/libs/ptr_container/doc/ptr_list.rst new file mode 100644 index 0000000000..0db63645ec --- /dev/null +++ b/libs/ptr_container/doc/ptr_list.rst @@ -0,0 +1,155 @@ +++++++++++++++++++++++++++++++++++ + |Boost| Pointer Container Library +++++++++++++++++++++++++++++++++++ + +.. |Boost| image:: boost.png + +Class ``ptr_list`` +------------------ + +A ``ptr_list<T>`` is a pointer container that uses an underlying ``std:list<void*>`` +to store the pointers. + +**Hierarchy:** + +- `reversible_ptr_container <reversible_ptr_container.html>`_ + + - `ptr_sequence_adapter <ptr_sequence_adapter.html>`_ + + - `ptr_vector <ptr_vector.html>`_ + - ``ptr_list`` + - `ptr_deque <ptr_deque.html>`_ + - `ptr_array <ptr_array.html>`_ + +**Navigate:** + +- `home <ptr_container.html>`_ +- `reference <reference.html>`_ + + +**Synopsis:** + +.. parsed-literal:: + + namespace boost + { + + template + < + class T, + class CloneAllocator = heap_clone_allocator, + class Allocator = std::allocator<void*> + > + class ptr_list : public ptr_sequence_adapter + < + T, + std::list<void*,Allocator>, + CloneAllocator + > + { + + public: // modifiers_ + void push_front( T* x ); + template< class U > + void push_front( std::auto_ptr<U> x ); + auto_type pop_front(); + + public: // `list operations`_ + void reverse(); + + }; // class 'ptr_list' + + } // namespace 'boost' + + +Semantics +--------- + +.. _modifiers: + +Semantics: modifiers +^^^^^^^^^^^^^^^^^^^^ + +- ``void push_front( T* x );`` + + - Requirements: ``x != 0`` + + - Effects: Inserts the pointer into container and takes ownership of it + + - Throws: ``bad_pointer`` if ``x == 0`` + + - Exception safety: Strong guarantee + +- ``template< class U > void push_front( std::auto_ptr<U> x );`` + + - Effects: ``push_front( x.release() );`` + +.. + - ``void push_front( const T& x );`` + + - Effects: push_front( allocate_clone( x ) ); + + - Exception safety: Strong guarantee + +- ``auto_type pop_front():`` + + - Requirements:``not empty()`` + + - Effects: Removes the first element in the container + + - Postconditions: ``size()`` is one less + + - Throws: ``bad_ptr_container_operation`` if ``empty() == true`` + + - Exception safety: Strong guarantee + +.. _`list operations`: + +Semantics: list operations +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. + - ``void splice( iterator before, ptr_list& x );`` + + - Requirements:``&x != this`` + + - Effects: inserts the all of ``x``'s elements before ``before`` + + - Postconditions: ``x.empty()`` + + - Throws: nothing + + - Remark: prefer this to ``transfer( before, x );`` + + - ``void splice( iterator before, ptr_list& x, iterator i );`` + + - Not ready yet + + - ``void splice( iterator before, ptr_list& x, iterator first, iterator last );`` + + - Not ready yet + + - ``void merge( ptr_list& x );`` + + - Not ready yet + + - ``template< typename Compare > + void merge( ptr_list& x, Compare comp );`` + + - Not ready yet + +- ``void reverse();`` + + - Effects: reverses the underlying sequence + + - Throws: nothing + +.. raw:: html + + <hr> + +:Copyright: Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). + +__ http://www.boost.org/LICENSE_1_0.txt + + diff --git a/libs/ptr_container/doc/ptr_map.html b/libs/ptr_container/doc/ptr_map.html new file mode 100644 index 0000000000..0086ee410d --- /dev/null +++ b/libs/ptr_container/doc/ptr_map.html @@ -0,0 +1,355 @@ +<?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: 2006-11-22 17:01:03 -0500 (Wed, 22 Nov 2006) $ +:Revision: $Revision: 36152 $ +: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="class-ptr-map">Class <tt class="docutils literal"><span class="pre">ptr_map</span></tt></h2> +<p>A <tt class="docutils literal"><span class="pre">ptr_map<Key,T></span></tt> is a pointer container that uses an underlying <tt class="docutils literal"><span class="pre">std::map<Key,void*></span></tt> +to store the pointers.</p> +<p><strong>Hierarchy:</strong></p> +<ul class="simple"> +<li><a class="reference" href="reversible_ptr_container.html">reversible_ptr_container</a><ul> +<li><a class="reference" href="associative_ptr_container.html">associative_ptr_container</a><ul> +<li><a class="reference" href="ptr_set_adapter.html">ptr_set_adapter</a></li> +<li><a class="reference" href="ptr_multiset_adapter.html">ptr_multiset_adapter</a></li> +<li><a class="reference" href="ptr_map_adapter.html">ptr_map_adapter</a></li> +<li><a class="reference" href="ptr_multimap_adapter.html">ptr_multi_map_adapter</a><ul> +<li><a class="reference" href="ptr_set.html">ptr_set</a></li> +<li><a class="reference" href="ptr_multiset.html">ptr_multi_set</a></li> +<li><tt class="docutils literal"><span class="pre">ptr_map</span></tt></li> +<li><a class="reference" href="ptr_multimap.html">ptr_multimap</a></li> +</ul> +</li> +</ul> +</li> +</ul> +</li> +</ul> +<p><strong>Navigate:</strong></p> +<ul class="simple"> +<li><a class="reference" href="ptr_container.html">home</a></li> +<li><a class="reference" href="reference.html">reference</a></li> +</ul> +<p><strong>Synopsis:</strong></p> +<pre class="literal-block"> +namespace boost +{ + + template + < + class Key, + class T, + class Compare = std::less<Key>, + class CloneAllocator = heap_clone_allocator, + class Allocator = std::allocator< std::pair<const Key,void*> > + > + class ptr_map : public ptr_map_adapter + < + T, + std::map<Key,void*,Compare,Allocator>, + CloneAllocator + > + { + // see references + + }; // class 'ptr_map' + +} // namespace 'boost' +</pre> +<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> +</body> +</html> diff --git a/libs/ptr_container/doc/ptr_map.rst b/libs/ptr_container/doc/ptr_map.rst new file mode 100644 index 0000000000..6b50a2bab0 --- /dev/null +++ b/libs/ptr_container/doc/ptr_map.rst @@ -0,0 +1,72 @@ +++++++++++++++++++++++++++++++++++ + |Boost| Pointer Container Library +++++++++++++++++++++++++++++++++++ + +.. |Boost| image:: boost.png + +Class ``ptr_map`` +----------------- + +A ``ptr_map<Key,T>`` is a pointer container that uses an underlying ``std::map<Key,void*>`` +to store the pointers. + +**Hierarchy:** + +- `reversible_ptr_container <reversible_ptr_container.html>`_ + + - `associative_ptr_container <associative_ptr_container.html>`_ + + - `ptr_set_adapter <ptr_set_adapter.html>`_ + - `ptr_multiset_adapter <ptr_multiset_adapter.html>`_ + - `ptr_map_adapter <ptr_map_adapter.html>`_ + - `ptr_multi_map_adapter <ptr_multimap_adapter.html>`_ + + - `ptr_set <ptr_set.html>`_ + - `ptr_multi_set <ptr_multiset.html>`_ + - ``ptr_map`` + - `ptr_multimap <ptr_multimap.html>`_ + +**Navigate:** + +- `home <ptr_container.html>`_ +- `reference <reference.html>`_ + + +**Synopsis:** + +.. parsed-literal:: + + + namespace boost + { + + template + < + class Key, + class T, + class Compare = std::less<Key>, + class CloneAllocator = heap_clone_allocator, + class Allocator = std::allocator< std::pair<const Key,void*> > + > + class ptr_map : public ptr_map_adapter + < + T, + std::map<Key,void*,Compare,Allocator>, + CloneAllocator + > + { + // see references + + }; // class 'ptr_map' + + } // namespace 'boost' + +.. raw:: html + + <hr> + +:Copyright: Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). + +__ http://www.boost.org/LICENSE_1_0.txt + + diff --git a/libs/ptr_container/doc/ptr_map_adapter.html b/libs/ptr_container/doc/ptr_map_adapter.html new file mode 100644 index 0000000000..0d10996246 --- /dev/null +++ b/libs/ptr_container/doc/ptr_map_adapter.html @@ -0,0 +1,497 @@ +<?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: 2006-11-22 17:01:03 -0500 (Wed, 22 Nov 2006) $ +:Revision: $Revision: 36152 $ +: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> +<div class="section"> +<h1><a id="class-ptr-map-adapter" name="class-ptr-map-adapter">Class <tt class="docutils literal"><span class="pre">ptr_map_adapter</span></tt></a></h1> +<p>This class is used to build custom pointer containers with +an underlying map-like container. The interface of the class is an extension +of the interface from <tt class="docutils literal"><span class="pre">associative_ptr_container</span></tt>.</p> +<p><strong>Hierarchy:</strong></p> +<ul class="simple"> +<li><a class="reference" href="reversible_ptr_container.html">reversible_ptr_container</a><ul> +<li><a class="reference" href="associative_ptr_container.html">associative_ptr_container</a><ul> +<li><a class="reference" href="ptr_set_adapter.html">ptr_set_adapter</a></li> +<li><a class="reference" href="ptr_multiset_adapter.html">ptr_multiset_adapter</a></li> +<li><tt class="docutils literal"><span class="pre">ptr_map_adapter</span></tt></li> +<li><a class="reference" href="ptr_multimap_adapter.html">ptr_multi_map_adapter</a><ul> +<li><a class="reference" href="ptr_set.html">ptr_set</a></li> +<li><a class="reference" href="ptr_multiset.html">ptr_multi_set</a></li> +<li><a class="reference" href="ptr_map.html">ptr_map</a></li> +<li><a class="reference" href="ptr_multimap.html">ptr_multimap</a></li> +</ul> +</li> +</ul> +</li> +</ul> +</li> +</ul> +<p><strong>Navigate:</strong></p> +<ul class="simple"> +<li><a class="reference" href="ptr_container.html">home</a></li> +<li><a class="reference" href="reference.html">reference</a></li> +</ul> +<p><strong>Synopsis:</strong></p> +<pre class="literal-block"> +namespace boost +{ + template + < + class T, + class VoidPtrMap, + class CloneAllocator = heap_clone_allocator + > + class ptr_map_adapter + { + public: // <a class="reference" href="#typedefs">typedefs</a> + typedef VoidPtrMap::key_type key_type; + typedef T* mapped_type; + typedef T& mapped_reference; + typedef const T& const_mapped_reference; + typedef ... value_type; + typedef ... reference; + typedef ... const_reference; + typedef ... pointer; + typedef ... const_pointer; + + public: // <a class="reference" href="#modifiers">modifiers</a> + std::pair<iterator,bool> insert( key_type& k, T* x ); + template< class U > + std::pair<iterator,bool> insert( const key_type& k, std::auto_ptr<U> x ); + + public; // <a class="reference" href="#lookup">lookup</a> + T& operator[]( const key_type& key ); + T& at( const key_type& key ); + const T& at( const key_type& key ) const; + + public: // <a class="reference" href="#pointer-container-requirements">pointer container requirements</a> + bool transfer( iterator object, ptr_map_adapter& from ); + size_type transfer( iterator first, iterator last, ptr_map_adapter& from ); + template< class Range > + size_type transfer( const Range& r, ptr_map_adapter& from ); + size_type transfer( ptr_map_adapter& from ); + + }; // class 'ptr_map_adapter' + +} // namespace 'boost' +</pre> +</div> +<div class="section"> +<h1><a id="semantics" name="semantics">Semantics</a></h1> +<div class="section"> +<h2><a id="semantics-typedefs" name="semantics-typedefs"><span id="typedefs"></span>Semantics: typedefs</a></h2> +<p>The following types are implementation defined:</p> +<pre class="literal-block"> +typedef ... value_type; +typedef ... reference; +typedef ... const_reference; +typedef ... pointer; +typedef ... const_pointer; +</pre> +<p>However, the structure of the type mimics <tt class="docutils literal"><span class="pre">std::pair</span></tt> s.t. one +can use <tt class="docutils literal"><span class="pre">first</span></tt> and <tt class="docutils literal"><span class="pre">second</span></tt> members. The reference-types +are not real references and the pointer-types are not real pointers. +However, one may still write</p> +<pre class="literal-block"> +map_type::value_type a_value = *m.begin(); +a_value.second->foo(); +map_type::reference a_reference = *m.begin(); +a_reference.second->foo(); +map_type::const_reference a_creference = *const_begin(m); +map_type::pointer a_pointer = &*m.begin(); +a_pointer->second->foo(); +map_type::const_pointer a_cpointer = &*const_begin(m); +</pre> +<p>The difference compared to <tt class="docutils literal"><span class="pre">std::map<Key,T*></span></tt> is that constness +is propagated to the pointer (that is, to <tt class="docutils literal"><span class="pre">second</span></tt>) in <tt class="docutils literal"><span class="pre">const_itertor</span></tt>.</p> +</div> +<div class="section"> +<h2><a id="semantics-modifiers" name="semantics-modifiers"><span id="modifiers"></span>Semantics: modifiers</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">std::pair<iterator,bool></span> <span class="pre">insert(</span> <span class="pre">key_type&</span> <span class="pre">k,</span> <span class="pre">value_type</span> <span class="pre">x</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">x</span> <span class="pre">!=</span> <span class="pre">0</span></tt></li> +<li>Effects: Takes ownership of <tt class="docutils literal"><span class="pre">x</span></tt> and insert it iff there is no equivalent of it already. The bool part of the return value indicates insertion and the iterator points to the element with key <tt class="docutils literal"><span class="pre">x</span></tt>.</li> +<li>Throws: bad_pointer if <tt class="docutils literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">0</span></tt></li> +<li>Exception safety: Strong guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">U</span> <span class="pre">></span> <span class="pre">std::pair<iterator,bool></span> <span class="pre">insert(</span> <span class="pre">const</span> <span class="pre">key_type&</span> <span class="pre">k,</span> <span class="pre">std::auto_ptr<U></span> <span class="pre">x</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Equivalent to (but without the <tt class="docutils literal"><span class="pre">const_cast</span></tt>): <tt class="docutils literal"><span class="pre">return</span> <span class="pre">insert(</span> <span class="pre">const_cast<key_type&>(k),</span> <span class="pre">x.release()</span> <span class="pre">);</span></tt></li> +</ul> +</blockquote> +</li> +</ul> +<!-- - ``std::pair<iterator,bool> insert( key_type& k, const_reference x );`` + +- Effects: ``return insert( allocate_clone( x ) );`` + +- Exception safety: Strong guarantee --> +</div> +<div class="section"> +<h2><a id="semantics-lookup" name="semantics-lookup"><span id="lookup"></span>Semantics: lookup</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">T&</span> <span class="pre">operator[](</span> <span class="pre">const</span> <span class="pre">key_type&</span> <span class="pre">key</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: returns the object with key <tt class="docutils literal"><span class="pre">key</span></tt> if it exists; otherwise a new object is allocated and inserted and its reference returned.</li> +<li>Exception-safety: Strong guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">T&</span> <span class="pre">at(</span> <span class="pre">const</span> <span class="pre">key_type&</span> <span class="pre">key</span> <span class="pre">);</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">const</span> <span class="pre">T&</span> <span class="pre">at(</span> <span class="pre">const</span> <span class="pre">key_type&</span> <span class="pre">jey</span> <span class="pre">)</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirement: the key exists</li> +<li>Throws: <tt class="docutils literal"><span class="pre">bad_ptr_container_operation</span></tt> if the key does not exist</li> +</ul> +</blockquote> +</li> +</ul> +</div> +<div class="section"> +<h2><a id="semantics-pointer-container-requirements" name="semantics-pointer-container-requirements"><span id="pointer-container-requirements"></span>Semantics: pointer container requirements</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">transfer(</span> <span class="pre">iterator</span> <span class="pre">object,</span> <span class="pre">ptr_map_adapter&</span> <span class="pre">from</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">not</span> <span class="pre">from.empty()</span></tt></li> +<li>Effects: Inserts the object defined by <tt class="docutils literal"><span class="pre">object</span></tt> into the container and remove it from <tt class="docutils literal"><span class="pre">from</span></tt> +iff no equivalent object exists.</li> +<li>Returns: whether the object was transfered</li> +<li>Exception safety: Strong guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">size_type</span> <span class="pre">transfer(</span> <span class="pre">iterator</span> <span class="pre">first,</span> <span class="pre">iterator</span> <span class="pre">last,</span> <span class="pre">ptr__set_adapter&</span> <span class="pre">from</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">not</span> <span class="pre">from.empty()</span></tt></li> +<li>Effects: Inserts the objects defined by the range <tt class="docutils literal"><span class="pre">[first,last)</span></tt> into the container and remove it from <tt class="docutils literal"><span class="pre">from</span></tt>. +An object is only transferred if no equivalent object exists.</li> +<li>Returns: the number of transfered objects</li> +<li>Exception safety: Basic guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">Range</span> <span class="pre">></span> <span class="pre">void</span> <span class="pre">transfer(</span> <span class="pre">const</span> <span class="pre">Range&</span> <span class="pre">r,</span> <span class="pre">ptr_map_adapter&</span> <span class="pre">from</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: <tt class="docutils literal"><span class="pre">return</span> <span class="pre">transfer(</span> <span class="pre">boost::begin(r),</span> <span class="pre">boost::end(r),</span> <span class="pre">from</span> <span class="pre">);</span></tt></li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">size_type</span> <span class="pre">transfer(</span> <span class="pre">ptr_set_adapter&</span> <span class="pre">from</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: <tt class="docutils literal"><span class="pre">return</span> <span class="pre">transfer(</span> <span class="pre">from.begin(),</span> <span class="pre">from.end(),</span> <span class="pre">from</span> <span class="pre">);</span></tt>.</li> +</ul> +</blockquote> +</li> +</ul> +<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> +</div> +</body> +</html> diff --git a/libs/ptr_container/doc/ptr_map_adapter.rst b/libs/ptr_container/doc/ptr_map_adapter.rst new file mode 100644 index 0000000000..3e0c5159e2 --- /dev/null +++ b/libs/ptr_container/doc/ptr_map_adapter.rst @@ -0,0 +1,203 @@ +++++++++++++++++++++++++++++++++++ + |Boost| Pointer Container Library +++++++++++++++++++++++++++++++++++ + +.. |Boost| image:: boost.png + +Class ``ptr_map_adapter`` +------------------------- + +This class is used to build custom pointer containers with +an underlying map-like container. The interface of the class is an extension +of the interface from ``associative_ptr_container``. + +**Hierarchy:** + +- `reversible_ptr_container <reversible_ptr_container.html>`_ + + - `associative_ptr_container <associative_ptr_container.html>`_ + + - `ptr_set_adapter <ptr_set_adapter.html>`_ + - `ptr_multiset_adapter <ptr_multiset_adapter.html>`_ + - ``ptr_map_adapter`` + - `ptr_multi_map_adapter <ptr_multimap_adapter.html>`_ + + - `ptr_set <ptr_set.html>`_ + - `ptr_multi_set <ptr_multiset.html>`_ + - `ptr_map <ptr_map.html>`_ + - `ptr_multimap <ptr_multimap.html>`_ + +**Navigate:** + +- `home <ptr_container.html>`_ +- `reference <reference.html>`_ + +**Synopsis:** + +.. parsed-literal:: + + + namespace boost + { + template + < + class T, + class VoidPtrMap, + class CloneAllocator = heap_clone_allocator + > + class ptr_map_adapter + { + public: // `typedefs`_ + typedef VoidPtrMap::key_type key_type; + typedef T* mapped_type; + typedef T& mapped_reference; + typedef const T& const_mapped_reference; + typedef ... value_type; + typedef ... reference; + typedef ... const_reference; + typedef ... pointer; + typedef ... const_pointer; + + public: // `modifiers`_ + std::pair<iterator,bool> insert( key_type& k, T* x ); + template< class U > + std::pair<iterator,bool> insert( const key_type& k, std::auto_ptr<U> x ); + + public; // `lookup`_ + T& operator[]( const key_type& key ); + T& at( const key_type& key ); + const T& at( const key_type& key ) const; + + public: // `pointer container requirements`_ + bool transfer( iterator object, ptr_map_adapter& from ); + size_type transfer( iterator first, iterator last, ptr_map_adapter& from ); + template< class Range > + size_type transfer( const Range& r, ptr_map_adapter& from ); + size_type transfer( ptr_map_adapter& from ); + + }; // class 'ptr_map_adapter' + + } // namespace 'boost' + + +Semantics +--------- + +.. _`typedefs`: + +Semantics: typedefs +^^^^^^^^^^^^^^^^^^^ + +The following types are implementation defined:: + + typedef ... value_type; + typedef ... reference; + typedef ... const_reference; + typedef ... pointer; + typedef ... const_pointer; + +However, the structure of the type mimics ``std::pair`` s.t. one +can use ``first`` and ``second`` members. The reference-types +are not real references and the pointer-types are not real pointers. +However, one may still write :: + + map_type::value_type a_value = *m.begin(); + a_value.second->foo(); + map_type::reference a_reference = *m.begin(); + a_reference.second->foo(); + map_type::const_reference a_creference = *const_begin(m); + map_type::pointer a_pointer = &*m.begin(); + a_pointer->second->foo(); + map_type::const_pointer a_cpointer = &*const_begin(m); + +The difference compared to ``std::map<Key,T*>`` is that constness +is propagated to the pointer (that is, to ``second``) in ``const_itertor``. + +.. _`modifiers`: + +Semantics: modifiers +^^^^^^^^^^^^^^^^^^^^ + +- ``std::pair<iterator,bool> insert( key_type& k, value_type x );`` + + - Requirements: ``x != 0`` + + - Effects: Takes ownership of ``x`` and insert it iff there is no equivalent of it already. The bool part of the return value indicates insertion and the iterator points to the element with key ``x``. + + - Throws: bad_pointer if ``x == 0`` + + - Exception safety: Strong guarantee + + +- ``template< class U > std::pair<iterator,bool> insert( const key_type& k, std::auto_ptr<U> x );`` + + - Equivalent to (but without the ``const_cast``): ``return insert( const_cast<key_type&>(k), x.release() );`` + +.. + - ``std::pair<iterator,bool> insert( key_type& k, const_reference x );`` + + - Effects: ``return insert( allocate_clone( x ) );`` + + - Exception safety: Strong guarantee + + +.. _`lookup`: + +Semantics: lookup +^^^^^^^^^^^^^^^^^ + +- ``T& operator[]( const key_type& key );`` + + - Effects: returns the object with key ``key`` if it exists; otherwise a new object is allocated and inserted and its reference returned. + - Exception-safety: Strong guarantee + +- ``T& at( const key_type& key );`` +- ``const T& at( const key_type& jey ) const;`` + + - Requirement: the key exists + - Throws: ``bad_ptr_container_operation`` if the key does not exist + +.. _`pointer container requirements`: + +Semantics: pointer container requirements +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``bool transfer( iterator object, ptr_map_adapter& from );`` + + - Requirements: ``not from.empty()`` + + - Effects: Inserts the object defined by ``object`` into the container and remove it from ``from`` + iff no equivalent object exists. + + - Returns: whether the object was transfered + + - Exception safety: Strong guarantee + +- ``size_type transfer( iterator first, iterator last, ptr__set_adapter& from );`` + + - Requirements: ``not from.empty()`` + + - Effects: Inserts the objects defined by the range ``[first,last)`` into the container and remove it from ``from``. + An object is only transferred if no equivalent object exists. + + - Returns: the number of transfered objects + + - Exception safety: Basic guarantee + +- ``template< class Range > void transfer( const Range& r, ptr_map_adapter& from );`` + + - Effects: ``return transfer( boost::begin(r), boost::end(r), from );`` + +- ``size_type transfer( ptr_set_adapter& from );`` + + - Effects: ``return transfer( from.begin(), from.end(), from );``. + +.. raw:: html + + <hr> + +:Copyright: Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). + +__ http://www.boost.org/LICENSE_1_0.txt + + diff --git a/libs/ptr_container/doc/ptr_multimap.html b/libs/ptr_container/doc/ptr_multimap.html new file mode 100644 index 0000000000..1325e44935 --- /dev/null +++ b/libs/ptr_container/doc/ptr_multimap.html @@ -0,0 +1,354 @@ +<?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: 2006-11-22 17:01:03 -0500 (Wed, 22 Nov 2006) $ +:Revision: $Revision: 36152 $ +: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="class-ptr-multimap">Class <tt class="docutils literal"><span class="pre">ptr_multimap</span></tt></h2> +<p>A <tt class="docutils literal"><span class="pre">ptr_multimap<Key,T></span></tt> is a pointer container that uses an underlying <tt class="docutils literal"><span class="pre">std::multimap<Key,void*></span></tt> +to store the pointers.</p> +<p><strong>Hierarchy:</strong></p> +<ul class="simple"> +<li><a class="reference" href="reversible_ptr_container.html">reversible_ptr_container</a><ul> +<li><a class="reference" href="associative_ptr_container.html">associative_ptr_container</a><ul> +<li><a class="reference" href="ptr_set_adapter.html">ptr_set_adapter</a></li> +<li><a class="reference" href="ptr_multiset_adapter.html">ptr_multiset_adapter</a></li> +<li><a class="reference" href="ptr_map_adapter.html">ptr_map_adapter</a></li> +<li><a class="reference" href="ptr_multimap_adapter.html">ptr_multi_map_adapter</a><ul> +<li><a class="reference" href="ptr_set.html">ptr_set</a></li> +<li><a class="reference" href="ptr_multiset.html">ptr_multi_set</a></li> +<li><a class="reference" href="ptr_map.html">ptr_map</a></li> +<li><tt class="docutils literal"><span class="pre">ptr_multimap</span></tt></li> +</ul> +</li> +</ul> +</li> +</ul> +</li> +</ul> +<p><strong>Navigate:</strong></p> +<ul class="simple"> +<li><a class="reference" href="ptr_container.html">home</a></li> +<li><a class="reference" href="reference.html">reference</a></li> +</ul> +<p><strong>Synopsis:</strong></p> +<pre class="literal-block"> +namespace boost +{ + template + < + class Key, + class T, + class Compare = std::less<Key>, + class CloneAllocator = heap_clone_allocator, + class Allocator = std::allocator< std::pair<const Key,void*> > + > + class ptr_multimap : public ptr_multimap_adapter + < + T, + std::multimap<Key,void*,Compare,Allocator>, + CloneAllocator + > + { + // see references + + }; // class 'ptr_multimap' + +} // namespace 'boost' +</pre> +<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> +</body> +</html> diff --git a/libs/ptr_container/doc/ptr_multimap.rst b/libs/ptr_container/doc/ptr_multimap.rst new file mode 100644 index 0000000000..27c86fb6cd --- /dev/null +++ b/libs/ptr_container/doc/ptr_multimap.rst @@ -0,0 +1,74 @@ +++++++++++++++++++++++++++++++++++ + |Boost| Pointer Container Library +++++++++++++++++++++++++++++++++++ + +.. |Boost| image:: boost.png + +Class ``ptr_multimap`` +---------------------- + +A ``ptr_multimap<Key,T>`` is a pointer container that uses an underlying ``std::multimap<Key,void*>`` +to store the pointers. + + +**Hierarchy:** + +- `reversible_ptr_container <reversible_ptr_container.html>`_ + + - `associative_ptr_container <associative_ptr_container.html>`_ + + - `ptr_set_adapter <ptr_set_adapter.html>`_ + - `ptr_multiset_adapter <ptr_multiset_adapter.html>`_ + - `ptr_map_adapter <ptr_map_adapter.html>`_ + - `ptr_multi_map_adapter <ptr_multimap_adapter.html>`_ + + - `ptr_set <ptr_set.html>`_ + - `ptr_multi_set <ptr_multiset.html>`_ + - `ptr_map <ptr_map.html>`_ + - ``ptr_multimap`` + +**Navigate:** + +- `home <ptr_container.html>`_ +- `reference <reference.html>`_ + +.. _reversible_ptr_container: reversible_ptr_container.html +.. _associative_ptr_container: associative_ptr_container.html +.. _ptr_multimap_adapter: ptr_multimap_adapter.html + + + +**Synopsis:** + +.. parsed-literal:: + + + namespace boost + { + template + < + class Key, + class T, + class Compare = std::less<Key>, + class CloneAllocator = heap_clone_allocator, + class Allocator = std::allocator< std::pair<const Key,void*> > + > + class ptr_multimap : public ptr_multimap_adapter + < + T, + std::multimap<Key,void*,Compare,Allocator>, + CloneAllocator + > + { + // see references + + }; // class 'ptr_multimap' + + } // namespace 'boost' + + +:Copyright: Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). + +__ http://www.boost.org/LICENSE_1_0.txt + + diff --git a/libs/ptr_container/doc/ptr_multimap_adapter.html b/libs/ptr_container/doc/ptr_multimap_adapter.html new file mode 100644 index 0000000000..3645e56b59 --- /dev/null +++ b/libs/ptr_container/doc/ptr_multimap_adapter.html @@ -0,0 +1,481 @@ +<?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: 2006-11-22 17:01:03 -0500 (Wed, 22 Nov 2006) $ +:Revision: $Revision: 36152 $ +: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> +<div class="section"> +<h1><a id="class-ptr-multimap-adapter" name="class-ptr-multimap-adapter">Class <tt class="docutils literal"><span class="pre">ptr_multimap_adapter</span></tt></a></h1> +<p>This class is used to build custom pointer containers with +an underlying multimap-like container. The interface of the class is an extension +of the interface from <tt class="docutils literal"><span class="pre">associative_ptr_container</span></tt>.</p> +<p><strong>Hierarchy:</strong></p> +<ul class="simple"> +<li><a class="reference" href="reversible_ptr_container.html">reversible_ptr_container</a><ul> +<li><a class="reference" href="associative_ptr_container.html">associative_ptr_container</a><ul> +<li><a class="reference" href="ptr_set_adapter.html">ptr_set_adapter</a></li> +<li><a class="reference" href="ptr_multiset_adapter.html">ptr_multiset_adapter</a></li> +<li><a class="reference" href="ptr_map_adapter.html">ptr_map_adapter</a></li> +<li><tt class="docutils literal"><span class="pre">ptr_multi_map_adapter</span></tt><ul> +<li><a class="reference" href="ptr_set.html">ptr_set</a></li> +<li><a class="reference" href="ptr_multiset.html">ptr_multi_set</a></li> +<li><a class="reference" href="ptr_map.html">ptr_map</a></li> +<li><a class="reference" href="ptr_multimap.html">ptr_multimap</a></li> +</ul> +</li> +</ul> +</li> +</ul> +</li> +</ul> +<p><strong>Navigate:</strong></p> +<ul class="simple"> +<li><a class="reference" href="ptr_container.html">home</a></li> +<li><a class="reference" href="reference.html">reference</a></li> +</ul> +<p><strong>Synopsis:</strong></p> +<pre class="literal-block"> +namespace boost +{ + template + < + T, + class VoidPtrMultiMap, + class CloneAllocator = heap_clone_allocator + > + class ptr_multimap_adapter + { + public: // <a class="reference" href="#typedefs">typedefs</a> + typedef VoidPtrMap::key_type key_type; + typedef T* mapped_type; + typedef T& mapped_reference; + typedef const T& const_mapped_reference; + typedef ... value_type; + typedef ... reference; + typedef ... const_reference; + typedef ... pointer; + typedef ... const_pointer; + + public: // <a class="reference" href="#modifiers">modifiers</a> + iterator insert( key_type& k, T* x ); + template< class U > + iterator insert( const key_type&, std::auto_ptr<U> x ); + + public: // <a class="reference" href="#pointer-container-requirements">pointer container requirements</a> + void transfer( iterator object, ptr_multimap_adapter& from ); + size_type transfer( iterator first, iterator last, ptr_multimap_adapter& from ); + template< class Range > + size_type transfer( const Range& r, ptr_multimap_adapter& from ); + void transfer( ptr_multimap_adapter& from ); + + }; // class 'ptr_multimap_adapter' + +} // namespace 'boost' +</pre> +</div> +<div class="section"> +<h1><a id="semantics" name="semantics">Semantics</a></h1> +<p>. <span class="target" id="typedefs">typedefs</span>:</p> +<div class="section"> +<h2><a id="semantics-typedefs" name="semantics-typedefs">Semantics: typedefs</a></h2> +<p>The following types are implementation defined:</p> +<pre class="literal-block"> +typedef ... value_type; +typedef ... reference; +typedef ... const_reference; +typedef ... pointer; +typedef ... const_pointer; +</pre> +<p>However, the structure of the type mimics <tt class="docutils literal"><span class="pre">std::pair</span></tt> s.t. one +can use <tt class="docutils literal"><span class="pre">first</span></tt> and <tt class="docutils literal"><span class="pre">second</span></tt> members. The reference-types +are not real references and the pointer-types are not real pointers. +However, one may still write</p> +<pre class="literal-block"> +map_type::value_type a_value = *m.begin(); +a_value.second->foo(); +map_type::reference a_reference = *m.begin(); +a_reference.second->foo(); +map_type::const_reference a_creference = *const_begin(m); +map_type::pointer a_pointer = &*m.begin(); +a_pointer->second->foo(); +map_type::const_pointer a_cpointer = &*const_begin(m); +</pre> +<p>The difference compared to <tt class="docutils literal"><span class="pre">std::map<Key,T*></span></tt> is that constness +is propagated to the pointer (that is, to <tt class="docutils literal"><span class="pre">second</span></tt>) in <tt class="docutils literal"><span class="pre">const_itertor</span></tt>.</p> +</div> +<div class="section"> +<h2><a id="semantics-modifiers" name="semantics-modifiers"><span id="modifiers"></span>Semantics: modifiers</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">iterator</span> <span class="pre">insert(</span> <span class="pre">key_type&</span> <span class="pre">k,</span> <span class="pre">T*</span> <span class="pre">x</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">x</span> <span class="pre">!=</span> <span class="pre">0</span></tt></li> +<li>Effects: Takes ownership of <tt class="docutils literal"><span class="pre">x</span></tt> and returns an iterator pointing to it.</li> +<li>Throws: bad_pointer if <tt class="docutils literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">0</span></tt></li> +<li>Exception safety: Strong guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">U</span> <span class="pre">></span> <span class="pre">iterator</span> <span class="pre">insert(</span> <span class="pre">const</span> <span class="pre">key_type&</span> <span class="pre">k,</span> <span class="pre">std::auto_ptr<U></span> <span class="pre">x</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Equivalent to (but without the <tt class="docutils literal"><span class="pre">const_cast</span></tt>): <tt class="docutils literal"><span class="pre">return</span> <span class="pre">insert(</span> <span class="pre">const_cast<key_type&>(k),</span> <span class="pre">x.release()</span> <span class="pre">);</span></tt></li> +</ul> +</blockquote> +</li> +</ul> +<!-- - ``iterator insert( key_type& k, const_reference x );`` + +- Effects: ``return insert( allocate_clone( x ) );`` + +- Exception safety: Strong guarantee --> +<span class="target" id="lookup"></span><!-- Semantics: lookup +^^^^^^^^^^^^^^^^^ + +- ``reference operator[]( const Key& key );`` +- ``const_reference operator[]( const Key& key ) const;`` + + - Requirements: the key exists + + - Effects: returns the object with key ``key`` + + - Throws: ``bad_ptr_container_operation`` if the key does not exist --> +</div> +<div class="section"> +<h2><a id="semantics-pointer-container-requirements" name="semantics-pointer-container-requirements"><span id="pointer-container-requirements"></span>Semantics: pointer container requirements</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">transfer(</span> <span class="pre">iterator</span> <span class="pre">object,</span> <span class="pre">ptr_multimap_adapter&</span> <span class="pre">from</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">not</span> <span class="pre">from.empty()</span></tt></li> +<li>Effects: Inserts the object defined by <tt class="docutils literal"><span class="pre">object</span></tt> into the container and remove it from <tt class="docutils literal"><span class="pre">from</span></tt>.</li> +<li>Postconditions: <tt class="docutils literal"><span class="pre">size()</span></tt> is one more, <tt class="docutils literal"><span class="pre">from.size()</span></tt> is one less.</li> +<li>Exception safety: Strong guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">transfer(</span> <span class="pre">iterator</span> <span class="pre">first,</span> <span class="pre">iterator</span> <span class="pre">last,</span> <span class="pre">ptr_multimap_adapter&</span> <span class="pre">from</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">not</span> <span class="pre">from.empty()</span></tt></li> +<li>Effects: Inserts the objects defined by the range <tt class="docutils literal"><span class="pre">[first,last)</span></tt> into the container and remove it from <tt class="docutils literal"><span class="pre">from</span></tt>.</li> +<li>Postconditions: Let <tt class="docutils literal"><span class="pre">N</span> <span class="pre">==</span> <span class="pre">std::distance(first,last);</span></tt> then <tt class="docutils literal"><span class="pre">size()</span></tt> is <tt class="docutils literal"><span class="pre">N</span></tt> more, <tt class="docutils literal"><span class="pre">from.size()</span></tt> is <tt class="docutils literal"><span class="pre">N</span></tt> less.</li> +<li>Exception safety: Basic guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">Range</span> <span class="pre">></span> <span class="pre">void</span> <span class="pre">transfer(</span> <span class="pre">const</span> <span class="pre">Range&</span> <span class="pre">r,</span> <span class="pre">ptr_multimap_adapter&</span> <span class="pre">from</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: <tt class="docutils literal"><span class="pre">transfer(</span> <span class="pre">boost::begin(r),</span> <span class="pre">boost::end(r),</span> <span class="pre">from</span> <span class="pre">);</span></tt></li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">transfer(</span> <span class="pre">ptr_multimap_adapter&</span> <span class="pre">from</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: <tt class="docutils literal"><span class="pre">transfer(</span> <span class="pre">from.begin(),</span> <span class="pre">from.end(),</span> <span class="pre">from</span> <span class="pre">);</span></tt>.</li> +<li>Postconditions: <tt class="docutils literal"><span class="pre">from.empty();</span></tt></li> +<li>Exception safety: Basic guarantee</li> +</ul> +</blockquote> +</li> +</ul> +<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> +</div> +</body> +</html> diff --git a/libs/ptr_container/doc/ptr_multimap_adapter.rst b/libs/ptr_container/doc/ptr_multimap_adapter.rst new file mode 100644 index 0000000000..cca905695d --- /dev/null +++ b/libs/ptr_container/doc/ptr_multimap_adapter.rst @@ -0,0 +1,198 @@ +++++++++++++++++++++++++++++++++++ + |Boost| Pointer Container Library +++++++++++++++++++++++++++++++++++ + +.. |Boost| image:: boost.png + +Class ``ptr_multimap_adapter`` +------------------------------ + +This class is used to build custom pointer containers with +an underlying multimap-like container. The interface of the class is an extension +of the interface from ``associative_ptr_container``. + +**Hierarchy:** + +- `reversible_ptr_container <reversible_ptr_container.html>`_ + + - `associative_ptr_container <associative_ptr_container.html>`_ + + - `ptr_set_adapter <ptr_set_adapter.html>`_ + - `ptr_multiset_adapter <ptr_multiset_adapter.html>`_ + - `ptr_map_adapter <ptr_map_adapter.html>`_ + - ``ptr_multi_map_adapter`` + + - `ptr_set <ptr_set.html>`_ + - `ptr_multi_set <ptr_multiset.html>`_ + - `ptr_map <ptr_map.html>`_ + - `ptr_multimap <ptr_multimap.html>`_ + +**Navigate:** + +- `home <ptr_container.html>`_ +- `reference <reference.html>`_ + +**Synopsis:** + +.. parsed-literal:: + + + namespace boost + { + template + < + T, + class VoidPtrMultiMap, + class CloneAllocator = heap_clone_allocator + > + class ptr_multimap_adapter + { + public: // `typedefs`_ + typedef VoidPtrMap::key_type key_type; + typedef T* mapped_type; + typedef T& mapped_reference; + typedef const T& const_mapped_reference; + typedef ... value_type; + typedef ... reference; + typedef ... const_reference; + typedef ... pointer; + typedef ... const_pointer; + + public: // `modifiers`_ + iterator insert( key_type& k, T* x ); + template< class U > + iterator insert( const key_type&, std::auto_ptr<U> x ); + + public: // `pointer container requirements`_ + void transfer( iterator object, ptr_multimap_adapter& from ); + size_type transfer( iterator first, iterator last, ptr_multimap_adapter& from ); + template< class Range > + size_type transfer( const Range& r, ptr_multimap_adapter& from ); + void transfer( ptr_multimap_adapter& from ); + + }; // class 'ptr_multimap_adapter' + + } // namespace 'boost' + + +Semantics +--------- + +. _`typedefs`: + +Semantics: typedefs +^^^^^^^^^^^^^^^^^^^ + +The following types are implementation defined:: + + typedef ... value_type; + typedef ... reference; + typedef ... const_reference; + typedef ... pointer; + typedef ... const_pointer; + +However, the structure of the type mimics ``std::pair`` s.t. one +can use ``first`` and ``second`` members. The reference-types +are not real references and the pointer-types are not real pointers. +However, one may still write :: + + map_type::value_type a_value = *m.begin(); + a_value.second->foo(); + map_type::reference a_reference = *m.begin(); + a_reference.second->foo(); + map_type::const_reference a_creference = *const_begin(m); + map_type::pointer a_pointer = &*m.begin(); + a_pointer->second->foo(); + map_type::const_pointer a_cpointer = &*const_begin(m); + +The difference compared to ``std::map<Key,T*>`` is that constness +is propagated to the pointer (that is, to ``second``) in ``const_itertor``. + +.. _`modifiers`: + +Semantics: modifiers +^^^^^^^^^^^^^^^^^^^^ + +- ``iterator insert( key_type& k, T* x );`` + + - Requirements: ``x != 0`` + + - Effects: Takes ownership of ``x`` and returns an iterator pointing to it. + + - Throws: bad_pointer if ``x == 0`` + + - Exception safety: Strong guarantee + +- ``template< class U > iterator insert( const key_type& k, std::auto_ptr<U> x );`` + + - Equivalent to (but without the ``const_cast``): ``return insert( const_cast<key_type&>(k), x.release() );`` + +.. + - ``iterator insert( key_type& k, const_reference x );`` + + - Effects: ``return insert( allocate_clone( x ) );`` + + - Exception safety: Strong guarantee + + +.. _`lookup`: + +.. + Semantics: lookup + ^^^^^^^^^^^^^^^^^ + + - ``reference operator[]( const Key& key );`` + - ``const_reference operator[]( const Key& key ) const;`` + + - Requirements: the key exists + + - Effects: returns the object with key ``key`` + + - Throws: ``bad_ptr_container_operation`` if the key does not exist + +.. _`pointer container requirements`: + +Semantics: pointer container requirements +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``void transfer( iterator object, ptr_multimap_adapter& from );`` + + - Requirements: ``not from.empty()`` + + - Effects: Inserts the object defined by ``object`` into the container and remove it from ``from``. + + - Postconditions: ``size()`` is one more, ``from.size()`` is one less. + + - Exception safety: Strong guarantee + +- ``void transfer( iterator first, iterator last, ptr_multimap_adapter& from );`` + + - Requirements: ``not from.empty()`` + + - Effects: Inserts the objects defined by the range ``[first,last)`` into the container and remove it from ``from``. + + - Postconditions: Let ``N == std::distance(first,last);`` then ``size()`` is ``N`` more, ``from.size()`` is ``N`` less. + + - Exception safety: Basic guarantee + +- ``template< class Range > void transfer( const Range& r, ptr_multimap_adapter& from );`` + + - Effects: ``transfer( boost::begin(r), boost::end(r), from );`` + +- ``void transfer( ptr_multimap_adapter& from );`` + + - Effects: ``transfer( from.begin(), from.end(), from );``. + + - Postconditions: ``from.empty();`` + + - Exception safety: Basic guarantee + +.. raw:: html + + <hr> + +:Copyright: Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). + +__ http://www.boost.org/LICENSE_1_0.txt + + diff --git a/libs/ptr_container/doc/ptr_multiset.html b/libs/ptr_container/doc/ptr_multiset.html new file mode 100644 index 0000000000..b1c65be7a6 --- /dev/null +++ b/libs/ptr_container/doc/ptr_multiset.html @@ -0,0 +1,362 @@ +<?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: 2007-11-25 13:38:02 -0500 (Sun, 25 Nov 2007) $ +:Revision: $Revision: 41370 $ +: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="class-ptr-multiset">Class <tt class="docutils literal"><span class="pre">ptr_multiset</span></tt></h2> +<p>A <tt class="docutils literal"><span class="pre">ptr_multiset<T></span></tt> is a pointer container that uses an underlying <tt class="docutils literal"><span class="pre">std::multiset<void*></span></tt> +to store the pointers.</p> +<p><strong>Hierarchy:</strong></p> +<ul class="simple"> +<li><a class="reference" href="reversible_ptr_container.html">reversible_ptr_container</a><ul> +<li><a class="reference" href="associative_ptr_container.html">associative_ptr_container</a><ul> +<li><a class="reference" href="ptr_set_adapter.html">ptr_set_adapter</a></li> +<li><a class="reference" href="ptr_multiset_adapter.html">ptr_multiset_adapter</a></li> +<li><a class="reference" href="ptr_map_adapter.html">ptr_map_adapter</a></li> +<li><a class="reference" href="ptr_multimap_adapter.html">ptr_multi_map_adapter</a><ul> +<li><a class="reference" href="ptr_set.html">ptr_set</a></li> +<li><tt class="docutils literal"><span class="pre">ptr_multi_set</span></tt></li> +<li><a class="reference" href="ptr_map.html">ptr_map</a></li> +<li><a class="reference" href="ptr_multimap.html">ptr_multimap</a></li> +</ul> +</li> +</ul> +</li> +</ul> +</li> +</ul> +<p><strong>See also:</strong></p> +<ul class="simple"> +<li><a class="reference" href="indirect_fun.html">void_ptr_indirect_fun</a></li> +</ul> +<p><strong>Navigate:</strong></p> +<ul class="simple"> +<li><a class="reference" href="ptr_container.html">home</a></li> +<li><a class="reference" href="reference.html">reference</a></li> +</ul> +<p><strong>Synopsis:</strong></p> +<pre class="literal-block"> +namespace boost +{ + + template + < + class Key, + class Compare = std::less<Key>, + class CloneAllocator = heap_clone_allocator, + class Allocator = std::allocator<void*> + > + class ptr_multiset : public ptr_multiset_adapter + < + Key, + std::multiset<void*,void_ptr_indirect_fun<Compare,Key>,Allocator>, + CloneAllocator + > + { + // see references + + }; // class 'ptr_multiset' + +} // namespace 'boost' +</pre> +<p><strong>Remarks:</strong></p> +<ul class="simple"> +<li>Using <tt class="docutils literal"><span class="pre">nullable<T></span></tt> as <tt class="docutils literal"><span class="pre">Key</span></tt> is meaningless and is not allowed</li> +</ul> +<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> +</body> +</html> diff --git a/libs/ptr_container/doc/ptr_multiset.rst b/libs/ptr_container/doc/ptr_multiset.rst new file mode 100644 index 0000000000..120891bdb7 --- /dev/null +++ b/libs/ptr_container/doc/ptr_multiset.rst @@ -0,0 +1,79 @@ +++++++++++++++++++++++++++++++++++ + |Boost| Pointer Container Library +++++++++++++++++++++++++++++++++++ + +.. |Boost| image:: boost.png + +Class ``ptr_multiset`` +---------------------- + +A ``ptr_multiset<T>`` is a pointer container that uses an underlying ``std::multiset<void*>`` +to store the pointers. + +**Hierarchy:** + +- `reversible_ptr_container <reversible_ptr_container.html>`_ + + - `associative_ptr_container <associative_ptr_container.html>`_ + + - `ptr_set_adapter <ptr_set_adapter.html>`_ + - `ptr_multiset_adapter <ptr_multiset_adapter.html>`_ + - `ptr_map_adapter <ptr_map_adapter.html>`_ + - `ptr_multi_map_adapter <ptr_multimap_adapter.html>`_ + + - `ptr_set <ptr_set.html>`_ + - ``ptr_multi_set`` + - `ptr_map <ptr_map.html>`_ + - `ptr_multimap <ptr_multimap.html>`_ + +**See also:** + +- `void_ptr_indirect_fun <indirect_fun.html>`_ + +**Navigate:** + +- `home <ptr_container.html>`_ +- `reference <reference.html>`_ + + +**Synopsis:** + +.. parsed-literal:: + + + namespace boost + { + + template + < + class Key, + class Compare = std::less<Key>, + class CloneAllocator = heap_clone_allocator, + class Allocator = std::allocator<void*> + > + class ptr_multiset : public ptr_multiset_adapter + < + Key, + std::multiset<void*,void_ptr_indirect_fun<Compare,Key>,Allocator>, + CloneAllocator + > + { + // see references + + }; // class 'ptr_multiset' + + } // namespace 'boost' + +**Remarks:** + +- Using ``nullable<T>`` as ``Key`` is meaningless and is not allowed + +.. raw:: html + + <hr> + +:Copyright: Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). + +__ http://www.boost.org/LICENSE_1_0.txt + + diff --git a/libs/ptr_container/doc/ptr_multiset_adapter.html b/libs/ptr_container/doc/ptr_multiset_adapter.html new file mode 100644 index 0000000000..2530661af5 --- /dev/null +++ b/libs/ptr_container/doc/ptr_multiset_adapter.html @@ -0,0 +1,432 @@ +<?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: 2006-11-22 17:01:03 -0500 (Wed, 22 Nov 2006) $ +:Revision: $Revision: 36152 $ +: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> +<div class="section"> +<h1><a id="class-ptr-multiset-adapter" name="class-ptr-multiset-adapter">Class <tt class="docutils literal"><span class="pre">ptr_multiset_adapter</span></tt></a></h1> +<p>This class is used to build custom pointer containers with +an underlying multiset-like container. The interface of the class is an extension +of the interface from <tt class="docutils literal"><span class="pre">associative_ptr_container</span></tt>.</p> +<p><strong>Hierarchy:</strong></p> +<ul class="simple"> +<li><a class="reference" href="reversible_ptr_container.html">reversible_ptr_container</a><ul> +<li><a class="reference" href="associative_ptr_container.html">associative_ptr_container</a><ul> +<li><a class="reference" href="ptr_set_adapter.html">ptr_set_adapter</a></li> +<li><tt class="docutils literal"><span class="pre">ptr_multiset_adapter</span></tt></li> +<li><a class="reference" href="ptr_map_adapter.html">ptr_map_adapter</a></li> +<li><a class="reference" href="ptr_multimap_adapter.html">ptr_multi_map_adapter</a><ul> +<li><a class="reference" href="ptr_set.html">ptr_set</a></li> +<li><a class="reference" href="ptr_multiset.html">ptr_multi_set</a></li> +<li><a class="reference" href="ptr_map.html">ptr_map</a></li> +<li><a class="reference" href="ptr_multimap.html">ptr_multimap</a></li> +</ul> +</li> +</ul> +</li> +</ul> +</li> +</ul> +<p><strong>Navigate:</strong></p> +<ul class="simple"> +<li><a class="reference" href="ptr_container.html">home</a></li> +<li><a class="reference" href="reference.html">reference</a></li> +</ul> +<p><strong>Synopsis:</strong></p> +<pre class="literal-block"> +namespace boost +{ + template + < + class Key, + class VoidPtrMultiSet, + class CloneAllocator = heap_clone_allocator + > + class ptr_multiset_adapter + { + + public: // <a class="reference" href="#modifiers">modifiers</a> + iterator insert( Key* x ); + template< class Key2 > + iterator insert( std::auto_ptr<Key2> x ); + + public: // <a class="reference" href="#pointer-container-requirements">pointer container requirements</a> + void transfer( iterator object, ptr_multiset_adapter& from ); + size_type transfer( iterator first, iterator last, ptr_multiset_adapter& from ); + template< class Range > + size_type transfer( const Range& r, ptr_multiset_adapter& from ); + void transfer( ptr_multiset_adapter& from ); + + }; // class 'ptr_multiset_adapter' + +} // namespace 'boost' +</pre> +</div> +<div class="section"> +<h1><a id="semantics" name="semantics">Semantics</a></h1> +<div class="section"> +<h2><a id="semantics-modifiers" name="semantics-modifiers"><span id="modifiers"></span>Semantics: modifiers</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">iterator</span> <span class="pre">insert(</span> <span class="pre">key_type*</span> <span class="pre">x</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">x</span> <span class="pre">!=</span> <span class="pre">0</span></tt></li> +<li>Effects: Takes ownership of <tt class="docutils literal"><span class="pre">x</span></tt>. The returned iterator points to the element with key <tt class="docutils literal"><span class="pre">x</span></tt>.</li> +<li>Throws: bad_pointer if <tt class="docutils literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">0</span></tt></li> +<li>Exception safety: Strong guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">Key2</span> <span class="pre">></span> <span class="pre">iterator</span> <span class="pre">insert(</span> <span class="pre">std::auto_ptr<Key2></span> <span class="pre">x</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: <tt class="docutils literal"><span class="pre">return</span> <span class="pre">insert(</span> <span class="pre">x.release()</span> <span class="pre">);</span></tt></li> +</ul> +</blockquote> +</li> +</ul> +<!-- - ``iterator insert( const key_type& x );`` + +- Effects: ``return insert( allocate_clone( x ) );`` + +- Exception safety: Strong guarantee --> +</div> +<div class="section"> +<h2><a id="semantics-pointer-container-requirements" name="semantics-pointer-container-requirements"><span id="pointer-container-requirements"></span>Semantics: pointer container requirements</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">transfer(</span> <span class="pre">iterator</span> <span class="pre">object,</span> <span class="pre">ptr_multiset_adapter&</span> <span class="pre">from</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">not</span> <span class="pre">from.empty()</span></tt></li> +<li>Effects: Inserts the object defined by <tt class="docutils literal"><span class="pre">object</span></tt> into the container and remove it from <tt class="docutils literal"><span class="pre">from</span></tt>.</li> +<li>Postconditions: <tt class="docutils literal"><span class="pre">size()</span></tt> is one more, <tt class="docutils literal"><span class="pre">from.size()</span></tt> is one less.</li> +<li>Exception safety: Strong guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">transfer(</span> <span class="pre">iterator</span> <span class="pre">first,</span> <span class="pre">iterator</span> <span class="pre">last,</span> <span class="pre">ptr_multiset_adapter&</span> <span class="pre">from</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">not</span> <span class="pre">from.empty()</span></tt></li> +<li>Effects: Inserts the objects defined by the range <tt class="docutils literal"><span class="pre">[first,last)</span></tt> into the container and remove it from <tt class="docutils literal"><span class="pre">from</span></tt>.</li> +<li>Postconditions: Let <tt class="docutils literal"><span class="pre">N</span> <span class="pre">==</span> <span class="pre">std::distance(first,last);</span></tt> then <tt class="docutils literal"><span class="pre">size()</span></tt> is <tt class="docutils literal"><span class="pre">N</span></tt> more, <tt class="docutils literal"><span class="pre">from.size()</span></tt> is <tt class="docutils literal"><span class="pre">N</span></tt> less.</li> +<li>Exception safety: Basic guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">Range</span> <span class="pre">></span> <span class="pre">void</span> <span class="pre">transfer(</span> <span class="pre">const</span> <span class="pre">Range&</span> <span class="pre">r,</span> <span class="pre">ptr_multiset_adapter&</span> <span class="pre">from</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: <tt class="docutils literal"><span class="pre">transfer(</span> <span class="pre">boost::begin(r),</span> <span class="pre">boost::end(r),</span> <span class="pre">from</span> <span class="pre">);</span></tt></li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">transfer(</span> <span class="pre">ptr_multiset_adapter&</span> <span class="pre">from</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: <tt class="docutils literal"><span class="pre">transfer(</span> <span class="pre">from.begin(),</span> <span class="pre">from.end(),</span> <span class="pre">from</span> <span class="pre">);</span></tt>.</li> +<li>Postconditions: <tt class="docutils literal"><span class="pre">from.empty();</span></tt></li> +<li>Exception safety: Basic guarantee</li> +</ul> +</blockquote> +</li> +</ul> +<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> +</div> +</body> +</html> diff --git a/libs/ptr_container/doc/ptr_multiset_adapter.rst b/libs/ptr_container/doc/ptr_multiset_adapter.rst new file mode 100644 index 0000000000..b1000bd87a --- /dev/null +++ b/libs/ptr_container/doc/ptr_multiset_adapter.rst @@ -0,0 +1,143 @@ +++++++++++++++++++++++++++++++++++ + |Boost| Pointer Container Library +++++++++++++++++++++++++++++++++++ + +.. |Boost| image:: boost.png + +Class ``ptr_multiset_adapter`` +------------------------------ + +This class is used to build custom pointer containers with +an underlying multiset-like container. The interface of the class is an extension +of the interface from ``associative_ptr_container``. + +**Hierarchy:** + +- `reversible_ptr_container <reversible_ptr_container.html>`_ + + - `associative_ptr_container <associative_ptr_container.html>`_ + + - `ptr_set_adapter <ptr_set_adapter.html>`_ + - ``ptr_multiset_adapter`` + - `ptr_map_adapter <ptr_map_adapter.html>`_ + - `ptr_multi_map_adapter <ptr_multimap_adapter.html>`_ + + - `ptr_set <ptr_set.html>`_ + - `ptr_multi_set <ptr_multiset.html>`_ + - `ptr_map <ptr_map.html>`_ + - `ptr_multimap <ptr_multimap.html>`_ + +**Navigate:** + +- `home <ptr_container.html>`_ +- `reference <reference.html>`_ + +**Synopsis:** + +.. parsed-literal:: + + + namespace boost + { + template + < + class Key, + class VoidPtrMultiSet, + class CloneAllocator = heap_clone_allocator + > + class ptr_multiset_adapter + { + + public: // `modifiers`_ + iterator insert( Key* x ); + template< class Key2 > + iterator insert( std::auto_ptr<Key2> x ); + + public: // `pointer container requirements`_ + void transfer( iterator object, ptr_multiset_adapter& from ); + size_type transfer( iterator first, iterator last, ptr_multiset_adapter& from ); + template< class Range > + size_type transfer( const Range& r, ptr_multiset_adapter& from ); + void transfer( ptr_multiset_adapter& from ); + + }; // class 'ptr_multiset_adapter' + + } // namespace 'boost' + + +Semantics +--------- + +.. _`modifiers`: + +Semantics: modifiers +^^^^^^^^^^^^^^^^^^^^ + +- ``iterator insert( key_type* x );`` + + - Requirements: ``x != 0`` + + - Effects: Takes ownership of ``x``. The returned iterator points to the element with key ``x``. + + - Throws: bad_pointer if ``x == 0`` + + - Exception safety: Strong guarantee + + +- ``template< class Key2 > iterator insert( std::auto_ptr<Key2> x );`` + + - Effects: ``return insert( x.release() );`` + +.. + - ``iterator insert( const key_type& x );`` + + - Effects: ``return insert( allocate_clone( x ) );`` + + - Exception safety: Strong guarantee + +.. _`pointer container requirements`: + +Semantics: pointer container requirements +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``void transfer( iterator object, ptr_multiset_adapter& from );`` + + - Requirements: ``not from.empty()`` + + - Effects: Inserts the object defined by ``object`` into the container and remove it from ``from``. + + - Postconditions: ``size()`` is one more, ``from.size()`` is one less. + + - Exception safety: Strong guarantee + +- ``void transfer( iterator first, iterator last, ptr_multiset_adapter& from );`` + + - Requirements: ``not from.empty()`` + + - Effects: Inserts the objects defined by the range ``[first,last)`` into the container and remove it from ``from``. + + - Postconditions: Let ``N == std::distance(first,last);`` then ``size()`` is ``N`` more, ``from.size()`` is ``N`` less. + + - Exception safety: Basic guarantee + +- ``template< class Range > void transfer( const Range& r, ptr_multiset_adapter& from );`` + + - Effects: ``transfer( boost::begin(r), boost::end(r), from );`` + +- ``void transfer( ptr_multiset_adapter& from );`` + + - Effects: ``transfer( from.begin(), from.end(), from );``. + + - Postconditions: ``from.empty();`` + + - Exception safety: Basic guarantee + +.. raw:: html + + <hr> + +:Copyright: Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). + +__ http://www.boost.org/LICENSE_1_0.txt + + diff --git a/libs/ptr_container/doc/ptr_sequence_adapter.html b/libs/ptr_container/doc/ptr_sequence_adapter.html new file mode 100644 index 0000000000..4572c134bb --- /dev/null +++ b/libs/ptr_container/doc/ptr_sequence_adapter.html @@ -0,0 +1,768 @@ +<?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: 2008-07-16 17:03:47 -0400 (Wed, 16 Jul 2008) $ +:Revision: $Revision: 47494 $ +: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> +<div class="section"> +<h1><a id="class-ptr-sequence-adapter" name="class-ptr-sequence-adapter">Class <tt class="docutils literal"><span class="pre">ptr_sequence_adapter</span></tt></a></h1> +<p>This section describes all the common operations for all the pointer +sequences:</p> +<ul class="simple"> +<li><a class="reference" href="ptr_vector.html">ptr_vector</a></li> +<li><a class="reference" href="ptr_list.html">ptr_list</a></li> +<li><a class="reference" href="ptr_deque.html">ptr_deque</a></li> +</ul> +<p>The <tt class="docutils literal"><span class="pre">ptr_sequence_adapter</span></tt> is also a concrete class that you can use to create custom pointer +containers from.</p> +<p><strong>Hierarchy:</strong></p> +<ul class="simple"> +<li><a class="reference" href="reversible_ptr_container.html">reversible_ptr_container</a><ul> +<li><tt class="docutils literal"><span class="pre">ptr_sequence_adapter</span></tt><ul> +<li><a class="reference" href="ptr_vector.html">ptr_vector</a></li> +<li><a class="reference" href="ptr_list.html">ptr_list</a></li> +<li><a class="reference" href="ptr_deque.html">ptr_deque</a></li> +<li><a class="reference" href="ptr_array.html">ptr_array</a></li> +</ul> +</li> +</ul> +</li> +</ul> +<p><strong>Navigate:</strong></p> +<ul class="simple"> +<li><a class="reference" href="ptr_container.html">home</a></li> +<li><a class="reference" href="reference.html">reference</a></li> +</ul> +<p><strong>Synopsis:</strong></p> +<pre class="literal-block"> +namespace boost +{ + + template + < + class T, + class VoidPtrSeq, + class CloneAllocator = heap_clone_allocator + > + class ptr_sequence_adapter + { + public: // <a class="reference" href="#construct-copy-destroy">construct/copy/destroy</a> + template< class InputIterator > + assign( InputIterator first, InputIterator last ); + template< class InputRange > + assign( const InputRange& e ); + + public: // <a class="reference" href="#element-access">element access</a> + T& front(); + const T& front() const; + T& back(); + const T& back() const; + + public: // <a class="reference" href="#modifiers">modifiers</a> + void push_back( T* x ); + template< class U > + void push_back( std::auto_ptr<U> x ); + auto_type pop_back(); + iterator insert( iterator position, T* x ); + template< class U > + iterator insert( iterator position, std::auto_ptr<U> x ); + template< class InputIterator > + void insert( iterator position, InputIterator first, InputIterator last ); + template< class InputRange > + void insert( iterator position, const InputRange& r ); + iterator erase( iterator position ); + iterator erase( iterator first, iterator last ); + template< class Range > + iterator erase( const Range& r ); + void resize( size_type size ); + void resize( size_type size, T* to_clone ); + + public: // <a class="reference" href="#pointer-container-requirements">pointer container requirements</a> + template< class PtrSequence > + void transfer( iterator before, typename PtrSequence::iterator object, + PtrSequence& from ); + template< class PtrSequence > + void transfer( iterator before, typename PtrSequence::iterator first, typename PtrSequence::iterator last, + PtrSequence& from ); + void template< class PtrSequence, class Range > + void transfer( iterator before, const Range& r, PtrSequence& from ); + template< class PtrSequence > + void transfer( iterator before, PtrSequence& from ); + + public: // <a class="reference" href="#algorithms">algorithms</a> + + void sort(); + void sort( iterator first, iterator last ); + template< class Compare > + void sort( Compare comp ); + template< class Compare > + void sort( iterator begin, iterator end, Compare comp ); + + void unique(); + void unique( iterator first, iterator last ); + template< class Compare > + void unique( Compare comp ); + template< class Compare > + void unique( iterator begin, iterator end, Compare comp ); + + template< class Pred > + void erase_if( Pred pred ); + template< class Pred > + void erase_if( iterator begin, iterator end, Pred pred ); + + void merge( ptr_sequence_adapter& r ); + template< class Compare > + void merge( ptr_sequence_adapter& r, Compare comp ); + void merge( iterator first, iterator last, ptr_sequence_adapter& from ); + template< class Compare > + void merge( iterator first, iterator last, ptr_sequence_adapter& from, Compare comp ); + + public: // <a class="reference" href="ptr_list.html">ptr_list interface</a> + + public: // <a class="reference" href="ptr_vector.html">ptr_vector interface</a> + + public: // <a class="reference" href="ptr_deque.html">ptr_deque interface</a> + + }; // class 'ptr_sequence_adapter' + +} // namespace 'boost' +</pre> +</div> +<div class="section"> +<h1><a id="semantics" name="semantics">Semantics</a></h1> +<div class="section"> +<h2><a id="semantics-construct-copy-destroy" name="semantics-construct-copy-destroy"><span id="construct-copy-destroy"></span>Semantics: construct/copy/destroy</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">InputIterator</span> <span class="pre">></span> +<span class="pre">void</span> <span class="pre">assign(</span> <span class="pre">InputIterator</span> <span class="pre">first,</span> <span class="pre">InputIterator</span> <span class="pre">last</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">(first,last]</span></tt> is a valid range</li> +<li>Effects: <tt class="docutils literal"><span class="pre">clear();</span> <span class="pre">insert(</span> <span class="pre">first,</span> <span class="pre">last</span> <span class="pre">);</span></tt></li> +<li>Postconditions: <tt class="docutils literal"><span class="pre">size()</span> <span class="pre">==</span> <span class="pre">std::distance(</span> <span class="pre">first,</span> <span class="pre">last</span> <span class="pre">);</span></tt></li> +<li>Exception safety: strong guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">InputRange</span> <span class="pre">></span> +<span class="pre">void</span> <span class="pre">assign(</span> <span class="pre">const</span> <span class="pre">InputRange&</span> <span class="pre">r</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: <tt class="docutils literal"><span class="pre">assign(</span> <span class="pre">boost::begin(r),</span> <span class="pre">boost::end(r)</span> <span class="pre">);</span></tt></li> +</ul> +</blockquote> +</li> +</ul> +<!-- - ``assign( size_type n, const T& u )`` + +- Effects: ``clear(); insert( begin(), n, u );`` + +- Postconditions: ``size() == n`` + +- Exception safety: Strong guarantee --> +<!-- void resize( size_type sz, const T& x ); +Effects: + +if ( sz > size() ) + insert( end(), sz-size(), x ); + else if ( sz < size() ) + erase( begin()+sz, end() ); + else + ; //do nothing + +Postconditions: size() == sz + +Exception safety: Strong guarantee --> +</div> +<div class="section"> +<h2><a id="semantics-element-access" name="semantics-element-access"><span id="element-access"></span>Semantics: element access</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">T&</span> <span class="pre">front();</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">not</span> <span class="pre">empty();</span></tt></li> +<li>Effects: <tt class="docutils literal"><span class="pre">return</span> <span class="pre">*begin();</span></tt></li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">const</span> <span class="pre">T&</span> <span class="pre">front()</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">not</span> <span class="pre">empty();</span></tt></li> +<li>Effects: <tt class="docutils literal"><span class="pre">return</span> <span class="pre">*begin();</span></tt></li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">T&</span> <span class="pre">back();</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">not</span> <span class="pre">empty();</span></tt></li> +<li>Effects: <tt class="docutils literal"><span class="pre">return</span> <span class="pre">*--end();</span></tt></li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">const</span> <span class="pre">T&</span> <span class="pre">back()</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">not</span> <span class="pre">empty();</span></tt></li> +<li>Effects: <tt class="docutils literal"><span class="pre">return</span> <span class="pre">*--end();</span></tt></li> +</ul> +</blockquote> +</li> +</ul> +</div> +<div class="section"> +<h2><a id="semantics-modifiers" name="semantics-modifiers"><span id="modifiers"></span>Semantics: modifiers</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">push_back(</span> <span class="pre">T*</span> <span class="pre">x</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">x</span> <span class="pre">!=</span> <span class="pre">0</span></tt></li> +<li>Effects: Inserts the pointer into container and takes ownership of it</li> +<li>Throws: <tt class="docutils literal"><span class="pre">bad_pointer</span></tt> if <tt class="docutils literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">0</span></tt></li> +<li>Exception safety: Strong guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">U</span> <span class="pre">></span> <span class="pre">void</span> <span class="pre">push_back(</span> <span class="pre">std::auto_ptr<U></span> <span class="pre">x</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: <tt class="docutils literal"><span class="pre">push_back(</span> <span class="pre">x.release()</span> <span class="pre">);</span></tt></li> +</ul> +</blockquote> +</li> +</ul> +<!-- - ``void push_back( const T& x );`` + +- Effects: ``push_back( CloneAllocator::clone( x ) );`` + +- Exception safety: Strong guarantee --> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">auto_type</span> <span class="pre">pop_back();</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements:<tt class="docutils literal"><span class="pre">not</span> <span class="pre">empty()</span></tt></li> +<li>Effects: Removes the last element in the container</li> +<li>Postconditions: <tt class="docutils literal"><span class="pre">size()</span></tt> is one less</li> +<li>Throws: <tt class="docutils literal"><span class="pre">bad_ptr_container_operation</span></tt> if <tt class="docutils literal"><span class="pre">empty()</span> <span class="pre">==</span> <span class="pre">true</span></tt></li> +<li>Exception safety: Strong guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">iterator</span> <span class="pre">insert(</span> <span class="pre">iterator</span> <span class="pre">position,</span> <span class="pre">T*</span> <span class="pre">x</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">position</span></tt> is a valid iterator from the container and +<tt class="docutils literal"><span class="pre">x</span> <span class="pre">!=</span> <span class="pre">0</span></tt></li> +<li>Effects: Inserts <tt class="docutils literal"><span class="pre">x</span></tt> before <tt class="docutils literal"><span class="pre">position</span></tt> and returns an iterator pointing to it</li> +<li>Throws: <tt class="docutils literal"><span class="pre">bad_pointer</span></tt> if <tt class="docutils literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">0</span></tt></li> +<li>Exception safety: Strong guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">U</span> <span class="pre">></span> <span class="pre">iterator</span> <span class="pre">insert(</span> <span class="pre">iterator</span> <span class="pre">position,</span> <span class="pre">std::auto_ptr<U></span> <span class="pre">x</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: <tt class="docutils literal"><span class="pre">return</span> <span class="pre">insert(</span> <span class="pre">position,</span> <span class="pre">x.release()</span> <span class="pre">);</span></tt></li> +</ul> +</blockquote> +</li> +</ul> +<!-- - ``iterator insert( iterator position, const T& x );`` + +- Requirements: ``position`` is a valid iterator from the container + +- Effects: ``return insert( position, CloneAllocator::clone( x ) );`` + +- Exception safety: Strong guarantee + +- ``void insert( iterator position, size_type n, const T& x );`` + +- Requirements: ``position`` is a valid iterator from the container + +- Effects: Inserts ``n`` clones of ``x`` before position into the container + +- Exception safety: Strong guarantee --> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">InputIterator</span> <span class="pre">></span> +<span class="pre">void</span> <span class="pre">insert(</span> <span class="pre">iterator</span> <span class="pre">position,</span> <span class="pre">InputIterator</span> <span class="pre">first,</span> <span class="pre">InputIterator</span> <span class="pre">last</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">position</span></tt> is a valid iterator from the container</li> +<li>Effects: Inserts a cloned range before <tt class="docutils literal"><span class="pre">position</span></tt></li> +<li>Exception safety: Strong guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">InputRange</span> <span class="pre">></span> +<span class="pre">void</span> <span class="pre">insert(</span> <span class="pre">iterator</span> <span class="pre">position,</span> <span class="pre">const</span> <span class="pre">InputRange&</span> <span class="pre">r</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: <tt class="docutils literal"><span class="pre">insert(</span> <span class="pre">position,</span> <span class="pre">boost::begin(r),</span> <span class="pre">boost::end(r)</span> <span class="pre">);</span></tt></li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">iterator</span> <span class="pre">erase(</span> <span class="pre">iterator</span> <span class="pre">position</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">position</span></tt> is a valid iterator from the container</li> +<li>Effects: Removes the element defined by <tt class="docutils literal"><span class="pre">position</span></tt> and returns an iterator to the following element</li> +<li>Throws: Nothing</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">iterator</span> <span class="pre">erase(</span> <span class="pre">iterator</span> <span class="pre">first,</span> <span class="pre">iterator</span> <span class="pre">last</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">[first,last)</span></tt> is a valid range</li> +<li>Effects: Removes the range of element defined by <tt class="docutils literal"><span class="pre">[first,last)</span></tt> and returns an iterator to the following element</li> +<li>Throws: Nothing</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">Range</span> <span class="pre">></span> +<span class="pre">void</span> <span class="pre">erase(</span> <span class="pre">const</span> <span class="pre">Range&</span> <span class="pre">r</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: <tt class="docutils literal"><span class="pre">erase(</span> <span class="pre">boost::begin(r),</span> <span class="pre">boost::end(r)</span> <span class="pre">);</span></tt></li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">resize(</span> <span class="pre">size_type</span> <span class="pre">size</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Resizes the container. If elements are erased, it happens from the back. If elements are inserted, it happens at the back.</li> +<li>Requirements: <tt class="docutils literal"><span class="pre">T</span></tt> is default constructible</li> +<li>Postcondition: <tt class="docutils literal"><span class="pre">size()</span> <span class="pre">==</span> <span class="pre">size;</span></tt></li> +<li>Exception safety: Basic guarantee under expansion; nothrow guarantee otherwise</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">resize(</span> <span class="pre">size_type</span> <span class="pre">size,</span> <span class="pre">T*</span> <span class="pre">to_clone</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Resizes the container. If elements are erased, it happens from the back. If elements are inserted, clones of <tt class="docutils literal"><span class="pre">*to_clone</span></tt> are inserted at the back.</li> +<li>Postcondition: <tt class="docutils literal"><span class="pre">size()</span> <span class="pre">==</span> <span class="pre">size;</span></tt></li> +<li>Exception safety: Basic guarantee under expansion; nothrow guarantee otherwise</li> +<li>Remarks: <tt class="docutils literal"><span class="pre">to_clone</span> <span class="pre">==</span> <span class="pre">0</span></tt> is valid if the container supports nulls. The container does not take ownership of <tt class="docutils literal"><span class="pre">to_clone</span></tt>.</li> +</ul> +</blockquote> +</li> +</ul> +</div> +<div class="section"> +<h2><a id="semantics-pointer-container-requirements" name="semantics-pointer-container-requirements"><span id="pointer-container-requirements"></span>Semantics: pointer container requirements</a></h2> +<p>You can use <tt class="docutils literal"><span class="pre">transfer()</span></tt> to move elements between two containers of the same type. Furthermore, +you can also move elements from a container of type <tt class="docutils literal"><span class="pre">T</span></tt> to a container of type <tt class="docutils literal"><span class="pre">U</span></tt> as long as +<tt class="docutils literal"><span class="pre">T::value_type</span></tt> is convertible to <tt class="docutils literal"><span class="pre">U::value_type</span></tt>. An example would be transferring from <tt class="docutils literal"><span class="pre">boost::ptr_vector<Derived></span></tt> +to <tt class="docutils literal"><span class="pre">boost::ptr_deque<Base></span></tt>.</p> +<p>(<strong>Remark:</strong> <em>When moving elements between two different containers, it is your responsibility to make sure the allocators are compatible.</em> +<em>The special latitude of being able to transfer between two different containers is only available for Sequences and not for Associative Containers.</em>)</p> +<!-- --> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">PtrSequence</span> <span class="pre">></span> <span class="pre">void</span> <span class="pre">transfer(</span> <span class="pre">iterator</span> <span class="pre">before,</span> <span class="pre">typename</span> <span class="pre">PtrSequence::iterator</span> <span class="pre">object,</span> <span class="pre">PtrSequence&</span> <span class="pre">from</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Inserts the object defined by <tt class="docutils literal"><span class="pre">object</span></tt> into the container and remove it from <tt class="docutils literal"><span class="pre">from</span></tt>. +Insertion takes place before <tt class="docutils literal"><span class="pre">before</span></tt>.</li> +<li>Postconditions: If <tt class="docutils literal"><span class="pre">from.empty()</span></tt>, nothing happens. Otherwise +<tt class="docutils literal"><span class="pre">size()</span></tt> is one more, <tt class="docutils literal"><span class="pre">from.size()</span></tt> is one less.</li> +<li>Exception safety: Strong guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">PtrSequence</span> <span class="pre">></span> <span class="pre">void</span> <span class="pre">transfer(</span> <span class="pre">iterator</span> <span class="pre">before,</span> <span class="pre">typename</span> <span class="pre">PtrSequence::iterator</span> <span class="pre">first,</span> <span class="pre">typename</span> <span class="pre">PtrSequence::iterator</span> <span class="pre">last,</span> <span class="pre">PtrSequence&</span> <span class="pre">from</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">from.size()</span> <span class="pre">>=</span> <span class="pre">std::distance(first,last)</span></tt></li> +<li>Effects: Inserts the objects defined by the range <tt class="docutils literal"><span class="pre">[first,last)</span></tt> into the container and remove it from <tt class="docutils literal"><span class="pre">from</span></tt>. +Insertion takes place before <tt class="docutils literal"><span class="pre">before</span></tt>.</li> +<li>Postconditions: If <tt class="docutils literal"><span class="pre">from.empty()</span></tt>, nothing happens. Otherwise, +let <tt class="docutils literal"><span class="pre">N</span> <span class="pre">==</span> <span class="pre">std::distance(first,last);</span></tt> then <tt class="docutils literal"><span class="pre">size()</span></tt> is <tt class="docutils literal"><span class="pre">N</span></tt> more, <tt class="docutils literal"><span class="pre">from.size()</span></tt> is <tt class="docutils literal"><span class="pre">N</span></tt> less.</li> +<li>Exception safety: Strong guarantee</li> +<li>Complexity: Linear or better</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">template<</span> <span class="pre">class</span> <span class="pre">PtrSequence,</span> <span class="pre">class</span> <span class="pre">Range</span> <span class="pre">></span> <span class="pre">void</span> <span class="pre">transfer(</span> <span class="pre">iterator</span> <span class="pre">before,</span> <span class="pre">const</span> <span class="pre">Range&</span> <span class="pre">r,</span> <span class="pre">PtrSequence&</span> <span class="pre">from</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: <tt class="docutils literal"><span class="pre">transfer(before,</span> <span class="pre">boost::begin(r),</span> <span class="pre">boost::end(r),</span> <span class="pre">from);</span></tt></li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">PtrSequence></span> <span class="pre">void</span> <span class="pre">transfer(</span> <span class="pre">iterator</span> <span class="pre">before,</span> <span class="pre">PtrSequence&</span> <span class="pre">from</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: <tt class="docutils literal"><span class="pre">transfer(before,</span> <span class="pre">from,</span> <span class="pre">from);</span></tt></li> +</ul> +</blockquote> +</li> +</ul> +</div> +<div class="section"> +<h2><a id="semantics-algorithms" name="semantics-algorithms"><span id="algorithms"></span>Semantics: algorithms</a></h2> +<p>The general requirement for these algorithms is that the container <em>does not +contain any nulls</em>.</p> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">sort();</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">sort(</span> <span class="pre">iterator</span> <span class="pre">first,</span> <span class="pre">iterator</span> <span class="pre">last</span> <span class="pre">);</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">Compare</span> <span class="pre">></span> <span class="pre">void</span> <span class="pre">sort(</span> <span class="pre">Compare</span> <span class="pre">comp</span> <span class="pre">);</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">Compare</span> <span class="pre">></span> <span class="pre">void</span> <span class="pre">sort(</span> <span class="pre">iterator</span> <span class="pre">begin,</span> <span class="pre">iterator</span> <span class="pre">end,</span> <span class="pre">Compare</span> <span class="pre">comp</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: (versions without <tt class="docutils literal"><span class="pre">Compare</span></tt>) <tt class="docutils literal"><span class="pre">bool</span> <span class="pre">operator<(</span> <span class="pre">const</span> <span class="pre">T&,</span> <span class="pre">const</span> <span class="pre">T&</span> <span class="pre">)</span></tt> is defined</li> +<li>Requirements: (<tt class="docutils literal"><span class="pre">Compare</span></tt> versions) <tt class="docutils literal"><span class="pre">Compare</span></tt> must take <tt class="docutils literal"><span class="pre">const</span> <span class="pre">T&</span></tt> arguments</li> +<li>Effects: sorts the entire container or the specified range</li> +<li>Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws)</li> +<li>Remarks: The versions of <tt class="docutils literal"><span class="pre">sort()</span></tt> that take two iterators are not available for <tt class="docutils literal"><span class="pre">ptr_list</span></tt></li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">unique();</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">unique(</span> <span class="pre">iterator</span> <span class="pre">first,</span> <span class="pre">iterator</span> <span class="pre">last</span> <span class="pre">);</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">Compare</span> <span class="pre">></span> <span class="pre">void</span> <span class="pre">unique(</span> <span class="pre">Compare</span> <span class="pre">comp</span> <span class="pre">);</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">Compare</span> <span class="pre">></span> <span class="pre">void</span> <span class="pre">unique(</span> <span class="pre">iterator</span> <span class="pre">begin,</span> <span class="pre">iterator</span> <span class="pre">end,</span> <span class="pre">Compare</span> <span class="pre">comp</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: (versions without <tt class="docutils literal"><span class="pre">Compare</span></tt>) <tt class="docutils literal"><span class="pre">bool</span> <span class="pre">operator==(</span> <span class="pre">const</span> <span class="pre">T&,</span> <span class="pre">const</span> <span class="pre">T&</span> <span class="pre">)</span></tt> is defined</li> +<li>Requirements: (<tt class="docutils literal"><span class="pre">Compare</span></tt> versions) <tt class="docutils literal"><span class="pre">Compare</span></tt> must take <tt class="docutils literal"><span class="pre">const</span> <span class="pre">T&</span></tt> arguments</li> +<li>Effects: removes adjacent and equal objects from the entire container or the specified range</li> +<li>Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws)</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">Pred</span> <span class="pre">></span> <span class="pre">void</span> <span class="pre">erase_if(</span> <span class="pre">Pred</span> <span class="pre">pred</span> <span class="pre">);</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">Pred</span> <span class="pre">></span> <span class="pre">void</span> <span class="pre">erase_if(</span> <span class="pre">iterator</span> <span class="pre">begin,</span> <span class="pre">iterator</span> <span class="pre">end,</span> <span class="pre">Pred</span> <span class="pre">pred</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">Pred</span></tt> must take an <tt class="docutils literal"><span class="pre">const</span> <span class="pre">T&</span></tt> argument</li> +<li>Effects: removes all elements <tt class="docutils literal"><span class="pre">t</span></tt> for which <tt class="docutils literal"><span class="pre">pred(t)</span></tt> returns <tt class="docutils literal"><span class="pre">true</span></tt> from the entire container or the specified range</li> +<li>Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws)</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">merge(</span> <span class="pre">ptr_sequence_adapter&</span> <span class="pre">r</span> <span class="pre">);</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">Compare</span> <span class="pre">></span> <span class="pre">void</span> <span class="pre">merge(</span> <span class="pre">ptr_sequence_adapter&</span> <span class="pre">r,</span> <span class="pre">Compare</span> <span class="pre">comp</span> <span class="pre">);</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">merge(</span> <span class="pre">iterator</span> <span class="pre">first,</span> <span class="pre">iterator</span> <span class="pre">last,</span> <span class="pre">ptr_sequence_adapter&</span> <span class="pre">from</span> <span class="pre">);</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">Compare</span> <span class="pre">></span> <span class="pre">void</span> <span class="pre">merge(</span> <span class="pre">iterator</span> <span class="pre">first,</span> <span class="pre">iterator</span> <span class="pre">last,</span> <span class="pre">ptr_sequence_adapter&</span> <span class="pre">from,</span> <span class="pre">Compare</span> <span class="pre">comp</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: (<tt class="docutils literal"><span class="pre">Compare</span></tt> versions) <tt class="docutils literal"><span class="pre">Compare</span></tt> must take <tt class="docutils literal"><span class="pre">const</span> <span class="pre">T&</span></tt> arguments</li> +<li>Requirements: both sequences are sorted wrt. the same predicate</li> +<li>Effects: transfers the entire container or the specified sequence to the container while +ensuring the new sequence is also sorted</li> +<li>Postconditions: (Container versions) <tt class="docutils literal"><span class="pre">r.empty()</span></tt></li> +<li>Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws)</li> +</ul> +</blockquote> +</li> +</ul> +<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> +</div> +</body> +</html> diff --git a/libs/ptr_container/doc/ptr_sequence_adapter.rst b/libs/ptr_container/doc/ptr_sequence_adapter.rst new file mode 100644 index 0000000000..a6b57ab01f --- /dev/null +++ b/libs/ptr_container/doc/ptr_sequence_adapter.rst @@ -0,0 +1,452 @@ +++++++++++++++++++++++++++++++++++ + |Boost| Pointer Container Library +++++++++++++++++++++++++++++++++++ + +.. |Boost| image:: boost.png + +Class ``ptr_sequence_adapter`` +------------------------------ + +This section describes all the common operations for all the pointer +sequences: + +- `ptr_vector <ptr_vector.html>`_ +- `ptr_list <ptr_list.html>`_ +- `ptr_deque <ptr_deque.html>`_ + + +The ``ptr_sequence_adapter`` is also a concrete class that you can use to create custom pointer +containers from. + +**Hierarchy:** + +- `reversible_ptr_container <reversible_ptr_container.html>`_ + + - ``ptr_sequence_adapter`` + + - `ptr_vector <ptr_vector.html>`_ + - `ptr_list <ptr_list.html>`_ + - `ptr_deque <ptr_deque.html>`_ + - `ptr_array <ptr_array.html>`_ + +**Navigate:** + +- `home <ptr_container.html>`_ +- `reference <reference.html>`_ + + +**Synopsis:** + +.. parsed-literal:: + + namespace boost + { + + template + < + class T, + class VoidPtrSeq, + class CloneAllocator = heap_clone_allocator + > + class ptr_sequence_adapter + { + public: // `construct/copy/destroy`_ + template< class InputIterator > + assign( InputIterator first, InputIterator last ); + template< class InputRange > + assign( const InputRange& e ); + + public: // `element access`_ + T& front(); + const T& front() const; + T& back(); + const T& back() const; + + public: // `modifiers`_ + void push_back( T* x ); + template< class U > + void push_back( std::auto_ptr<U> x ); + auto_type pop_back(); + iterator insert( iterator position, T* x ); + template< class U > + iterator insert( iterator position, std::auto_ptr<U> x ); + template< class InputIterator > + void insert( iterator position, InputIterator first, InputIterator last ); + template< class InputRange > + void insert( iterator position, const InputRange& r ); + iterator erase( iterator position ); + iterator erase( iterator first, iterator last ); + template< class Range > + iterator erase( const Range& r ); + void resize( size_type size ); + void resize( size_type size, T* to_clone ); + + public: // `pointer container requirements`_ + template< class PtrSequence > + void transfer( iterator before, typename PtrSequence::iterator object, + PtrSequence& from ); + template< class PtrSequence > + void transfer( iterator before, typename PtrSequence::iterator first, typename PtrSequence::iterator last, + PtrSequence& from ); + void template< class PtrSequence, class Range > + void transfer( iterator before, const Range& r, PtrSequence& from ); + template< class PtrSequence > + void transfer( iterator before, PtrSequence& from ); + + public: // `algorithms`_ + + void sort(); + void sort( iterator first, iterator last ); + template< class Compare > + void sort( Compare comp ); + template< class Compare > + void sort( iterator begin, iterator end, Compare comp ); + + void unique(); + void unique( iterator first, iterator last ); + template< class Compare > + void unique( Compare comp ); + template< class Compare > + void unique( iterator begin, iterator end, Compare comp ); + + template< class Pred > + void erase_if( Pred pred ); + template< class Pred > + void erase_if( iterator begin, iterator end, Pred pred ); + + void merge( ptr_sequence_adapter& r ); + template< class Compare > + void merge( ptr_sequence_adapter& r, Compare comp ); + void merge( iterator first, iterator last, ptr_sequence_adapter& from ); + template< class Compare > + void merge( iterator first, iterator last, ptr_sequence_adapter& from, Compare comp ); + + public: // `ptr_list interface`_ + + public: // `ptr_vector interface`_ + + public: // `ptr_deque interface`_ + + }; // class 'ptr_sequence_adapter' + + } // namespace 'boost' + +.. _`ptr_list interface`: ptr_list.html +.. _`ptr_vector interface`: ptr_vector.html +.. _`ptr_deque interface`: ptr_deque.html + +Semantics +--------- + +.. _`construct/copy/destroy`: + +Semantics: construct/copy/destroy +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``template< class InputIterator > + void assign( InputIterator first, InputIterator last );`` + + - Requirements: ``(first,last]`` is a valid range + + - Effects: ``clear(); insert( first, last );`` + + - Postconditions: ``size() == std::distance( first, last );`` + + - Exception safety: strong guarantee + +- ``template< class InputRange > + void assign( const InputRange& r );`` + + - Effects: ``assign( boost::begin(r), boost::end(r) );`` + + +.. + - ``assign( size_type n, const T& u )`` + + - Effects: ``clear(); insert( begin(), n, u );`` + + - Postconditions: ``size() == n`` + + - Exception safety: Strong guarantee + + +.. + void resize( size_type sz, const T& x ); + Effects: + + if ( sz > size() ) + insert( end(), sz-size(), x ); + else if ( sz < size() ) + erase( begin()+sz, end() ); + else + ; //do nothing + + Postconditions: size() == sz + + Exception safety: Strong guarantee + + +.. _`element access`: + +Semantics: element access +^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``T& front();`` + + - Requirements: ``not empty();`` + + - Effects: ``return *begin();`` + + +- ``const T& front() const;`` + + - Requirements: ``not empty();`` + + - Effects: ``return *begin();`` + + +- ``T& back();`` + + - Requirements: ``not empty();`` + + - Effects: ``return *--end();`` + + +- ``const T& back() const;`` + + - Requirements: ``not empty();`` + + - Effects: ``return *--end();`` + + +.. _`modifiers`: + +Semantics: modifiers +^^^^^^^^^^^^^^^^^^^^ + +- ``void push_back( T* x );`` + + - Requirements: ``x != 0`` + + - Effects: Inserts the pointer into container and takes ownership of it + + - Throws: ``bad_pointer`` if ``x == 0`` + + - Exception safety: Strong guarantee + +- ``template< class U > void push_back( std::auto_ptr<U> x );`` + + - Effects: ``push_back( x.release() );`` + +.. + - ``void push_back( const T& x );`` + + - Effects: ``push_back( CloneAllocator::clone( x ) );`` + + - Exception safety: Strong guarantee + +- ``auto_type pop_back();`` + + - Requirements:``not empty()`` + + - Effects: Removes the last element in the container + + - Postconditions: ``size()`` is one less + + - Throws: ``bad_ptr_container_operation`` if ``empty() == true`` + + - Exception safety: Strong guarantee + + +- ``iterator insert( iterator position, T* x );`` + + - Requirements: ``position`` is a valid iterator from the container and + ``x != 0`` + + - Effects: Inserts ``x`` before ``position`` and returns an iterator pointing to it + + - Throws: ``bad_pointer`` if ``x == 0`` + + - Exception safety: Strong guarantee + +- ``template< class U > iterator insert( iterator position, std::auto_ptr<U> x );`` + + - Effects: ``return insert( position, x.release() );`` + +.. + - ``iterator insert( iterator position, const T& x );`` + + - Requirements: ``position`` is a valid iterator from the container + + - Effects: ``return insert( position, CloneAllocator::clone( x ) );`` + + - Exception safety: Strong guarantee + + - ``void insert( iterator position, size_type n, const T& x );`` + + - Requirements: ``position`` is a valid iterator from the container + + - Effects: Inserts ``n`` clones of ``x`` before position into the container + + - Exception safety: Strong guarantee + +- ``template< class InputIterator > + void insert( iterator position, InputIterator first, InputIterator last );`` + + - Requirements: ``position`` is a valid iterator from the container + + - Effects: Inserts a cloned range before ``position`` + + - Exception safety: Strong guarantee + +- ``template< class InputRange > + void insert( iterator position, const InputRange& r );`` + + - Effects: ``insert( position, boost::begin(r), boost::end(r) );`` + +- ``iterator erase( iterator position );`` + + - Requirements: ``position`` is a valid iterator from the container + + - Effects: Removes the element defined by ``position`` and returns an iterator to the following element + + - Throws: Nothing + +- ``iterator erase( iterator first, iterator last );`` + + - Requirements: ``[first,last)`` is a valid range + + - Effects: Removes the range of element defined by ``[first,last)`` and returns an iterator to the following element + + - Throws: Nothing + +- ``template< class Range > + void erase( const Range& r );`` + + - Effects: ``erase( boost::begin(r), boost::end(r) );`` + +- ``void resize( size_type size );`` + + - Effects: Resizes the container. If elements are erased, it happens from the back. If elements are inserted, it happens at the back. + + - Requirements: ``T`` is default constructible + + - Postcondition: ``size() == size;`` + + - Exception safety: Basic guarantee under expansion; nothrow guarantee otherwise + +- ``void resize( size_type size, T* to_clone );`` + + - Effects: Resizes the container. If elements are erased, it happens from the back. If elements are inserted, clones of ``*to_clone`` are inserted at the back. + + - Postcondition: ``size() == size;`` + + - Exception safety: Basic guarantee under expansion; nothrow guarantee otherwise + + - Remarks: ``to_clone == 0`` is valid if the container supports nulls. The container does not take ownership of ``to_clone``. + +.. _`pointer container requirements`: + +Semantics: pointer container requirements +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can use ``transfer()`` to move elements between two containers of the same type. Furthermore, +you can also move elements from a container of type ``T`` to a container of type ``U`` as long as +``T::value_type`` is convertible to ``U::value_type``. An example would be transferring from ``boost::ptr_vector<Derived>`` +to ``boost::ptr_deque<Base>``. + +(**Remark:** *When moving elements between two different containers, it is your responsibility to make sure the allocators are compatible.* +*The special latitude of being able to transfer between two different containers is only available for Sequences and not for Associative Containers.*) + +.. + +- ``template< class PtrSequence > void transfer( iterator before, typename PtrSequence::iterator object, PtrSequence& from );`` + + - Effects: Inserts the object defined by ``object`` into the container and remove it from ``from``. + Insertion takes place before ``before``. + + - Postconditions: If ``from.empty()``, nothing happens. Otherwise + ``size()`` is one more, ``from.size()`` is one less. + + - Exception safety: Strong guarantee + + +- ``template< class PtrSequence > void transfer( iterator before, typename PtrSequence::iterator first, typename PtrSequence::iterator last, PtrSequence& from );`` + + - Requirements: ``from.size() >= std::distance(first,last)`` + + - Effects: Inserts the objects defined by the range ``[first,last)`` into the container and remove it from ``from``. + Insertion takes place before ``before``. + + - Postconditions: If ``from.empty()``, nothing happens. Otherwise, + let ``N == std::distance(first,last);`` then ``size()`` is ``N`` more, ``from.size()`` is ``N`` less. + + - Exception safety: Strong guarantee + + - Complexity: Linear or better + +- ``void template< class PtrSequence, class Range > void transfer( iterator before, const Range& r, PtrSequence& from );`` + + - Effects: ``transfer(before, boost::begin(r), boost::end(r), from);`` + +- ``template< class PtrSequence> void transfer( iterator before, PtrSequence& from );`` + + - Effects: ``transfer(before, from, from);`` + +.. _`algorithms`: + +Semantics: algorithms +^^^^^^^^^^^^^^^^^^^^^ + +The general requirement for these algorithms is that the container *does not +contain any nulls*. + +- ``void sort();`` +- ``void sort( iterator first, iterator last );`` +- ``template< class Compare > void sort( Compare comp );`` +- ``template< class Compare > void sort( iterator begin, iterator end, Compare comp );`` + + - Requirements: (versions without ``Compare``) ``bool operator<( const T&, const T& )`` is defined + - Requirements: (``Compare`` versions) ``Compare`` must take ``const T&`` arguments + - Effects: sorts the entire container or the specified range + - Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws) + - Remarks: The versions of ``sort()`` that take two iterators are not available for ``ptr_list`` + +- ``void unique();`` +- ``void unique( iterator first, iterator last );`` +- ``template< class Compare > void unique( Compare comp );`` +- ``template< class Compare > void unique( iterator begin, iterator end, Compare comp );`` + + - Requirements: (versions without ``Compare``) ``bool operator==( const T&, const T& )`` is defined + - Requirements: (``Compare`` versions) ``Compare`` must take ``const T&`` arguments + - Effects: removes adjacent and equal objects from the entire container or the specified range + - Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws) + +- ``template< class Pred > void erase_if( Pred pred );`` +- ``template< class Pred > void erase_if( iterator begin, iterator end, Pred pred );`` + + - Requirements: ``Pred`` must take an ``const T&`` argument + - Effects: removes all elements ``t`` for which ``pred(t)`` returns ``true`` from the entire container or the specified range + - Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws) + +- ``void merge( ptr_sequence_adapter& r );`` +- ``template< class Compare > void merge( ptr_sequence_adapter& r, Compare comp );`` +- ``void merge( iterator first, iterator last, ptr_sequence_adapter& from );`` +- ``template< class Compare > void merge( iterator first, iterator last, ptr_sequence_adapter& from, Compare comp );`` + + - Requirements: (``Compare`` versions) ``Compare`` must take ``const T&`` arguments + - Requirements: both sequences are sorted wrt. the same predicate + - Effects: transfers the entire container or the specified sequence to the container while + ensuring the new sequence is also sorted + - Postconditions: (Container versions) ``r.empty()`` + - Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws) + +.. raw:: html + + <hr> + +:Copyright: Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). + +__ http://www.boost.org/LICENSE_1_0.txt + + diff --git a/libs/ptr_container/doc/ptr_set.html b/libs/ptr_container/doc/ptr_set.html new file mode 100644 index 0000000000..408293b781 --- /dev/null +++ b/libs/ptr_container/doc/ptr_set.html @@ -0,0 +1,363 @@ +<?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: 2007-11-25 13:38:02 -0500 (Sun, 25 Nov 2007) $ +:Revision: $Revision: 41370 $ +: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="class-ptr-set">Class <tt class="docutils literal"><span class="pre">ptr_set</span></tt></h2> +<p>A <tt class="docutils literal"><span class="pre">ptr_set<T></span></tt> is a pointer container that uses an underlying <tt class="docutils literal"><span class="pre">std::set<void*></span></tt> +to store the pointers.</p> +<p><strong>Hierarchy:</strong></p> +<ul class="simple"> +<li><a class="reference" href="reversible_ptr_container.html">reversible_ptr_container</a><ul> +<li><a class="reference" href="associative_ptr_container.html">associative_ptr_container</a><ul> +<li><a class="reference" href="ptr_set_adapter.html">ptr_set_adapter</a></li> +<li><a class="reference" href="ptr_multiset_adapter.html">ptr_multiset_adapter</a></li> +<li><a class="reference" href="ptr_map_adapter.html">ptr_map_adapter</a></li> +<li><a class="reference" href="ptr_multimap_adapter.html">ptr_multi_map_adapter</a><ul> +<li><tt class="docutils literal"><span class="pre">ptr_set</span></tt></li> +<li><a class="reference" href="ptr_multiset.html">ptr_multi_set</a></li> +<li><a class="reference" href="ptr_map.html">ptr_map</a></li> +<li><a class="reference" href="ptr_multimap.html">ptr_multimap</a></li> +</ul> +</li> +</ul> +</li> +</ul> +</li> +</ul> +<p><strong>See also:</strong></p> +<ul class="simple"> +<li><a class="reference" href="indirect_fun.html">void_ptr_indirect_fun</a></li> +</ul> +<p><strong>Navigate:</strong></p> +<ul class="simple"> +<li><a class="reference" href="ptr_container.html">home</a></li> +<li><a class="reference" href="reference.html">reference</a></li> +</ul> +<p><strong>Synopsis:</strong></p> +<pre class="literal-block"> +namespace boost +{ + + template + < + class Key, + class Compare = std::less<Key>, + class CloneAllocator = heap_clone_allocator, + class Allocator = std::allocator<void*> + > + class ptr_set : public ptr_set_adapter + < + Key, + std::set<void*, + void_ptr_indirect_fun<Compare,Key>,Allocator>, + CloneAllocator + > + { + // see references + + }; // class 'ptr_set' + +} // namespace 'boost' +</pre> +<p><strong>Remarks:</strong></p> +<ul class="simple"> +<li>Using <tt class="docutils literal"><span class="pre">nullable<T></span></tt> as <tt class="docutils literal"><span class="pre">Key</span></tt> is meaningless and is not allowed</li> +</ul> +<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> +</body> +</html> diff --git a/libs/ptr_container/doc/ptr_set.rst b/libs/ptr_container/doc/ptr_set.rst new file mode 100644 index 0000000000..6679a8b24b --- /dev/null +++ b/libs/ptr_container/doc/ptr_set.rst @@ -0,0 +1,81 @@ +++++++++++++++++++++++++++++++++++ + |Boost| Pointer Container Library +++++++++++++++++++++++++++++++++++ + +.. |Boost| image:: boost.png + +Class ``ptr_set`` +----------------- + +A ``ptr_set<T>`` is a pointer container that uses an underlying ``std::set<void*>`` +to store the pointers. + +**Hierarchy:** + +- `reversible_ptr_container <reversible_ptr_container.html>`_ + + - `associative_ptr_container <associative_ptr_container.html>`_ + + - `ptr_set_adapter <ptr_set_adapter.html>`_ + - `ptr_multiset_adapter <ptr_multiset_adapter.html>`_ + - `ptr_map_adapter <ptr_map_adapter.html>`_ + - `ptr_multi_map_adapter <ptr_multimap_adapter.html>`_ + + - ``ptr_set`` + - `ptr_multi_set <ptr_multiset.html>`_ + - `ptr_map <ptr_map.html>`_ + - `ptr_multimap <ptr_multimap.html>`_ + + +**See also:** + +- `void_ptr_indirect_fun <indirect_fun.html>`_ + +**Navigate:** + +- `home <ptr_container.html>`_ +- `reference <reference.html>`_ + + +**Synopsis:** + +.. parsed-literal:: + + + namespace boost + { + + template + < + class Key, + class Compare = std::less<Key>, + class CloneAllocator = heap_clone_allocator, + class Allocator = std::allocator<void*> + > + class ptr_set : public ptr_set_adapter + < + Key, + std::set<void*, + void_ptr_indirect_fun<Compare,Key>,Allocator>, + CloneAllocator + > + { + // see references + + }; // class 'ptr_set' + + } // namespace 'boost' + +**Remarks:** + +- Using ``nullable<T>`` as ``Key`` is meaningless and is not allowed + +.. raw:: html + + <hr> + +:Copyright: Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). + +__ http://www.boost.org/LICENSE_1_0.txt + + diff --git a/libs/ptr_container/doc/ptr_set_adapter.html b/libs/ptr_container/doc/ptr_set_adapter.html new file mode 100644 index 0000000000..ae47b45bfc --- /dev/null +++ b/libs/ptr_container/doc/ptr_set_adapter.html @@ -0,0 +1,432 @@ +<?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: 2006-11-22 17:01:03 -0500 (Wed, 22 Nov 2006) $ +:Revision: $Revision: 36152 $ +: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> +<div class="section"> +<h1><a id="class-ptr-set-adapter" name="class-ptr-set-adapter">Class <tt class="docutils literal"><span class="pre">ptr_set_adapter</span></tt></a></h1> +<p>This class is used to build custom pointer containers with +an underlying set-like container. The interface of the class is an extension +of the interface from <tt class="docutils literal"><span class="pre">associative_ptr_container</span></tt>.</p> +<p><strong>Hierarchy:</strong></p> +<ul class="simple"> +<li><a class="reference" href="reversible_ptr_container.html">reversible_ptr_container</a><ul> +<li><a class="reference" href="associative_ptr_container.html">associative_ptr_container</a><ul> +<li><tt class="docutils literal"><span class="pre">ptr_set_adapter</span></tt></li> +<li><a class="reference" href="ptr_multiset_adapter.html">ptr_multiset_adapter</a></li> +<li><a class="reference" href="ptr_map_adapter.html">ptr_map_adapter</a></li> +<li><a class="reference" href="ptr_multimap_adapter.html">ptr_multi_map_adapter</a><ul> +<li><a class="reference" href="ptr_set.html">ptr_set</a></li> +<li><a class="reference" href="ptr_multiset.html">ptr_multi_set</a></li> +<li><a class="reference" href="ptr_map.html">ptr_map</a></li> +<li><a class="reference" href="ptr_multimap.html">ptr_multimap</a></li> +</ul> +</li> +</ul> +</li> +</ul> +</li> +</ul> +<p><strong>Navigate:</strong></p> +<ul class="simple"> +<li><a class="reference" href="ptr_container.html">home</a></li> +<li><a class="reference" href="reference.html">reference</a></li> +</ul> +<p><strong>Synopsis:</strong></p> +<pre class="literal-block"> +namespace boost +{ + template + < + class Key, + class VoidPtrSet, + class CloneAllocator = heap_clone_allocator + > + class ptr_set_adapter + { + + public: // <a class="reference" href="#modifiers">modifiers</a> + std::pair<iterator,bool> insert( Key* x ); + template< class Key2 > + std::pair<iterator,bool> insert( std::auto_ptr<Key2> x ); + + public: // <a class="reference" href="#pointer-container-requirements">pointer container requirements</a> + bool transfer( iterator object, ptr_set_adapter& from ); + size_type transfer( iterator first, iterator last, ptr_set_adapter& from ); + template< class Range > + size_type transfer( const Range& r, ptr_set_adapter& from ); + size_type transfer( ptr_set_adapter& from ); + + }; // class 'ptr_set_adapter' + +} // namespace 'boost' +</pre> +</div> +<div class="section"> +<h1><a id="semantics" name="semantics">Semantics</a></h1> +<div class="section"> +<h2><a id="semantics-modifiers" name="semantics-modifiers"><span id="modifiers"></span>Semantics: modifiers</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">std::pair<iterator,bool></span> <span class="pre">insert(</span> <span class="pre">key_type*</span> <span class="pre">x</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">x</span> <span class="pre">!=</span> <span class="pre">0</span></tt></li> +<li>Effects: Takes ownership of <tt class="docutils literal"><span class="pre">x</span></tt> and insert it if there is no equivalent of it already. The <tt class="docutils literal"><span class="pre">bool</span></tt> part of the return value indicates insertion and the iterator points to the element with key <tt class="docutils literal"><span class="pre">x</span></tt>.</li> +<li>Throws: bad_pointer if <tt class="docutils literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">0</span></tt></li> +<li>Exception safety: Strong guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">Key2</span> <span class="pre">></span> <span class="pre">std::pair<iterator,bool></span> <span class="pre">insert(</span> <span class="pre">std::auto_ptr<Key2></span> <span class="pre">x</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: <tt class="docutils literal"><span class="pre">return</span> <span class="pre">insert(</span> <span class="pre">x.release()</span> <span class="pre">);</span></tt></li> +</ul> +</blockquote> +</li> +</ul> +<!-- - ``std::pair<iterator,bool> insert( const key_type& x );`` + +- Effects: ``return insert( allocate_clone( x ) );`` + +- Exception safety: Strong guarantee --> +</div> +<div class="section"> +<h2><a id="semantics-pointer-container-requirements" name="semantics-pointer-container-requirements"><span id="pointer-container-requirements"></span>Semantics: pointer container requirements</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">transfer(</span> <span class="pre">iterator</span> <span class="pre">object,</span> <span class="pre">ptr_set_adapter&</span> <span class="pre">from</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">not</span> <span class="pre">from.empty()</span></tt></li> +<li>Effects: Inserts the object defined by <tt class="docutils literal"><span class="pre">object</span></tt> into the container and remove it from <tt class="docutils literal"><span class="pre">from</span></tt> +iff no equivalent object exists.</li> +<li>Returns: whether the object was transfered</li> +<li>Exception safety: Strong guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">transfer(</span> <span class="pre">iterator</span> <span class="pre">first,</span> <span class="pre">iterator</span> <span class="pre">last,</span> <span class="pre">ptr__set_adapter&</span> <span class="pre">from</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">not</span> <span class="pre">from.empty()</span></tt></li> +<li>Effects: Inserts the objects defined by the range <tt class="docutils literal"><span class="pre">[first,last)</span></tt> into the container and remove it from <tt class="docutils literal"><span class="pre">from</span></tt>. +An object is only transferred if no equivalent object exists.</li> +<li>Returns: the number of transfered objects</li> +<li>Exception safety: Basic guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">Range</span> <span class="pre">></span> <span class="pre">void</span> <span class="pre">transfer(</span> <span class="pre">const</span> <span class="pre">Range&</span> <span class="pre">r,</span> <span class="pre">ptr_set_adapter&</span> <span class="pre">from</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: <tt class="docutils literal"><span class="pre">return</span> <span class="pre">transfer(</span> <span class="pre">boost::begin(r),</span> <span class="pre">boost::end(r),</span> <span class="pre">from</span> <span class="pre">);</span></tt></li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">size_type</span> <span class="pre">transfer(</span> <span class="pre">ptr_set_adapter&</span> <span class="pre">from</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: <tt class="docutils literal"><span class="pre">return</span> <span class="pre">transfer(</span> <span class="pre">from.begin(),</span> <span class="pre">from.end(),</span> <span class="pre">from</span> <span class="pre">);</span></tt>.</li> +</ul> +</blockquote> +</li> +</ul> +<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> +</div> +</body> +</html> diff --git a/libs/ptr_container/doc/ptr_set_adapter.rst b/libs/ptr_container/doc/ptr_set_adapter.rst new file mode 100644 index 0000000000..48e9b385d2 --- /dev/null +++ b/libs/ptr_container/doc/ptr_set_adapter.rst @@ -0,0 +1,145 @@ +++++++++++++++++++++++++++++++++++ + |Boost| Pointer Container Library +++++++++++++++++++++++++++++++++++ + +.. |Boost| image:: boost.png + +Class ``ptr_set_adapter`` +------------------------- + +This class is used to build custom pointer containers with +an underlying set-like container. The interface of the class is an extension +of the interface from ``associative_ptr_container``. + +**Hierarchy:** + +- `reversible_ptr_container <reversible_ptr_container.html>`_ + + - `associative_ptr_container <associative_ptr_container.html>`_ + + - ``ptr_set_adapter`` + - `ptr_multiset_adapter <ptr_multiset_adapter.html>`_ + - `ptr_map_adapter <ptr_map_adapter.html>`_ + - `ptr_multi_map_adapter <ptr_multimap_adapter.html>`_ + + - `ptr_set <ptr_set.html>`_ + - `ptr_multi_set <ptr_multiset.html>`_ + - `ptr_map <ptr_map.html>`_ + - `ptr_multimap <ptr_multimap.html>`_ + +**Navigate:** + +- `home <ptr_container.html>`_ +- `reference <reference.html>`_ + +.. _reversible_ptr_container: reversible_ptr_container.html +.. _associative_ptr_container: associative_ptr_container.html +.. _ptr_set: ptr_set.html + +**Synopsis:** + +.. parsed-literal:: + + + namespace boost + { + template + < + class Key, + class VoidPtrSet, + class CloneAllocator = heap_clone_allocator + > + class ptr_set_adapter + { + + public: // `modifiers`_ + std::pair<iterator,bool> insert( Key* x ); + template< class Key2 > + std::pair<iterator,bool> insert( std::auto_ptr<Key2> x ); + + public: // `pointer container requirements`_ + bool transfer( iterator object, ptr_set_adapter& from ); + size_type transfer( iterator first, iterator last, ptr_set_adapter& from ); + template< class Range > + size_type transfer( const Range& r, ptr_set_adapter& from ); + size_type transfer( ptr_set_adapter& from ); + + }; // class 'ptr_set_adapter' + + } // namespace 'boost' + + +Semantics +--------- + +.. _`modifiers`: + +Semantics: modifiers +^^^^^^^^^^^^^^^^^^^^ + +- ``std::pair<iterator,bool> insert( key_type* x );`` + + - Requirements: ``x != 0`` + + - Effects: Takes ownership of ``x`` and insert it if there is no equivalent of it already. The ``bool`` part of the return value indicates insertion and the iterator points to the element with key ``x``. + + - Throws: bad_pointer if ``x == 0`` + + - Exception safety: Strong guarantee + +- ``template< class Key2 > std::pair<iterator,bool> insert( std::auto_ptr<Key2> x );`` + + - Effects: ``return insert( x.release() );`` + + +.. + - ``std::pair<iterator,bool> insert( const key_type& x );`` + + - Effects: ``return insert( allocate_clone( x ) );`` + + - Exception safety: Strong guarantee + +.. _`pointer container requirements`: + +Semantics: pointer container requirements +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``bool transfer( iterator object, ptr_set_adapter& from );`` + + - Requirements: ``not from.empty()`` + + - Effects: Inserts the object defined by ``object`` into the container and remove it from ``from`` + iff no equivalent object exists. + + - Returns: whether the object was transfered + + - Exception safety: Strong guarantee + +- ``void transfer( iterator first, iterator last, ptr__set_adapter& from );`` + + - Requirements: ``not from.empty()`` + + - Effects: Inserts the objects defined by the range ``[first,last)`` into the container and remove it from ``from``. + An object is only transferred if no equivalent object exists. + + - Returns: the number of transfered objects + + - Exception safety: Basic guarantee + +- ``template< class Range > void transfer( const Range& r, ptr_set_adapter& from );`` + + - Effects: ``return transfer( boost::begin(r), boost::end(r), from );`` + +- ``size_type transfer( ptr_set_adapter& from );`` + + - Effects: ``return transfer( from.begin(), from.end(), from );``. + +.. raw:: html + + <hr> + +:Copyright: Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). + +__ http://www.boost.org/LICENSE_1_0.txt + + diff --git a/libs/ptr_container/doc/ptr_vector.html b/libs/ptr_container/doc/ptr_vector.html new file mode 100644 index 0000000000..6c1f6d2b99 --- /dev/null +++ b/libs/ptr_container/doc/ptr_vector.html @@ -0,0 +1,491 @@ +<?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: 2007-11-25 13:38:02 -0500 (Sun, 25 Nov 2007) $ +:Revision: $Revision: 41370 $ +: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> +<div class="section"> +<h1><a id="class-ptr-vector" name="class-ptr-vector">Class <tt class="docutils literal"><span class="pre">ptr_vector</span></tt></a></h1> +<p>A <tt class="docutils literal"><span class="pre">ptr_vector<T></span></tt> is a pointer container that uses an underlying <tt class="docutils literal"><span class="pre">std::vector<void*></span></tt> +to store the pointers.</p> +<p><strong>Hierarchy:</strong></p> +<ul class="simple"> +<li><a class="reference" href="reversible_ptr_container.html">reversible_ptr_container</a><ul> +<li><a class="reference" href="ptr_sequence_adapter.html">ptr_sequence_adapter</a><ul> +<li><tt class="docutils literal"><span class="pre">ptr_vector</span></tt></li> +<li><a class="reference" href="ptr_list.html">ptr_list</a></li> +<li><a class="reference" href="ptr_deque.html">ptr_deque</a></li> +<li><a class="reference" href="ptr_array.html">ptr_array</a></li> +</ul> +</li> +</ul> +</li> +</ul> +<p><strong>Navigate:</strong></p> +<ul class="simple"> +<li><a class="reference" href="ptr_container.html">home</a></li> +<li><a class="reference" href="reference.html">reference</a></li> +</ul> +<p><strong>Synopsis:</strong></p> +<pre class="literal-block"> +namespace boost +{ + + template + < + class T, + class CloneAllocator = heap_clone_allocator, + class Allocator = std::allocator<void*> + > + class ptr_vector : public ptr_sequence_adapter + < + T, + std::vector<void*,Allocator>, + CloneAllocator + > + { + public: // <a class="reference" href="#construction">construction</a> + explicit ptr_vector( size_type to_reserve ); + + public: // <a class="reference" href="#capacity">capacity</a> + size_type capacity() const; + void reserve( size_type n ); + + public: // <a class="reference" href="#element-access">element access</a> + T& operator[]( size_type n ); + const T& operator[]( size_type n ) const; + T& at( size_type n ); + const T& at( size_type n ) const; + + public: // <a class="reference" href="#pointer-container-requirements">pointer container requirements</a> + auto_type replace( size_type idx, T* x ); + template< class U > + auto_type replace( size_type idx, std::auto_ptr<U> x ); + bool is_null( size_type idx ) const; + + public: // <a class="reference" href="#c-array-support">C-array support</a> + void transfer( iterator before, T** from, size_type size, bool delete_from = true ); + T** c_array(); + + }; + +} // namespace 'boost' +</pre> +</div> +<div class="section"> +<h1><a id="semantics" name="semantics">Semantics</a></h1> +<div class="section"> +<h2><a id="semantics-construction" name="semantics-construction"><span id="construction"></span>Semantics: construction</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">explicit</span> <span class="pre">ptr_vector(</span> <span class="pre">size_type</span> <span class="pre">to_reserve</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>constructs an empty vector with a buffer +of size least <tt class="docutils literal"><span class="pre">to_reserve</span></tt></li> +</ul> +</blockquote> +</li> +</ul> +</div> +<div class="section"> +<h2><a id="semantics-capacity" name="semantics-capacity"><span id="capacity"></span>Semantics: capacity</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">size_type</span> <span class="pre">capacity()</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Returns the size of the allocated buffer</li> +<li>Throws: Nothing</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">reserve(</span> <span class="pre">size_type</span> <span class="pre">n</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">n</span> <span class="pre"><=</span> <span class="pre">max_size()</span></tt></li> +<li>Effects: Expands the allocated buffer</li> +<li>Postcondition: <tt class="docutils literal"><span class="pre">capacity()</span> <span class="pre">>=</span> <span class="pre">n</span></tt></li> +<li>Throws: <tt class="docutils literal"><span class="pre">std::length_error()</span></tt> if <tt class="docutils literal"><span class="pre">n</span> <span class="pre">></span> <span class="pre">max_size()</span></tt></li> +</ul> +</blockquote> +</li> +</ul> +</div> +<div class="section"> +<h2><a id="semantics-element-access" name="semantics-element-access"><span id="element-access"></span>Semantics: element access</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">T&</span> <span class="pre">operator[](</span> <span class="pre">size_type</span> <span class="pre">n</span> <span class="pre">);</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">const</span> <span class="pre">T&</span> <span class="pre">operator[](</span> <span class="pre">size_type</span> <span class="pre">n</span> <span class="pre">)</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">n</span> <span class="pre"><</span> <span class="pre">size()</span></tt></li> +<li>Effects: Returns a reference to the <tt class="docutils literal"><span class="pre">n</span></tt>'th element</li> +<li>Throws: Nothing</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">T&</span> <span class="pre">at(</span> <span class="pre">size_type</span> <span class="pre">n</span> <span class="pre">);</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">const</span> <span class="pre">T&</span> <span class="pre">at(</span> <span class="pre">size_type</span> <span class="pre">n</span> <span class="pre">)</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">n</span> <span class="pre"><</span> <span class="pre">size()</span></tt></li> +<li>Effects: Returns a reference to the <tt class="docutils literal"><span class="pre">n</span></tt>'th element</li> +<li>Throws: <tt class="docutils literal"><span class="pre">bad_index</span></tt> if <tt class="docutils literal"><span class="pre">n</span> <span class="pre">>=</span> <span class="pre">size()</span></tt></li> +</ul> +</blockquote> +</li> +</ul> +</div> +<div class="section"> +<h2><a id="semantics-pointer-container-requirements" name="semantics-pointer-container-requirements"><span id="pointer-container-requirements"></span>Semantics: pointer container requirements</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">auto_type</span> <span class="pre">replace(</span> <span class="pre">size_type</span> <span class="pre">idx,</span> <span class="pre">T*</span> <span class="pre">x</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: `` x != 0 and idx < size()``</li> +<li>Effects: returns the object indexed by <tt class="docutils literal"><span class="pre">idx</span></tt> and replaces it with <tt class="docutils literal"><span class="pre">x</span></tt>.</li> +<li>Throws: <tt class="docutils literal"><span class="pre">bad_index</span></tt> if <tt class="docutils literal"><span class="pre">idx</span> <span class="pre">>=</span> <span class="pre">size()</span></tt> and <tt class="docutils literal"><span class="pre">bad_pointer</span></tt> if <tt class="docutils literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">0</span></tt>.</li> +<li>Exception safety: Strong guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">U</span> <span class="pre">></span> <span class="pre">auto_type</span> <span class="pre">replace(</span> <span class="pre">size_type</span> <span class="pre">idx,</span> <span class="pre">std::auto_ptr<U></span> <span class="pre">x</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: <tt class="docutils literal"><span class="pre">return</span> <span class="pre">replace(</span> <span class="pre">idx,</span> <span class="pre">x.release()</span> <span class="pre">);</span></tt></li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">is_null(</span> <span class="pre">size_type</span> <span class="pre">idx</span> <span class="pre">)</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">idx</span> <span class="pre"><</span> <span class="pre">size()</span></tt></li> +<li>Effects: returns whether the pointer at index <tt class="docutils literal"><span class="pre">idx</span></tt> is null</li> +<li>Exception safety: Nothrow guarantee</li> +</ul> +</blockquote> +</li> +</ul> +</div> +<div class="section"> +<h2><a id="semantics-c-array-support" name="semantics-c-array-support"><span id="c-array-support"></span>Semantics: C-array support</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">transfer(</span> <span class="pre">iterator</span> <span class="pre">before,</span> <span class="pre">T**</span> <span class="pre">from,</span> <span class="pre">size_type</span> <span class="pre">size,</span> <span class="pre">bool</span> <span class="pre">delete_from</span> <span class="pre">=</span> <span class="pre">true</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">from</span> <span class="pre">!=</span> <span class="pre">0</span></tt></li> +<li>Effects: Takes ownership of the dynamic array <tt class="docutils literal"><span class="pre">from</span></tt></li> +<li>Exception safety: Strong guarantee if <tt class="docutils literal"><span class="pre">delete_from</span> <span class="pre">==</span> <span class="pre">true</span></tt>; if <tt class="docutils literal"><span class="pre">delete_from</span> <span class="pre">==</span> <span class="pre">false</span></tt>, +and an exception is thrown, the container fails to take ownership.</li> +<li>Remarks: Eventually calls <tt class="docutils literal"><span class="pre">delete[]</span> <span class="pre">from</span></tt> if <tt class="docutils literal"><span class="pre">delete_from</span> <span class="pre">==</span> <span class="pre">true</span></tt>.</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">T**</span> <span class="pre">c_array();</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Returns: <tt class="docutils literal"><span class="pre">0</span></tt> if the container is empty; otherwise a pointer to the first element of the stored array</li> +<li>Throws: Nothing</li> +</ul> +</blockquote> +</li> +</ul> +<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-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> +</tr> +</tbody> +</table> +</div> +</div> +</div> +</body> +</html> diff --git a/libs/ptr_container/doc/ptr_vector.rst b/libs/ptr_container/doc/ptr_vector.rst new file mode 100644 index 0000000000..2d00607551 --- /dev/null +++ b/libs/ptr_container/doc/ptr_vector.rst @@ -0,0 +1,194 @@ +++++++++++++++++++++++++++++++++++ + |Boost| Pointer Container Library +++++++++++++++++++++++++++++++++++ + +.. |Boost| image:: boost.png + +Class ``ptr_vector`` +-------------------- + +A ``ptr_vector<T>`` is a pointer container that uses an underlying ``std::vector<void*>`` +to store the pointers. + +**Hierarchy:** + +- `reversible_ptr_container <reversible_ptr_container.html>`_ + + - `ptr_sequence_adapter <ptr_sequence_adapter.html>`_ + + - ``ptr_vector`` + - `ptr_list <ptr_list.html>`_ + - `ptr_deque <ptr_deque.html>`_ + - `ptr_array <ptr_array.html>`_ + +**Navigate:** + +- `home <ptr_container.html>`_ +- `reference <reference.html>`_ + +**Synopsis:** + +.. parsed-literal:: + + namespace boost + { + + template + < + class T, + class CloneAllocator = heap_clone_allocator, + class Allocator = std::allocator<void*> + > + class ptr_vector : public ptr_sequence_adapter + < + T, + std::vector<void*,Allocator>, + CloneAllocator + > + { + public: // `construction`_ + explicit ptr_vector( size_type to_reserve ); + + public: // capacity_ + size_type capacity() const; + void reserve( size_type n ); + + public: // `element access`_ + T& operator[]( size_type n ); + const T& operator[]( size_type n ) const; + T& at( size_type n ); + const T& at( size_type n ) const; + + public: // `pointer container requirements`_ + auto_type replace( size_type idx, T* x ); + template< class U > + auto_type replace( size_type idx, std::auto_ptr<U> x ); + bool is_null( size_type idx ) const; + + public: // `C-array support`_ + void transfer( iterator before, T** from, size_type size, bool delete_from = true ); + T** c_array(); + + }; + + } // namespace 'boost' + + +Semantics +--------- + +.. _`construction`: + +Semantics: construction +^^^^^^^^^^^^^^^^^^^^^^^ + +- ``explicit ptr_vector( size_type to_reserve );`` + + - constructs an empty vector with a buffer + of size least ``to_reserve`` + +.. _`capacity`: + +Semantics: capacity +^^^^^^^^^^^^^^^^^^^ + +- ``size_type capacity() const;`` + + - Effects: Returns the size of the allocated buffer + + - Throws: Nothing + +- ``void reserve( size_type n );`` + + - Requirements: ``n <= max_size()`` + + - Effects: Expands the allocated buffer + + - Postcondition: ``capacity() >= n`` + + - Throws: ``std::length_error()`` if ``n > max_size()`` + + +.. _`element access`: + +Semantics: element access +^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``T& operator[]( size_type n );`` +- ``const T& operator[]( size_type n ) const;`` + + - Requirements: ``n < size()`` + + - Effects: Returns a reference to the ``n``'th element + + - Throws: Nothing + +- ``T& at( size_type n );`` +- ``const T& at( size_type n ) const;`` + + - Requirements: ``n < size()`` + + - Effects: Returns a reference to the ``n``'th element + + - Throws: ``bad_index`` if ``n >= size()`` + + +.. _`pointer container requirements`: + +Semantics: pointer container requirements +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``auto_type replace( size_type idx, T* x );`` + + - Requirements: `` x != 0 and idx < size()`` + + - Effects: returns the object indexed by ``idx`` and replaces it with ``x``. + + - Throws: ``bad_index`` if ``idx >= size()`` and ``bad_pointer`` if ``x == 0``. + + - Exception safety: Strong guarantee + +- ``template< class U > auto_type replace( size_type idx, std::auto_ptr<U> x );`` + + - Effects: ``return replace( idx, x.release() );`` + +- ``bool is_null( size_type idx ) const;`` + + - Requirements: ``idx < size()`` + + - Effects: returns whether the pointer at index ``idx`` is null + + - Exception safety: Nothrow guarantee + + +.. _`C-array support`: + +Semantics: C-array support +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``void transfer( iterator before, T** from, size_type size, bool delete_from = true );`` + + - Requirements: ``from != 0`` + + - Effects: Takes ownership of the dynamic array ``from`` + + - Exception safety: Strong guarantee if ``delete_from == true``; if ``delete_from == false``, + and an exception is thrown, the container fails to take ownership. + + - Remarks: Eventually calls ``delete[] from`` if ``delete_from == true``. + +- ``T** c_array();`` + + - Returns: ``0`` if the container is empty; otherwise a pointer to the first element of the stored array + + - Throws: Nothing + +.. raw:: html + + <hr> + +:Copyright: Thorsten Ottosen 2004-2007. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). + +__ http://www.boost.org/LICENSE_1_0.txt + + diff --git a/libs/ptr_container/doc/reference.html b/libs/ptr_container/doc/reference.html new file mode 100644 index 0000000000..5278035b30 --- /dev/null +++ b/libs/ptr_container/doc/reference.html @@ -0,0 +1,815 @@ +<?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: 2008-07-16 17:03:47 -0400 (Wed, 16 Jul 2008) $ +:Revision: $Revision: 47494 $ +: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="reference">Reference</h2> +<p>The documentation is divided into an explanation for +each container. When containers have the same interface, that common interface is explained only once, +but links are always provided to more relevant information. +Please make sure you understand +the <a class="reference" href="reference.html#the-Clonable-concept">Clonable</a> concept and +the <a class="reference" href="reference.html#the-clone-allocator-concept">Clone Allocator</a> concept.</p> +<ul class="simple"> +<li><a class="reference" href="conventions.html">Conventions</a></li> +<li><a class="reference" href="#the-clonable-concept">The Clonable concept</a></li> +<li><a class="reference" href="#the-clone-allocator-concept">The Clone Allocator concept</a></li> +<li><a class="reference" href="#class-hierarchy">Class hierarchy</a>:<ul> +<li><a class="reference" href="reversible_ptr_container.html">reversible_ptr_container</a><ul> +<li><a class="reference" href="ptr_sequence_adapter.html">ptr_sequence_adapter</a><ul> +<li><a class="reference" href="ptr_vector.html">ptr_vector</a></li> +<li><a class="reference" href="ptr_list.html">ptr_list</a></li> +<li><a class="reference" href="ptr_deque.html">ptr_deque</a></li> +<li><a class="reference" href="ptr_array.html">ptr_array</a></li> +</ul> +</li> +<li><a class="reference" href="associative_ptr_container.html">associative_ptr_container</a><ul> +<li><a class="reference" href="ptr_set_adapter.html">ptr_set_adapter</a></li> +<li><a class="reference" href="ptr_multiset_adapter.html">ptr_multiset_adapter</a></li> +<li><a class="reference" href="ptr_map_adapter.html">ptr_map_adapter</a></li> +<li><a class="reference" href="ptr_multimap_adapter.html">ptr_multi_map_adapter</a><ul> +<li><a class="reference" href="ptr_set.html">ptr_set</a></li> +<li><a class="reference" href="ptr_multiset.html">ptr_multi_set</a></li> +<li><a class="reference" href="ptr_map.html">ptr_map</a></li> +<li><a class="reference" href="ptr_multimap.html">ptr_multimap</a></li> +</ul> +</li> +</ul> +</li> +</ul> +</li> +</ul> +</li> +<li><a class="reference" href="#serialization">Serialization</a></li> +<li><a class="reference" href="indirect_fun.html">Indirected functions</a></li> +<li><a class="reference" href="ptr_inserter.html">Insert iterators</a></li> +<li><a class="reference" href="#class-nullable">Class nullable</a></li> +<li><a class="reference" href="#exception-classes">Exception classes</a></li> +<li><a class="reference" href="#disabling-the-use-of-exceptions">Disabling the use of exceptions</a></li> +</ul> +<!-- - Class `reversible_ptr_container <reversible_ptr_container.html>`_ +- Class `associative_ptr_container <associative_ptr_container.html>`_ +- `Pointer container adapters`_ + + - `ptr_sequence_adapter <ptr_sequence_adapter.html>`_ + - `ptr_set_adapter <ptr_set_adapter.html>`_ + - `ptr_multiset_adapter <ptr_multiset_adapter.html>`_ + - `ptr_map_adapter <ptr_map_adapter.html>`_ + - `ptr_multimap_adapter <ptr_multimap_adapter.html>`_ +- `Sequence containers`_ + + - `ptr_vector <ptr_vector.html>`_ + - `ptr_deque <ptr_deque.html>`_ + - `ptr_list <ptr_list.html>`_ + - `ptr_array <ptr_array.html>`_ +- `Associative containers`_ + + - `ptr_set <ptr_set.html>`_ + - `ptr_multiset <ptr_multiset.html>`_ + - `ptr_map <ptr_map.html>`_ + - `ptr_multimap <ptr_multimap.html>`_ --> +<div class="section"> +<h1><a id="the-clonable-concept" name="the-clonable-concept">The Clonable concept</a></h1> +<p><strong>Refinement of</strong></p> +<ul class="simple"> +<li>Heap Allocable</li> +<li>Heap Deallocable</li> +</ul> +<p>The Clonable concept is introduced to formalize the requirements for +copying heap-allocated objects. A type <tt class="docutils literal"><span class="pre">T</span></tt> might be Clonable even though it +is not Assignable or Copy Constructible. Notice that many operations on +the containers do not even require the stored type to be Clonable.</p> +<p><strong>Notation</strong></p> +<table border="1" class="docutils"> +<colgroup> +<col width="21%" /> +<col width="41%" /> +<col width="18%" /> +<col width="20%" /> +</colgroup> +<tbody valign="top"> +<tr><td><strong>Type</strong></td> +<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> +<td><strong>Pointer</strong></td> +<td><strong>Describes</strong></td> +</tr> +<tr><td><tt class="docutils literal"><span class="pre">T</span></tt></td> +<td><tt class="docutils literal"><span class="pre">a</span></tt></td> +<td><tt class="docutils literal"><span class="pre">ptr</span></tt></td> +<td>A Clonable type</td> +</tr> +</tbody> +</table> +<p><strong>Valid expressions</strong></p> +<table border="1" class="docutils"> +<colgroup> +<col width="19%" /> +<col width="14%" /> +<col width="46%" /> +<col width="20%" /> +</colgroup> +<tbody valign="top"> +<tr><td><strong>Expression</strong></td> +<td><strong>Type</strong></td> +<td><strong>Semantics</strong></td> +<td><strong>Postcondition</strong></td> +</tr> +<tr><td><tt class="docutils literal"><span class="pre">new_clone(a);</span></tt></td> +<td><tt class="docutils literal"><span class="pre">T*</span></tt></td> +<td>Allocate a new object that can be considered equivalent to the <tt class="docutils literal"><span class="pre">a</span></tt> object</td> +<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> +</tr> +<tr><td><tt class="docutils literal"><span class="pre">delete_clone(ptr);</span></tt></td> +<td><tt class="docutils literal"><span class="pre">void</span></tt></td> +<td>Deallocate an object previously allocated with <tt class="docutils literal"><span class="pre">allocate_clone()</span></tt>. Must not throw</td> +<td> </td> +</tr> +</tbody> +</table> +<div class="section"> +<h2><a id="default-implementation" name="default-implementation">Default implementation</a></h2> +<p>In the <tt class="docutils literal"><span class="pre"><boost/ptr_container/clone_allocator.hpp></span></tt> header a default implementation +of the two functions is given:</p> +<pre class="literal-block"> +namespace boost +{ + template< class T > + inline T* new_clone( const T& t ) + { + return new T( t ); + } + + template< class T > + void delete_clone( const T* t ) + { + checked_delete( t ); + } +} +</pre> +<p>Notice that this implementation makes normal Copy Constructible classes automatically +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> +<p>The two functions represent a layer of indirection which is necessary to support +classes that are not Copy Constructible by default. Notice that the implementation +relies on argument-dependent lookup (ADL) to find the right version of +<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 +the function in the boost namespace, but it can be placed together with +the rest of the interface of the class. If you are implementing a class +inline in headers, remember to forward declare the functions.</p> +<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> +</div> +</div> +<div class="section"> +<h1><a id="the-clone-allocator-concept" name="the-clone-allocator-concept">The Clone Allocator concept</a></h1> +<p>The Clone Allocator concept is introduced to formalize the way +pointer containers control memory of +the stored objects (and not the pointers to the stored objects). +The clone allocator allows +users to apply custom allocators/deallocators for the cloned objects.</p> +<p>More information can be found below:</p> +<div class="contents local topic"> +<ul class="simple"> +<li><a class="reference" href="#clone-allocator-requirements" id="id19" name="id19">Clone Allocator requirements</a></li> +<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> +<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> +</ul> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id19" id="clone-allocator-requirements" name="clone-allocator-requirements">Clone Allocator requirements</a></h2> +<p><strong>Notation</strong></p> +<table border="1" class="docutils"> +<colgroup> +<col width="18%" /> +<col width="39%" /> +<col width="43%" /> +</colgroup> +<tbody valign="top"> +<tr><td><strong>Type</strong></td> +<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> +<td><strong>Describes</strong></td> +</tr> +<tr><td><tt class="docutils literal"><span class="pre">T</span></tt></td> +<td><tt class="docutils literal"><span class="pre">a</span></tt></td> +<td>A type</td> +</tr> +<tr><td><tt class="docutils literal"><span class="pre">T*</span></tt></td> +<td><tt class="docutils literal"><span class="pre">ptr</span></tt></td> +<td>A pointer to <tt class="docutils literal"><span class="pre">T</span></tt></td> +</tr> +</tbody> +</table> +<p><strong>Valid expressions</strong></p> +<table border="1" class="docutils"> +<colgroup> +<col width="23%" /> +<col width="7%" /> +<col width="39%" /> +<col width="31%" /> +</colgroup> +<tbody valign="top"> +<tr><td><strong>Expression</strong></td> +<td><strong>Type</strong></td> +<td><strong>Semantics</strong></td> +<td><strong>Postcondition</strong></td> +</tr> +<tr><td><tt class="docutils literal"><span class="pre">CloneAllocator::allocate_clone(a);</span></tt></td> +<td><tt class="docutils literal"><span class="pre">T*</span></tt></td> +<td>Allocate a new object that can be considered equivalent to the +<tt class="docutils literal"><span class="pre">a</span></tt> object</td> +<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> +</tr> +<tr><td><tt class="docutils literal"><span class="pre">CloneAllocator::deallocate_clone(ptr);</span></tt></td> +<td><tt class="docutils literal"><span class="pre">void</span></tt></td> +<td>Deallocate an object previously allocated with +<tt class="docutils literal"><span class="pre">CloneAllocator::allocate_clone()</span></tt> or a compatible allocator. +Must not throw.</td> +<td> </td> +</tr> +</tbody> +</table> +<p>The library comes with two predefined clone allocators.</p> +</div> +<div class="section"> +<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> +<p>This is the default clone allocator used by all pointer containers. For most +purposes you will never have to change this default.</p> +<p><strong>Definition</strong></p> +<pre class="literal-block"> +namespace boost +{ + struct heap_clone_allocator + { + template< class U > + static U* allocate_clone( const U& r ) + { + return new_clone( r ); + } + + template< class U > + static void deallocate_clone( const U* r ) + { + delete_clone( r ); + } + }; +} +</pre> +<p>Notice that the above definition allows you to support custom allocation +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> +</div> +<div class="section"> +<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> +<p>This class provides a way to remove ownership properties of the +pointer containers. As its name implies, this means that you can +instead use the pointer containers as a view into an existing +container.</p> +<p><strong>Definition</strong></p> +<pre class="literal-block"> +namespace boost +{ + struct view_clone_allocator + { + template< class U > + static U* allocate_clone( const U& r ) + { + return const_cast<U*>(&r); + } + + template< class U > + static void deallocate_clone( const U* ) + { + // empty + } + }; +} +</pre> +<!-- **See also** + +- `Changing the clone allocator <examples.html#changing-the-clone-allocator>`_ --> +</div> +</div> +<div class="section"> +<h1><a id="class-hierarchy" name="class-hierarchy">Class hierarchy</a></h1> +<p>The library consists of the following types of classes:</p> +<ol class="arabic simple"> +<li>Pointer container adapters</li> +</ol> +<!-- --> +<ol class="arabic simple" start="2"> +<li>Pointer containers</li> +</ol> +<p>The pointer container adapters are used when you +want to make a pointer container starting from +your own "normal" container. For example, you +might have a map class that extends <tt class="docutils literal"><span class="pre">std::map</span></tt> +in some way; the adapter class then allows you +to use your map class as a basis for a new +pointer container.</p> +<p>The library provides an adapter for each type +of standard container highlighted as links below:</p> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">reversible_ptr_container</span></tt><ul> +<li><a class="reference" href="ptr_sequence_adapter.html">ptr_sequence_adapter</a><ul> +<li><tt class="docutils literal"><span class="pre">ptr_vector</span></tt></li> +<li><tt class="docutils literal"><span class="pre">ptr_list</span></tt></li> +<li><tt class="docutils literal"><span class="pre">ptr_deque</span></tt></li> +<li><tt class="docutils literal"><span class="pre">ptr_array</span></tt></li> +</ul> +</li> +<li><tt class="docutils literal"><span class="pre">associative_ptr_container</span></tt><ul> +<li><a class="reference" href="ptr_set_adapter.html">ptr_set_adapter</a></li> +<li><a class="reference" href="ptr_multiset_adapter.html">ptr_multiset_adapter</a></li> +<li><a class="reference" href="ptr_map_adapter.html">ptr_map_adapter</a></li> +<li><a class="reference" href="ptr_multimap_adapter.html">ptr_multi_map_adapter</a><ul> +<li><tt class="docutils literal"><span class="pre">ptr_set</span></tt></li> +<li><tt class="docutils literal"><span class="pre">ptr_multi_set</span></tt></li> +<li><tt class="docutils literal"><span class="pre">ptr_map</span></tt></li> +<li><tt class="docutils literal"><span class="pre">ptr_multimap</span></tt></li> +</ul> +</li> +</ul> +</li> +</ul> +</li> +</ul> +<p>The pointer containers of this library are all built using +the adapters. There is a pointer container +for each type of "normal" standard container highlighted as links below.</p> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">reversible_ptr_container</span></tt><ul> +<li><tt class="docutils literal"><span class="pre">ptr_sequence_adapter</span></tt><ul> +<li><a class="reference" href="ptr_vector.html">ptr_vector</a></li> +<li><a class="reference" href="ptr_list.html">ptr_list</a></li> +<li><a class="reference" href="ptr_deque.html">ptr_deque</a></li> +<li><a class="reference" href="ptr_array.html">ptr_array</a></li> +</ul> +</li> +<li><tt class="docutils literal"><span class="pre">associative_ptr_container</span></tt><ul> +<li><tt class="docutils literal"><span class="pre">ptr_set_adapter</span></tt></li> +<li><tt class="docutils literal"><span class="pre">ptr_multiset_adapter</span></tt></li> +<li><tt class="docutils literal"><span class="pre">ptr_map_adapter</span></tt></li> +<li><tt class="docutils literal"><span class="pre">ptr_multi_map_adapter</span></tt><ul> +<li><a class="reference" href="ptr_set.html">ptr_set</a></li> +<li><a class="reference" href="ptr_multiset.html">ptr_multi_set</a></li> +<li><a class="reference" href="ptr_map.html">ptr_map</a></li> +<li><a class="reference" href="ptr_multimap.html">ptr_multimap</a></li> +</ul> +</li> +</ul> +</li> +</ul> +</li> +</ul> +</div> +<div class="section"> +<h1><a id="serialization" name="serialization">Serialization</a></h1> +<p>As of version 1.34.0 of Boost, the library supports +serialization via <a class="reference" href="../../serialization/index.html">Boost.Serialization</a>.</p> +<p>Of course, for serialization to work it is required +that the stored type itself is serializable. For maps, both +the key type and the mapped type must be serializable.</p> +<p>When dealing with serialization (and serialization of polymophic objects in particular), +pay special attention to these parts of Boost.Serialization:</p> +<ol class="arabic"> +<li><p class="first">Output/saving requires a const-reference:</p> +<pre class="literal-block"> +// +// serialization helper: we can't save a non-const object +// +template< class T > +inline T const& as_const( T const& r ) +{ + return r; +} +... +Container cont; + +std::ofstream ofs("filename"); +boost::archive::text_oarchive oa(ofs); +oa << as_const(cont); +</pre> +<p>See <a class="reference" href="../../serialization/doc/rationale.html#trap">Compile time trap when saving a non-const value</a> for +details.</p> +</li> +</ol> +<ol class="arabic" start="2"> +<li><p class="first">Derived classes need to call <tt class="docutils literal"><span class="pre">base_object()</span></tt> function:</p> +<pre class="literal-block"> +struct Derived : Base +{ + template< class Archive > + void serialize( Archive& ar, const unsigned int version ) + { + ar & boost::serialization::base_object<Base>( *this ); + ... + } +}; +</pre> +<p>For details, see <a class="reference" href="../../serialization/doc/tutorial.html#derivedclasses">Derived Classes</a>.</p> +</li> +</ol> +<ol class="arabic" start="3"> +<li><p class="first">You need to use <tt class="docutils literal"><span class="pre">BOOST_CLASS_EXPORT</span></tt> to register the +derived classes in your class hierarchy:</p> +<pre class="literal-block"> +BOOST_CLASS_EXPORT( Derived ) +</pre> +<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> +for details.</p> +</li> +</ol> +<p>Remember these three issues and it might save you some trouble.</p> +<!-- Map iterator operations ++++++++++++++++++++++++ + +The map iterators are a bit different compared to the normal ones. The +reason is that it is a bit clumsy to access the key and the mapped object +through i->first and i->second, and one tends to forget what is what. +Moreover, and more importantly, we also want to hide the pointer as much as possibble. +The new style can be illustrated with a small example:: + + typedef ptr_map<string,int> map_t; + map_t m; + m[ "foo" ] = 4; // insert pair + m[ "bar" ] = 5; // ditto + ... + for( map_t::iterator i = m.begin(); i != m.end(); ++i ) + { + *i += 42; // add 42 to each value + cout << "value=" << *i << ", key=" << i.key() << "n"; + } + +So the difference from the normal map iterator is that + +- ``operator*()`` returns a reference to the mapped object (normally it returns a reference to a ``std::pair``, and +- that the key can be accessed through the ``key()`` function. --> +</div> +<div class="section"> +<h1><a id="class-nullable" name="class-nullable">Class <tt class="docutils literal"><span class="pre">nullable</span></tt></a></h1> +<p>The purpose of the class is simply to tell the containers +that null values should be allowed. Its definition is +trivial:</p> +<pre class="literal-block"> +namespace boost +{ + template< class T > + struct nullable + { + typedef T type; + }; +} +</pre> +<p>Please notice that <tt class="docutils literal"><span class="pre">nullable</span></tt> has no effect on the containers +interface (except for <tt class="docutils literal"><span class="pre">is_null()</span></tt> functions). For example, it +does not make sense to do</p> +<pre class="literal-block"> +boost::ptr_vector< boost::nullable<T> > vec; +vec.push_back( 0 ); // ok +vec.push_back( new boost::nullable<T> ); // no no! +boost::nullable<T>& ref = vec[0]; // also no no! +</pre> +</div> +<div class="section"> +<h1><a id="exception-classes" name="exception-classes">Exception classes</a></h1> +<p>There are three exceptions that are thrown by this library. The exception +hierarchy looks as follows:</p> +<pre class="literal-block"> +namespace boost +{ + class bad_ptr_container_operation : public std::exception + { + public: + bad_ptr_container_operation( const char* what ); + }; + + class bad_index : public bad_ptr_container_operation + { + public: + bad_index( const char* what ); + }; + + class bad_pointer : public bad_ptr_container_operation + { + public: + bad_pointer(); + bad_pointer( const char* what ); + }; +} +</pre> +</div> +<div class="section"> +<h1><a id="disabling-the-use-of-exceptions" name="disabling-the-use-of-exceptions">Disabling the use of exceptions</a></h1> +<p>As of version 1.34.0 of Boost, the library allows you to disable exceptions +completely. This means the library is more fit for domains where exceptions +are not used. Furthermore, it also speeds up a operations a little. Instead +of throwing an exception, the library simply calls <a class="reference" href="../../utility/assert.html">BOOST_ASSERT</a>.</p> +<p>To disable exceptions, simply define this macro before including any header:</p> +<pre class="literal-block"> +#define BOOST_PTR_CONTAINER_NO_EXCEPTIONS 1 +#include <boost/ptr_container/ptr_vector.hpp> +</pre> +<p>It is, however, recommended that you define the macro on the command-line, so +you are absolutely certain that all headers are compiled the same way. Otherwise +you might end up breaking the One Definition Rule.</p> +<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> +is also defined.</p> +<hr><p><strong>Navigate:</strong></p> +<ul class="simple"> +<li><a class="reference" href="ptr_container.html">home</a></li> +</ul> +<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-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> +</tr> +</tbody> +</table> +</div> +</div> +</body> +</html> diff --git a/libs/ptr_container/doc/reference.rst b/libs/ptr_container/doc/reference.rst new file mode 100644 index 0000000000..3dffbc68af --- /dev/null +++ b/libs/ptr_container/doc/reference.rst @@ -0,0 +1,503 @@ +++++++++++++++++++++++++++++++++++ + |Boost| Pointer Container Library +++++++++++++++++++++++++++++++++++ + +.. |Boost| image:: boost.png + +========= +Reference +========= + +The documentation is divided into an explanation for +each container. When containers have the same interface, that common interface is explained only once, +but links are always provided to more relevant information. +Please make sure you understand +the `Clonable <reference.html#the-Clonable-concept>`_ concept and +the `Clone Allocator <reference.html#the-clone-allocator-concept>`_ concept. + +- `Conventions <conventions.html>`_ +- `The Clonable concept`_ +- `The Clone Allocator concept`_ + +- `Class hierarchy`_: + + - `reversible_ptr_container <reversible_ptr_container.html>`_ + + - `ptr_sequence_adapter <ptr_sequence_adapter.html>`_ + + - `ptr_vector <ptr_vector.html>`_ + - `ptr_list <ptr_list.html>`_ + - `ptr_deque <ptr_deque.html>`_ + - `ptr_array <ptr_array.html>`_ + + - `associative_ptr_container <associative_ptr_container.html>`_ + + - `ptr_set_adapter <ptr_set_adapter.html>`_ + - `ptr_multiset_adapter <ptr_multiset_adapter.html>`_ + - `ptr_map_adapter <ptr_map_adapter.html>`_ + - `ptr_multi_map_adapter <ptr_multimap_adapter.html>`_ + + - `ptr_set <ptr_set.html>`_ + - `ptr_multi_set <ptr_multiset.html>`_ + - `ptr_map <ptr_map.html>`_ + - `ptr_multimap <ptr_multimap.html>`_ + +- `Serialization`_ +- `Indirected functions <indirect_fun.html>`_ +- `Insert iterators <ptr_inserter.html>`_ +- `Class nullable`_ +- `Exception classes`_ +- `Disabling the use of exceptions`_ + + +.. + - Class `reversible_ptr_container <reversible_ptr_container.html>`_ + - Class `associative_ptr_container <associative_ptr_container.html>`_ + - `Pointer container adapters`_ + + - `ptr_sequence_adapter <ptr_sequence_adapter.html>`_ + - `ptr_set_adapter <ptr_set_adapter.html>`_ + - `ptr_multiset_adapter <ptr_multiset_adapter.html>`_ + - `ptr_map_adapter <ptr_map_adapter.html>`_ + - `ptr_multimap_adapter <ptr_multimap_adapter.html>`_ + - `Sequence containers`_ + + - `ptr_vector <ptr_vector.html>`_ + - `ptr_deque <ptr_deque.html>`_ + - `ptr_list <ptr_list.html>`_ + - `ptr_array <ptr_array.html>`_ + - `Associative containers`_ + + - `ptr_set <ptr_set.html>`_ + - `ptr_multiset <ptr_multiset.html>`_ + - `ptr_map <ptr_map.html>`_ + - `ptr_multimap <ptr_multimap.html>`_ + + + +The Clonable concept +++++++++++++++++++++ + +**Refinement of** + +- Heap Allocable +- Heap Deallocable + +The Clonable concept is introduced to formalize the requirements for +copying heap-allocated objects. A type ``T`` might be Clonable even though it +is not Assignable or Copy Constructible. Notice that many operations on +the containers do not even require the stored type to be Clonable. + +**Notation** + +======================= ============================================ =================== ===================== + **Type** **Object** (``const`` or non-``const``) **Pointer** **Describes** + ``T`` ``a`` ``ptr`` A Clonable type +======================= ============================================ =================== ===================== + +**Valid expressions** + +===================================== =========================== ======================================================================================== =================================== + **Expression** **Type** **Semantics** **Postcondition** + ``new_clone(a);`` ``T*`` Allocate a new object that can be considered equivalent to the ``a`` object ``typeid(*new_clone(a)) == typeid(a)`` + ``delete_clone(ptr);`` ``void`` Deallocate an object previously allocated with ``allocate_clone()``. Must not throw +===================================== =========================== ======================================================================================== =================================== + + +Default implementation +---------------------- + +In the ``<boost/ptr_container/clone_allocator.hpp>`` header a default implementation +of the two functions is given: + +.. parsed-literal:: + + namespace boost + { + template< class T > + inline T* new_clone( const T& t ) + { + return new T( t ); + } + + template< class T > + void delete_clone( const T* t ) + { + checked_delete( t ); + } + } + + +Notice that this implementation makes normal Copy Constructible classes automatically +Clonable unless ``operator new()`` or ``operator delete()`` are hidden. + +The two functions represent a layer of indirection which is necessary to support +classes that are not Copy Constructible by default. Notice that the implementation +relies on argument-dependent lookup (ADL) to find the right version of +``new_clone()`` and ``delete_clone()``. This means that one does not need to overload or specialize +the function in the boost namespace, but it can be placed together with +the rest of the interface of the class. If you are implementing a class +inline in headers, remember to forward declare the functions. + +**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.** + +The Clone Allocator concept ++++++++++++++++++++++++++++ + +The Clone Allocator concept is introduced to formalize the way +pointer containers control memory of +the stored objects (and not the pointers to the stored objects). +The clone allocator allows +users to apply custom allocators/deallocators for the cloned objects. + +More information can be found below: + +.. contents:: :depth: 1 + :local: + + +Clone Allocator requirements +---------------------------- + +**Notation** + +===================== ============================================= ================================================== + **Type** **Object** (``const`` or non-``const``) **Describes** + ``T`` ``a`` A type + ``T*`` ``ptr`` A pointer to ``T`` +===================== ============================================= ================================================== + +**Valid expressions** + +============================================== ============= ============================================================================= ============================================================= + **Expression** **Type** **Semantics** **Postcondition** + ``CloneAllocator::allocate_clone(a);`` ``T*`` Allocate a new object that can be considered equivalent to the + ``a`` object ``typeid(*CloneAllocator::allocate_clone(a)) == typeid(a)`` + ``CloneAllocator::deallocate_clone(ptr);`` ``void`` Deallocate an object previously allocated with + ``CloneAllocator::allocate_clone()`` or a compatible allocator. + Must not throw. +============================================== ============= ============================================================================= ============================================================= + + + +The library comes with two predefined clone allocators. + +Class ``heap_clone_allocator`` +------------------------------ + +This is the default clone allocator used by all pointer containers. For most +purposes you will never have to change this default. + +**Definition** + +.. parsed-literal:: + + namespace boost + { + struct heap_clone_allocator + { + template< class U > + static U* allocate_clone( const U& r ) + { + return new_clone( r ); + } + + template< class U > + static void deallocate_clone( const U* r ) + { + delete_clone( r ); + } + }; + } + +Notice that the above definition allows you to support custom allocation +schemes by relying on ``new_clone()`` and ``delete_clone()``. + +Class ``view_clone_allocator`` +------------------------------ + +This class provides a way to remove ownership properties of the +pointer containers. As its name implies, this means that you can +instead use the pointer containers as a view into an existing +container. + +**Definition** + +.. parsed-literal:: + + namespace boost + { + struct view_clone_allocator + { + template< class U > + static U* allocate_clone( const U& r ) + { + return const_cast<U*>(&r); + } + + template< class U > + static void deallocate_clone( const U* ) + { + // empty + } + }; + } + +.. **See also** + + - `Changing the clone allocator <examples.html#changing-the-clone-allocator>`_ + +Class hierarchy ++++++++++++++++ + +The library consists of the following types of classes: + +1. Pointer container adapters + +.. + +2. Pointer containers + +The pointer container adapters are used when you +want to make a pointer container starting from +your own "normal" container. For example, you +might have a map class that extends ``std::map`` +in some way; the adapter class then allows you +to use your map class as a basis for a new +pointer container. + +The library provides an adapter for each type +of standard container highlighted as links below: + +- ``reversible_ptr_container`` + + - `ptr_sequence_adapter <ptr_sequence_adapter.html>`_ + + - ``ptr_vector`` + - ``ptr_list`` + - ``ptr_deque`` + - ``ptr_array`` + + - ``associative_ptr_container`` + + - `ptr_set_adapter <ptr_set_adapter.html>`_ + - `ptr_multiset_adapter <ptr_multiset_adapter.html>`_ + - `ptr_map_adapter <ptr_map_adapter.html>`_ + - `ptr_multi_map_adapter <ptr_multimap_adapter.html>`_ + + - ``ptr_set`` + - ``ptr_multi_set`` + - ``ptr_map`` + - ``ptr_multimap`` + + +The pointer containers of this library are all built using +the adapters. There is a pointer container +for each type of "normal" standard container highlighted as links below. + +- ``reversible_ptr_container`` + + - ``ptr_sequence_adapter`` + + - `ptr_vector <ptr_vector.html>`_ + - `ptr_list <ptr_list.html>`_ + - `ptr_deque <ptr_deque.html>`_ + - `ptr_array <ptr_array.html>`_ + + - ``associative_ptr_container`` + + - ``ptr_set_adapter`` + - ``ptr_multiset_adapter`` + - ``ptr_map_adapter`` + - ``ptr_multi_map_adapter`` + + - `ptr_set <ptr_set.html>`_ + - `ptr_multi_set <ptr_multiset.html>`_ + - `ptr_map <ptr_map.html>`_ + - `ptr_multimap <ptr_multimap.html>`_ + +Serialization ++++++++++++++ + +As of version 1.34.0 of Boost, the library supports +serialization via `Boost.Serialization`__. + +.. __: ../../serialization/index.html + +Of course, for serialization to work it is required +that the stored type itself is serializable. For maps, both +the key type and the mapped type must be serializable. + +When dealing with serialization (and serialization of polymophic objects in particular), +pay special attention to these parts of Boost.Serialization: + +1. Output/saving requires a const-reference:: + + // + // serialization helper: we can't save a non-const object + // + template< class T > + inline T const& as_const( T const& r ) + { + return r; + } + ... + Container cont; + + std::ofstream ofs("filename"); + boost::archive::text_oarchive oa(ofs); + oa << as_const(cont); + + See `Compile time trap when saving a non-const value`__ for + details. + +.. __: ../../serialization/doc/rationale.html#trap + +2. Derived classes need to call ``base_object()`` function:: + + struct Derived : Base + { + template< class Archive > + void serialize( Archive& ar, const unsigned int version ) + { + ar & boost::serialization::base_object<Base>( *this ); + ... + } + }; + + For details, see `Derived Classes`_. + +.. _`Derived Classes`: ../../serialization/doc/tutorial.html#derivedclasses + +3. You need to use ``BOOST_CLASS_EXPORT`` to register the + derived classes in your class hierarchy:: + + BOOST_CLASS_EXPORT( Derived ) + + See `Export Key`__ and `Object Tracking`_ + for details. + +.. __: ../../serialization/doc/traits.html#export +.. _`Object Tracking`: ../../serialization/doc/special.html + +Remember these three issues and it might save you some trouble. + +.. + Map iterator operations + +++++++++++++++++++++++ + + The map iterators are a bit different compared to the normal ones. The + reason is that it is a bit clumsy to access the key and the mapped object + through i->first and i->second, and one tends to forget what is what. + Moreover, and more importantly, we also want to hide the pointer as much as possibble. + The new style can be illustrated with a small example:: + + typedef ptr_map<string,int> map_t; + map_t m; + m[ "foo" ] = 4; // insert pair + m[ "bar" ] = 5; // ditto + ... + for( map_t::iterator i = m.begin(); i != m.end(); ++i ) + { + *i += 42; // add 42 to each value + cout << "value=" << *i << ", key=" << i.key() << "n"; + } + + So the difference from the normal map iterator is that + + - ``operator*()`` returns a reference to the mapped object (normally it returns a reference to a ``std::pair``, and + - that the key can be accessed through the ``key()`` function. + +Class ``nullable`` +++++++++++++++++++ + +The purpose of the class is simply to tell the containers +that null values should be allowed. Its definition is +trivial:: + + namespace boost + { + template< class T > + struct nullable + { + typedef T type; + }; + } + +Please notice that ``nullable`` has no effect on the containers +interface (except for ``is_null()`` functions). For example, it +does not make sense to do :: + + boost::ptr_vector< boost::nullable<T> > vec; + vec.push_back( 0 ); // ok + vec.push_back( new boost::nullable<T> ); // no no! + boost::nullable<T>& ref = vec[0]; // also no no! + +Exception classes ++++++++++++++++++ + +There are three exceptions that are thrown by this library. The exception +hierarchy looks as follows:: + + + namespace boost + { + class bad_ptr_container_operation : public std::exception + { + public: + bad_ptr_container_operation( const char* what ); + }; + + class bad_index : public bad_ptr_container_operation + { + public: + bad_index( const char* what ); + }; + + class bad_pointer : public bad_ptr_container_operation + { + public: + bad_pointer(); + bad_pointer( const char* what ); + }; + } + +Disabling the use of exceptions ++++++++++++++++++++++++++++++++ + +As of version 1.34.0 of Boost, the library allows you to disable exceptions +completely. This means the library is more fit for domains where exceptions +are not used. Furthermore, it also speeds up a operations a little. Instead +of throwing an exception, the library simply calls `BOOST_ASSERT`__. + +.. __: ../../utility/assert.html + +To disable exceptions, simply define this macro before including any header:: + + #define BOOST_PTR_CONTAINER_NO_EXCEPTIONS 1 + #include <boost/ptr_container/ptr_vector.hpp> + +It is, however, recommended that you define the macro on the command-line, so +you are absolutely certain that all headers are compiled the same way. Otherwise +you might end up breaking the One Definition Rule. + +If ``BOOST_NO_EXCEPTIONS`` is defined, then ``BOOST_PTR_CONTAINER_NO_EXCEPTIONS`` +is also defined. + +.. raw:: html + + <hr> + +**Navigate:** + +- `home <ptr_container.html>`_ + +.. raw:: html + + <hr> + +:Copyright: Thorsten Ottosen 2004-2007. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). + +__ http://www.boost.org/LICENSE_1_0.txt + + diff --git a/libs/ptr_container/doc/reversible_ptr_container.html b/libs/ptr_container/doc/reversible_ptr_container.html new file mode 100644 index 0000000000..7074fca7f9 --- /dev/null +++ b/libs/ptr_container/doc/reversible_ptr_container.html @@ -0,0 +1,826 @@ +<?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: 2007-11-25 13:38:02 -0500 (Sun, 25 Nov 2007) $ +:Revision: $Revision: 41370 $ +: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> +<div class="section"> +<h1><a id="class-reversible-ptr-container" name="class-reversible-ptr-container">Class <tt class="docutils literal"><span class="pre">reversible_ptr_container</span></tt></a></h1> +<p>This class is not a real class that can be found in the library. +Its purpose is to present the general interface of all the pointer containers.</p> +<p><strong>Hierarchy:</strong></p> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">reversible_ptr_container</span></tt><ul> +<li><a class="reference" href="ptr_sequence_adapter.html">ptr_sequence_adapter</a><ul> +<li><a class="reference" href="ptr_vector.html">ptr_vector</a></li> +<li><a class="reference" href="ptr_list.html">ptr_list</a></li> +<li><a class="reference" href="ptr_deque.html">ptr_deque</a></li> +<li><a class="reference" href="ptr_array.html">ptr_array</a></li> +</ul> +</li> +<li><a class="reference" href="associative_ptr_container.html">associative_ptr_container</a><ul> +<li><a class="reference" href="ptr_set_adapter.html">ptr_set_adapter</a></li> +<li><a class="reference" href="ptr_multiset_adapter.html">ptr_multiset_adapter</a></li> +<li><a class="reference" href="ptr_map_adapter.html">ptr_map_adapter</a></li> +<li><a class="reference" href="ptr_multimap_adapter.html">ptr_multi_map_adapter</a><ul> +<li><a class="reference" href="ptr_set.html">ptr_set</a></li> +<li><a class="reference" href="ptr_multiset.html">ptr_multi_set</a></li> +<li><a class="reference" href="ptr_map.html">ptr_map</a></li> +<li><a class="reference" href="ptr_multimap.html">ptr_multimap</a></li> +</ul> +</li> +</ul> +</li> +</ul> +</li> +</ul> +<p><strong>Navigate:</strong></p> +<ul class="simple"> +<li><a class="reference" href="ptr_container.html">home</a></li> +<li><a class="reference" href="reference.html">reference</a></li> +</ul> +<p><strong>synopsis:</strong></p> +<pre class="literal-block"> +namespace boost +{ + template + < + class T, + class CloneAllocator, + class VoidPtrContainer + > + class reversible_ptr_container + { + public: // <a class="reference" href="#typedefs">typedefs</a> + typedef T* value_type; + typedef T& reference; + typedef const T& const_reference; + typedef <em>implementation defined</em> iterator; + typedef <em>implementation defined</em> const_iterator; + typedef typename VoidPtrContainer::differnce_type difference_type; + typedef typename VoidPtrContainer::size_type size_type; + typedef typename VoidPtrContainer::allocator_type allocator_type; + typedef <em>implementation defined</em> reverse_iterator; + typedef <em>implementation defined</em> const_reverse_iterator; + typedef <em>implementation defined</em> auto_type; + + public: // <a class="reference" href="#construct-copy-destroy">construct/copy/destroy</a> + reversible_ptr_container(); + explicit reversible_ptr_container( const reversible_ptr_container& r ); + template< class Derived > + explicit reversible_ptr_container( const reversible_ptr_container<Derived>& r ); + explicit reversible_ptr_container( std::auto_ptr<reversible_ptr_container> r ); + template< class InputIterator > + reversible_ptr_container( InputIterator first, InputIterator last ); + + ~reversible_ptr_container(); + + reversible_ptr_container& operator=( const reversible_ptr_container& r ); + template<class Derived> + reversible_ptr_container& operator=( const reversible_ptr_container<Derived>& r ); + reversible_ptr_container& operator=( std::auto_ptr<reversible_ptr_container> r ); + allocator_type get_allocator() const; + + public: // <a class="reference" href="#iterators">iterators</a> + iterator begin(); + const_iterator begin() const; + iterator end(); + const_iterator end() const; + reverse_iterator rbegin(); + const_reverse_iterator rbegin() const; + reverse_iterator rend(); + const_reverse_iterator rend() const; + + public: // <a class="reference" href="#capacity">capacity</a> + size_type size() const; + size_type max_size() const; + bool empty() const; + + public: // <a class="reference" href="#modifiers">modifiers</a> + void swap( reversible_ptr_container& r ); + void clear(): + VoidPtrContainer& base(); + const VoidPtrContainer& base() const; + + public: // <a class="reference" href="#pointer-container-requirements">pointer container requirements</a> + auto_type replace( iterator position, T* x ); + template< class U > + auto_type replace( iterator position, std::auto_ptr<U> x ); + std::auto_ptr<reversible_ptr_container> clone() const; + std::auto_ptr<reversible_ptr_container> release(); + auto_type release( iterator position ); + + }; // class 'reversible_ptr_container' + + // <a class="reference" href="#comparison">comparison</a> + template < class T, class CA, class VPC > + bool operator==( const reversible_ptr_container<T,CA,VPC>& x, + const reversible_ptr_container<T,CA,VPC>& y); + + template < class T, class CA, class VPC > + bool operator<( const reversible_ptr_container<T,CA,VPC>& x, + const reversible_ptr_container<T,CA,VPC>& y); + + template < class T, class CA, class VPC > + bool operator!=( const reversible_ptr_container<T,CA,VPC>& x, + const reversible_ptr_container<T,CA,VPC>& y); + + template < class T, class CA, class VPC > + bool operator>( const reversible_ptr_container<T,CA,VPC>& x, + const reversible_ptr_container<T,CA,VPC>& y); + + template < class T, class CA, class VPC > + bool operator>=( const reversible_ptr_container<T,CA,VPC>& x, + const reversible_ptr_container<T,CA,VPC>& y); + + template < class T, class CA, class VPC > + bool operator<=( const reversible_ptr_container<T,CA,VPC>& x, + const reversible_ptr_container<T,CA,VPC>& y); + + template< class T, class CA, class VPC > + void swap( reversible_ptr_container<T,CA,VPC>& x, + reversible_ptr_container<T,CA,VPC>& y ); + + // <a class="reference" href="#cloneability">cloneability</a> + template< class T, class CA, class VPC > + reversible_ptr_container<T,CA,VPC>* + new_clone( const reversible_ptr_container<T,CA,VPC>& r ); + + // <a class="reference" href="#null-predicate">null predicate</a> + template< class Iterator > + bool is_null( Iterator i ); + + // <a class="reference" href="#serialization">serialization</a> + template<class Archive, class T, class CA, class VPC> + void serialize( Archive& ar, reversible_ptr_container<T,CÃ,VPC>& c, const unsigned int version ); + + +} // namespace 'boost' +</pre> +</div> +<div class="section"> +<h1><a id="semantics" name="semantics">Semantics</a></h1> +<div class="section"> +<h2><a id="semantics-typedefs" name="semantics-typedefs"><span id="typedefs"></span>Semantics: typedefs</a></h2> +<p>Notice how these two types differ:</p> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">T*</span> <span class="pre">value_type;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>notice this has pointer type</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">T&</span> <span class="pre">reference;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>notice this is not a pointer type</li> +</ul> +</blockquote> +</li> +</ul> +<p>This is done to be able to add pointers directly +to the container, but to hide the pointers externally.</p> +<!-- - ``typedef *implementation defined* object_type;`` +- this is ``T`` for sequences and sets +- this is ``std::pair<const Key, void*>`` for maps --> +<p>Also notice that</p> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">...</span> <span class="pre">iterator</span></tt></li> +</ul> +<p>allows one to iterate over <tt class="docutils literal"><span class="pre">T&</span></tt> objects, not <tt class="docutils literal"><span class="pre">T*</span></tt>. +Note that:</p> +<pre class="literal-block"> +iterator i = ...; +i.base(); +</pre> +<p>returns an iterator that allows one to iterate over <tt class="docutils literal"><span class="pre">void*</span></tt> +elements (<em>this is very rarely needed and you should not use the +functionality unless you know what you are doing</em>).</p> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">...</span> <span class="pre">auto_type</span></tt></li> +</ul> +<p>This declaration hides a pointer pointer type. You can rely on the following +operations</p> +<pre class="literal-block"> +T* operator->() const; +T& operator*() const; +T* release(); +~auto_type(); +operator <em>implementation-defined bool</em>(); +</pre> +<p>The destructor will delete the stored object <em>using the clone allocator of the container</em> +(this explains why we cannot use <tt class="docutils literal"><span class="pre">std::auto_ptr<T></span></tt>). It might help to +think it is just an <tt class="docutils literal"><span class="pre">std::auto_ptr<T></span></tt>. You can also return +the pointer from a function or assign it to another pointer via the <tt class="docutils literal"><span class="pre">move()</span></tt> +function</p> +<pre class="literal-block"> +auto_type ptr = ...; +auto_type other = boost::ptr_container::move( ptr ); +return boost::ptr_container::move( other ); +</pre> +</div> +<div class="section"> +<h2><a id="semantics-construct-copy-destroy" name="semantics-construct-copy-destroy"><span id="construct-copy-destroy"></span>Semantics: construct/copy/destroy</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">reversible_ptr_container();</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Constructs an empty container</li> +<li>Postconditions: <tt class="docutils literal"><span class="pre">size()</span> <span class="pre">==</span> <span class="pre">0</span></tt></li> +</ul> +</blockquote> +</li> +</ul> +<!-- - ``reversible_ptr_container( size_type n, const T& x );`` + +- Effects: Constructs a container with ``n`` clones of ``x`` + +- Postconditions: ``size() == n`` --> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">explicit</span> <span class="pre">reversible_ptr_container(</span> <span class="pre">const</span> <span class="pre">reversible_ptr_container&</span> <span class="pre">r</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Constructs a container by cloning all elements of <tt class="docutils literal"><span class="pre">r</span></tt></li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">Derived</span> <span class="pre">></span> <span class="pre">explicit</span> <span class="pre">reversible_ptr_container(</span> <span class="pre">const</span> <span class="pre">reversible_ptr_container<Derived>&</span> <span class="pre">r</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Constructs a container by cloning all elements of <tt class="docutils literal"><span class="pre">r</span></tt></li> +<li>Requirements: <tt class="docutils literal"><span class="pre">Derived</span></tt> is derived from <tt class="docutils literal"><span class="pre">T</span></tt></li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">explicit</span> <span class="pre">reversible_ptr_container(</span> <span class="pre">std::auto_ptr<</span> <span class="pre">reversible_ptr_container</span> <span class="pre">></span> <span class="pre">r</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Constructs a container by taking ownership of the supplied pointers</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">InputIterator</span> <span class="pre">></span></tt> +<tt class="docutils literal"><span class="pre">reversible_ptr_container(</span> <span class="pre">InputIterator</span> <span class="pre">first,</span> <span class="pre">InputIterator</span> <span class="pre">last</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">(first,last]</span></tt> is a valid range</li> +<li>Effects: Constructs a container with a cloned range of <tt class="docutils literal"><span class="pre">(first,last]</span></tt></li> +<li>Postconditions: <tt class="docutils literal"><span class="pre">size()</span> <span class="pre">==</span> <span class="pre">std::distance(</span> <span class="pre">first,</span> <span class="pre">last</span> <span class="pre">)</span></tt></li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">~reversible_ptr_container();</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Deletes the stored objects via the clone allocator</li> +<li>Throws: Nothing</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">reversible_ptr_container&</span> <span class="pre">operator=(</span> <span class="pre">const</span> <span class="pre">reversible_ptr_container&</span> <span class="pre">r</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Assigns a clone of <tt class="docutils literal"><span class="pre">r</span></tt></li> +<li>Exception safety: strong guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<class</span> <span class="pre">Derived></span> <span class="pre">reversible_ptr_container&</span> <span class="pre">operator=(</span> <span class="pre">const</span> <span class="pre">reversible_ptr_container<Derived>&</span> <span class="pre">r</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Assigns a clone of <tt class="docutils literal"><span class="pre">r</span></tt></li> +<li>Requirements: <tt class="docutils literal"><span class="pre">Derived</span></tt> is derived from <tt class="docutils literal"><span class="pre">T</span></tt></li> +<li>Exception safety: Strong guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">reversible_ptr_container&</span> <span class="pre">operator=(</span> <span class="pre">std::auto_ptr<reversible_ptr_container></span> <span class="pre">r</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Deletes the stored objects and then takes ownership of the supplied pointers</li> +<li>Throws: Nothing</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">allocator_type</span> <span class="pre">get_allocator()</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Returns a copy of the allocator of the container object</li> +</ul> +</blockquote> +</li> +</ul> +</div> +<div class="section"> +<h2><a id="semantics-iterators" name="semantics-iterators"><span id="iterators"></span>Semantics: iterators</a></h2> +<p><strong>See also:</strong> <a class="reference" href="conventions.html#iterators-are-invalidated-as-in-the-corresponding-standard-container">iterator invalidation</a></p> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">iterator</span> <span class="pre">begin();</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">const_iterator</span> <span class="pre">begin()</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Returns a mutable/non-mutable iterator with <tt class="docutils literal"><span class="pre">value_type</span> <span class="pre">T</span></tt></li> +<li>Throws: Nothing</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">iterator</span> <span class="pre">end();</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">const_iterator</span> <span class="pre">end()</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Returns a mutable/non-mutable iterator with <tt class="docutils literal"><span class="pre">value_type</span> <span class="pre">T</span></tt></li> +<li>Throws: Nothing</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">reverse_iterator</span> <span class="pre">rbegin();</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">const_reverse_iterator</span> <span class="pre">rbegin()</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Returns a mutable/non-mutable reverse iterator with <tt class="docutils literal"><span class="pre">value_type</span> <span class="pre">T</span></tt></li> +<li>Throws: Nothing</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">reverse_iterator</span> <span class="pre">rend();</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">const_reverse_iterator</span> <span class="pre">rend()</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Returns a mutable/non-mutable reverse iterator with <tt class="docutils literal"><span class="pre">value_type</span> <span class="pre">T</span></tt></li> +<li>Throws: Nothing</li> +</ul> +</blockquote> +</li> +</ul> +</div> +<div class="section"> +<h2><a id="semantics-capacity" name="semantics-capacity"><span id="capacity"></span>Semantics: capacity</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">size_type</span> <span class="pre">size()</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Returns the number of stored elements</li> +<li>Throws: Nothing</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">size_type</span> <span class="pre">max_size()</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Returns the maximum number of stored elements</li> +<li>Throws: Nothing</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">empty()</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Returns whether the container is empty or not</li> +<li>Throws: Nothing</li> +</ul> +</blockquote> +</li> +</ul> +</div> +<div class="section"> +<h2><a id="semantics-modifiers" name="semantics-modifiers"><span id="modifiers"></span>Semantics: modifiers</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">swap(</span> <span class="pre">reversible_ptr_container&</span> <span class="pre">r</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Swaps the content of the two containers</li> +<li>Throws: Nothing</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">clear();</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Destroys all object of the container</li> +<li>Postconditions: <tt class="docutils literal"><span class="pre">empty()</span> <span class="pre">==</span> <span class="pre">true</span></tt></li> +<li>Throws: Nothing</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">VoidPtrContainer&</span> <span class="pre">base();</span></tt></p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">const</span> <span class="pre">VoidPtrContainer&</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Returns: a reference to the wrapped container</li> +</ul> +</blockquote> +</li> +</ul> +</div> +<div class="section"> +<h2><a id="semantics-pointer-container-requirements" name="semantics-pointer-container-requirements"><span id="pointer-container-requirements"></span>Semantics: pointer container requirements</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">auto_type</span> <span class="pre">replace(</span> <span class="pre">iterator</span> <span class="pre">position,</span> <span class="pre">T*</span> <span class="pre">x</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">not</span> <span class="pre">empty()</span> <span class="pre">and</span> <span class="pre">x</span> <span class="pre">!=</span> <span class="pre">0</span></tt></li> +<li>Effects: returns the object pointed to by <tt class="docutils literal"><span class="pre">position</span></tt> and replaces it with <tt class="docutils literal"><span class="pre">x</span></tt>.</li> +<li>Throws: <tt class="docutils literal"><span class="pre">bad_ptr_container_operation</span></tt> if the container is empty and <tt class="docutils literal"><span class="pre">bad_pointer</span></tt> if <tt class="docutils literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">0</span></tt>.</li> +<li>Exception safety: Strong guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">U</span> <span class="pre">></span> <span class="pre">auto_type</span> <span class="pre">replace(</span> <span class="pre">iterator</span> <span class="pre">position,</span> <span class="pre">std::auto_ptr<U></span> <span class="pre">x</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: <tt class="docutils literal"><span class="pre">return</span> <span class="pre">replace(</span> <span class="pre">position,</span> <span class="pre">x.release()</span> <span class="pre">);</span></tt></li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">std::auto_ptr<</span> <span class="pre">reversible_ptr_container</span> <span class="pre">></span> <span class="pre">clone()</span> <span class="pre">const;</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Returns a deep copy of the container</li> +<li>Throws: <tt class="docutils literal"><span class="pre">std::bad_alloc</span></tt> if there is not enough memory to make a clone of the container</li> +<li>Complexity: Linear</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">std::auto_ptr<</span> <span class="pre">reversible_ptr_container</span> <span class="pre">></span> <span class="pre">release();</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: Releases ownership of the container. This is a useful way of returning a container from a function.</li> +<li>Postconditions: <tt class="docutils literal"><span class="pre">empty()</span> <span class="pre">==</span> <span class="pre">true</span></tt></li> +<li>Throws: <tt class="docutils literal"><span class="pre">std::bad_alloc</span></tt> if the return value cannot be allocated</li> +<li>Exception safety: Strong guarantee</li> +</ul> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">auto_type</span> <span class="pre">release(</span> <span class="pre">iterator</span> <span class="pre">position</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">not</span> <span class="pre">empty();</span></tt></li> +<li>Effects: Releases ownership of the pointer referred to by position</li> +<li>Postconditions: <tt class="docutils literal"><span class="pre">size()</span></tt> is one less</li> +<li>Throws: <tt class="docutils literal"><span class="pre">bad_ptr_container_operation</span></tt> if the container is empty</li> +<li>Exception safety: Strong guarantee</li> +</ul> +</blockquote> +</li> +</ul> +</div> +<div class="section"> +<h2><a id="semantics-comparison" name="semantics-comparison"><span id="comparison"></span>Semantics: comparison</a></h2> +<p>These functions compare the underlying range of objects. +So</p> +<pre class="literal-block"> +operation( const ptr_container& l, const ptr_container& r ); +</pre> +<p>has the effect one would expect of normal standard containers. Hence +objects are compared and not the pointers to objects.</p> +</div> +<div class="section"> +<h2><a id="semantics-cloneability" name="semantics-cloneability"><span id="cloneability"></span>Semantics: cloneability</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">T,</span> <span class="pre">class</span> <span class="pre">CloneAllocator</span> <span class="pre">></span> +<span class="pre">reversible_ptr_container<T,CA,VPC>*</span> +<span class="pre">new_clone(</span> <span class="pre">const</span> <span class="pre">reversible_ptr_container<T,CA,VPC>&</span> <span class="pre">r</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Effects: <tt class="docutils literal"><span class="pre">return</span> <span class="pre">r.clone().release();</span></tt></li> +<li>Remarks: This function is only defined for concrete <a class="reference" href="ptr_container.html#smart-containers">pointer containers</a>, but not for +<a class="reference" href="ptr_container.html#smart-container-adapters">pointer container adapters</a>.</li> +</ul> +</blockquote> +</li> +</ul> +</div> +<div class="section"> +<h2><a id="semantics-null-predicate" name="semantics-null-predicate"><span id="null-predicate"></span>Semantics: null predicate</a></h2> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">template<</span> <span class="pre">class</span> <span class="pre">Iterator</span> <span class="pre">></span> <span class="pre">bool</span> <span class="pre">is_null(</span> <span class="pre">Iterator</span> <span class="pre">i</span> <span class="pre">);</span></tt></p> +<blockquote> +<ul class="simple"> +<li>Requirements: <tt class="docutils literal"><span class="pre">i</span></tt> is a valid dereferencable iterator</li> +<li>Returns: <tt class="docutils literal"><span class="pre">*i.base()</span> <span class="pre">==</span> <span class="pre">0;</span></tt></li> +</ul> +</blockquote> +</li> +</ul> +</div> +<div class="section"> +<h2><a id="semantics-serialization" name="semantics-serialization"><span id="serialization"></span>Semantics: serialization</a></h2> +<p>All containers can be serialized by means of +<a class="reference" href="../../serialization/index.html">Boost.Serialization</a>. For an overview, see +<a class="reference" href="reference.html#serialization">Serialization of Pointer Containers</a>.</p> +<blockquote> +<pre class="literal-block"> +template<class Archive, class T, class CA, class VPC> +void serialize( Archive& ar, reversible_ptr_container<T,CA,VPC>& c, const unsigned int version ); +</pre> +</blockquote> +<ul class="simple"> +<li>Effects: Saves or loads the container to/from the archive.</li> +<li>Remarks: This function is called automatically be stream operators in +Boost.Serialization</li> +<li>Exception safety: Loading gives the basic guarantee</li> +</ul> +<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-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> +</tr> +</tbody> +</table> +</div> +</div> +</div> +</body> +</html> diff --git a/libs/ptr_container/doc/reversible_ptr_container.rst b/libs/ptr_container/doc/reversible_ptr_container.rst new file mode 100644 index 0000000000..1833539d94 --- /dev/null +++ b/libs/ptr_container/doc/reversible_ptr_container.rst @@ -0,0 +1,513 @@ +++++++++++++++++++++++++++++++++++ + |Boost| Pointer Container Library +++++++++++++++++++++++++++++++++++ + +.. |Boost| image:: boost.png + +Class ``reversible_ptr_container`` +------------------------------------ + +This class is not a real class that can be found in the library. +Its purpose is to present the general interface of all the pointer containers. + +**Hierarchy:** + +- ``reversible_ptr_container`` + + - `ptr_sequence_adapter <ptr_sequence_adapter.html>`_ + + - `ptr_vector <ptr_vector.html>`_ + - `ptr_list <ptr_list.html>`_ + - `ptr_deque <ptr_deque.html>`_ + - `ptr_array <ptr_array.html>`_ + + - `associative_ptr_container <associative_ptr_container.html>`_ + + - `ptr_set_adapter <ptr_set_adapter.html>`_ + - `ptr_multiset_adapter <ptr_multiset_adapter.html>`_ + - `ptr_map_adapter <ptr_map_adapter.html>`_ + - `ptr_multi_map_adapter <ptr_multimap_adapter.html>`_ + + - `ptr_set <ptr_set.html>`_ + - `ptr_multi_set <ptr_multiset.html>`_ + - `ptr_map <ptr_map.html>`_ + - `ptr_multimap <ptr_multimap.html>`_ + +**Navigate:** + +- `home <ptr_container.html>`_ +- `reference <reference.html>`_ + +**synopsis:** + +.. parsed-literal:: + + namespace boost + { + template + < + class T, + class CloneAllocator, + class VoidPtrContainer + > + class reversible_ptr_container + { + public: // `typedefs`_ + typedef T* value_type; + typedef T& reference; + typedef const T& const_reference; + typedef *implementation defined* iterator; + typedef *implementation defined* const_iterator; + typedef typename VoidPtrContainer::differnce_type difference_type; + typedef typename VoidPtrContainer::size_type size_type; + typedef typename VoidPtrContainer::allocator_type allocator_type; + typedef *implementation defined* reverse_iterator; + typedef *implementation defined* const_reverse_iterator; + typedef *implementation defined* auto_type; + + public: // `construct/copy/destroy`_ + reversible_ptr_container(); + explicit reversible_ptr_container( const reversible_ptr_container& r ); + template< class Derived > + explicit reversible_ptr_container( const reversible_ptr_container<Derived>& r ); + explicit reversible_ptr_container( std::auto_ptr<reversible_ptr_container> r ); + template< class InputIterator > + reversible_ptr_container( InputIterator first, InputIterator last ); + + ~reversible_ptr_container(); + + reversible_ptr_container& operator=( const reversible_ptr_container& r ); + template<class Derived> + reversible_ptr_container& operator=( const reversible_ptr_container<Derived>& r ); + reversible_ptr_container& operator=( std::auto_ptr<reversible_ptr_container> r ); + allocator_type get_allocator() const; + + public: // `iterators`_ + iterator begin(); + const_iterator begin() const; + iterator end(); + const_iterator end() const; + reverse_iterator rbegin(); + const_reverse_iterator rbegin() const; + reverse_iterator rend(); + const_reverse_iterator rend() const; + + public: // `capacity`_ + size_type size() const; + size_type max_size() const; + bool empty() const; + + public: // `modifiers`_ + void swap( reversible_ptr_container& r ); + void clear(): + VoidPtrContainer& base(); + const VoidPtrContainer& base() const; + + public: // `pointer container requirements`_ + auto_type replace( iterator position, T* x ); + template< class U > + auto_type replace( iterator position, std::auto_ptr<U> x ); + std::auto_ptr<reversible_ptr_container> clone() const; + std::auto_ptr<reversible_ptr_container> release(); + auto_type release( iterator position ); + + }; // class 'reversible_ptr_container' + + // `comparison`_ + template < class T, class CA, class VPC > + bool operator==( const reversible_ptr_container<T,CA,VPC>& x, + const reversible_ptr_container<T,CA,VPC>& y); + + template < class T, class CA, class VPC > + bool operator<( const reversible_ptr_container<T,CA,VPC>& x, + const reversible_ptr_container<T,CA,VPC>& y); + + template < class T, class CA, class VPC > + bool operator!=( const reversible_ptr_container<T,CA,VPC>& x, + const reversible_ptr_container<T,CA,VPC>& y); + + template < class T, class CA, class VPC > + bool operator>( const reversible_ptr_container<T,CA,VPC>& x, + const reversible_ptr_container<T,CA,VPC>& y); + + template < class T, class CA, class VPC > + bool operator>=( const reversible_ptr_container<T,CA,VPC>& x, + const reversible_ptr_container<T,CA,VPC>& y); + + template < class T, class CA, class VPC > + bool operator<=( const reversible_ptr_container<T,CA,VPC>& x, + const reversible_ptr_container<T,CA,VPC>& y); + + template< class T, class CA, class VPC > + void swap( reversible_ptr_container<T,CA,VPC>& x, + reversible_ptr_container<T,CA,VPC>& y ); + + // cloneability_ + template< class T, class CA, class VPC > + reversible_ptr_container<T,CA,VPC>* + new_clone( const reversible_ptr_container<T,CA,VPC>& r ); + + // `null predicate`_ + template< class Iterator > + bool is_null( Iterator i ); + + // `serialization`_ + template<class Archive, class T, class CA, class VPC> + void serialize( Archive& ar, reversible_ptr_container<T,CÁ,VPC>& c, const unsigned int version ); + + + } // namespace 'boost' + + + +Semantics +--------- + +.. _`typedefs`: + +Semantics: typedefs +^^^^^^^^^^^^^^^^^^^ + +Notice how these two types differ: + + +- ``typedef T* value_type;`` + + - notice this has pointer type + +- ``typedef T& reference;`` + + - notice this is not a pointer type + +This is done to be able to add pointers directly +to the container, but to hide the pointers externally. + +.. + - ``typedef *implementation defined* object_type;`` + - this is ``T`` for sequences and sets + - this is ``std::pair<const Key, void*>`` for maps + +Also notice that + +- ``typedef ... iterator`` + +allows one to iterate over ``T&`` objects, not ``T*``. +Note that:: + + iterator i = ...; + i.base(); + +returns an iterator that allows one to iterate over ``void*`` +elements (*this is very rarely needed and you should not use the +functionality unless you know what you are doing*). + +- ``typedef ... auto_type`` + +This declaration hides a pointer pointer type. You can rely on the following +operations + +.. parsed-literal:: + + T* operator->() const; + T& operator*() const; + T* release(); + ~auto_type(); + operator *implementation-defined bool*\ (); + +The destructor will delete the stored object *using the clone allocator of the container* +(this explains why we cannot use ``std::auto_ptr<T>``). It might help to +think it is just an ``std::auto_ptr<T>``. You can also return +the pointer from a function or assign it to another pointer via the ``move()`` +function + +.. parsed-literal:: + + auto_type ptr = ...; + auto_type other = boost::ptr_container::move( ptr ); + return boost::ptr_container::move( other ); + +.. _construct/copy/destroy: + +Semantics: construct/copy/destroy +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``reversible_ptr_container();`` + + - Effects: Constructs an empty container + + - Postconditions: ``size() == 0`` + +.. + - ``reversible_ptr_container( size_type n, const T& x );`` + + - Effects: Constructs a container with ``n`` clones of ``x`` + + - Postconditions: ``size() == n`` + +- ``explicit reversible_ptr_container( const reversible_ptr_container& r );`` + + - Effects: Constructs a container by cloning all elements of ``r`` + +- ``template< class Derived > explicit reversible_ptr_container( const reversible_ptr_container<Derived>& r );`` + + - Effects: Constructs a container by cloning all elements of ``r`` + + - Requirements: ``Derived`` is derived from ``T`` + +- ``explicit reversible_ptr_container( std::auto_ptr< reversible_ptr_container > r );`` + + - Effects: Constructs a container by taking ownership of the supplied pointers + + +- ``template< class InputIterator >`` + ``reversible_ptr_container( InputIterator first, InputIterator last );`` + + - Requirements: ``(first,last]`` is a valid range + + - Effects: Constructs a container with a cloned range of ``(first,last]`` + + - Postconditions: ``size() == std::distance( first, last )`` + +- ``~reversible_ptr_container();`` + + - Effects: Deletes the stored objects via the clone allocator + + - Throws: Nothing + +- ``reversible_ptr_container& operator=( const reversible_ptr_container& r );`` + + - Effects: Assigns a clone of ``r`` + + - Exception safety: strong guarantee + +- ``template<class Derived> reversible_ptr_container& operator=( const reversible_ptr_container<Derived>& r );`` + + - Effects: Assigns a clone of ``r`` + + - Requirements: ``Derived`` is derived from ``T`` + + - Exception safety: Strong guarantee + +- ``reversible_ptr_container& operator=( std::auto_ptr<reversible_ptr_container> r );`` + + - Effects: Deletes the stored objects and then takes ownership of the supplied pointers + + - Throws: Nothing + +- ``allocator_type get_allocator() const;`` + + - Effects: Returns a copy of the allocator of the container object + + +.. _iterators: + +Semantics: iterators +^^^^^^^^^^^^^^^^^^^^ + +**See also:** `iterator invalidation <conventions.html#iterators-are-invalidated-as-in-the-corresponding-standard-container>`_ + +- ``iterator begin();`` +- ``const_iterator begin() const;`` + + - Effects: Returns a mutable/non-mutable iterator with ``value_type T`` + + - Throws: Nothing + +- ``iterator end();`` +- ``const_iterator end() const;`` + + - Effects: Returns a mutable/non-mutable iterator with ``value_type T`` + + - Throws: Nothing + +- ``reverse_iterator rbegin();`` + +- ``const_reverse_iterator rbegin() const;`` + + - Effects: Returns a mutable/non-mutable reverse iterator with ``value_type T`` + + - Throws: Nothing + +- ``reverse_iterator rend();`` + +- ``const_reverse_iterator rend() const;`` + + - Effects: Returns a mutable/non-mutable reverse iterator with ``value_type T`` + + - Throws: Nothing + +.. _capacity: + +Semantics: capacity +^^^^^^^^^^^^^^^^^^^ + +- ``size_type size() const;`` + + - Effects: Returns the number of stored elements + + - Throws: Nothing + +- ``size_type max_size() const;`` + + - Effects: Returns the maximum number of stored elements + + - Throws: Nothing + +- ``bool empty() const;`` + + - Effects: Returns whether the container is empty or not + + - Throws: Nothing + + +.. _modifiers: + +Semantics: modifiers +^^^^^^^^^^^^^^^^^^^^ + +- ``void swap( reversible_ptr_container& r );`` + + - Effects: Swaps the content of the two containers + + - Throws: Nothing + +- ``void clear();`` + + - Effects: Destroys all object of the container + + - Postconditions: ``empty() == true`` + + - Throws: Nothing + +- ``VoidPtrContainer& base();`` + +- ``const VoidPtrContainer& base() const;`` + + - Returns: a reference to the wrapped container + +.. _`pointer container requirements`: + +Semantics: pointer container requirements +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``auto_type replace( iterator position, T* x );`` + + - Requirements: ``not empty() and x != 0`` + + - Effects: returns the object pointed to by ``position`` and replaces it with ``x``. + + - Throws: ``bad_ptr_container_operation`` if the container is empty and ``bad_pointer`` if ``x == 0``. + + - Exception safety: Strong guarantee + +- ``template< class U > auto_type replace( iterator position, std::auto_ptr<U> x );`` + + - Effects: ``return replace( position, x.release() );`` + +- ``std::auto_ptr< reversible_ptr_container > clone() const;`` + + - Effects: Returns a deep copy of the container + + - Throws: ``std::bad_alloc`` if there is not enough memory to make a clone of the container + + - Complexity: Linear + +- ``std::auto_ptr< reversible_ptr_container > release();`` + + - Effects: Releases ownership of the container. This is a useful way of returning a container from a function. + + - Postconditions: ``empty() == true`` + + - Throws: ``std::bad_alloc`` if the return value cannot be allocated + + - Exception safety: Strong guarantee + +- ``auto_type release( iterator position );`` + + - Requirements: ``not empty();`` + + - Effects: Releases ownership of the pointer referred to by position + + - Postconditions: ``size()`` is one less + + - Throws: ``bad_ptr_container_operation`` if the container is empty + + - Exception safety: Strong guarantee + + +.. _comparison: + +Semantics: comparison +^^^^^^^^^^^^^^^^^^^^^ + +These functions compare the underlying range of objects. +So :: + + operation( const ptr_container& l, const ptr_container& r ); + +has the effect one would expect of normal standard containers. Hence +objects are compared and not the pointers to objects. + +.. _`cloneability`: + +Semantics: cloneability +^^^^^^^^^^^^^^^^^^^^^^^ + +- ``template< class T, class CloneAllocator > + reversible_ptr_container<T,CA,VPC>* + new_clone( const reversible_ptr_container<T,CA,VPC>& r );`` + + + - Effects: ``return r.clone().release();`` + + - Remarks: This function is only defined for concrete `pointer containers`_, but not for + `pointer container adapters`_. + +.. _`pointer containers`: ptr_container.html#smart-containers +.. _`pointer container adapters`: ptr_container.html#smart-container-adapters + +.. _`null predicate`: + +Semantics: null predicate +^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``template< class Iterator > bool is_null( Iterator i );`` + + - Requirements: ``i`` is a valid dereferencable iterator + + - Returns: ``*i.base() == 0;`` + +.. _`serialization`: + +Semantics: serialization +^^^^^^^^^^^^^^^^^^^^^^^^ + +All containers can be serialized by means of +`Boost.Serialization`__. For an overview, see +`Serialization of Pointer Containers`_. + +.. __: ../../serialization/index.html +.. _`Serialization of Pointer Containers`: reference.html#serialization + + :: + + template<class Archive, class T, class CA, class VPC> + void serialize( Archive& ar, reversible_ptr_container<T,CA,VPC>& c, const unsigned int version ); + + +- Effects: Saves or loads the container to/from the archive. + +- Remarks: This function is called automatically be stream operators in + Boost.Serialization + +- Exception safety: Loading gives the basic guarantee + + +.. raw:: html + + <hr> + +:Copyright: Thorsten Ottosen 2004-2007. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). + +__ http://www.boost.org/LICENSE_1_0.txt + diff --git a/libs/ptr_container/doc/todo.txt b/libs/ptr_container/doc/todo.txt new file mode 100644 index 0000000000..a89a01b6fd --- /dev/null +++ b/libs/ptr_container/doc/todo.txt @@ -0,0 +1,83 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2005. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +1. use splice() to speed up transfer for list + +5. small usage exmaple with each class + +10. update tutorial to show boost::assign link + auto_ptr + + +11. should find_key() be added to ptr_map? + + + +13. transfer for set/map may need to +be revisted (rg. !from.empty() precondition) + + +15. Some of the headlines are too big... + + +18. range-based sort() needs to be provided for list. use stable_sort for this purpose. + + +19. use flat_set,flat_map internally when certain situations arise, eg. when the size of the objects + is small, eg. 4bytes (does this affect key=string? + + + +21. map::at() should throw bad_index + +auto_type skal være converter-bar til std::auto_ptr<U>, if the deleter is +trivial (heap_clone_allocator) + +(Spørg Thomas Witt om denne ændring can komme med...kan ikke ødelægge existerende kode, som +vill have kaldt .release()) Kræve en hel del ambiguity resolution pga auto_ptr augument er +templates og ikke non-templates! Desuden kan vi ikke bruge non-template argument, da alle +converterings operatorer for auto_ptr tager en & argument og ikke en by-value!!! måske +skal der blot et hack til, hvor vi tilføjer en ny ukenkt klasse og overloader kun for +den, og så laver en implicit konvertering til denne i static_move_ptr + +The easiert implementation would be to detect its presence in the +body of the range based overloads and then dispatch to that implementation. + + +22. hvor gode er kompilere til at optimere release() for en auto_ptr. Hvordan med move_ptr +and auto_ptr interaction? Contracts må kunne fortælle kompileren at den skal +genere optimeret kode + +template< class T > +class auto_ptr +{ + T* get() const; + + // + // this expresses that the constructor is a no-op if + // the condition is true. This might be useful in many other + // context + // + ~auto_ptr() + precondition { if( get() == 0 ) return; } + + T* release() + postcondition { get() == 0; } +} + +... + +std::auto_ptr<T> p( new T ); +foo( p.release() ); +// don't generate destructor + +Does raw_storage iterator have an impact on in-place consrtcution + + diff --git a/libs/ptr_container/doc/tutorial.html b/libs/ptr_container/doc/tutorial.html new file mode 100644 index 0000000000..e43771ccfd --- /dev/null +++ b/libs/ptr_container/doc/tutorial.html @@ -0,0 +1,715 @@ +<?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: 2007-11-25 13:38:02 -0500 (Sun, 25 Nov 2007) $ +:Revision: $Revision: 41370 $ +: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="tutorial">Tutorial</h2> +<p>The tutorial shows you the most simple usage of the +library. It is assumed that the reader is familiar +with the use of standard containers. Although +the tutorial is devided into sections, it is recommended +that you read it all from top to bottom.</p> +<ul class="simple"> +<li><a class="reference" href="#basic-usage">Basic usage</a></li> +<li><a class="reference" href="#indirected-interface">Indirected interface</a></li> +<li><a class="reference" href="#sequence-containers">Sequence containers</a></li> +<li><a class="reference" href="#associative-containers">Associative containers</a></li> +<li><a class="reference" href="#null-values">Null values</a></li> +<li><a class="reference" href="#cloneability">Cloneability</a></li> +<li><a class="reference" href="#new-functions">New functions</a></li> +<li><a class="reference" href="#std-auto-ptr-u-overloads">std::auto_ptr<U> overloads</a></li> +<li><a class="reference" href="#algorithms">Algorithms</a></li> +</ul> +<div class="section"> +<h1><a id="basic-usage" name="basic-usage">Basic usage</a></h1> +<p>The most important aspect of a pointer container is that it manages +memory for you. This means that you in most cases do not need to worry +about deleting memory.</p> +<p>Let us assume that we have an OO-hierarchy of animals</p> +<pre class="literal-block"> +class animal : <a class="reference" href="http://www.boost.org/libs/utility/utility.htm#Class_noncopyable">boost::noncopyable</a> +{ +public: + virtual ~animal() {} + virtual void eat() = 0; + virtual int age() const = 0; + // ... +}; + +class mammal : public animal +{ + // ... +}; + +class bird : public animal +{ + // ... +}; +</pre> +<p>Then the managing of the animals is straight-forward. Imagine a +Zoo:</p> +<pre class="literal-block"> +class zoo +{ + boost::ptr_vector<animal> the_animals; +public: + + void add_animal( animal* a ) + { + the_animals.push_back( a ); + } +}; +</pre> +<p>Notice how we just pass the class name to the container; there +is no <tt class="docutils literal"><span class="pre">*</span></tt> to indicate it is a pointer. +With this declaration we can now say:</p> +<pre class="literal-block"> +zoo the_zoo; +the_zoo.add_animal( new mammal("joe") ); +the_zoo.add_animal( new bird("dodo") ); +</pre> +<p>Thus we heap-allocate all elements of the container +and never rely on copy-semantics.</p> +</div> +<div class="section"> +<h1><a id="indirected-interface" name="indirected-interface">Indirected interface</a></h1> +<p>A particular feature of the pointer containers is that +the query interface is indirected. For example,</p> +<pre class="literal-block"> +boost::ptr_vector<animal> vec; +vec.push_back( new animal ); // you add it as pointer ... +vec[0].eat(); // but get a reference back +</pre> +<p>This indirection also happens to iterators, so</p> +<pre class="literal-block"> +typedef std::vector<animal*> std_vec; +std_vec vec; +... +std_vec::iterator i = vec.begin(); +(*i)->eat(); // '*' needed +</pre> +<p>now becomes</p> +<pre class="literal-block"> +typedef boost::ptr_vector<animal> ptr_vec; +ptr_vec vec; +ptr_vec::iterator i = vec.begin(); +i->eat(); // no indirection needed +</pre> +</div> +<div class="section"> +<h1><a id="sequence-containers" name="sequence-containers">Sequence containers</a></h1> +<p>The sequence containers are used when you do not need to +keep an ordering on your elements. You can basically +expect all operations of the normal standard containers +to be available. So, for example, with a <tt class="docutils literal"><span class="pre">ptr_deque</span></tt> +and <tt class="docutils literal"><span class="pre">ptr_list</span></tt> object you can say:</p> +<pre class="literal-block"> +boost::ptr_deque<animal> deq; +deq.push_front( new animal ); +deq.pop_front(); +</pre> +<p>because <tt class="docutils literal"><span class="pre">std::deque</span></tt> and <tt class="docutils literal"><span class="pre">std::list</span></tt> have <tt class="docutils literal"><span class="pre">push_front()</span></tt> +and <tt class="docutils literal"><span class="pre">pop_front()</span></tt> members.</p> +<p>If the standard sequence supports +random access, so does the pointer container; for example:</p> +<pre class="literal-block"> +for( boost::ptr_deque<animal>::size_type i = 0u; + i != deq.size(); ++i ) + deq[i].eat(); +</pre> +<p>The <tt class="docutils literal"><span class="pre">ptr_vector</span></tt> also allows you to specify the size of +the buffer to allocate; for example</p> +<pre class="literal-block"> +boost::ptr_vector<animal> animals( 10u ); +</pre> +<p>will reserve room for 10 animals.</p> +</div> +<div class="section"> +<h1><a id="associative-containers" name="associative-containers">Associative containers</a></h1> +<p>To keep an ordering on our animals, we could use a <tt class="docutils literal"><span class="pre">ptr_set</span></tt>:</p> +<pre class="literal-block"> +boost::ptr_set<animal> set; +set.insert( new monkey("bobo") ); +set.insert( new whale("anna") ); +... +</pre> +<p>This requires that <tt class="docutils literal"><span class="pre">operator<()</span></tt> is defined for animals. One +way to do this could be</p> +<pre class="literal-block"> +inline bool operator<( const animal& l, const animal& r ) +{ + return l.name() < r.name(); +} +</pre> +<p>if we wanted to keep the animals sorted by name.</p> +<p>Maybe you want to keep all the animals in zoo ordered wrt. +their name, but it so happens that many animals have the +same name. We can then use a <tt class="docutils literal"><span class="pre">ptr_multimap</span></tt>:</p> +<pre class="literal-block"> +typedef boost::ptr_multimap<std::string,animal> zoo_type; +zoo_type zoo; +std::string bobo = "bobo", + anna = "anna"; +zoo.insert( bobo, new monkey(bobo) ); +zoo.insert( bobo, new elephant(bobo) ); +zoo.insert( anna, new whale(anna) ); +zoo.insert( anna, new emu(anna) ); +</pre> +<p>Note that must create the key as an lvalue +(due to exception-safety issues); the following would not +have compiled</p> +<pre class="literal-block"> +zoo.insert( "bobo", // this is bad, but you get compile error + new monkey("bobo") ); +</pre> +<p>If a multimap is not needed, we can use <tt class="docutils literal"><span class="pre">operator[]()</span></tt> +to avoid the clumsiness:</p> +<pre class="literal-block"> +boost::ptr_map<std::string,animal> animals; +animals["bobo"].set_name("bobo"); +</pre> +<p>This requires a default constructor for animals and +a function to do the initialization, in this case <tt class="docutils literal"><span class="pre">set_name()</span></tt>.</p> +<p>A better alternative is to use <a class="reference" href="../../assign/index.html">Boost.Assign</a> +to help you out. In particular, consider</p> +<ul class="simple"> +<li><a class="reference" href="../../assign/doc/index.html#ptr_push_back">ptr_push_back(), ptr_push_front(), ptr_insert() and ptr_map_insert()</a></li> +<li><a class="reference" href="../../assign/doc/index.html#ptr_list_of">ptr_list_of()</a></li> +</ul> +<p>For example, the above insertion may now be written</p> +<pre class="literal-block"> +boost::ptr_multimap<std::string,animal> animals; + +using namespace boost::assign; +ptr_map_insert<monkey>( animals )( "bobo", "bobo" ); +ptr_map_insert<elephant>( animals )( "bobo", "bobo" ); +ptr_map_insert<whale>( animals )( "anna", "anna" ); +ptr_map_insert<emu>( animals )( "anna", "anna" ); +</pre> +</div> +<div class="section"> +<h1><a id="null-values" name="null-values">Null values</a></h1> +<p>By default, if you try to insert null into a container, an exception +is thrown. If you want to allow nulls, then you must +say so explicitly when declaring the container variable</p> +<pre class="literal-block"> +boost::ptr_vector< boost::nullable<animal> > animals_type; +animals_type animals; +... +animals.insert( animals.end(), new dodo("fido") ); +animals.insert( animals.begin(), 0 ) // ok +</pre> +<p>Once you have inserted a null into the container, you must +always check if the value is null before accessing the object</p> +<pre class="literal-block"> +for( animals_type::iterator i = animals.begin(); + i != animals.end(); ++i ) +{ + if( !boost::is_null(i) ) // always check for validity + i->eat(); +} +</pre> +<p>If the container support random access, you may also check this as</p> +<pre class="literal-block"> +for( animals_type::size_type i = 0u; + i != animals.size(); ++i ) +{ + if( !animals.is_null(i) ) + animals[i].eat(); +} +</pre> +<p>Note that it is meaningless to insert +null into <tt class="docutils literal"><span class="pre">ptr_set</span></tt> and <tt class="docutils literal"><span class="pre">ptr_multiset</span></tt>.</p> +</div> +<div class="section"> +<h1><a id="cloneability" name="cloneability">Cloneability</a></h1> +<p>In OO programming it is typical to prohibit copying of objects; the +objects may sometimes be allowed to be Cloneable; for example,:</p> +<pre class="literal-block"> +animal* animal::clone() const +{ + return do_clone(); // implemented by private virtual function +} +</pre> +<p>If the OO hierarchy thus allows cloning, we need to tell the +pointer containers how cloning is to be done. This is simply +done by defining a free-standing function, <tt class="docutils literal"><span class="pre">new_clone()</span></tt>, +in the same namespace as +the object hierarchy:</p> +<pre class="literal-block"> +inline animal* new_clone( const animal& a ) +{ + return a.clone(); +} +</pre> +<p>That is all, now a lot of functions in a pointer container +can exploit the cloneability of the animal objects. For example</p> +<pre class="literal-block"> +typedef boost::ptr_list<animal> zoo_type; +zoo_type zoo, another_zoo; +... +another_zoo.assign( zoo.begin(), zoo.end() ); +</pre> +<p>will fill another zoo with clones of the first zoo. Similarly, +<tt class="docutils literal"><span class="pre">insert()</span></tt> can now insert clones into your pointer container</p> +<pre class="literal-block"> +another_zoo.insert( another_zoo.begin(), zoo.begin(), zoo.end() ); +</pre> +<p>The whole container can now also be cloned</p> +<pre class="literal-block"> +zoo_type yet_another_zoo = zoo.clone(); +</pre> +<p>Copying or assigning the container has the same effect as cloning (though it is slightly cheaper):</p> +<pre class="literal-block"> +zoo_type yet_another_zoo = zoo; +</pre> +<p>Copying also support derived-to-base class conversions:</p> +<pre class="literal-block"> +boost::ptr_vector<monkey> monkeys = boost::assign::ptr_list_of<monkey>( "bobo" )( "bebe")( "uhuh" ); +boost::ptr_vector<animal> animals = monkeys; +</pre> +<p>This also works for maps:</p> +<pre class="literal-block"> +boost::ptr_map<std::string,monkey> monkeys = ...; +boost::ptr_map<std::string,animal> animals = monkeys; +</pre> +</div> +<div class="section"> +<h1><a id="new-functions" name="new-functions">New functions</a></h1> +<p>Given that we know we are working with pointers, a few new functions +make sense. For example, say you want to remove an +animal from the zoo</p> +<pre class="literal-block"> +zoo_type::auto_type the_animal = zoo.release( zoo.begin() ); +the_animal->eat(); +animal* the_animal_ptr = the_animal.release(); // now this is not deleted +zoo.release(2); // for random access containers +</pre> +<p>You can think of <tt class="docutils literal"><span class="pre">auto_type</span></tt> as a non-copyable form of +<tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt>. Notice that when you release an object, the +pointer is removed from the container and the containers size +shrinks. For containers that store nulls, we can exploit that +<tt class="docutils literal"><span class="pre">auto_type</span></tt> is convertible to <tt class="docutils literal"><span class="pre">bool</span></tt>:</p> +<pre class="literal-block"> +if( ptr_vector< nullable<T> >::auto_type r = vec.pop_back() ) +{ + ... +} +</pre> +<p>You can also release the entire container if you +want to return it from a function</p> +<pre class="literal-block"> +std::auto_ptr< boost::ptr_deque<animal> > get_zoo() +{ + boost::ptr_deque<animal> result; + ... + return result.release(); // give up ownership +} +... +boost::ptr_deque<animal> animals = get_zoo(); +</pre> +<p>Let us assume we want to move an animal object from +one zoo to another. In other words, we want to move the +animal and the responsibility of it to another zoo</p> +<pre class="literal-block"> +another_zoo.transfer( another_zoo.end(), // insert before end + zoo.begin(), // insert this animal ... + zoo ); // from this container +</pre> +<p>This kind of "move-semantics" is different from +normal value-based containers. You can think of <tt class="docutils literal"><span class="pre">transfer()</span></tt> +as the same as <tt class="docutils literal"><span class="pre">splice()</span></tt> on <tt class="docutils literal"><span class="pre">std::list</span></tt>.</p> +<p>If you want to replace an element, you can easily do so</p> +<pre class="literal-block"> +zoo_type::auto_type old_animal = zoo.replace( zoo.begin(), new monkey("bibi") ); +zoo.replace( 2, old_animal.release() ); // for random access containers +</pre> +<p>A map is slightly different to iterate over than standard maps. +Now we say</p> +<pre class="literal-block"> +typedef boost::ptr_map<std::string, boost::nullable<animal> > animal_map; +animal_map map; +... +for( animal_map::const_iterator i = map.begin(), e = map.end(); i != e; ++i ) +{ + std::cout << "\n key: " << i->first; + std::cout << "\n age: "; + + if( boost::is_null(i) ) + std::cout << "unknown"; + else + std::cout << i->second->age(); + } +</pre> +<p>Except for the check for null, this looks like it would with a normal map. But if <tt class="docutils literal"><span class="pre">age()</span></tt> had +not been a <tt class="docutils literal"><span class="pre">const</span></tt> member function, +it would not have compiled.</p> +<p>Maps can also be indexed with bounds-checking</p> +<pre class="literal-block"> +try +{ + animal& bobo = map.at("bobo"); +} +catch( boost::bad_ptr_container_operation& e ) +{ + // "bobo" not found +} +</pre> +</div> +<div class="section"> +<h1><a id="std-auto-ptr-u-overloads" name="std-auto-ptr-u-overloads"><tt class="docutils literal"><span class="pre">std::auto_ptr<U></span></tt> overloads</a></h1> +<p>Every time there is a function that takes a <tt class="docutils literal"><span class="pre">T*</span></tt> parameter, there is +also a function taking an <tt class="docutils literal"><span class="pre">std::auto_ptr<U></span></tt> parameter. This is of course done +to make the library intregrate seamlessly with <tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt>. For example</p> +<pre class="literal-block"> +std::ptr_vector<Base> vec; +vec.push_back( new Base ); +</pre> +<p>is complemented by</p> +<pre class="literal-block"> +std::auto_ptr<Derived> p( new Derived ); +vec.push_back( p ); +</pre> +<p>Notice that the template argument for <tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt> does not need to +follow the template argument for <tt class="docutils literal"><span class="pre">ptr_vector</span></tt> as long as <tt class="docutils literal"><span class="pre">Derived*</span></tt> +can be implicitly converted to <tt class="docutils literal"><span class="pre">Base*</span></tt>.</p> +</div> +<div class="section"> +<h1><a id="algorithms" name="algorithms">Algorithms</a></h1> +<p>Unfortunately it is not possible to use pointer containers with +mutating algorithms from the standard library. However, +the most useful ones +are instead provided as member functions:</p> +<pre class="literal-block"> +boost::ptr_vector<animal> zoo; +... +zoo.sort(); // assume 'bool operator<( const animal&, const animal& )' +zoo.sort( std::less<animal>() ); // the same, notice no '*' is present +zoo.sort( zoo.begin(), zoo.begin() + 5 ); // sort selected range +</pre> +<p>Notice that predicates are automatically wrapped in an <a class="reference" href="indirect_fun.html">indirect_fun</a> object.</p> +<p>You can remove equal and adjacent elements using <tt class="docutils literal"><span class="pre">unique()</span></tt>:</p> +<pre class="literal-block"> +zoo.unique(); // assume 'bool operator==( const animal&, const animal& )' +zoo.unique( zoo.begin(), zoo.begin() + 5, my_comparison_predicate() ); +</pre> +<p>If you just want to remove certain elements, use <tt class="docutils literal"><span class="pre">erase_if</span></tt>:</p> +<pre class="literal-block"> +zoo.erase_if( my_predicate() ); +</pre> +<p>Finally you may want to merge two sorted containers:</p> +<pre class="literal-block"> +boost::ptr_vector<animal> another_zoo = ...; +another_zoo.sort(); // sorted wrt. to same order as 'zoo' +zoo.merge( another_zoo ); +BOOST_ASSERT( another_zoo.empty() ); +</pre> +<p>That is all; now you have learned all the basics!</p> +<hr><p><strong>See also</strong></p> +<ul class="simple"> +<li><a class="reference" href="guidelines.html">Usage guidelines</a></li> +<li><a class="reference" href="../../conversion/cast.htm#Polymorphic_castl">Cast utilities</a></li> +</ul> +<p><strong>Navigate</strong></p> +<ul class="simple"> +<li><a class="reference" href="ptr_container.html">home</a></li> +<li><a class="reference" href="examples.html">examples</a></li> +</ul> +<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> diff --git a/libs/ptr_container/doc/tutorial.rst b/libs/ptr_container/doc/tutorial.rst new file mode 100644 index 0000000000..e83eabaa4c --- /dev/null +++ b/libs/ptr_container/doc/tutorial.rst @@ -0,0 +1,455 @@ +++++++++++++++++++++++++++++++++++ + |Boost| Pointer Container Library +++++++++++++++++++++++++++++++++++ + +.. |Boost| image:: boost.png + +======== +Tutorial +======== + +The tutorial shows you the most simple usage of the +library. It is assumed that the reader is familiar +with the use of standard containers. Although +the tutorial is devided into sections, it is recommended +that you read it all from top to bottom. + +* `Basic usage`_ +* `Indirected interface`_ +* `Sequence containers`_ +* `Associative containers`_ +* `Null values`_ +* `Cloneability`_ +* `New functions`_ +* `std::auto_ptr<U> overloads`_ +* `Algorithms`_ + +Basic usage +----------- + +The most important aspect of a pointer container is that it manages +memory for you. This means that you in most cases do not need to worry +about deleting memory. + +Let us assume that we have an OO-hierarchy of animals + +.. parsed-literal:: + + class animal : `boost::noncopyable <http://www.boost.org/libs/utility/utility.htm#Class_noncopyable>`_ + { + public: + virtual ~animal() {} + virtual void eat() = 0; + virtual int age() const = 0; + // ... + }; + + class mammal : public animal + { + // ... + }; + + class bird : public animal + { + // ... + }; + + +Then the managing of the animals is straight-forward. Imagine a +Zoo:: + + class zoo + { + boost::ptr_vector<animal> the_animals; + public: + + void add_animal( animal* a ) + { + the_animals.push_back( a ); + } + }; + +Notice how we just pass the class name to the container; there +is no ``*`` to indicate it is a pointer. +With this declaration we can now say:: + + zoo the_zoo; + the_zoo.add_animal( new mammal("joe") ); + the_zoo.add_animal( new bird("dodo") ); + +Thus we heap-allocate all elements of the container +and never rely on copy-semantics. + +Indirected interface +-------------------- + +A particular feature of the pointer containers is that +the query interface is indirected. For example, :: + + boost::ptr_vector<animal> vec; + vec.push_back( new animal ); // you add it as pointer ... + vec[0].eat(); // but get a reference back + +This indirection also happens to iterators, so :: + + typedef std::vector<animal*> std_vec; + std_vec vec; + ... + std_vec::iterator i = vec.begin(); + (*i)->eat(); // '*' needed + +now becomes :: + + typedef boost::ptr_vector<animal> ptr_vec; + ptr_vec vec; + ptr_vec::iterator i = vec.begin(); + i->eat(); // no indirection needed + + +Sequence containers +------------------- + +The sequence containers are used when you do not need to +keep an ordering on your elements. You can basically +expect all operations of the normal standard containers +to be available. So, for example, with a ``ptr_deque`` +and ``ptr_list`` object you can say:: + + boost::ptr_deque<animal> deq; + deq.push_front( new animal ); + deq.pop_front(); + +because ``std::deque`` and ``std::list`` have ``push_front()`` +and ``pop_front()`` members. + +If the standard sequence supports +random access, so does the pointer container; for example:: + + for( boost::ptr_deque<animal>::size_type i = 0u; + i != deq.size(); ++i ) + deq[i].eat(); + +The ``ptr_vector`` also allows you to specify the size of +the buffer to allocate; for example :: + + boost::ptr_vector<animal> animals( 10u ); + +will reserve room for 10 animals. + +Associative containers +---------------------- + +To keep an ordering on our animals, we could use a ``ptr_set``:: + + boost::ptr_set<animal> set; + set.insert( new monkey("bobo") ); + set.insert( new whale("anna") ); + ... + +This requires that ``operator<()`` is defined for animals. One +way to do this could be :: + + inline bool operator<( const animal& l, const animal& r ) + { + return l.name() < r.name(); + } + +if we wanted to keep the animals sorted by name. + +Maybe you want to keep all the animals in zoo ordered wrt. +their name, but it so happens that many animals have the +same name. We can then use a ``ptr_multimap``:: + + typedef boost::ptr_multimap<std::string,animal> zoo_type; + zoo_type zoo; + std::string bobo = "bobo", + anna = "anna"; + zoo.insert( bobo, new monkey(bobo) ); + zoo.insert( bobo, new elephant(bobo) ); + zoo.insert( anna, new whale(anna) ); + zoo.insert( anna, new emu(anna) ); + +Note that must create the key as an lvalue +(due to exception-safety issues); the following would not +have compiled :: + + zoo.insert( "bobo", // this is bad, but you get compile error + new monkey("bobo") ); + +If a multimap is not needed, we can use ``operator[]()`` +to avoid the clumsiness:: + + boost::ptr_map<std::string,animal> animals; + animals["bobo"].set_name("bobo"); + +This requires a default constructor for animals and +a function to do the initialization, in this case ``set_name()``. + +A better alternative is to use `Boost.Assign <../../assign/index.html>`_ +to help you out. In particular, consider + +- `ptr_push_back(), ptr_push_front(), ptr_insert() and ptr_map_insert() <../../assign/doc/index.html#ptr_push_back>`_ + +- `ptr_list_of() <../../assign/doc/index.html#ptr_list_of>`_ + +For example, the above insertion may now be written :: + + boost::ptr_multimap<std::string,animal> animals; + + using namespace boost::assign; + ptr_map_insert<monkey>( animals )( "bobo", "bobo" ); + ptr_map_insert<elephant>( animals )( "bobo", "bobo" ); + ptr_map_insert<whale>( animals )( "anna", "anna" ); + ptr_map_insert<emu>( animals )( "anna", "anna" ); + + +Null values +----------- + +By default, if you try to insert null into a container, an exception +is thrown. If you want to allow nulls, then you must +say so explicitly when declaring the container variable :: + + boost::ptr_vector< boost::nullable<animal> > animals_type; + animals_type animals; + ... + animals.insert( animals.end(), new dodo("fido") ); + animals.insert( animals.begin(), 0 ) // ok + +Once you have inserted a null into the container, you must +always check if the value is null before accessing the object :: + + for( animals_type::iterator i = animals.begin(); + i != animals.end(); ++i ) + { + if( !boost::is_null(i) ) // always check for validity + i->eat(); + } + +If the container support random access, you may also check this as :: + + for( animals_type::size_type i = 0u; + i != animals.size(); ++i ) + { + if( !animals.is_null(i) ) + animals[i].eat(); + } + +Note that it is meaningless to insert +null into ``ptr_set`` and ``ptr_multiset``. + +Cloneability +------------ + +In OO programming it is typical to prohibit copying of objects; the +objects may sometimes be allowed to be Cloneable; for example,:: + + animal* animal::clone() const + { + return do_clone(); // implemented by private virtual function + } + +If the OO hierarchy thus allows cloning, we need to tell the +pointer containers how cloning is to be done. This is simply +done by defining a free-standing function, ``new_clone()``, +in the same namespace as +the object hierarchy:: + + inline animal* new_clone( const animal& a ) + { + return a.clone(); + } + +That is all, now a lot of functions in a pointer container +can exploit the cloneability of the animal objects. For example :: + + typedef boost::ptr_list<animal> zoo_type; + zoo_type zoo, another_zoo; + ... + another_zoo.assign( zoo.begin(), zoo.end() ); + +will fill another zoo with clones of the first zoo. Similarly, +``insert()`` can now insert clones into your pointer container :: + + another_zoo.insert( another_zoo.begin(), zoo.begin(), zoo.end() ); + +The whole container can now also be cloned :: + + zoo_type yet_another_zoo = zoo.clone(); + +Copying or assigning the container has the same effect as cloning (though it is slightly cheaper):: + + zoo_type yet_another_zoo = zoo; + +Copying also support derived-to-base class conversions:: + + boost::ptr_vector<monkey> monkeys = boost::assign::ptr_list_of<monkey>( "bobo" )( "bebe")( "uhuh" ); + boost::ptr_vector<animal> animals = monkeys; + +This also works for maps:: + + boost::ptr_map<std::string,monkey> monkeys = ...; + boost::ptr_map<std::string,animal> animals = monkeys; + +New functions +------------- + +Given that we know we are working with pointers, a few new functions +make sense. For example, say you want to remove an +animal from the zoo :: + + zoo_type::auto_type the_animal = zoo.release( zoo.begin() ); + the_animal->eat(); + animal* the_animal_ptr = the_animal.release(); // now this is not deleted + zoo.release(2); // for random access containers + +You can think of ``auto_type`` as a non-copyable form of +``std::auto_ptr``. Notice that when you release an object, the +pointer is removed from the container and the containers size +shrinks. For containers that store nulls, we can exploit that +``auto_type`` is convertible to ``bool``:: + + if( ptr_vector< nullable<T> >::auto_type r = vec.pop_back() ) + { + ... + } + +You can also release the entire container if you +want to return it from a function :: + + std::auto_ptr< boost::ptr_deque<animal> > get_zoo() + { + boost::ptr_deque<animal> result; + ... + return result.release(); // give up ownership + } + ... + boost::ptr_deque<animal> animals = get_zoo(); + +Let us assume we want to move an animal object from +one zoo to another. In other words, we want to move the +animal and the responsibility of it to another zoo :: + + another_zoo.transfer( another_zoo.end(), // insert before end + zoo.begin(), // insert this animal ... + zoo ); // from this container + +This kind of "move-semantics" is different from +normal value-based containers. You can think of ``transfer()`` +as the same as ``splice()`` on ``std::list``. + +If you want to replace an element, you can easily do so :: + + zoo_type::auto_type old_animal = zoo.replace( zoo.begin(), new monkey("bibi") ); + zoo.replace( 2, old_animal.release() ); // for random access containers + +A map is slightly different to iterate over than standard maps. +Now we say :: + + typedef boost::ptr_map<std::string, boost::nullable<animal> > animal_map; + animal_map map; + ... + for( animal_map::const_iterator i = map.begin(), e = map.end(); i != e; ++i ) + { + std::cout << "\n key: " << i->first; + std::cout << "\n age: "; + + if( boost::is_null(i) ) + std::cout << "unknown"; + else + std::cout << i->second->age(); + } + +Except for the check for null, this looks like it would with a normal map. But if ``age()`` had +not been a ``const`` member function, +it would not have compiled. + +Maps can also be indexed with bounds-checking :: + + try + { + animal& bobo = map.at("bobo"); + } + catch( boost::bad_ptr_container_operation& e ) + { + // "bobo" not found + } + +``std::auto_ptr<U>`` overloads +------------------------------ + +Every time there is a function that takes a ``T*`` parameter, there is +also a function taking an ``std::auto_ptr<U>`` parameter. This is of course done +to make the library intregrate seamlessly with ``std::auto_ptr``. For example :: + + std::ptr_vector<Base> vec; + vec.push_back( new Base ); + +is complemented by :: + + std::auto_ptr<Derived> p( new Derived ); + vec.push_back( p ); + +Notice that the template argument for ``std::auto_ptr`` does not need to +follow the template argument for ``ptr_vector`` as long as ``Derived*`` +can be implicitly converted to ``Base*``. + +Algorithms +---------- + +Unfortunately it is not possible to use pointer containers with +mutating algorithms from the standard library. However, +the most useful ones +are instead provided as member functions:: + + boost::ptr_vector<animal> zoo; + ... + zoo.sort(); // assume 'bool operator<( const animal&, const animal& )' + zoo.sort( std::less<animal>() ); // the same, notice no '*' is present + zoo.sort( zoo.begin(), zoo.begin() + 5 ); // sort selected range + +Notice that predicates are automatically wrapped in an `indirect_fun`_ object. + +.. _`indirect_fun`: indirect_fun.html + +You can remove equal and adjacent elements using ``unique()``:: + + zoo.unique(); // assume 'bool operator==( const animal&, const animal& )' + zoo.unique( zoo.begin(), zoo.begin() + 5, my_comparison_predicate() ); + +If you just want to remove certain elements, use ``erase_if``:: + + zoo.erase_if( my_predicate() ); + +Finally you may want to merge two sorted containers:: + + boost::ptr_vector<animal> another_zoo = ...; + another_zoo.sort(); // sorted wrt. to same order as 'zoo' + zoo.merge( another_zoo ); + BOOST_ASSERT( another_zoo.empty() ); + +That is all; now you have learned all the basics! + +.. raw:: html + + <hr> + +**See also** + +- `Usage guidelines <guidelines.html>`_ + +- `Cast utilities <../../conversion/cast.htm#Polymorphic_castl>`_ + +**Navigate** + +- `home <ptr_container.html>`_ +- `examples <examples.html>`_ + +.. raw:: html + + <hr> + +:Copyright: Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). + +__ http://www.boost.org/LICENSE_1_0.txt + diff --git a/libs/ptr_container/doc/tutorial_example.html b/libs/ptr_container/doc/tutorial_example.html new file mode 100644 index 0000000000..d0bed03ea7 --- /dev/null +++ b/libs/ptr_container/doc/tutorial_example.html @@ -0,0 +1,365 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title> </title> +<link rel="stylesheet" href="default.css" type="text/css"> +</head> + +<body> + <pre><span class=comment>// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +// +// This example is intended to get you started. +// Notice how the smart container +// +// 1. takes ownership of objects +// 2. transfers ownership +// 3. applies indirection to iterators +// 4. clones objects from other smart containers +// + +// +// First we select which container to use. +//</span> +<span class=preprocessor>#include</span> <span class=special><</span><span class=identifier>boost</span><span class=special>/</span><span class=identifier>ptr_container</span><span class=special>/</span><span class=identifier>ptr_deque</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>></span> + +<span class=comment>// +// we need these later in the example +//</span> +<span class=preprocessor>#include</span> <span class=special><</span><span class=identifier>boost</span><span class=special>/</span><span class=identifier>assert</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>></span> +<span class=preprocessor>#include</span> <span class=special><</span><span class=identifier>string</span><span class=special>></span> +<span class=preprocessor>#include</span> <span class=special><</span><span class=identifier>exception</span><span class=special>></span> + + +<span class=comment>// +// Then we define a small polymorphic class +// hierarchy. +//</span> + +<span class=keyword>class</span> <span class=identifier>animal</span> <span class=special>:</span> <span class=identifier>boost</span><span class=special>::</span><span class=identifier>noncopyable</span> +<span class=special>{</span> + <span class=keyword>virtual</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span> <span class=identifier>do_speak</span><span class=special>()</span> <span class=keyword>const</span> <span class=special>=</span> <span class=number>0</span><span class=special>;</span> + <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span> <span class=identifier>name_</span><span class=special>;</span> + +<span class=keyword>protected</span><span class=special>:</span> + <span class=comment>// + // Animals cannot be copied... + //</span> + <span class=identifier>animal</span><span class=special>(</span> <span class=keyword>const</span> <span class=identifier>animal</span><span class=special>&</span> <span class=identifier>r</span> <span class=special>)</span> <span class=special>:</span> <span class=identifier>name_</span><span class=special>(</span> <span class=identifier>r</span><span class=special>.</span><span class=identifier>name_</span> <span class=special>)</span> <span class=special>{</span> <span class=special>}</span> + <span class=keyword>void</span> <span class=keyword>operator</span><span class=special>=(</span> <span class=keyword>const</span> <span class=identifier>animal</span><span class=special>&</span> <span class=special>);</span> + +<span class=keyword>private</span><span class=special>:</span> + <span class=comment>// + // ...but due to advances in genetics, we can clone them! + //</span> + + <span class=keyword>virtual</span> <span class=identifier>animal</span><span class=special>*</span> <span class=identifier>do_clone</span><span class=special>()</span> <span class=keyword>const</span> <span class=special>=</span> <span class=number>0</span><span class=special>;</span> + +<span class=keyword>public</span><span class=special>:</span> + <span class=identifier>animal</span><span class=special>(</span> <span class=keyword>const</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span><span class=special>&</span> <span class=identifier>name</span> <span class=special>)</span> <span class=special>:</span> <span class=identifier>name_</span><span class=special>(</span><span class=identifier>name</span><span class=special>)</span> <span class=special>{</span> <span class=special>}</span> + <span class=keyword>virtual</span> <span class=special>~</span><span class=identifier>animal</span><span class=special>()</span> <span class=keyword>throw</span><span class=special>()</span> <span class=special>{</span> <span class=special>}</span> + + <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span> <span class=identifier>speak</span><span class=special>()</span> <span class=keyword>const</span> + <span class=special>{</span> + <span class=keyword>return</span> <span class=identifier>do_speak</span><span class=special>();</span> + <span class=special>}</span> + + <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span> <span class=identifier>name</span><span class=special>()</span> <span class=keyword>const</span> + <span class=special>{</span> + <span class=keyword>return</span> <span class=identifier>name_</span><span class=special>;</span> + <span class=special>}</span> + + <span class=identifier>animal</span><span class=special>*</span> <span class=identifier>clone</span><span class=special>()</span> <span class=keyword>const</span> + <span class=special>{</span> + <span class=keyword>return</span> <span class=identifier>do_clone</span><span class=special>();</span> + <span class=special>}</span> +<span class=special>};</span> + +<span class=comment>// +// An animal is still not Clonable. We need this last hook. +// +// Notice that we pass the animal by const reference +// and return by pointer. +//</span> + +<span class=identifier>animal</span><span class=special>*</span> <span class=identifier>new_clone</span><span class=special>(</span> <span class=keyword>const</span> <span class=identifier>animal</span><span class=special>&</span> <span class=identifier>a</span> <span class=special>)</span> +<span class=special>{</span> + <span class=keyword>return</span> <span class=identifier>a</span><span class=special>.</span><span class=identifier>clone</span><span class=special>();</span> +<span class=special>}</span> + +<span class=comment>// +// We do not need to define 'delete_clone()' since +// since the default is to call the default 'operator delete()'. +//</span> + +<span class=keyword>const</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span> <span class=identifier>muuuh</span> <span class=special>=</span> <span class=string>"Muuuh!"</span><span class=special>;</span> +<span class=keyword>const</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span> <span class=identifier>oiink</span> <span class=special>=</span> <span class=string>"Oiiink"</span><span class=special>;</span> + +<span class=keyword>class</span> <span class=identifier>cow</span> <span class=special>:</span> <span class=keyword>public</span> <span class=identifier>animal</span> +<span class=special>{</span> + <span class=keyword>virtual</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span> <span class=identifier>do_speak</span><span class=special>()</span> <span class=keyword>const</span> + <span class=special>{</span> + <span class=keyword>return</span> <span class=identifier>muuuh</span><span class=special>;</span> + <span class=special>}</span> + + <span class=keyword>virtual</span> <span class=identifier>animal</span><span class=special>*</span> <span class=identifier>do_clone</span><span class=special>()</span> <span class=keyword>const</span> + <span class=special>{</span> + <span class=keyword>return</span> <span class=keyword>new</span> <span class=identifier>cow</span><span class=special>(</span> <span class=special>*</span><span class=keyword>this</span> <span class=special>);</span> + <span class=special>}</span> + +<span class=keyword>public</span><span class=special>:</span> + <span class=identifier>cow</span><span class=special>(</span> <span class=keyword>const</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span><span class=special>&</span> <span class=identifier>name</span> <span class=special>)</span> <span class=special>:</span> <span class=identifier>animal</span><span class=special>(</span><span class=identifier>name</span><span class=special>)</span> <span class=special>{</span> <span class=special>}</span> +<span class=special>};</span> + +<span class=keyword>class</span> <span class=identifier>pig</span> <span class=special>:</span> <span class=keyword>public</span> <span class=identifier>animal</span> +<span class=special>{</span> + <span class=keyword>virtual</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span> <span class=identifier>do_speak</span><span class=special>()</span> <span class=keyword>const</span> + <span class=special>{</span> + <span class=keyword>return</span> <span class=identifier>oiink</span><span class=special>;</span> + <span class=special>}</span> + + <span class=keyword>virtual</span> <span class=identifier>animal</span><span class=special>*</span> <span class=identifier>do_clone</span><span class=special>()</span> <span class=keyword>const</span> + <span class=special>{</span> + <span class=keyword>return</span> <span class=keyword>new</span> <span class=identifier>pig</span><span class=special>(</span> <span class=special>*</span><span class=keyword>this</span> <span class=special>);</span> + <span class=special>}</span> + +<span class=keyword>public</span><span class=special>:</span> + <span class=identifier>pig</span><span class=special>(</span> <span class=keyword>const</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span><span class=special>&</span> <span class=identifier>name</span> <span class=special>)</span> <span class=special>:</span> <span class=identifier>animal</span><span class=special>(</span><span class=identifier>name</span><span class=special>)</span> <span class=special>{</span> <span class=special>}</span> +<span class=special>};</span> + +<span class=comment>// +// Then we, of course, need a place to put all +// those animals. +//</span> + +<span class=keyword>class</span> <span class=identifier>farm</span> +<span class=special>{</span> + <span class=comment>// + // This is where the smart containers are handy + //</span> + <span class=keyword>typedef</span> <span class=identifier>boost</span><span class=special>::</span><span class=identifier>ptr_deque</span><span class=special><</span><span class=identifier>animal</span><span class=special>></span> <span class=identifier>barn_type</span><span class=special>;</span> + <span class=identifier>barn_type</span> <span class=identifier>barn</span><span class=special>;</span> + + <span class=comment>// + // An error type + //</span> + <span class=keyword>struct</span> <span class=identifier>farm_trouble</span> <span class=special>:</span> <span class=keyword>public</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>exception</span> <span class=special>{</span> <span class=special>};</span> + +<span class=keyword>public</span><span class=special>:</span> + <span class=comment>// + // We would like to make it possible to + // iterate over the animals in the farm + //</span> + <span class=keyword>typedef</span> <span class=identifier>barn_type</span><span class=special>::</span><span class=identifier>iterator</span> <span class=identifier>animal_iterator</span><span class=special>;</span> + + <span class=comment>// + // We also need to count the farm's size... + //</span> + <span class=keyword>typedef</span> <span class=identifier>barn_type</span><span class=special>::</span><span class=identifier>size_type</span> <span class=identifier>size_type</span><span class=special>;</span> + + <span class=comment>// + // And we also want to transfer an animal + // safely around. The easiest way to think + // about '::auto_type' is to imagine a simplified + // 'std::auto_ptr<T>' ... this means you can expect + // + // T* operator->() + // T* release() + // deleting destructor + // + // but not more. + //</span> + <span class=keyword>typedef</span> <span class=identifier>barn_type</span><span class=special>::</span><span class=identifier>auto_type</span> <span class=identifier>animal_transport</span><span class=special>;</span> + + <span class=comment>// + // Create an empty farm. + //</span> + <span class=identifier>farm</span><span class=special>()</span> <span class=special>{</span> <span class=special>}</span> + + <span class=comment>// + // We need a constructor that can make a new + // farm by cloning a range of animals. + //</span> + <span class=identifier>farm</span><span class=special>(</span> <span class=identifier>animal_iterator</span> <span class=identifier>begin</span><span class=special>,</span> <span class=identifier>animal_iterator</span> <span class=identifier>end</span> <span class=special>)</span> + <span class=special>:</span> + <span class=comment>// + // Objects are always cloned before insertion + // unless we explicitly add a pointer or + // use 'release()'. Therefore we actually + // clone all animals in the range + //</span> + <span class=identifier>barn</span><span class=special>(</span> <span class=identifier>begin</span><span class=special>,</span> <span class=identifier>end</span> <span class=special>)</span> <span class=special>{</span> <span class=special>}</span> + + <span class=comment>// + // ... so we need some other function too + //</span> + + <span class=identifier>animal_iterator</span> <span class=identifier>begin</span><span class=special>()</span> + <span class=special>{</span> + <span class=keyword>return</span> <span class=identifier>barn</span><span class=special>.</span><span class=identifier>begin</span><span class=special>();</span> + <span class=special>}</span> + + <span class=identifier>animal_iterator</span> <span class=identifier>end</span><span class=special>()</span> + <span class=special>{</span> + <span class=keyword>return</span> <span class=identifier>barn</span><span class=special>.</span><span class=identifier>end</span><span class=special>();</span> + <span class=special>}</span> + + <span class=comment>// + // Here it is quite ok to have an 'animal*' argument. + // The smart container will handle all ownership + // issues. + //</span> + <span class=keyword>void</span> <span class=identifier>buy_animal</span><span class=special>(</span> <span class=identifier>animal</span><span class=special>*</span> <span class=identifier>a</span> <span class=special>)</span> + <span class=special>{</span> + <span class=identifier>barn</span><span class=special>.</span><span class=identifier>push_back</span><span class=special>(</span> <span class=identifier>a</span> <span class=special>);</span> + <span class=special>}</span> + + <span class=comment>// + // The farm can also be in economical trouble and + // therefore be in the need to sell animals. + //</span> + <span class=identifier>animal_transport</span> <span class=identifier>sell_animal</span><span class=special>(</span> <span class=identifier>animal_iterator</span> <span class=identifier>to_sell</span> <span class=special>)</span> + <span class=special>{</span> + <span class=keyword>if</span><span class=special>(</span> <span class=identifier>to_sell</span> <span class=special>==</span> <span class=identifier>end</span><span class=special>()</span> <span class=special>)</span> + <span class=keyword>throw</span> <span class=identifier>farm_trouble</span><span class=special>();</span> + + <span class=comment>// + // Here we remove the animal from the barn, + // but the animal is not deleted yet...it's + // up to the buyer to decide what + // to do with it. + //</span> + <span class=keyword>return</span> <span class=identifier>barn</span><span class=special>.</span><span class=identifier>release</span><span class=special>(</span> <span class=identifier>to_sell</span> <span class=special>);</span> + <span class=special>}</span> + + <span class=comment>// + // How big a farm do we have? + //</span> + <span class=identifier>size_type</span> <span class=identifier>size</span><span class=special>()</span> <span class=keyword>const</span> + <span class=special>{</span> + <span class=keyword>return</span> <span class=identifier>barn</span><span class=special>.</span><span class=identifier>size</span><span class=special>();</span> + <span class=special>}</span> + + <span class=comment>// + // If things are bad, we might choose to sell all animals :-( + //</span> + <span class=identifier>std</span><span class=special>::</span><span class=identifier>auto_ptr</span><span class=special><</span><span class=identifier>barn_type</span><span class=special>></span> <span class=identifier>sell_farm</span><span class=special>()</span> + <span class=special>{</span> + <span class=keyword>return</span> <span class=identifier>barn</span><span class=special>.</span><span class=identifier>release</span><span class=special>();</span> + <span class=special>}</span> + + <span class=comment>// + // However, if things are good, we might buy somebody + // else's farm :-) + //</span> + + <span class=keyword>void</span> <span class=identifier>buy_farm</span><span class=special>(</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>auto_ptr</span><span class=special><</span><span class=identifier>barn_type</span><span class=special>></span> <span class=identifier>other</span> <span class=special>)</span> + <span class=special>{</span> + <span class=comment>// + // This line inserts all the animals from 'other' + // and is guaranteed either to succeed or to have no + // effect + //</span> + <span class=identifier>barn</span><span class=special>.</span><span class=identifier>transfer</span><span class=special>(</span> <span class=identifier>barn</span><span class=special>.</span><span class=identifier>end</span><span class=special>(),</span> <span class=comment>// insert new animals at the end</span> + <span class=special>*</span><span class=identifier>other</span> <span class=special>);</span> <span class=comment>// we want to transfer all animals, + // so we use the whole container as argument + // + // You might think you would have to do + // + // other.release(); + // + // but '*other' is empty and can go out of scope as it wants + //</span> + <span class=identifier>BOOST_ASSERT</span><span class=special>(</span> <span class=identifier>other</span><span class=special>-></span><span class=identifier>empty</span><span class=special>()</span> <span class=special>);</span> + <span class=special>}</span> + +<span class=special>};</span> <span class=comment>// class 'farm'.</span> + +<span class=keyword>int</span> <span class=identifier>main</span><span class=special>()</span> +<span class=special>{</span> + <span class=comment>// + // First we make a farm + //</span> + <span class=identifier>farm</span> <span class=identifier>animal_farm</span><span class=special>;</span> + <span class=identifier>BOOST_ASSERT</span><span class=special>(</span> <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>size</span><span class=special>()</span> <span class=special>==</span> <span class=number>0u</span> <span class=special>);</span> + + <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>buy_animal</span><span class=special>(</span> <span class=keyword>new</span> <span class=identifier>pig</span><span class=special>(</span><span class=string>"Betty"</span><span class=special>)</span> <span class=special>);</span> + <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>buy_animal</span><span class=special>(</span> <span class=keyword>new</span> <span class=identifier>pig</span><span class=special>(</span><span class=string>"Benny"</span><span class=special>)</span> <span class=special>);</span> + <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>buy_animal</span><span class=special>(</span> <span class=keyword>new</span> <span class=identifier>pig</span><span class=special>(</span><span class=string>"Jeltzin"</span><span class=special>)</span> <span class=special>);</span> + <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>buy_animal</span><span class=special>(</span> <span class=keyword>new</span> <span class=identifier>cow</span><span class=special>(</span><span class=string>"Hanz"</span><span class=special>)</span> <span class=special>);</span> + <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>buy_animal</span><span class=special>(</span> <span class=keyword>new</span> <span class=identifier>cow</span><span class=special>(</span><span class=string>"Mary"</span><span class=special>)</span> <span class=special>);</span> + <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>buy_animal</span><span class=special>(</span> <span class=keyword>new</span> <span class=identifier>cow</span><span class=special>(</span><span class=string>"Frederik"</span><span class=special>)</span> <span class=special>);</span> + <span class=identifier>BOOST_ASSERT</span><span class=special>(</span> <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>size</span><span class=special>()</span> <span class=special>==</span> <span class=number>6u</span> <span class=special>);</span> + + <span class=comment>// + // Then we make another farm...it will actually contain + // a clone of the other farm. + //</span> + <span class=identifier>farm</span> <span class=identifier>new_farm</span><span class=special>(</span> <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>begin</span><span class=special>(),</span> <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>end</span><span class=special>()</span> <span class=special>);</span> + <span class=identifier>BOOST_ASSERT</span><span class=special>(</span> <span class=identifier>new_farm</span><span class=special>.</span><span class=identifier>size</span><span class=special>()</span> <span class=special>==</span> <span class=number>6u</span> <span class=special>);</span> + + <span class=comment>// + // Is it really clones in the new farm? + //</span> + <span class=identifier>BOOST_ASSERT</span><span class=special>(</span> <span class=identifier>new_farm</span><span class=special>.</span><span class=identifier>begin</span><span class=special>()-></span><span class=identifier>name</span><span class=special>()</span> <span class=special>==</span> <span class=string>"Betty"</span> <span class=special>);</span> + + <span class=comment>// + // Then we search for an animal, Mary (the Crown Princess of Denmark), + // because we would like to buy her ... + //</span> + <span class=keyword>typedef</span> <span class=identifier>farm</span><span class=special>::</span><span class=identifier>animal_iterator</span> <span class=identifier>iterator</span><span class=special>;</span> + <span class=identifier>iterator</span> <span class=identifier>to_sell</span><span class=special>;</span> + <span class=keyword>for</span><span class=special>(</span> <span class=identifier>iterator</span> <span class=identifier>i</span> <span class=special>=</span> <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>begin</span><span class=special>(),</span> + <span class=identifier>end</span> <span class=special>=</span> <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>end</span><span class=special>();</span> + <span class=identifier>i</span> <span class=special>!=</span> <span class=identifier>end</span><span class=special>;</span> <span class=special>++</span><span class=identifier>i</span> <span class=special>)</span> + <span class=special>{</span> + <span class=keyword>if</span><span class=special>(</span> <span class=identifier>i</span><span class=special>-></span><span class=identifier>name</span><span class=special>()</span> <span class=special>==</span> <span class=string>"Mary"</span> <span class=special>)</span> + <span class=special>{</span> + <span class=identifier>to_sell</span> <span class=special>=</span> <span class=identifier>i</span><span class=special>;</span> + <span class=keyword>break</span><span class=special>;</span> + <span class=special>}</span> + <span class=special>}</span> + + <span class=identifier>farm</span><span class=special>::</span><span class=identifier>animal_transport</span> <span class=identifier>mary</span> <span class=special>=</span> <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>sell_animal</span><span class=special>(</span> <span class=identifier>to_sell</span> <span class=special>);</span> + + + <span class=keyword>if</span><span class=special>(</span> <span class=identifier>mary</span><span class=special>-></span><span class=identifier>speak</span><span class=special>()</span> <span class=special>==</span> <span class=identifier>muuuh</span> <span class=special>)</span> + <span class=comment>// + // Great, Mary is a cow, and she may live longer + //</span> + <span class=identifier>new_farm</span><span class=special>.</span><span class=identifier>buy_animal</span><span class=special>(</span> <span class=identifier>mary</span><span class=special>.</span><span class=identifier>release</span><span class=special>()</span> <span class=special>);</span> + <span class=keyword>else</span> + <span class=comment>// + // Then the animal would be destroyed (!) + // when we go out of scope. + //</span> + <span class=special>;</span> + + <span class=comment>// + // Now we can observe some changes to the two farms... + //</span> + <span class=identifier>BOOST_ASSERT</span><span class=special>(</span> <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>size</span><span class=special>()</span> <span class=special>==</span> <span class=number>5u</span> <span class=special>);</span> + <span class=identifier>BOOST_ASSERT</span><span class=special>(</span> <span class=identifier>new_farm</span><span class=special>.</span><span class=identifier>size</span><span class=special>()</span> <span class=special>==</span> <span class=number>7u</span> <span class=special>);</span> + + <span class=comment>// + // The new farm has however underestimated how much + // it cost to feed Mary and its owner is forced to sell the farm... + //</span> + <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>buy_farm</span><span class=special>(</span> <span class=identifier>new_farm</span><span class=special>.</span><span class=identifier>sell_farm</span><span class=special>()</span> <span class=special>);</span> + + <span class=identifier>BOOST_ASSERT</span><span class=special>(</span> <span class=identifier>new_farm</span><span class=special>.</span><span class=identifier>size</span><span class=special>()</span> <span class=special>==</span> <span class=number>0u</span> <span class=special>);</span> + <span class=identifier>BOOST_ASSERT</span><span class=special>(</span> <span class=identifier>animal_farm</span><span class=special>.</span><span class=identifier>size</span><span class=special>()</span> <span class=special>==</span> <span class=number>12u</span> <span class=special>);</span> +<span class=special>}</span> +</pre> +</body> + +</html> diff --git a/libs/ptr_container/index.html b/libs/ptr_container/index.html new file mode 100644 index 0000000000..9c8de621c5 --- /dev/null +++ b/libs/ptr_container/index.html @@ -0,0 +1,20 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> + +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<meta http-equiv="refresh" content="0; URL=doc/ptr_container.html"> +<title>Boost.Pointer Container Documentation</title> +<link rel="stylesheet" href="doc/default.css" type="text/css"> +</head> + +<body> +Automatic redirection failed, please go to +<a href="doc/ptr_container.html">doc/pointer_container.html</a> +<hr> +<p>© Copyright Beman Dawes, 2001</p> +<p>Distributed under the Boost Software License, Version 1.0. (See accompanying +file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy +at <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)</p> +</body> +</html>
\ No newline at end of file diff --git a/libs/ptr_container/test/Jamfile.v2 b/libs/ptr_container/test/Jamfile.v2 new file mode 100644 index 0000000000..04cb295698 --- /dev/null +++ b/libs/ptr_container/test/Jamfile.v2 @@ -0,0 +1,43 @@ +#// +#// Boost.Pointer Container +#// +#// Copyright Thorsten Ottosen 2003-2008. Use, modification and +#// distribution is subject to the Boost Software License, Version +#// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +#// http://www.boost.org/LICENSE_1_0.txt) +#// +#// For more information, see http://www.boost.org/libs/ptr_container/ +#// + +rule sc-test ( name : extra-sources * ) +{ + return [ + run $(name).cpp /boost/test//boost_unit_test_framework/<link>static $(extra-sources) ] + ; +} + + +test-suite ptr_container : + [ sc-test ptr_inserter ] + [ sc-test ptr_vector ] + [ sc-test ptr_list ] + [ sc-test ptr_deque ] + [ sc-test ptr_set ] + [ sc-test ptr_map ] + [ sc-test ptr_map_adapter ] + [ sc-test ptr_array ] + [ sc-test tree_test ] + [ sc-test incomplete_type_test ] + [ run view_example.cpp ] + [ sc-test iterator_test ] + [ run tut1.cpp ] + [ sc-test indirect_fun ] + [ sc-test serialization : /boost/serialization//boost_serialization ] + [ sc-test no_exceptions ] + + [ sc-test ptr_unordered_set ] + [ sc-test ptr_unordered_map ] + [ sc-test ptr_circular_buffer ] + # [ sc-test null_filter_iterator ] + + ; diff --git a/libs/ptr_container/test/associative_test_data.hpp b/libs/ptr_container/test/associative_test_data.hpp new file mode 100644 index 0000000000..3f3d9ad8a4 --- /dev/null +++ b/libs/ptr_container/test/associative_test_data.hpp @@ -0,0 +1,191 @@ +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +#include "test_data.hpp" +#include <boost/ptr_container/exception.hpp> +#include <boost/range/sub_range.hpp> + +template< typename C, typename B, typename T, bool Ordered > +void ptr_set_test(); + +template< class T, bool Ordered > +struct test_algorithms +{ + template< class Cont > + void operator()( Cont& c, const Cont& c2 ) const + { + typename Cont::iterator i; + typename Cont::const_iterator ci; + + T* t = new T; + i = c.lower_bound( *t ); + ci = c2.lower_bound( *t ); + i = c.upper_bound( *t ); + ci = c2.upper_bound( *t ); + delete t; + + BOOST_DEDUCED_TYPENAME Cont::reverse_iterator ri = c.rbegin(); + BOOST_DEDUCED_TYPENAME Cont::const_reverse_iterator cri = c2.rbegin(); + BOOST_DEDUCED_TYPENAME Cont::reverse_iterator rv2 = c.rend(); + BOOST_DEDUCED_TYPENAME Cont::const_reverse_iterator cvr2 = c2.rend(); + cri = c.crbegin(); + cri = c.crend(); + } +}; + +template< class T > +struct test_algorithms<T,false> +{ + template< class Cont> + void operator()( Cont& c, const Cont& c2 ) const + { + } +}; + +template< typename C, typename B, typename T, bool Ordered > +void ptr_set_test() +{ + using namespace boost; + + BOOST_MESSAGE( "starting associative container test" ); + enum { max_cnt = 10, size = 100 }; + C c; + BOOST_CHECK( c.size() == 0 ); + c.insert( c.end(), new T ); + c.insert( c.end(), new T ); + + const C c2( c.begin(), c.end() ); + BOOST_CHECK( c.size() == c2.size() ); + + C c3; + + BOOST_MESSAGE( "finished construction test" ); + + C a_copy( c ); + BOOST_CHECK_EQUAL( a_copy.size(), c.size() ); + a_copy = a_copy; + BOOST_CHECK_EQUAL( a_copy.size(), c.size() ); + c.clear(); + a_copy = c; + a_copy = a_copy; + BOOST_CHECK( a_copy.empty() ); + + BOOST_MESSAGE( "finished copying test" ); + + BOOST_DEDUCED_TYPENAME C::allocator_type alloc = c.get_allocator(); + BOOST_DEDUCED_TYPENAME C::iterator i = c.begin(); + BOOST_DEDUCED_TYPENAME C::const_iterator ci = c2.begin(); + ci = c.cbegin(); + ci = c.cend(); + BOOST_DEDUCED_TYPENAME C::iterator i2 = c.end(); + BOOST_DEDUCED_TYPENAME C::const_iterator ci2 = c2.begin(); + + BOOST_MESSAGE( "finished iterator test" ); + + BOOST_DEDUCED_TYPENAME C::size_type s = c.size(); + BOOST_DEDUCED_TYPENAME C::size_type s2 = c.max_size(); + hide_warning(s2); + BOOST_CHECK_EQUAL( c.size(), s ); + bool b = c.empty(); + hide_warning(b); + BOOST_MESSAGE( "finished accessors test" ); + + T* t = new T; + c.insert( c.end(), t ); + c.insert( c.end(), std::auto_ptr<T>( new T ) ); + c.insert( new T ); + std::auto_ptr<T> ap( new T ); + c.insert( ap ); + c3.insert( c.begin(), c.end() ); + c.erase( c.begin() ); + c3.erase( c3.begin(), c3.end() ); + t = new T; + c.insert( new T ); + c.erase( *t ); + delete t; + + BOOST_CHECK( c3.empty() ); + c.swap( c3 ); + BOOST_CHECK( !c3.empty() ); + BOOST_CHECK( c.empty() ); + c3.clear(); + + // + // remark: we cannot pass c3 directly as it would + // extract const iterators ... and the + // current standard does not allow erase() + // to be given const iterators + // + c3.erase( boost::make_iterator_range(c3) ); + BOOST_CHECK( c3.empty() ); + BOOST_MESSAGE( "finished modifiers test" ); + + c.insert( c.end(), new T ); + typename C::auto_type ptr2 = c.release( c.begin() ); + std::auto_ptr<C> ap2 = c.release(); + c = c2.clone(); + BOOST_MESSAGE( "finished release/clone test" ); + + c3.insert( new T ); + c3.insert( new T ); + BOOST_CHECK_EQUAL( c3.size(), 2u ); +#if defined(BOOST_NO_SFINAE) || defined(BOOST_NO_FUNCTION_TEMPLATE_ORDERING) +#else + c3.insert( make_iterator_range( c ) ); +// BOOST_CHECK_EQUAL( c3.size(), 4u ); +#endif + c. BOOST_NESTED_TEMPLATE transfer<C>( c3.begin(), c3 ); + BOOST_CHECK( c3.empty() == false ); + c.clear(); + unsigned long c3size = c3.size(); + hide_warning( c3size ); + unsigned long num = c. BOOST_NESTED_TEMPLATE transfer<C>( c3.begin(), + c3.end(), + c3 ); + + BOOST_CHECK( num > 0 ); + BOOST_CHECK_EQUAL( num, c.size() ); + BOOST_CHECK( c3.empty() ); + BOOST_CHECK( !c.empty() ); + c3. BOOST_NESTED_TEMPLATE transfer<C>( c ); + BOOST_CHECK( !c3.empty() ); + BOOST_CHECK( c.empty() ); +#ifdef BOOST_NO_SFINAE +#else + c. BOOST_NESTED_TEMPLATE transfer<C>( make_iterator_range( c3 ), c3 ); + BOOST_CHECK( !c.empty() ); + BOOST_CHECK( c3.empty() ); +#endif + + BOOST_MESSAGE( "finished transfer test" ); + + C c4; + c4.swap(c3); + swap(c4,c3); + BOOST_MESSAGE( "finished set/map interface test" ); + + sub_range<C> sub; + sub_range<const C> csub; + + t = new T; + i = c.find( *t ); + ci = c2.find( *t ); + c2.count( *t ); + + test_algorithms<T,Ordered>()( c, c2 ); + sub = c.equal_range( *t ); + csub = c2.equal_range( *t ); + delete t; + + BOOST_MESSAGE( "finished algorithms interface test" ); + +} + diff --git a/libs/ptr_container/test/incomplete_type_test.cpp b/libs/ptr_container/test/incomplete_type_test.cpp new file mode 100644 index 0000000000..b8afbd4c4f --- /dev/null +++ b/libs/ptr_container/test/incomplete_type_test.cpp @@ -0,0 +1,186 @@ +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +#include "test_data.hpp" +#include <boost/ptr_container/ptr_vector.hpp> +#include <boost/utility.hpp> +#include <algorithm> +#include <iostream> + +using namespace std; +using namespace boost; + +// +// Forward declare 'allocate_clone()' to be able +// use clonability of 'Composite' inline in the class. +// This is normally not needed when using .hpp + .cpp files. +// +class Composite; +Composite* new_clone( const Composite& ); + + +class Composite +{ + typedef ptr_vector<Composite> composite_t; + typedef composite_t::iterator iterator; + typedef composite_t::const_iterator const_iterator; + typedef composite_t::size_type size_type; + composite_t elements_; + + // + // only used internally for 'clone()' + // + Composite( const Composite& r ) : elements_( r.elements_.clone() ) + { } + + // + // this class is not Copyable nor Assignable + // + void operator=( const Composite& ); + +public: + Composite() + { } + + // + // of course detructor is virtual + // + virtual ~Composite() + { } + + // + // one way of adding new elements + // + void add( Composite* c ) + { + elements_.push_back( c ); + } + + // + // second way of adding new elements + // + void add( Composite& c ) + { + elements_.push_back( new_clone( c ) ); + } + + void remove( iterator where ) + { + elements_.erase( where ); + } + + // + // recusively count the elements + // + size_type size() const + { + size_type res = 0; + for( const_iterator i = elements_.begin(); i != elements_.end(); ++i ) + res += i->size(); + return 1 /* this */ + res; + } + + void foo() + { + do_foo(); + for( iterator i = elements_.begin(); i != elements_.end(); ++i ) + i->foo(); + } + + // + // this class is clonable and this is the callback for 'allocate_clone()' + // + Composite* clone() const + { + return do_clone(); + } + +private: + virtual void do_foo() + { + cout << "composite base" << "\n"; + } + + virtual Composite* do_clone() const + { + return new Composite( *this ); + } +}; + +// +// make 'Composite' clonable; note that we do not need to overload +// the function in the 'boost' namespace. +// +Composite* new_clone( const Composite& c ) +{ + return c.clone(); +} + + +class ConcreteComposite1 : public Composite +{ + virtual void do_foo() + { + cout << "composite 1" << "\n"; + } + + virtual Composite* do_clone() const + { + return new ConcreteComposite1(); + } +}; + + +class ConcreteComposite2 : public Composite +{ + virtual void do_foo() + { + cout << "composite 2" << "\n"; + } + + virtual Composite* do_clone() const + { + return new ConcreteComposite2(); + } +}; + +void test_incomplete() +{ + Composite c; + c.add( new ConcreteComposite1 ); + c.add( new ConcreteComposite2 ); + BOOST_CHECK_EQUAL( c.size(), 3u ); + c.add( new_clone( c ) ); // add c to itself + BOOST_CHECK_EQUAL( c.size(), 6u ); + c.add( c ); // add c to itself + BOOST_CHECK_EQUAL( c.size(), 12u ); + c.foo(); +} + +using namespace boost; + + +#include <boost/test/unit_test.hpp> +using boost::unit_test::test_suite; + +test_suite* init_unit_test_suite( int argc, char* argv[] ) +{ + test_suite* test = BOOST_TEST_SUITE( "Pointer Container Test Suite" ); + + test->add( BOOST_TEST_CASE( &test_incomplete ) ); + + return test; +} + +// +// todo: remake example with shared_ptr +// + diff --git a/libs/ptr_container/test/indirect_fun.cpp b/libs/ptr_container/test/indirect_fun.cpp new file mode 100644 index 0000000000..f3c6755ef1 --- /dev/null +++ b/libs/ptr_container/test/indirect_fun.cpp @@ -0,0 +1,78 @@ +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +#include <boost/ptr_container/indirect_fun.hpp> +#include <boost/ptr_container/ptr_vector.hpp> +#include <boost/assign/list_inserter.hpp> +#include <boost/test/test_tools.hpp> +#include <algorithm> +#include <functional> +#include <string> + +bool lesser_than( const std::string& l, const std::string& r ) +{ + return l < r; +} + + +void test_fun() +{ + using namespace boost; + ptr_vector<std::string> vec; + + indirect_fun< std::less<std::string> > fun; + + std::string* ptr1 = new std::string("bar"); + std::string* ptr2 = new std::string("foo"); + BOOST_CHECK( fun( ptr1, ptr2 ) == true ); + + void* vptr1 = ptr1; + void* vptr2 = ptr2; + + void_ptr_indirect_fun< std::less<std::string>, std::string> cast_fun; + BOOST_CHECK( cast_fun( vptr1, vptr2 ) == true ); + + assign::push_back( vec )( new std::string("aa") ) + ( new std::string("bb") ) + ( new std::string("dd") ) + ( new std::string("cc") ) + ( new std::string("a") ); + + std::sort( vec.begin().base(), vec.end().base(), cast_fun ); + BOOST_CHECK( vec[0] == "a" ); + BOOST_CHECK( vec[4] == "dd" ); + + std::sort( vec.begin().base(), vec.end().base(), + make_void_ptr_indirect_fun<std::string>( &lesser_than ) ); + BOOST_CHECK( vec[1] == "aa" ); + BOOST_CHECK( vec[2] == "bb" ); + + void* iptr1 = new int(2); + void* iptr2 = new int(3); + + void_ptr_indirect_fun<std::less<int>, int> int_cast_fun; + BOOST_CHECK( int_cast_fun(iptr1,iptr2) ); + +} + +#include <boost/test/unit_test.hpp> +using boost::unit_test::test_suite; + +test_suite* init_unit_test_suite( int argc, char* argv[] ) +{ + test_suite* test = BOOST_TEST_SUITE( "Pointer Container Test Suite" ); + + test->add( BOOST_TEST_CASE( &test_fun ) ); + + return test; +} + + diff --git a/libs/ptr_container/test/iterator_test.cpp b/libs/ptr_container/test/iterator_test.cpp new file mode 100644 index 0000000000..6df9749693 --- /dev/null +++ b/libs/ptr_container/test/iterator_test.cpp @@ -0,0 +1,78 @@ +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +#include <boost/ptr_container/ptr_vector.hpp> +#include <boost/ptr_container/ptr_map.hpp> +#include <boost/test/test_tools.hpp> + +void test_iterator() +{ + using namespace boost; + ptr_vector<int> vec; + vec.push_back( new int(0) ); + ptr_vector<int>::iterator mutable_i = vec.begin(); + ptr_vector<int>::const_iterator const_i = vec.begin(); + + BOOST_CHECK( mutable_i == const_i ); + BOOST_CHECK( ! (mutable_i != const_i ) ); + BOOST_CHECK( const_i == mutable_i ); + BOOST_CHECK( ! ( const_i != mutable_i ) ); + + BOOST_CHECK( !( mutable_i < const_i ) ); + BOOST_CHECK( mutable_i <= const_i ); + BOOST_CHECK( ! ( mutable_i > const_i ) ); + BOOST_CHECK( mutable_i >= const_i ); + BOOST_CHECK( !( const_i < mutable_i ) ); + BOOST_CHECK( const_i <= mutable_i ); + BOOST_CHECK( ! ( const_i > mutable_i ) ); + BOOST_CHECK( const_i >= mutable_i ); + + BOOST_CHECK( const_i - mutable_i == 0 ); + BOOST_CHECK( mutable_i - const_i == 0 ); + + const ptr_vector<int>& rvec = vec; + const_i = rvec.begin(); + + ptr_map<int,int> map; + int i = 0; + map.insert( i, new int(0) ); + ptr_map<int,int>::iterator map_mutable_i = map.begin(); + ptr_map<int,int>::const_iterator map_const_i = map.begin(); + +#if !BOOST_WORKAROUND(__DECCXX_VER, BOOST_TESTED_AT(70190006)) + // This only works for library implementations which conform to the + // proposed resolution of the C++ Standard Library DR#179. See + // http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#179. + BOOST_CHECK( map_mutable_i == map_const_i ); + BOOST_CHECK( ! ( map_mutable_i != map_const_i ) ); + BOOST_CHECK( map_const_i == map_mutable_i ); + BOOST_CHECK( ! ( map_const_i != map_mutable_i ) ); +#endif + + const ptr_map<int,int>& rmap = map; + map_const_i = rmap.begin(); +} + +#include <boost/test/unit_test.hpp> +using boost::unit_test::test_suite; + +test_suite* init_unit_test_suite( int argc, char* argv[] ) +{ + test_suite* test = BOOST_TEST_SUITE( "Pointer Container Test Suite" ); + + test->add( BOOST_TEST_CASE( &test_iterator ) ); + + return test; +} + + + + diff --git a/libs/ptr_container/test/no_exceptions.cpp b/libs/ptr_container/test/no_exceptions.cpp new file mode 100644 index 0000000000..d7cfa43d4a --- /dev/null +++ b/libs/ptr_container/test/no_exceptions.cpp @@ -0,0 +1,21 @@ +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2006. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +#define BOOST_PTR_CONTAINER_NO_EXCEPTIONS 1 + +#include "ptr_vector.cpp" + + + + + + + diff --git a/libs/ptr_container/test/pointainer_speed.cpp b/libs/ptr_container/test/pointainer_speed.cpp new file mode 100644 index 0000000000..716a5a0c27 --- /dev/null +++ b/libs/ptr_container/test/pointainer_speed.cpp @@ -0,0 +1,205 @@ +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +#include "test_data.hpp" +#include <boost/ptr_container/ptr_vector.hpp> +#include <boost/shared_ptr.hpp> +#include <boost/progress.hpp> + + +using namespace boost; +using namespace std; + + +typedef shared_ptr<Base> PolyPtr; + +struct PolyPtrOps +{ + void operator()( const PolyPtr& a ) + { a->foo(); } +}; + +struct less_than +{ + bool operator()( const PolyPtr& l, const PolyPtr& r ) const + { + return *l < *r; + } + + bool operator()( const Base* l, const Base* r ) const + { + return *l < *r; + } +}; + +struct greater_than +{ + bool operator()( const PolyPtr& l, const PolyPtr& r ) const + { + return *l > *r; + } + + bool operator()( const Base* l, const Base* r ) const + { + return *l > *r; + } +}; + +struct data_less_than +{ + bool operator()( const PolyPtr& l, const PolyPtr& r ) const + { + return l->data_less_than(*r); + } + + bool operator()( const Base* l, const Base* r ) const + { + return l->data_less_than(*r); + } +}; + +struct data_less_than2 +{ + bool operator()( const PolyPtr& l, const PolyPtr& r ) const + { + return l->data_less_than2(*r); + } + + bool operator()( const Base* l, const Base* r ) const + { + return l->data_less_than2(*r); + } +}; + + +void test_speed() +{ + enum { size = 50000 }; + vector<PolyPtr> svec; + ptr_vector<Base> pvec; + + { + progress_timer timer; + for( int i = 0; i < size; ++i ) + svec.push_back( PolyPtr( new Derived ) ); + cout << "\n shared_ptr call new: "; + } + + { + progress_timer timer; + for( int i = 0; i < size; ++i ) + pvec.push_back( new Derived ); + cout << "\n smart container call new: "; + } + + { + progress_timer timer; + for_each( svec.begin(), svec.end(), PolyPtrOps() ); + cout << "\n shared_ptr call foo(): "; + } + + { + progress_timer timer; + for_each( pvec.begin(), pvec.end(), mem_fun_ref( &Base::foo ) ); + cout << "\n smart container call foo(): "; + } + + { + progress_timer timer; + sort( svec.begin(), svec.end(), less_than() ); + cout << "\n shared_ptr call sort(): "; + } + + { + progress_timer timer; + sort( pvec.ptr_begin(), pvec.ptr_end(), less_than() ); + cout << "\n smart container call sort(): "; + } + + { + progress_timer timer; + sort( svec.begin(), svec.end(), greater_than() ); + cout << "\n shared_ptr call sort() #2: "; + } + + { + progress_timer timer; + sort( pvec.ptr_begin(), pvec.ptr_end(), greater_than() ); + cout << "\n smart container call sort() #2: "; + } + + { + progress_timer timer; + sort( svec.begin(), svec.end(), data_less_than() ); + cout << "\n shared_ptr call sort() #3: "; + } + + { + progress_timer timer; + sort( pvec.ptr_begin(), pvec.ptr_end(), data_less_than() ); + cout << "\n smart container call sort() #3: "; + } + + { + progress_timer timer; + sort( svec.begin(), svec.end(), data_less_than2() ); + cout << "\n shared_ptr call sort() #4: "; + } + + { + progress_timer timer; + sort( pvec.ptr_begin(), pvec.ptr_end(), data_less_than2() ); + cout << "\n smart container call sort() #4: "; + } + + vector<Base*> copy1; + for( ptr_vector<Base>::ptr_iterator i = pvec.ptr_begin(); i != pvec.ptr_end(); ++ i ) + copy1.push_back( *i ); + + sort( pvec.ptr_begin(), pvec.ptr_end() ); + + + vector<Base*> copy2; + for( ptr_vector<Base>::ptr_iterator i = pvec.ptr_begin(); i != pvec.ptr_end(); ++ i ) + copy2.push_back( *i ); + + + for( unsigned int i = 0; i < copy1.size(); ++i ) + { + bool found = false; + for( int j = 0; j < copy1.size(); ++ j ) + if( copy1[i] == copy2[j] ) + found = true; + + if( !found ) + cout << copy1[i] << endl; + } + + BOOST_REQUIRE( pvec.size() == size ); + cout << endl; +} + + +#include <boost/test/unit_test.hpp> +using boost::unit_test::test_suite; + +test_suite* init_unit_test_suite( int argc, char* argv[] ) +{ + test_suite* test = BOOST_TEST_SUITE( "Pointer Container Test Suite" ); + + test->add( BOOST_TEST_CASE( &test_speed ) ); + + return test; +} + + + + diff --git a/libs/ptr_container/test/ptr_array.cpp b/libs/ptr_container/test/ptr_array.cpp new file mode 100644 index 0000000000..0d9718ee99 --- /dev/null +++ b/libs/ptr_container/test/ptr_array.cpp @@ -0,0 +1,171 @@ +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +#include <boost/test/unit_test.hpp> +#include "test_data.hpp" +#include <boost/ptr_container/ptr_array.hpp> +#include <boost/utility.hpp> +#include <boost/array.hpp> +#include <algorithm> +#include <iostream> +#include <cstddef> +#include <string> + +using namespace std; +using namespace boost; + +template< class Node, size_t N > +class n_ary_tree : boost::noncopyable +{ + typedef n_ary_tree<Node,N> this_type; + typedef ptr_array<this_type,N> tree_t; + + tree_t tree; + Node data; + +public: + n_ary_tree() { } + n_ary_tree( const Node& r ) : data(r) { } + +public: // modifers + void set_data( const Node& r ) { data = r; } + template< size_t idx > + void set_child( this_type* r ) { tree. BOOST_NESTED_TEMPLATE replace<idx>(r); } + +public: // accessors + void print( std::ostream&, std::string indent = " " ); + template< size_t idx > + this_type& child() { return tree. BOOST_NESTED_TEMPLATE at<idx>(); } + template< size_t idx > + const this_type& child() const { return tree. BOOST_NESTED_TEMPLATE at<idx>(); } + +}; + + + +template< class Node, size_t N > +void n_ary_tree<Node,N>::print( std::ostream& out, std::string indent ) +{ + out << indent << data << "\n"; + indent += " "; + for( size_t i = 0; i != N; ++i ) + if( !tree.is_null(i) ) + tree[i].print( out, indent + " " ); +} + + +template< class C, class B, class T > +void test_array_interface(); + +void test_array() +{ + typedef n_ary_tree<std::string,2> binary_tree; + binary_tree tree; + tree.set_data( "root" ); + tree.set_child<0>( new binary_tree( "left subtree" ) ); + tree.set_child<1>( new binary_tree( "right subtree" ) ); + binary_tree& left = tree.child<0>(); + left.set_child<0>( new binary_tree( "left left subtree" ) ); + left.set_child<1>( new binary_tree( "left right subtree" ) ); + binary_tree& right = tree.child<1>(); + right.set_child<0>( new binary_tree( "right left subtree" ) ); + right.set_child<1>( new binary_tree( "right right subtree" ) ); + + tree.print( std::cout ); + + test_array_interface<ptr_array<Base,10>,Base,Derived_class>(); + test_array_interface<ptr_array<nullable<Base>,10>,Base,Derived_class>(); + test_array_interface<ptr_array<Value,10>,Value,Value>(); + test_array_interface<ptr_array<nullable<Value>,10>,Value,Value>(); + + ptr_array<int,10> vec; + BOOST_CHECK_THROW( vec.at(10), bad_ptr_container_operation ); + BOOST_CHECK_THROW( (vec.replace(10u, new int(0))), bad_ptr_container_operation ); + BOOST_CHECK_THROW( (vec.replace(10u, std::auto_ptr<int>(new int(0)))), bad_ptr_container_operation ); + BOOST_CHECK_THROW( (vec.replace(0u, 0)), bad_ptr_container_operation ); + + ptr_array<Derived_class,2> derived; + derived.replace( 0, new Derived_class ); + derived.replace( 1, new Derived_class ); + ptr_array<Base,2> base( derived ); + + BOOST_MESSAGE( "finished derived to base test" ); + + base = derived; + ptr_array<Base,2> base2( base ); + base2 = base; + base = base; +} + +template< class C, class B, class T > +void test_array_interface() +{ + C c; + c.replace( 0, new T ); + c.replace( 1, new B ); + c.replace( 9, new T ); + c.replace( 0, std::auto_ptr<T>( new T ) ); + const C c2( c.clone() ); + + BOOST_DEDUCED_TYPENAME C::iterator i = c.begin(); + BOOST_DEDUCED_TYPENAME C::const_iterator ci = c2.begin(); + BOOST_DEDUCED_TYPENAME C::iterator i2 = c.end(); + BOOST_DEDUCED_TYPENAME C::const_iterator ci2 = c2.begin(); + BOOST_DEDUCED_TYPENAME C::reverse_iterator ri = c.rbegin(); + BOOST_DEDUCED_TYPENAME C::const_reverse_iterator cri = c2.rbegin(); + BOOST_DEDUCED_TYPENAME C::reverse_iterator rv2 = c.rend(); + BOOST_DEDUCED_TYPENAME C::const_reverse_iterator cvr2 = c2.rend(); + + BOOST_MESSAGE( "finished iterator test" ); + + BOOST_CHECK_EQUAL( c.empty(), false ); + BOOST_CHECK_EQUAL( c.size(), c.max_size() ); + + BOOST_MESSAGE( "finished capacity test" ); + + BOOST_CHECK_EQUAL( c.is_null(0), false ); + BOOST_CHECK_EQUAL( c.is_null(1), false ); + BOOST_CHECK_EQUAL( c.is_null(2), true ); + + c.front(); + c.back(); + c2.front(); + c2.back(); + C c3; + c.swap( c3 ); + C c4; + swap(c4,c3); + c3.swap(c4); + + BOOST_CHECK_EQUAL( c.is_null(0), true ); + BOOST_CHECK_EQUAL( c3.is_null(0), false ); + + c.replace( 5, new T ); + BOOST_CHECK_EQUAL( c.is_null(5), false ); + c = c3.release(); + for( size_t i = 0; i < c3.size(); ++i ) + BOOST_CHECK_EQUAL( c3.is_null(i), true ); + + BOOST_MESSAGE( "finished element access test" ); +} + +using boost::unit_test::test_suite; + +test_suite* init_unit_test_suite( int argc, char* argv[] ) +{ + test_suite* test = BOOST_TEST_SUITE( "Pointer Container Test Suite" ); + + test->add( BOOST_TEST_CASE( &test_array ) ); + + return test; +} + + diff --git a/libs/ptr_container/test/ptr_circular_buffer.cpp b/libs/ptr_container/test/ptr_circular_buffer.cpp new file mode 100644 index 0000000000..90d1b8b48c --- /dev/null +++ b/libs/ptr_container/test/ptr_circular_buffer.cpp @@ -0,0 +1,198 @@ +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +#include <boost/test/unit_test.hpp> +#include "sequence_test_data.hpp" +#include <boost/ptr_container/ptr_circular_buffer.hpp> +#include <boost/ptr_container/ptr_list.hpp> +#include <boost/assign/list_inserter.hpp> + +template<class T> +struct set_capacity< ptr_circular_buffer<T> > +{ + void operator()( ptr_circular_buffer<T>& c ) const + { + c.set_capacity( 100u ); + } +}; + +void test_ptr_circular_buffer() +{ + reversible_container_test< ptr_circular_buffer<Base>, Base, Derived_class >(); + reversible_container_test< ptr_circular_buffer<Value>, Value, Value >(); + +#ifdef BOOST_NO_SFINAE +#else + reversible_container_test< ptr_circular_buffer< nullable<Base> >, Base, Derived_class >(); + reversible_container_test< ptr_circular_buffer< nullable<Value> >, Value, Value >(); +#endif + + container_assignment_test< ptr_circular_buffer<Base>, ptr_circular_buffer<Derived_class>, + Derived_class>(); + container_assignment_test< ptr_circular_buffer< nullable<Base> >, + ptr_circular_buffer< nullable<Derived_class> >, + Derived_class>(); + container_assignment_test< ptr_circular_buffer< nullable<Base> >, + ptr_circular_buffer<Derived_class>, + Derived_class>(); + container_assignment_test< ptr_circular_buffer<Base>, + ptr_circular_buffer< nullable<Derived_class> >, + Derived_class>(); + + test_transfer< ptr_circular_buffer<Derived_class>, ptr_circular_buffer<Base>, Derived_class>(); + test_transfer< ptr_circular_buffer<Derived_class>, ptr_list<Base>, Derived_class>(); + + random_access_algorithms_test< ptr_circular_buffer<int> >(); + + + BOOST_MESSAGE( "starting ptr_circular_buffer test" ); + ptr_circular_buffer<int> vec( 100u ); + BOOST_CHECK( vec.capacity() >= 100u ); + +#ifdef BOOST_PTR_CONTAINER_NO_EXCEPTIONS +#else + + BOOST_CHECK_THROW( vec.push_back(0), bad_ptr_container_operation ); + BOOST_CHECK_THROW( (vec.insert( vec.begin(), 0 )), bad_ptr_container_operation ); + BOOST_CHECK_THROW( vec.at( 42 ), bad_ptr_container_operation ); + vec.push_back( new int(0) ); + BOOST_CHECK_THROW( (vec.replace(10u, new int(0))), bad_ptr_container_operation ); + BOOST_CHECK_THROW( (vec.replace(0u, 0)), bad_ptr_container_operation ); + BOOST_CHECK_THROW( (vec.replace(vec.begin(), 0 )), bad_ptr_container_operation ); + +#endif + + vec.clear(); + assign::push_back( vec )( new int(2) ) + ( new int(4) ) + ( new int(6) ) + ( new int(8) ); + ptr_circular_buffer<int> vec2( 100u ); + assign::push_back( vec2 ) + ( new int(1) ) + ( new int(3) ) + ( new int(5) ) + ( new int(7) ); + BOOST_CHECK_EQUAL( vec.size(), vec2.size() ); + BOOST_CHECK( vec > vec2 ); + BOOST_CHECK( vec != vec2 ); + BOOST_CHECK( !(vec == vec2) ); + BOOST_CHECK( vec2 < vec ); + BOOST_CHECK( vec2 <= vec ); + BOOST_CHECK( vec >= vec2 ); + + BOOST_MESSAGE( "push_front test" ); + assign::push_front( vec2 ) + ( new int(2) ) + ( new int(4) ) + ( new int(6) ) + ( new int(8) ); + BOOST_CHECK_EQUAL( vec2.size(), 8u ); + BOOST_CHECK_EQUAL( vec2[0], 8 ); + BOOST_CHECK_EQUAL( vec2.front(), 8 ); + BOOST_CHECK_EQUAL( vec2.back(), 7 ); + + //vec2.linearize(); + vec2.rset_capacity( vec2.size() - 2u ); + vec2.rresize( 0 ); + //vec2.reverse(); + + BOOST_MESSAGE( "when full test" ); + + ptr_circular_buffer<int> vec3; + BOOST_CHECK_EQUAL( vec3.capacity(), 0u ); + vec3.set_capacity( 2u ); + BOOST_CHECK_EQUAL( vec3.capacity(), 2u ); + + vec3.push_back( new int(1) ); + vec3.push_back( new int(2) ); + BOOST_CHECK_EQUAL( vec3.size(), 2u ); + BOOST_CHECK( vec3.full() ); + + vec3.push_back( new int(3) ); + BOOST_CHECK_EQUAL( vec3.front(), 2 ); + BOOST_CHECK_EQUAL( vec3.back(), 3 ); + + vec3.push_front( new int(4) ); + BOOST_CHECK_EQUAL( vec3.size(), 2u ); + BOOST_CHECK_EQUAL( vec3.front(), 4 ); + BOOST_CHECK_EQUAL( vec3.back(), 2 ); + + vec3.insert( vec3.end(), new int(5) ); + BOOST_CHECK_EQUAL( vec3.front(), 2 ); + BOOST_CHECK_EQUAL( vec3.back(), 5 ); + + vec3.rinsert( vec3.begin(), new int(6) ); + BOOST_CHECK_EQUAL( vec3.front(), 6 ); + BOOST_CHECK_EQUAL( vec3.back(), 2 ); + + BOOST_MESSAGE( "transfer test" ); + ptr_circular_buffer<int> vec4(2u); + vec4.transfer( vec4.end(), vec3 ); + BOOST_CHECK_EQUAL( vec4.size(), 2u ); + BOOST_CHECK_EQUAL( vec3.size(), 0u ); + vec3.set_capacity(1u); + vec3.transfer( vec3.end(), vec4 ); + BOOST_CHECK_EQUAL( vec4.size(), 0u ); + BOOST_CHECK_EQUAL( vec3.size(), 1u ); + BOOST_CHECK_EQUAL( vec3.front(), 2 ); + + BOOST_MESSAGE( "rerase test" ); + vec.rerase( vec.begin() ); + vec.rerase( boost::make_iterator_range( vec ) ); + + BOOST_MESSAGE( "array test" ); + const int data_size = 10; + int** array = new int*[data_size]; + for( int i = 0; i != data_size; ++i ) + array[i] = new int(i); + + vec.transfer( vec.begin(), array, data_size ); + int** array2 = vec.c_array(); + BOOST_CHECK( array2 != array ); + + ptr_circular_buffer<int>::array_range array_range = vec.array_one(); + array_range = vec.array_two(); + ptr_circular_buffer<int>::const_array_range const_array_range = array_range; + const_array_range = const_cast< const ptr_circular_buffer<int>& >(vec).array_one(); + const_array_range = const_cast< const ptr_circular_buffer<int>& >(vec).array_two(); + + BOOST_MESSAGE( "finishing ptr_circular_buffer test" ); + +} + + + +void test_circular_buffer() +{ + boost::circular_buffer<void*> b(25u); + BOOST_CHECK_EQUAL( b.capacity(), 25u ); + b.push_back( 0 ); + BOOST_CHECK_EQUAL( b.size(), 1u ); + boost::circular_buffer<void*> b2( b.begin(), b.end() ); + BOOST_CHECK_EQUAL( b2.size(), b.size() ); +} + +using boost::unit_test::test_suite; + +test_suite* init_unit_test_suite( int argc, char* argv[] ) +{ + test_suite* test = BOOST_TEST_SUITE( "Pointer Container Test Suite" ); + + test->add( BOOST_TEST_CASE( &test_circular_buffer ) ); + test->add( BOOST_TEST_CASE( &test_ptr_circular_buffer ) ); + + return test; +} + + + + diff --git a/libs/ptr_container/test/ptr_container_adapter.cpp b/libs/ptr_container/test/ptr_container_adapter.cpp new file mode 100644 index 0000000000..2dcc978b62 --- /dev/null +++ b/libs/ptr_container/test/ptr_container_adapter.cpp @@ -0,0 +1,68 @@ +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +#include "sequence_test_data.hpp" +#include <boost/ptr_container/ptr_container_adapter.hpp> +#include <list> + + +template< class T > +class my_list : public std::list<T> +{ + typedef BOOST_DEDUCED_TYPENAME std::list<T> base_class; + +public: +/* + my_list( const base_class::allocator_type& alloc = base_class::allocator_type() ) + : base_class( alloc ) {} + + my_list( size_type n, const T& x, const base_class::allocator_type& alloc = base_class::allocator_type() ) + : base_class( n, x, alloc ) {} + + template< class InputIterator > + my_list( InputIterator first, InputIterator last ) : base_class( first, last ) {} +*/ +}; + +void test_container_adapter() +{ + typedef ptr_container_adapter< my_list<Base*> > base_ptr_list; + typedef ptr_container_adapter< my_list<Value*> > value_ptr_list; + + typedef_test< base_ptr_list, Derived_class >(); + typedef_test< value_ptr_list, Value >(); + +// reversible_container_test< base_ptr_list, Base, Derived_class >(); +// reversible_container_test< value_ptr_list, Value, Value >(); + + base_ptr_list l; + l.push_back( new Derived_class ); + l.push_back( new Derived_class ); + +// algo_test< ptr_list<Value>, Value >(); +// algo_test_polymorphic< ptr_list<Base>, Derived_class >(); +} + +#include <boost/test/included/unit_test_framework.hpp> + +using boost::unit_test_framework::test_suite; + +test_suite* init_unit_test_suite( int argc, char* argv[] ) +{ + test_suite* test = BOOST_TEST_SUITE( "Pointer Container Test Suite" ); + + test->add( BOOST_TEST_CASE( &test_container_adapter ) ); + + return test; +} + + + diff --git a/libs/ptr_container/test/ptr_deque.cpp b/libs/ptr_container/test/ptr_deque.cpp new file mode 100644 index 0000000000..d76e555d33 --- /dev/null +++ b/libs/ptr_container/test/ptr_deque.cpp @@ -0,0 +1,55 @@ +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +#include <boost/test/unit_test.hpp> +#include "sequence_test_data.hpp" +#include <boost/ptr_container/ptr_deque.hpp> + +void test_ptr_deque() +{ + reversible_container_test< ptr_deque<Base>, Base, Derived_class >(); + reversible_container_test< ptr_deque<Value>, Value, Value >(); + reversible_container_test< ptr_deque< nullable<Base> >, Base, Derived_class >(); + reversible_container_test< ptr_deque< nullable<Value> >, Value, Value >(); + + container_assignment_test< ptr_deque<Base>, ptr_deque<Derived_class>, + Derived_class>(); + container_assignment_test< ptr_deque< nullable<Base> >, + ptr_deque< nullable<Derived_class> >, + Derived_class>(); + container_assignment_test< ptr_deque< nullable<Base> >, + ptr_deque<Derived_class>, + Derived_class>(); + container_assignment_test< ptr_deque<Base>, + ptr_deque< nullable<Derived_class> >, + Derived_class>(); + + test_transfer< ptr_deque<Derived_class>, ptr_deque<Base>, Derived_class>(); + + random_access_algorithms_test< ptr_deque<int> >(); + ptr_deque<int> di; + di.push_front( new int(0) ); + BOOST_CHECK_EQUAL( di.size(), 1u ); + di.push_front( std::auto_ptr<int>( new int(1) ) ); + BOOST_CHECK_EQUAL( di.size(), 2u ); +} + +using boost::unit_test::test_suite; + +test_suite* init_unit_test_suite( int argc, char* argv[] ) +{ + test_suite* test = BOOST_TEST_SUITE( "Pointer Container Test Suite" ); + + test->add( BOOST_TEST_CASE( &test_ptr_deque ) ); + + return test; +} + diff --git a/libs/ptr_container/test/ptr_inserter.cpp b/libs/ptr_container/test/ptr_inserter.cpp new file mode 100644 index 0000000000..a15cac5c2c --- /dev/null +++ b/libs/ptr_container/test/ptr_inserter.cpp @@ -0,0 +1,93 @@ +//
+// Boost.Pointer Container
+//
+// Copyright Thorsten Ottosen 2008. Use, modification and
+// distribution is subject to the Boost Software License, Version
+// 1.0. (See accompanying file LICENSE_1_0.txt or copy at
+// http://www.boost.org/LICENSE_1_0.txt)
+//
+// For more information, see http://www.boost.org/libs/ptr_container/
+//
+
+#include <boost/ptr_container/ptr_inserter.hpp>
+#include <boost/ptr_container/indirect_fun.hpp>
+#include <boost/ptr_container/ptr_deque.hpp>
+#include <boost/ptr_container/ptr_list.hpp>
+#include <boost/assign/list_inserter.hpp>
+#include <boost/iterator/transform_iterator.hpp>
+#include <boost/test/test_tools.hpp>
+#include <algorithm>
+#include <functional>
+#include <string>
+
+template< class T >
+struct caster_to
+{
+ typedef T result_type;
+
+ T operator()( void* obj ) const
+ {
+ return static_cast<T>( obj );
+ }
+};
+
+template< class PtrSequence >
+void test_ptr_inserter_helper()
+{
+ using namespace boost;
+ PtrSequence seq;
+ const int size = 1000;
+ for( int i = 0; i != size; ++i )
+ seq.push_back( i % 3 == 0 ? 0 : new int(i) );
+
+ PtrSequence seq2;
+ //
+ // @remark: we call .base() to avoid null pointer indirection.
+ // The clone_inserter will handle the nulls correctly.
+ //
+ std::copy( boost::make_transform_iterator( seq.begin().base(), caster_to<int*>() ),
+ boost::make_transform_iterator( seq.end().base(), caster_to<int*>() ),
+ ptr_container::ptr_back_inserter( seq2 ) );
+
+ std::copy( boost::make_transform_iterator( seq.begin().base(), caster_to<int*>() ),
+ boost::make_transform_iterator( seq.end().base(), caster_to<int*>() ),
+ ptr_container::ptr_front_inserter( seq2 ) );
+ BOOST_CHECK_EQUAL( seq.size()*2, seq2.size() );
+
+ PtrSequence seq3;
+ for( int i = 0; i != size; ++i )
+ seq3.push_back( new int(i%3) );
+
+ //
+ // @remark: since there are no nulls in this container, it
+ // is easier to handle.
+ //
+ std::copy( seq3.begin(), seq3.end(),
+ ptr_container::ptr_inserter( seq, seq.end() ) );
+ BOOST_CHECK_EQUAL( seq.size(), seq2.size() );
+}
+
+
+void test_ptr_inserter()
+{
+ test_ptr_inserter_helper< boost::ptr_list< boost::nullable<int> > >();
+ test_ptr_inserter_helper< boost::ptr_deque< boost::nullable<int> > >();
+
+
+}
+
+
+
+#include <boost/test/unit_test.hpp>
+using boost::unit_test::test_suite;
+
+test_suite* init_unit_test_suite( int argc, char* argv[] )
+{
+ test_suite* test = BOOST_TEST_SUITE( "Pointer Container Test Suite" );
+
+ test->add( BOOST_TEST_CASE( &test_ptr_inserter ) );
+
+ return test;
+}
+
+
diff --git a/libs/ptr_container/test/ptr_list.cpp b/libs/ptr_container/test/ptr_list.cpp new file mode 100644 index 0000000000..f75016ba6a --- /dev/null +++ b/libs/ptr_container/test/ptr_list.cpp @@ -0,0 +1,67 @@ +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +#define PTR_LIST_TEST 1 +#define PTR_CONTAINER_DEBUG 0 + +#include <boost/test/unit_test.hpp> +#include "sequence_test_data.hpp" +#include <boost/ptr_container/ptr_list.hpp> + +void test_list() +{ + + reversible_container_test< ptr_list<Base>, Base, Derived_class >(); + reversible_container_test< ptr_list<Value>, Value, Value >(); + reversible_container_test< ptr_list< nullable<Base> >, Base, Derived_class >(); + reversible_container_test< ptr_list< nullable<Value> >, Value, Value >(); + + container_assignment_test< ptr_list<Base>, ptr_list<Derived_class>, + Derived_class>(); + container_assignment_test< ptr_list< nullable<Base> >, + ptr_list< nullable<Derived_class> >, + Derived_class>(); + container_assignment_test< ptr_list< nullable<Base> >, + ptr_list<Derived_class>, + Derived_class>(); + container_assignment_test< ptr_list<Base>, + ptr_list< nullable<Derived_class> >, + Derived_class>(); + + test_transfer< ptr_list<Derived_class>, ptr_list<Base>, Derived_class>(); + + random_access_algorithms_test< ptr_list<int> >(); + ptr_list<int> list; + list.push_back( new int(0) ); + list.push_back( new int(2) ); + list.push_back( new int(1) ); + list.push_front( new int(3) ); + list.push_front( std::auto_ptr<int>( new int(42) ) ); + list.reverse(); + +} + + + +using boost::unit_test::test_suite; + +test_suite* init_unit_test_suite( int argc, char* argv[] ) +{ + test_suite* test = BOOST_TEST_SUITE( "Pointer Container Test Suite" ); + + test->add( BOOST_TEST_CASE( &test_list ) ); + + return test; +} + + + + diff --git a/libs/ptr_container/test/ptr_map.cpp b/libs/ptr_container/test/ptr_map.cpp new file mode 100644 index 0000000000..9b5cc70903 --- /dev/null +++ b/libs/ptr_container/test/ptr_map.cpp @@ -0,0 +1,431 @@ +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +#include "test_data.hpp" +#include <boost/test/unit_test.hpp> +#include <boost/ptr_container/exception.hpp> +#include <boost/range/sub_range.hpp> +#include <boost/cast.hpp> +#include <cstdlib> +#include <iostream> +#include <memory> +#include <string> + +// +// abstract base class definition +// +struct abstract_base +{ + virtual ~abstract_base() {} + virtual void foo() = 0; + virtual abstract_base* clone() const = 0; +}; + +struct implementation : abstract_base +{ + implementation() + { } + + implementation( const implementation& ) + { } + + implementation( int, std::string, int, std::string ) + { } + + virtual void foo() {} + virtual abstract_base* clone() const + { + return new implementation( *this ); + } +}; + +inline std::ostream& operator<<( std::ostream& out, const abstract_base& r ) +{ + return out; +} + +inline abstract_base* new_clone( const abstract_base& r ) +{ + return r.clone(); +} + +// +// ptr_map test +// + +template< typename C, typename B, typename T > +void ptr_map_test(); + +template< class Key > +Key get_next_key( const Key& k ); + +template<> +int get_next_key<int>( const int& ) +{ + return rand(); +} + +template<> +std::string get_next_key<std::string>( const std::string& ) +{ + return boost::lexical_cast<std::string>( rand() ); +} + + +template< typename C, typename B, typename T > +void ptr_map_test() +{ + using namespace boost; + + BOOST_MESSAGE( "starting associative container test" ); + enum { max_cnt = 10, size = 100 }; + C c; + BOOST_CHECK( c.size() == 0 ); + + const C c2( c.begin(), c.end() ); + BOOST_CHECK( c.size() == c2.size() ); + + C c3; + + BOOST_MESSAGE( "finished construction test" ); + + BOOST_DEDUCED_TYPENAME C::allocator_type alloc = c.get_allocator(); + BOOST_DEDUCED_TYPENAME C::iterator i = c.begin(); + BOOST_DEDUCED_TYPENAME C::const_iterator ci = c2.begin(); + BOOST_DEDUCED_TYPENAME C::iterator i2 = c.end(); + BOOST_DEDUCED_TYPENAME C::const_iterator ci2 = c2.begin(); + BOOST_DEDUCED_TYPENAME C::reverse_iterator ri = c.rbegin(); + BOOST_DEDUCED_TYPENAME C::const_reverse_iterator cri = c2.rbegin(); + BOOST_DEDUCED_TYPENAME C::reverse_iterator rv2 = c.rend(); + BOOST_DEDUCED_TYPENAME C::const_reverse_iterator cvr2 = c2.rend(); + + BOOST_DEDUCED_TYPENAME C::key_type a_key; + + BOOST_MESSAGE( "finished iterator test" ); + + BOOST_DEDUCED_TYPENAME C::size_type s = c.size(); + BOOST_DEDUCED_TYPENAME C::size_type s2 = c.max_size(); + hide_warning(s2); + BOOST_CHECK_EQUAL( c.size(), s ); + bool b = c.empty(); + hide_warning(b); + BOOST_MESSAGE( "finished accessors test" ); + + a_key = get_next_key( a_key ); + c.insert( a_key, new T ); + a_key = get_next_key( a_key ); + c.insert( a_key, new T ); + c3.insert( c.begin(), c.end() ); + c.insert( c3 ); + c.erase( c.begin() ); + BOOST_CHECK( c3.end() == c3.erase( boost::make_iterator_range(c3) ) ); + c3.erase( a_key ); + + BOOST_CHECK( c3.empty() ); + c.swap( c3 ); + swap(c,c3); + swap(c3,c); + BOOST_CHECK( !c3.empty() ); + c3.clear(); + BOOST_CHECK( c3.empty() ); + BOOST_MESSAGE( "finished modifiers test" ); + + + a_key = get_next_key( a_key ); + c.insert( a_key, new T ); + a_key = get_next_key( a_key ); + c.insert( a_key, std::auto_ptr<T>( new T ) ); + typename C::auto_type ptr2 = c.release( c.begin() ); + std::auto_ptr<C> ap = c.release(); + c = c2.clone(); + BOOST_MESSAGE( "finished release/clone test" ); + + + a_key = get_next_key( a_key ); + c3.insert( a_key, new T ); + a_key = get_next_key( a_key ); + c3.insert( a_key, new T ); + + c. BOOST_NESTED_TEMPLATE transfer<C>( c3.begin(), c3 ); + c. BOOST_NESTED_TEMPLATE transfer<C>( c3.begin(), c3.end(), c3 ); + BOOST_CHECK( c3.empty() ); + BOOST_CHECK( !c.empty() ); + c3. BOOST_NESTED_TEMPLATE transfer<C>( c ); + BOOST_CHECK( !c3.empty() ); + BOOST_CHECK( c.empty() ); +#ifdef BOOST_NO_SFINAE +#else + c. BOOST_NESTED_TEMPLATE transfer<C>( make_iterator_range(c3), c3 ); + BOOST_CHECK( !c.empty() ); + BOOST_CHECK( c3.empty() ); + c3. BOOST_NESTED_TEMPLATE transfer<C>(c); +#endif + BOOST_MESSAGE( "finished transfer test" ); + + BOOST_CHECK( !c3.empty() ); + c3.replace( c3.begin(), new T ); + c3.replace( c3.begin(), std::auto_ptr<T>( new T ) ); + BOOST_MESSAGE( "finished set/map interface test" ); + + // @todo: make macro with algorithms so that the right erase() is called. + // c.unique(); + // c.unique( std::not_equal_to<T>() ); + // c.remove( T() ); + // c.remove_if( std::binder1st< std::equal_to<T> >( T() ) ); + + sub_range<C> sub; + sub_range<const C> csub; + + i = c.find( get_next_key( a_key ) ); + ci = c2.find( get_next_key( a_key ) ); + c2.count( get_next_key( a_key ) ); + i = c.lower_bound( get_next_key( a_key ) ); + ci = c2.lower_bound( get_next_key( a_key ) ); + i = c.upper_bound( get_next_key( a_key ) ); + ci = c2.upper_bound( get_next_key( a_key ) ); + sub = c.equal_range( get_next_key( a_key ) ); + csub = c2.equal_range( get_next_key( a_key ) ); + + try + { + c.at( get_next_key( a_key ) ); + } + catch( const bad_ptr_container_operation& ) + { } + + try + { + c2.at( get_next_key( a_key ) ); + } + catch( const bad_ptr_container_operation& ) + { } + + BOOST_MESSAGE( "finished algorithms interface test" ); + + typename C::iterator it = c.begin(), e = c.end(); + for( ; it != e; ++it ) + { + std::cout << "\n mapped value = " << *it->second << " key = " << it->first; + //std::cout << "\n mapped value = " << it.value() << " key = " << it.key(); + } + + typename C::reverse_iterator rit = c.rbegin(), re = c.rend(); + for( ; rit != re; ++rit ) + { + std::cout << "\n mapped value = " << *rit->second << " key = " << rit->first; + //std::cout << "\n mapped value = " << rit.value() << " key = " << rit.key(); + //std::cout << "\n mapped value (base) = " + // << rit.base().value() << " key = " << rit.base().key(); + } + + typename C::const_reverse_iterator crit = c2.rbegin(), cre = c2.rend(); + for( ; crit != cre; ++crit ) + { + std::cout << "\n mapped value = " << *(*crit).second << " key = " << (*crit).first; + //std::cout << "\n mapped value = " << crit.value() << " key = " << crit.key(); + //std::cout << "\n mapped value (base) = " + // << crit.base().value() << " key = " << crit.base().key(); + } + + BOOST_MESSAGE( "finished iterator test" ); + + a_key = get_next_key( a_key ); + c.insert( a_key, new T ); + c.erase( a_key ); + c.erase( a_key ); + +} + + + +template< class CDerived, class CBase, class T > +void test_transfer() +{ + CDerived from; + CBase to; + + int key = get_next_key( key ); + from.insert( key, new T ); + key = get_next_key( key ); + from.insert( key, new T ); + transfer_test( from, to ); +} + + + +template< class BaseContainer, class DerivedContainer, class Derived > +void map_container_assignment_test() +{ + DerivedContainer derived; + std::string foo( "foo" ); + std::string bar( "foo" ); + derived.insert( foo, new Derived ); + derived.insert( bar, new Derived ); + + BaseContainer base_container( derived ); + BOOST_CHECK_EQUAL( derived.size(), base_container.size() ); + base_container.clear(); + base_container = derived; + BOOST_CHECK_EQUAL( derived.size(), base_container.size() ); + + BaseContainer base2( base_container ); + BOOST_CHECK_EQUAL( base2.size(), base_container.size() ); + base2 = base_container; + BOOST_CHECK_EQUAL( base2.size(), base_container.size() ); + base_container = base_container; +} + + + +#include <boost/ptr_container/ptr_map.hpp> + +using namespace std; + +void test_map() +{ + ptr_map_test< ptr_map<int, Base>, Base, Derived_class >(); + ptr_map_test< ptr_map<int, Value>, Value, Value >(); + ptr_map_test< ptr_map<int, nullable<Base> >, Base, Derived_class >(); + ptr_map_test< ptr_map<int, nullable<Value> >, Value, Value >(); + ptr_map_test< ptr_map<int, abstract_base>, abstract_base, implementation >(); + + ptr_map_test< ptr_multimap<int,Base>, Base, Derived_class >(); + ptr_map_test< ptr_multimap<int,Value>, Value, Value >(); + ptr_map_test< ptr_multimap<int, nullable<Base> >, Base, Derived_class >(); + ptr_map_test< ptr_multimap<int, nullable<Value> >, Value, Value >(); + + map_container_assignment_test< ptr_map<std::string,Base>, + ptr_map<std::string,Derived_class>, + Derived_class>(); + map_container_assignment_test< ptr_map<std::string, nullable<Base> >, + ptr_map<std::string,Derived_class>, + Derived_class>(); + map_container_assignment_test< ptr_map<std::string, nullable<Base> >, + ptr_map<std::string, nullable<Derived_class> >, + Derived_class>(); + map_container_assignment_test< ptr_multimap<std::string,Base>, + ptr_multimap<std::string,Derived_class>, + Derived_class>(); + map_container_assignment_test< ptr_multimap<std::string, nullable<Base> >, + ptr_multimap<std::string,Derived_class>, + Derived_class>(); + map_container_assignment_test< ptr_multimap<std::string, nullable<Base> >, + ptr_multimap<std::string, nullable<Derived_class> >, + Derived_class>(); + + + test_transfer< ptr_map<int,Derived_class>, ptr_map<int,Base>, Derived_class >(); + test_transfer< ptr_multimap<int,Derived_class>, ptr_multimap<int,Base>, Derived_class >(); + + string joe = "joe"; + string brian = "brian"; + string kenny = "kenny"; + + ptr_map<string,int> m; + m.insert( joe, new int( 4 ) ); + m.insert( brian, new int( 6 ) ); + BOOST_CHECK( m[ "foo" ] == 0 ); + m[ "bar" ] += 5; + BOOST_CHECK( m[ "bar" ] == 5 ); + m[ joe ] += 56; + m[ brian ] += 10; + + BOOST_CHECK_THROW( (m.insert(kenny, 0 )), bad_ptr_container_operation ); + BOOST_CHECK_THROW( (m.replace(m.begin(), 0 )), bad_ptr_container_operation ); + BOOST_CHECK_THROW( (m.at("not there")), bad_ptr_container_operation ); + + for( ptr_map<string,int>::iterator i = m.begin(); + i != m.end(); ++i ) + { + if( is_null(i) ) + BOOST_CHECK( false ); + const string& ref = i->first; + hide_warning(ref); + int& ref2 = *(*i).second; + ref2++; + } + + typedef ptr_map<string,Derived_class> map_type; + map_type m2; + m2.insert( joe, new Derived_class ); + // + // This works fine since 'm2' is not const + // + m2.begin()->second->foo(); + + // + // These all return an implementation-defined proxy + // with two public members: 'first' and 'second' + // + map_type::value_type a_value = *m2.begin(); + a_value.second->foo(); + map_type::reference a_reference = *m2.begin(); + a_reference.second->foo(); + map_type::const_reference a_creference = *const_begin(m2); + + // + // + // These will fail as iterators propagate constness + // + //a_creference.second->foo(); + //a_cpointer->second->foo(); + //const_begin(m2)->second->foo(); + +} + +#include <boost/tuple/tuple.hpp> +#include <boost/iterator/zip_iterator.hpp> +#include <map> +#include <boost/ptr_container/ptr_map.hpp> + +void test_map_iterators() +{ + using boost::zip_iterator; + using boost::tuple; + using boost::make_tuple; + using boost::ptr_map; + using std::map; + + //typedef map<int, int> theMapType; + /* + @remark: the following will not compile + because of the proxy (non-reference) returned by operator*() + of the ptr_map's iterator type. + + typedef boost::ptr_map<int, int> theMapType; + typedef zip_iterator + <tuple<theMapType::iterator, theMapType::iterator> > zipIter; + theMapType map1; + theMapType map2; + zipIter zip(make_tuple(map1.begin(), map2.begin())); + */ +} + + + +using boost::unit_test::test_suite; + +test_suite* init_unit_test_suite( int argc, char* argv[] ) +{ + test_suite* test = BOOST_TEST_SUITE( "Pointer Container Test Suite" ); + + test->add( BOOST_TEST_CASE( &test_map ) ); + test->add( BOOST_TEST_CASE( &test_map_iterators ) ); + + return test; +} + + + + + + + diff --git a/libs/ptr_container/test/ptr_map_adapter.cpp b/libs/ptr_container/test/ptr_map_adapter.cpp new file mode 100644 index 0000000000..ba94c97c9f --- /dev/null +++ b/libs/ptr_container/test/ptr_map_adapter.cpp @@ -0,0 +1,80 @@ +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +#include "test_data.hpp" +#include <boost/ptr_container/ptr_map.hpp> +#include <string> + +using namespace std; + +void test_ptr_map_adapter() +{ + //typedef_test< ptr_map<int, Base>, Derived >(); + //typedef_test< ptr_map<int, Value>, Value >(); + + //associative_container_test< ptr_map<int, Base>, Base, Derived >(); + //associative_container_test< ptr_map<int, Value>, Value, Value >(); + + //typedef_test< ptr_multimap<int, Base>, Derived >(); + //typedef_test< ptr_multimap<int, Value>, Value >(); + + //associative_container_test< ptr_multimap<int, Base>, Base, Derived >(); + //associative_container_test< ptr_multimap<int, Value>, Value, Value >(); + + string joe = "joe"; + string brian = "brian"; + + ptr_map<string,int> m; + m.insert( joe, new int( 4 ) ); + m.insert( brian, std::auto_ptr<int>( new int( 6 ) ) ); + m[ joe ] += 56; + m[ brian ] += 10; + + try + { + m[ "hans" ] = 4; + } + catch( const bad_ptr_container_operation& ) + { } + + ptr_map<string,int> m2; + m2.insert( m2.begin(), *m.begin() ); + BOOST_CHECK( m != m2 ); + BOOST_CHECK( m2 < m ); + m2.insert( m2.begin(), joe, new int(5) ); + BOOST_CHECK( m != m2 ); + BOOST_CHECK( m2 > m ); + + ptr_multimap<string,int> m3; + m3.insert( m3.begin(), *m.begin() ); + BOOST_CHECK( m3.size() == 1u ); + m3.insert( m3.begin(), brian, new int(11 ) ); + BOOST_CHECK( m3.size() == 2u ); +} + + +#include <boost/test/included/unit_test_framework.hpp> + +using boost::unit_test_framework::test_suite; + +test_suite* init_unit_test_suite( int argc, char* argv[] ) +{ + test_suite* test = BOOST_TEST_SUITE( "Pointer Container Test Suite" ); + + test->add( BOOST_TEST_CASE( &test_ptr_map_adapter ) ); + + return test; +} + + + + + diff --git a/libs/ptr_container/test/ptr_set.cpp b/libs/ptr_container/test/ptr_set.cpp new file mode 100644 index 0000000000..dcc9ea77e7 --- /dev/null +++ b/libs/ptr_container/test/ptr_set.cpp @@ -0,0 +1,111 @@ +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +#include <boost/test/unit_test.hpp> +#include "associative_test_data.hpp" +#include <boost/ptr_container/ptr_set.hpp> + +template< class SetDerived, class SetBase, class T > +void test_transfer() +{ + SetBase to; + SetDerived from; + from.insert( new T ); + from.insert( new T ); + transfer_test( from, to ); +} + +template< class BaseContainer, class DerivedContainer, class Derived > +void test_copy() +{ + DerivedContainer derived; + derived.insert( new Derived ); + derived.insert( new Derived ); + + BaseContainer base( derived ); + BOOST_CHECK_EQUAL( derived.size(), base.size() ); + base.clear(); + base = derived; + BOOST_CHECK_EQUAL( derived.size(), base.size() ); + base = base; +} + + + +template< class PtrSet > +void test_erase() +{ + PtrSet s; + typedef typename PtrSet::key_type T; + + T t; + T* t2 = t.clone(); + s.insert ( new T ); + s.insert ( t2 ); + s.insert ( new T ); + BOOST_CHECK_EQUAL( s.size(), 3u ); + BOOST_CHECK_EQUAL( t, *t2 ); + BOOST_CHECK( ! (t < *t2) ); + BOOST_CHECK( ! (*t2 < t) ); + BOOST_CHECK_EQUAL( t, *t2 ); + + unsigned n = s.erase( t ); + BOOST_CHECK( n > 0 ); +} + + + +void test_set() +{ + srand( 0 ); + ptr_set_test< ptr_set<Base>, Base, Derived_class, true >(); + ptr_set_test< ptr_set<Value>, Value, Value, true >(); + + ptr_set_test< ptr_multiset<Base>, Base, Derived_class, true >(); + ptr_set_test< ptr_multiset<Value>, Value, Value, true >(); + + test_copy< ptr_set<Base>, ptr_set<Derived_class>, + Derived_class>(); + test_copy< ptr_multiset<Base>, ptr_multiset<Derived_class>, + Derived_class>(); + + test_transfer< ptr_set<Derived_class>, ptr_set<Base>, Derived_class>(); + test_transfer< ptr_multiset<Derived_class>, ptr_multiset<Base>, Derived_class>(); + + ptr_set<int> set; + + BOOST_CHECK_THROW( set.insert( 0 ), bad_ptr_container_operation ); + set.insert( new int(0) ); + std::auto_ptr<int> ap( new int(1) ); + set.insert( ap ); + BOOST_CHECK_THROW( (set.replace(set.begin(), 0 )), bad_ptr_container_operation ); + BOOST_CHECK_THROW( (set.replace(set.begin(), std::auto_ptr<int>(0) )), bad_ptr_container_operation ); + + test_erase< ptr_set<Base> >(); + test_erase< ptr_multiset<Base> >(); +} + +using boost::unit_test::test_suite; + +test_suite* init_unit_test_suite( int argc, char* argv[] ) +{ + test_suite* test = BOOST_TEST_SUITE( "Pointer Container Test Suite" ); + + test->add( BOOST_TEST_CASE( &test_set ) ); + + return test; +} + + + + + + diff --git a/libs/ptr_container/test/ptr_unordered_map.cpp b/libs/ptr_container/test/ptr_unordered_map.cpp new file mode 100644 index 0000000000..5685a162e7 --- /dev/null +++ b/libs/ptr_container/test/ptr_unordered_map.cpp @@ -0,0 +1,406 @@ +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2008. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +#include "test_data.hpp" +#include <boost/test/unit_test.hpp> +#include <boost/ptr_container/exception.hpp> +#include <boost/range/sub_range.hpp> +#include <boost/cast.hpp> +#include <cstdlib> +#include <iostream> +#include <memory> +#include <string> + +// +// abstract base class definition +// +struct abstract_base +{ + virtual ~abstract_base() {} + virtual void foo() = 0; + virtual abstract_base* clone() const = 0; +}; + +struct implementation : abstract_base +{ + implementation() + { } + + implementation( const implementation& ) + { } + + implementation( int, std::string, int, std::string ) + { } + + virtual void foo() {} + virtual abstract_base* clone() const + { + return new implementation( *this ); + } +}; + +inline std::ostream& operator<<( std::ostream& out, const abstract_base& r ) +{ + return out; +} + +inline abstract_base* new_clone( const abstract_base& r ) +{ + return r.clone(); +} + +inline std::size_t hash_value( const abstract_base& b ) +{ + return boost::hash_value( &b ); +} + +// +// ptr_map test +// + +template< typename C, typename B, typename T > +void ptr_map_test(); + +template< class Key > +Key get_next_key( const Key& k ); + +template<> +int get_next_key<int>( const int& ) +{ + return rand(); +} + +template<> +std::string get_next_key<std::string>( const std::string& ) +{ + return boost::lexical_cast<std::string>( rand() ); +} + + + +template< typename C, typename B, typename T > +void ptr_map_test() +{ + using namespace boost; + + BOOST_MESSAGE( "starting associative container test" ); + enum { max_cnt = 10, size = 100 }; + C c; + BOOST_CHECK( c.size() == 0 ); + + const C c2( c.begin(), c.end() ); + BOOST_CHECK( c.size() == c2.size() ); + + C c3; + + BOOST_MESSAGE( "finished construction test" ); + + BOOST_DEDUCED_TYPENAME C::allocator_type alloc = c.get_allocator(); + BOOST_DEDUCED_TYPENAME C::iterator i = c.begin(); + BOOST_DEDUCED_TYPENAME C::const_iterator ci = c2.begin(); + BOOST_DEDUCED_TYPENAME C::iterator i2 = c.end(); + BOOST_DEDUCED_TYPENAME C::const_iterator ci2 = c2.begin(); + ci = c.cbegin(); + ci = c.cend(); + + BOOST_DEDUCED_TYPENAME C::key_type a_key; + + BOOST_MESSAGE( "finished iterator test" ); + + BOOST_DEDUCED_TYPENAME C::size_type s = c.size(); + BOOST_DEDUCED_TYPENAME C::size_type s2 = c.max_size(); + hide_warning(s2); + BOOST_CHECK_EQUAL( c.size(), s ); + bool b = c.empty(); + hide_warning(b); + BOOST_MESSAGE( "finished accessors test" ); + + a_key = get_next_key( a_key ); + c.insert( a_key, new T ); + a_key = get_next_key( a_key ); + c.insert( a_key, new T ); + c3.insert( c.begin(), c.end() ); + c.insert( c3 ); + c.erase( c.begin() ); + BOOST_CHECK( c3.end() == c3.erase( boost::make_iterator_range(c3) ) ); + c3.erase( a_key ); + + BOOST_CHECK( c3.empty() ); + c.swap( c3 ); + swap(c,c3); + swap(c3,c); + BOOST_CHECK( !c3.empty() ); + c3.clear(); + BOOST_CHECK( c3.empty() ); + BOOST_MESSAGE( "finished modifiers test" ); + + + a_key = get_next_key( a_key ); + c.insert( a_key, new T ); + a_key = get_next_key( a_key ); + c.insert( a_key, std::auto_ptr<T>( new T ) ); + typename C::auto_type ptr2 = c.release( c.begin() ); + std::auto_ptr<C> ap = c.release(); + c = c2.clone(); + BOOST_MESSAGE( "finished release/clone test" ); + + + a_key = get_next_key( a_key ); + c3.insert( a_key, new T ); + a_key = get_next_key( a_key ); + c3.insert( a_key, new T ); + + c. BOOST_NESTED_TEMPLATE transfer<C>( c3.begin(), c3 ); + c. BOOST_NESTED_TEMPLATE transfer<C>( c3.begin(), c3.end(), c3 ); + BOOST_CHECK( c3.empty() ); + BOOST_CHECK( !c.empty() ); + c3. BOOST_NESTED_TEMPLATE transfer<C>( c ); + BOOST_CHECK( !c3.empty() ); + BOOST_CHECK( c.empty() ); +#ifdef BOOST_NO_SFINAE +#else + c. BOOST_NESTED_TEMPLATE transfer<C>( make_iterator_range(c3), c3 ); + BOOST_CHECK( !c.empty() ); + BOOST_CHECK( c3.empty() ); + c3. BOOST_NESTED_TEMPLATE transfer<C>(c); +#endif + BOOST_MESSAGE( "finished transfer test" ); + + BOOST_CHECK( !c3.empty() ); + c3.replace( c3.begin(), new T ); + c3.replace( c3.begin(), std::auto_ptr<T>( new T ) ); + BOOST_MESSAGE( "finished set/map interface test" ); + + // @todo: make macro with algorithms so that the right erase() is called. + // c.unique(); + // c.unique( std::not_equal_to<T>() ); + // c.remove( T() ); + // c.remove_if( std::binder1st< std::equal_to<T> >( T() ) ); + + sub_range<C> sub; + sub_range<const C> csub; + + i = c.find( get_next_key( a_key ) ); + ci = c2.find( get_next_key( a_key ) ); + c2.count( get_next_key( a_key ) ); + sub = c.equal_range( get_next_key( a_key ) ); + csub = c2.equal_range( get_next_key( a_key ) ); + + try + { + c.at( get_next_key( a_key ) ); + } + catch( const bad_ptr_container_operation& ) + { } + + try + { + c2.at( get_next_key( a_key ) ); + } + catch( const bad_ptr_container_operation& ) + { } + + BOOST_MESSAGE( "finished algorithms interface test" ); + + typename C::iterator it = c.begin(), e = c.end(); + for( ; it != e; ++it ) + { + std::cout << "\n mapped value = " << *it->second << " key = " << it->first; + //std::cout << "\n mapped value = " << it.value() << " key = " << it.key(); + } + + BOOST_MESSAGE( "finished iterator test" ); + + a_key = get_next_key( a_key ); + c.insert( a_key, new T ); + c.erase( a_key ); + c.erase( a_key ); + +} + + + +template< class CDerived, class CBase, class T > +void test_transfer() +{ + CDerived from; + CBase to; + + int key = get_next_key( key ); + from.insert( key, new T ); + key = get_next_key( key ); + from.insert( key, new T ); + transfer_test( from, to ); +} + + + +template< class BaseContainer, class DerivedContainer, class Derived > +void map_container_assignment_test() +{ + DerivedContainer derived; + std::string foo( "foo" ); + std::string bar( "foo" ); + derived.insert( foo, new Derived ); + derived.insert( bar, new Derived ); + + BaseContainer base_container( derived ); + BOOST_CHECK_EQUAL( derived.size(), base_container.size() ); + base_container.clear(); + base_container = derived; + BOOST_CHECK_EQUAL( derived.size(), base_container.size() ); + + BaseContainer base2( base_container ); + BOOST_CHECK_EQUAL( base2.size(), base_container.size() ); + base2 = base_container; + BOOST_CHECK_EQUAL( base2.size(), base_container.size() ); + base_container = base_container; +} + + + +template< class Cont, class Key, class T > +void test_unordered_interface() +{ + Cont c; + T* t = new T; + Key key = get_next_key( key ); + c.insert( key, t ); + typename Cont::local_iterator i = c.begin( 0 ); + typename Cont::const_local_iterator ci = i; + ci = c.cbegin( 0 ); + i = c.end( 0 ); + ci = c.cend( 0 ); + typename Cont::size_type s = c.bucket_count(); + s = c.max_bucket_count(); + s = c.bucket_size( 0 ); + s = c.bucket( key ); + float f = c.load_factor(); + f = c.max_load_factor(); + c.max_load_factor(f); + c.rehash(1000); +} + +#include <boost/ptr_container/ptr_unordered_map.hpp> + +using namespace std; + +void test_map() +{ + ptr_map_test< ptr_unordered_map<int, Base>, Base, Derived_class >(); + ptr_map_test< ptr_unordered_map<int, Value>, Value, Value >(); + ptr_map_test< ptr_unordered_map<int, nullable<Base> >, Base, Derived_class >(); + ptr_map_test< ptr_unordered_map<int, nullable<Value> >, Value, Value >(); + ptr_map_test< ptr_unordered_map<int, abstract_base>, abstract_base, implementation >(); + + ptr_map_test< ptr_unordered_multimap<int,Base>, Base, Derived_class >(); + ptr_map_test< ptr_unordered_multimap<int,Value>, Value, Value >(); + ptr_map_test< ptr_unordered_multimap<int, nullable<Base> >, Base, Derived_class >(); + ptr_map_test< ptr_unordered_multimap<int, nullable<Value> >, Value, Value >(); + + map_container_assignment_test< ptr_unordered_map<std::string,Base>, + ptr_unordered_map<std::string,Derived_class>, + Derived_class>(); + map_container_assignment_test< ptr_unordered_map<std::string, nullable<Base> >, + ptr_unordered_map<std::string,Derived_class>, + Derived_class>(); + map_container_assignment_test< ptr_unordered_map<std::string, nullable<Base> >, + ptr_unordered_map<std::string, nullable<Derived_class> >, + Derived_class>(); + map_container_assignment_test< ptr_unordered_multimap<std::string,Base>, + ptr_unordered_multimap<std::string,Derived_class>, + Derived_class>(); + map_container_assignment_test< ptr_unordered_multimap<std::string, nullable<Base> >, + ptr_unordered_multimap<std::string,Derived_class>, + Derived_class>(); + map_container_assignment_test< ptr_unordered_multimap<std::string, nullable<Base> >, + ptr_unordered_multimap<std::string, nullable<Derived_class> >, + Derived_class>(); + + + test_transfer< ptr_unordered_map<int,Derived_class>, ptr_unordered_map<int,Base>, Derived_class >(); + test_transfer< ptr_unordered_multimap<int,Derived_class>, ptr_unordered_multimap<int,Base>, Derived_class >(); + + string joe = "joe"; + string brian = "brian"; + string kenny = "kenny"; + + ptr_unordered_map<string,int> m; + m.insert( joe, new int( 4 ) ); + m.insert( brian, new int( 6 ) ); + BOOST_CHECK( m[ "foo" ] == 0 ); + m[ "bar" ] += 5; + BOOST_CHECK( m[ "bar" ] == 5 ); + m[ joe ] += 56; + m[ brian ] += 10; + + BOOST_CHECK_THROW( (m.insert(kenny, 0 )), bad_ptr_container_operation ); + BOOST_CHECK_THROW( (m.replace(m.begin(), 0 )), bad_ptr_container_operation ); + BOOST_CHECK_THROW( (m.at("not there")), bad_ptr_container_operation ); + + for( ptr_unordered_map<string,int>::iterator i = m.begin(); + i != m.end(); ++i ) + { + if( is_null(i) ) + BOOST_CHECK( false ); + const string& ref = i->first; + hide_warning(ref); + int& ref2 = *(*i).second; + ref2++; + } + + typedef ptr_unordered_map<string,Derived_class> map_type; + map_type m2; + m2.insert( joe, new Derived_class ); + // + // This works fine since 'm2' is not const + // + m2.begin()->second->foo(); + + // + // These all return an implementation-defined proxy + // with two public members: 'first' and 'second' + // + map_type::value_type a_value = *m2.begin(); + a_value.second->foo(); + map_type::reference a_reference = *m2.begin(); + a_reference.second->foo(); + map_type::const_reference a_creference = *const_begin(m2); + + // + // + // These will fail as iterators propagate constness + // + //a_creference.second->foo(); + //a_cpointer->second->foo(); + //const_begin(m2)->second->foo(); + + test_unordered_interface< ptr_unordered_map<string,Base>, string, Derived_class >(); + test_unordered_interface< ptr_unordered_map<string,Base>, string, Derived_class >(); +} + +using boost::unit_test::test_suite; + +test_suite* init_unit_test_suite( int argc, char* argv[] ) +{ + test_suite* test = BOOST_TEST_SUITE( "Pointer Container Test Suite" ); + + test->add( BOOST_TEST_CASE( &test_map ) ); + + return test; +} + + + + + + + diff --git a/libs/ptr_container/test/ptr_unordered_set.cpp b/libs/ptr_container/test/ptr_unordered_set.cpp new file mode 100644 index 0000000000..0476945292 --- /dev/null +++ b/libs/ptr_container/test/ptr_unordered_set.cpp @@ -0,0 +1,136 @@ +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +#include <boost/test/unit_test.hpp> +#include "associative_test_data.hpp" +#include <boost/ptr_container/ptr_unordered_set.hpp> + +template< class SetDerived, class SetBase, class T > +void test_transfer() +{ + SetBase to; + SetDerived from; + from.insert( new T ); + from.insert( new T ); + transfer_test( from, to ); +} + +template< class BaseContainer, class DerivedContainer, class Derived > +void test_copy() +{ + DerivedContainer derived; + derived.insert( new Derived ); + derived.insert( new Derived ); + + BaseContainer base( derived ); + BOOST_CHECK_EQUAL( derived.size(), base.size() ); + base.clear(); + base = derived; + BOOST_CHECK_EQUAL( derived.size(), base.size() ); + base = base; +} + +template< class Cont, class T > +void test_unordered_interface() +{ + Cont c; + T* t = new T; + c.insert( t ); + typename Cont::local_iterator i = c.begin( 0 ); + typename Cont::const_local_iterator ci = i; + ci = c.cbegin( 0 ); + i = c.end( 0 ); + ci = c.cend( 0 ); + typename Cont::size_type s = c.bucket_count(); + s = c.max_bucket_count(); + s = c.bucket_size( 0 ); + s = c.bucket( *t ); + float f = c.load_factor(); + f = c.max_load_factor(); + c.max_load_factor(f); + c.rehash(1000); +} + + + +template< class PtrSet > +void test_erase() +{ + PtrSet s; + typedef typename PtrSet::key_type T; + + T t; + s.insert ( new T ); + T* t2 = t.clone(); + s.insert ( t2 ); + s.insert ( new T ); + BOOST_CHECK_EQUAL( s.size(), 3u ); + BOOST_CHECK_EQUAL( hash_value(t), hash_value(*t2) ); + BOOST_CHECK_EQUAL( t, *t2 ); + + typename PtrSet::iterator i = s.find( t ); + + BOOST_CHECK( i != s.end() ); + unsigned n = s.erase( t ); + BOOST_CHECK( n > 0 ); +} + + + +void test_set() +{ + srand( 0 ); + ptr_set_test< ptr_unordered_set<Base>, Base, Derived_class, false >(); + ptr_set_test< ptr_unordered_set<Value>, Value, Value, false >(); + + ptr_set_test< ptr_unordered_multiset<Base>, Base, Derived_class, false >(); + ptr_set_test< ptr_unordered_multiset<Value>, Value, Value, false >(); + + test_copy< ptr_unordered_set<Base>, ptr_unordered_set<Derived_class>, + Derived_class>(); + test_copy< ptr_unordered_multiset<Base>, ptr_unordered_multiset<Derived_class>, + Derived_class>(); + + test_transfer< ptr_unordered_set<Derived_class>, ptr_unordered_set<Base>, Derived_class>(); + test_transfer< ptr_unordered_multiset<Derived_class>, ptr_unordered_multiset<Base>, Derived_class>(); + + ptr_unordered_set<int> set; + + BOOST_CHECK_THROW( set.insert( 0 ), bad_ptr_container_operation ); + set.insert( new int(0) ); + std::auto_ptr<int> ap( new int(1) ); + set.insert( ap ); + BOOST_CHECK_THROW( (set.replace(set.begin(), 0 )), bad_ptr_container_operation ); + BOOST_CHECK_THROW( (set.replace(set.begin(), std::auto_ptr<int>(0) )), bad_ptr_container_operation ); + + test_unordered_interface< ptr_unordered_set<Base>, Derived_class >(); + test_unordered_interface< ptr_unordered_multiset<Base>, Derived_class >(); + + test_erase< ptr_unordered_set<Base> >(); + test_erase< ptr_unordered_multiset<Base> >(); +} + +using boost::unit_test::test_suite; + +test_suite* init_unit_test_suite( int argc, char* argv[] ) +{ + test_suite* test = BOOST_TEST_SUITE( "Pointer Container Test Suite" ); + + test->add( BOOST_TEST_CASE( &test_set ) ); + + return test; +} + + + + + + diff --git a/libs/ptr_container/test/ptr_vector.cpp b/libs/ptr_container/test/ptr_vector.cpp new file mode 100644 index 0000000000..bf8b6a3a32 --- /dev/null +++ b/libs/ptr_container/test/ptr_vector.cpp @@ -0,0 +1,106 @@ +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +#include <boost/test/unit_test.hpp> +#include "sequence_test_data.hpp" +#include <boost/ptr_container/ptr_vector.hpp> +#include <boost/ptr_container/ptr_list.hpp> +#include <boost/assign/list_inserter.hpp> + +void test_ptr_vector() +{ + reversible_container_test< ptr_vector<Base>, Base, Derived_class >(); + reversible_container_test< ptr_vector<Value>, Value, Value >(); + +#ifdef BOOST_NO_SFINAE +#else + reversible_container_test< ptr_vector< nullable<Base> >, Base, Derived_class >(); + reversible_container_test< ptr_vector< nullable<Value> >, Value, Value >(); +#endif + + container_assignment_test< ptr_vector<Base>, ptr_vector<Derived_class>, + Derived_class>(); + container_assignment_test< ptr_vector< nullable<Base> >, + ptr_vector< nullable<Derived_class> >, + Derived_class>(); + container_assignment_test< ptr_vector< nullable<Base> >, + ptr_vector<Derived_class>, + Derived_class>(); + container_assignment_test< ptr_vector<Base>, + ptr_vector< nullable<Derived_class> >, + Derived_class>(); + + test_transfer< ptr_vector<Derived_class>, ptr_vector<Base>, Derived_class>(); + test_transfer< ptr_vector<Derived_class>, ptr_list<Base>, Derived_class>(); + + random_access_algorithms_test< ptr_vector<int> >(); + + + ptr_vector<int> vec( 100u ); + BOOST_CHECK( vec.capacity() >= 100u ); + +#ifdef BOOST_PTR_CONTAINER_NO_EXCEPTIONS +#else + + BOOST_CHECK_THROW( vec.push_back(0), bad_ptr_container_operation ); + BOOST_CHECK_THROW( (vec.insert( vec.begin(), 0 )), bad_ptr_container_operation ); + BOOST_CHECK_THROW( vec.at( 42 ), bad_ptr_container_operation ); + vec.push_back( new int(0) ); + BOOST_CHECK_THROW( (vec.replace(10u, new int(0))), bad_ptr_container_operation ); + BOOST_CHECK_THROW( (vec.replace(0u, 0)), bad_ptr_container_operation ); + BOOST_CHECK_THROW( (vec.replace(vec.begin(), 0 )), bad_ptr_container_operation ); + +#endif + + vec.clear(); + assign::push_back( vec )( new int(2) ) + ( new int(4) ) + ( new int(6) ) + ( new int(8) ); + ptr_vector<int> vec2; + assign::push_back( vec2 ) + ( new int(1) ) + ( new int(3) ) + ( new int(5) ) + ( new int(7) ); + BOOST_CHECK_EQUAL( vec.size(), vec2.size() ); + BOOST_CHECK( vec > vec2 ); + BOOST_CHECK( vec != vec2 ); + BOOST_CHECK( !(vec == vec2) ); + BOOST_CHECK( vec2 < vec ); + BOOST_CHECK( vec2 <= vec ); + BOOST_CHECK( vec >= vec2 ); + + const int data_size = 10; + int** array = new int*[data_size]; + for( int i = 0; i != data_size; ++i ) + array[i] = new int(i); + + vec.transfer( vec.begin(), array, data_size ); + int** array2 = vec.c_array(); + BOOST_CHECK( array2 != array ); + +} + +using boost::unit_test::test_suite; + +test_suite* init_unit_test_suite( int argc, char* argv[] ) +{ + test_suite* test = BOOST_TEST_SUITE( "Pointer Container Test Suite" ); + + test->add( BOOST_TEST_CASE( &test_ptr_vector ) ); + + return test; +} + + + + diff --git a/libs/ptr_container/test/ptr_vector_size.cpp b/libs/ptr_container/test/ptr_vector_size.cpp new file mode 100644 index 0000000000..7d48fcf302 --- /dev/null +++ b/libs/ptr_container/test/ptr_vector_size.cpp @@ -0,0 +1,26 @@ +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +#include <boost/ptr_container/ptr_vector.hpp> + +template class +boost::ptr_vector<int>; + +template class +boost::ptr_vector<short>; + +template class +boost::ptr_vector<char>; + +template class +boost::ptr_vector<char*>; + + diff --git a/libs/ptr_container/test/sequence_test_data.hpp b/libs/ptr_container/test/sequence_test_data.hpp new file mode 100644 index 0000000000..e9cf873221 --- /dev/null +++ b/libs/ptr_container/test/sequence_test_data.hpp @@ -0,0 +1,301 @@ +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +#include "test_data.hpp" +#include <boost/range/iterator_range.hpp> +#include <boost/bind.hpp> + +template< typename C, typename B, typename T > +void reversible_container_test(); + +template< class IntContainer > +void algorithms_test(); + +template< typename C, typename B, typename T > +void reversible_container_test() +{ + using namespace boost; + + BOOST_MESSAGE( "starting reversible container test" ); + enum { max_cnt = 10, size = 100 }; + C c; + set_capacity<C>()( c ); + BOOST_CHECK( c.size() == 0 ); + c.push_back( new T ); + BOOST_CHECK( c.size() == 1 ); + + const C c2_dummy( c.begin(), c.end() ); + BOOST_CHECK_EQUAL( c2_dummy.size(), c.size() ); + const C c2( c.clone() ); + BOOST_CHECK_EQUAL( c2.size(), c.size() ); + + C c3( c.begin(), c.end() ); + set_capacity<C>()( c3 ); + BOOST_CHECK_EQUAL( c.size(), c3.size() ); + + c.assign( c3.begin(), c3.end() ); + BOOST_CHECK_EQUAL( c.size(), c3.size() ); + + c.assign( c3 ); + set_capacity<C>()( c ); + BOOST_MESSAGE( "finished construction test" ); + + C a_copy( c ); + BOOST_CHECK_EQUAL( a_copy.size(), c.size() ); + a_copy = a_copy; + BOOST_CHECK_EQUAL( a_copy.size(), c.size() ); + a_copy.clear(); + a_copy = a_copy; + BOOST_CHECK( a_copy.empty() ); + BOOST_CHECK( !c.empty() ); + BOOST_MESSAGE( "finished copying test" ); + + BOOST_DEDUCED_TYPENAME C::allocator_type alloc = c.get_allocator(); + hide_warning(alloc); + BOOST_DEDUCED_TYPENAME C::iterator i = c.begin(); + BOOST_DEDUCED_TYPENAME C::const_iterator ci = c2.begin(); + BOOST_DEDUCED_TYPENAME C::iterator i2 = c.end(); + BOOST_DEDUCED_TYPENAME C::const_iterator ci2 = c2.begin(); + BOOST_DEDUCED_TYPENAME C::reverse_iterator ri = c.rbegin(); + BOOST_DEDUCED_TYPENAME C::const_reverse_iterator cri = c2.rbegin(); + BOOST_DEDUCED_TYPENAME C::reverse_iterator rv2 = c.rend(); + BOOST_DEDUCED_TYPENAME C::const_reverse_iterator cvr2 = c2.rend(); + i = c.rbegin().base(); + ci = c2.rbegin().base(); + i = c.rend().base(); + ci = c2.rend().base(); + BOOST_CHECK_EQUAL( std::distance( c.rbegin(), c.rend() ), + std::distance( c.begin(), c.end() ) ); + + BOOST_MESSAGE( "finished iterator test" ); + + BOOST_DEDUCED_TYPENAME C::size_type s = c.size(); + hide_warning(s); + BOOST_DEDUCED_TYPENAME C::size_type s2 = c.max_size(); + hide_warning(s2); + c.push_back( new T ); + c.push_back( std::auto_ptr<T>( new T ) ); + bool b = c.empty(); + BOOST_CHECK( !c.empty() ); + b = is_null( c.begin() ); + BOOST_CHECK( b == false ); + BOOST_DEDUCED_TYPENAME C::reference r = c.front(); + hide_warning(r); + BOOST_DEDUCED_TYPENAME C::const_reference cr = c2.front(); + hide_warning(cr); + BOOST_DEDUCED_TYPENAME C::reference r2 = c.back(); + hide_warning(r2); + BOOST_DEDUCED_TYPENAME C::const_reference cr2 = c2.back(); + hide_warning(cr2); + BOOST_MESSAGE( "finished accessors test" ); + + c.push_back( new T ); + BOOST_CHECK_EQUAL( c.size(), 4u ); + + c.pop_back(); + BOOST_CHECK( !c.empty() ); + c.insert( c.end(), new T ); + std::auto_ptr<T> ap(new T); + c.insert( c.end(), ap ); + BOOST_CHECK_EQUAL( c.size(), 5u ); + +#if defined(BOOST_NO_SFINAE) || defined(BOOST_NO_FUNCTION_TEMPLATE_ORDERING) +#else + c.insert( c.end(), c3 ); +#endif + c3.insert( c3.end(), c.begin(), c.end() ); + c.erase( c.begin() ); + c3.erase( c3.begin(), c3.end() ); + c3.erase( boost::make_iterator_range(c3) ); + BOOST_CHECK( c3.empty() ); + BOOST_CHECK( !c.empty() ); + c.swap( c3 ); + BOOST_CHECK( !c3.empty() ); + c3.clear(); + BOOST_CHECK( c3.empty() ); + C c4; + c4.swap(c3); +#ifdef BOOST_NO_SFINAE +#else + swap(c4,c3); +#endif + BOOST_MESSAGE( "finished modifiers test" ); + + c.push_back( new T ); c.push_back( new T ); c.push_back( new T ); + typedef BOOST_DEDUCED_TYPENAME C::auto_type auto_type; + +#ifdef BOOST_NO_SFINAE +#else + auto_type ptr = c.release( c.begin() ); +#endif + std::auto_ptr<C> ap2 = c.release(); + c = c2.clone(); + BOOST_CHECK( !c.empty() ); + auto_type ptr2 = c.replace( c.begin(), new T ); + ptr2 = c.replace( c.begin(), std::auto_ptr<T>( new T ) ); + BOOST_MESSAGE( "finished release/clone/replace test" ); + + c3.push_back( new T ); + c3.push_back( new T ); + c3.push_back( new T ); + c. BOOST_NESTED_TEMPLATE transfer<C>( c.begin(), c3.begin(), c3 ); + c. BOOST_NESTED_TEMPLATE transfer<C>( c.end(), c3.begin(), c3.end(), c3 ); +#ifdef BOOST_NO_SFINAE +#else + c. BOOST_NESTED_TEMPLATE transfer<C>( c.end(), boost::make_iterator_range( c3 ), c3 ); + BOOST_CHECK( c3.empty() ); + BOOST_CHECK( !c.empty() ); +#endif + c3. BOOST_NESTED_TEMPLATE transfer<C>( c3.begin(), c ); + BOOST_CHECK( !c3.empty() ); + BOOST_CHECK( c.empty() ); + BOOST_MESSAGE( "finished transfer test" ); + + c3.resize( 0u ); + BOOST_CHECK( c3.empty() ); + c3.resize( 10u ); + BOOST_CHECK_EQUAL( c3.size(), 10u ); + c3.resize( 12u, &*c3.begin() ); + BOOST_CHECK_EQUAL( c3.size(), 12u ); + BOOST_MESSAGE( "finished resize test" ); + +} + + + +template< class CDerived, class CBase, class T > +void test_transfer() +{ + BOOST_MESSAGE( "starting transfer test" ); + CDerived from; + CBase to; + + set_capacity<CDerived>()( from ); + set_capacity<CBase>()( to ); + + from.push_back( new T ); + from.push_back( new T ); + to. BOOST_NESTED_TEMPLATE transfer<CDerived>( to.end(), from ); + BOOST_MESSAGE( "finished transfer test" ); +} + + + +#include <boost/assign/list_inserter.hpp> +#include <iostream> + +template< class Compare, class C > +bool is_sorted( const C& c ) +{ + if( c.size() < 2 ) + return true; + + typename C::const_iterator prev = c.begin(), + e = c.end(), + next = prev; + Compare pred; + for( ; next != e ; ) + { + prev = next; + ++next; + + if( next == c.end() ) + return true; + + if( !pred(*prev,*next) ) + return false; + } + return true; +} + + + + +struct equal_to_int +{ + int i_; + + equal_to_int( int i ) : i_(i) + { } + + bool operator()( int i ) const + { + return i_ == i; + } +}; + + +template< class IntContainer > +void random_access_algorithms_test() +{ + BOOST_MESSAGE( "starting random accessors algorithms test" ); + + IntContainer c; + set_capacity<IntContainer>()( c ); + assign::push_back( c ) + ( new int(1) ) + ( new int(3) ) + ( new int(6) ) + ( new int(7) ) + ( new int(2) ) + ( new int(2) ) + ( new int(0) ) + ( new int(6) ) + ( new int(3) ); + c.sort(); + BOOST_CHECK( is_sorted< std::less_equal<int> >( c ) ); + BOOST_CHECK_EQUAL( c.size(), 9u ); + + c.unique(); + BOOST_CHECK_EQUAL( c.size(), 6u ); +#ifdef PTR_LIST_TEST + BOOST_CHECK( c.front() == 0 ); + BOOST_CHECK( c.back() == 7 ); +#else + BOOST_CHECK( c[0] == 0 ); + BOOST_CHECK( c[1] == 1 ); + BOOST_CHECK( c[2] == 2 ); + BOOST_CHECK( c[3] == 3 ); + BOOST_CHECK( c[4] == 6 ); + BOOST_CHECK( c[5] == 7 ); +#endif + + c.erase_if( equal_to_int(1) ); + BOOST_CHECK_EQUAL( c.size(), 5u ); +#ifdef PTR_LIST_TEST + BOOST_CHECK_EQUAL( c.front(), 0 ); +#else + BOOST_CHECK_EQUAL( c[0], 0 ); + BOOST_CHECK_EQUAL( c[1], 2 ); +#endif + + c.erase_if( equal_to_int(7) ); + BOOST_CHECK_EQUAL( c.size(), 4u ); + BOOST_CHECK_EQUAL( c.back(), 6 ); + + // C = [0,2,3,6] + + IntContainer c2; + set_capacity<IntContainer>()( c2 ); + assign::push_back( c2 ) + ( new int(-1) ) + ( new int(1) ) + ( new int(4) ) + ( new int(5) ) + ( new int(7) ); + BOOST_CHECK( c2.size() == 5u ); + c.merge( c2 ); + BOOST_CHECK( c2.empty() ); + BOOST_CHECK( c.size() == 9u ); + BOOST_CHECK( is_sorted< std::less_equal<int> >( c ) ); + BOOST_MESSAGE( "finished random accessors algorithms test" ); +} + diff --git a/libs/ptr_container/test/serialization.cpp b/libs/ptr_container/test/serialization.cpp new file mode 100644 index 0000000000..546e2a3d85 --- /dev/null +++ b/libs/ptr_container/test/serialization.cpp @@ -0,0 +1,335 @@ +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +#include <boost/config.hpp> +#ifdef BOOST_MSVC +#pragma warning( disable: 4996 ) +#endif + +#include <boost/test/unit_test.hpp> +#include <boost/archive/text_oarchive.hpp> +#include <boost/archive/text_iarchive.hpp> +#include <boost/archive/xml_iarchive.hpp> +#include <boost/archive/xml_oarchive.hpp> +#include <boost/functional/hash.hpp> +#include <boost/ptr_container/ptr_container.hpp> +#include <boost/ptr_container/serialize_ptr_container.hpp> +#include <boost/serialization/export.hpp> +#include <boost/serialization/base_object.hpp> +#include <boost/serialization/utility.hpp> +#include <boost/serialization/string.hpp> +#include <fstream> +#include <string> + +// +// serialization helper: we can't save a non-const object +// +template< class T > +inline T const& as_const( T const& r ) +{ + return r; +} + +// +// used to customize tests for circular_buffer +// +template< class Cont > +struct set_capacity +{ + void operator()( Cont& ) const + { } +}; + +template<class T> +struct set_capacity< boost::ptr_circular_buffer<T> > +{ + void operator()( boost::ptr_circular_buffer<T>& c ) const + { + c.set_capacity( 100u ); + } +}; + +// +// class hierarchy +// +struct Base +{ + friend class boost::serialization::access; + + int i; + + + template< class Archive > + void serialize( Archive& ar, const unsigned int /*version*/ ) + { + ar & boost::serialization::make_nvp( "i", i ); + } + + Base() : i(42) + { } + + Base( int i ) : i(i) + { } + + virtual ~Base() + { } +}; + +inline bool operator<( const Base& l, const Base& r ) +{ + return l.i < r.i; +} + +inline bool operator==( const Base& l, const Base& r ) +{ + return l.i == r.i; +} + +inline std::size_t hash_value( const Base& b ) +{ + return boost::hash_value( b.i ); +} + +struct Derived : Base +{ + int i2; + + template< class Archive > + void serialize( Archive& ar, const unsigned int /*version*/ ) + { + ar & boost::serialization::make_nvp( "Base", + boost::serialization::base_object<Base>( *this ) ); + ar & boost::serialization::make_nvp( "i2", i2 ); + } + + Derived() : Base(42), i2(42) + { } + + explicit Derived( int i2 ) : Base(0), i2(i2) + { } +}; + +BOOST_CLASS_EXPORT_GUID( Derived, "Derived" ) + +// +// test of containers +// +// + +template< class C, class T > +void add( C& c, T* r, unsigned /*n*/ ) +{ + c.insert( c.end(), r ); +} + +template< class U, class T > +void add( boost::ptr_array<U,2>& c, T* r, unsigned n ) +{ + c.replace( n, r ); +} + +template< class Cont, class OArchive, class IArchive > +void test_serialization_helper() +{ + Cont vec; + set_capacity<Cont>()( vec ); + add( vec, new Base( -1 ), 0u ); + add( vec, new Derived( 1 ), 1u ); + BOOST_CHECK_EQUAL( vec.size(), 2u ); + + std::ofstream ofs("filename"); + OArchive oa(ofs); + oa << boost::serialization::make_nvp( "container", as_const(vec) ); + ofs.close(); + + + std::ifstream ifs("filename", std::ios::binary); + IArchive ia(ifs); + Cont vec2; + ia >> boost::serialization::make_nvp( "container", vec2 ); + ifs.close(); + + BOOST_CHECK_EQUAL( vec.size(), vec2.size() ); + BOOST_CHECK_EQUAL( (*vec2.begin()).i, -1 ); + BOOST_CHECK_EQUAL( (*++vec2.begin()).i, 0 ); + + typename Cont::iterator i = vec2.begin(); + ++i; + Derived* d = dynamic_cast<Derived*>( &*i ); + BOOST_CHECK_EQUAL( d->i2, 1 ); + +} + +template< class Cont, class OArchive, class IArchive > +void test_serialization_unordered_set_helper() +{ + Cont vec; + set_capacity<Cont>()( vec ); + add( vec, new Base( -1 ), 0u ); + add( vec, new Derived( 1 ), 1u ); + BOOST_CHECK_EQUAL( vec.size(), 2u ); + + std::ofstream ofs("filename"); + OArchive oa(ofs); + oa << boost::serialization::make_nvp( "container", as_const(vec) ); + ofs.close(); + + + std::ifstream ifs("filename", std::ios::binary); + IArchive ia(ifs); + Cont vec2; + ia >> boost::serialization::make_nvp( "container", vec2 ); + ifs.close(); + + BOOST_CHECK_EQUAL( vec.size(), vec2.size() ); + BOOST_CHECK_EQUAL( (*vec2.begin()).i, 0 ); + BOOST_CHECK_EQUAL( (*++vec2.begin()).i, -1 ); +} + +template< class Map, class OArchive, class IArchive > +void test_serialization_map_helper() +{ + Map m; + std::string key1("key1"), key2("key2"); + m.insert( key1, new Base( -1 ) ); + m.insert( key2, new Derived( 1 ) ); + BOOST_CHECK_EQUAL( m.size(), 2u ); + + std::ofstream ofs("filename"); + OArchive oa(ofs); + oa << boost::serialization::make_nvp( "container", as_const(m) ); + ofs.close(); + + + std::ifstream ifs("filename", std::ios::binary); + IArchive ia(ifs); + Map m2; + ia >> boost::serialization::make_nvp( "container", m2 ); + ifs.close(); + + BOOST_CHECK_EQUAL( m.size(), m2.size() ); + BOOST_CHECK_EQUAL( m2.find(key1)->second->i, -1 ); + BOOST_CHECK_EQUAL( m2.find(key2)->second->i, 0 ); + + typename Map::iterator i = m2.find(key2); + Derived* d = dynamic_cast<Derived*>( i->second ); + BOOST_CHECK_EQUAL( d->i2, 1 ); +} + +// +// basic test of hierarchy +// +void test_hierarchy() +{ + Base* p = new Derived(); + std::ofstream ofs("filename"); + boost::archive::text_oarchive oa(ofs); + oa << as_const(p); + ofs.close(); + + + Base* d = 0; + std::ifstream ifs("filename", std::ios::binary); + boost::archive::text_iarchive ia(ifs); + ia >> d; + ifs.close(); + + BOOST_CHECK_EQUAL( p->i, d->i ); + BOOST_CHECK( p != d ); + BOOST_CHECK( dynamic_cast<Derived*>( d ) ); + delete p; + delete d; +} + +// +// test initializer +// +void test_serialization() +{ + test_hierarchy(); + test_serialization_helper< boost::ptr_deque<Base>, + boost::archive::text_oarchive, + boost::archive::text_iarchive >(); + test_serialization_helper< boost::ptr_list<Base>, + boost::archive::text_oarchive, + boost::archive::text_iarchive>(); + test_serialization_helper< boost::ptr_vector<Base>, + boost::archive::text_oarchive, + boost::archive::text_iarchive>(); + test_serialization_helper< boost::ptr_vector<Base>, + boost::archive::xml_oarchive, + boost::archive::xml_iarchive>(); + test_serialization_helper< boost::ptr_circular_buffer<Base>, + boost::archive::text_oarchive, + boost::archive::text_iarchive>(); + test_serialization_helper< boost::ptr_circular_buffer<Base>, + boost::archive::xml_oarchive, + boost::archive::xml_iarchive>(); + test_serialization_helper< boost::ptr_array<Base,2>, + boost::archive::text_oarchive, + boost::archive::text_iarchive>(); + test_serialization_helper< boost::ptr_set<Base>, + boost::archive::text_oarchive, + boost::archive::text_iarchive>(); + test_serialization_helper< boost::ptr_multiset<Base>, + boost::archive::text_oarchive, + boost::archive::text_iarchive>(); + + test_serialization_unordered_set_helper< boost::ptr_unordered_set<Base>, + boost::archive::text_oarchive, + boost::archive::text_iarchive>(); + test_serialization_unordered_set_helper<boost::ptr_unordered_multiset<Base>, + boost::archive::text_oarchive, + boost::archive::text_iarchive>(); + + test_serialization_map_helper< boost::ptr_map<std::string,Base>, + boost::archive::text_oarchive, + boost::archive::text_iarchive>(); + test_serialization_map_helper< boost::ptr_multimap<std::string,Base>, + boost::archive::text_oarchive, + boost::archive::text_iarchive>(); + + test_serialization_map_helper< boost::ptr_map<std::string,Base>, + boost::archive::xml_oarchive, + boost::archive::xml_iarchive>(); + test_serialization_map_helper< boost::ptr_multimap<std::string,Base>, + boost::archive::xml_oarchive, + boost::archive::xml_iarchive>(); + + test_serialization_map_helper< boost::ptr_unordered_map<std::string,Base>, + boost::archive::text_oarchive, + boost::archive::text_iarchive>(); + test_serialization_map_helper< boost::ptr_unordered_multimap<std::string,Base>, + boost::archive::text_oarchive, + boost::archive::text_iarchive>(); + + test_serialization_map_helper< boost::ptr_unordered_map<std::string,Base>, + boost::archive::xml_oarchive, + boost::archive::xml_iarchive>(); + test_serialization_map_helper< boost::ptr_unordered_multimap<std::string,Base>, + boost::archive::xml_oarchive, + boost::archive::xml_iarchive>(); + +} + + +using boost::unit_test::test_suite; + +test_suite* init_unit_test_suite( int argc, char* argv[] ) +{ + test_suite* test = BOOST_TEST_SUITE( "Pointer Container Test Suite" ); + + test->add( BOOST_TEST_CASE( &test_serialization ) ); + + return test; +} + + diff --git a/libs/ptr_container/test/simple_test.cpp b/libs/ptr_container/test/simple_test.cpp new file mode 100644 index 0000000000..bdd6711189 --- /dev/null +++ b/libs/ptr_container/test/simple_test.cpp @@ -0,0 +1,106 @@ +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +#include <boost/ptr_container/ptr_vector.hpp> +#include <boost/shared_ptr.hpp> +#include <boost/lambda/lambda.hpp> +#include <algorithm> + +using namespace std; + +// +// A simple polymorphic class +// +class Poly +{ + int i_; + static int cnt_; + +public: + Poly() : i_( cnt_++ ) { } + virtual ~Poly() { } + void foo() { doFoo(); } + +private: + virtual void doFoo() { ++i_; } + +public: + friend inline bool operator>( const Poly& l, const Poly r ) + { + return l.i_ > r.i_; + } +}; + +int Poly::cnt_ = 0; + +// +// Normally we need something like this to compare pointers to objects +// +template< typename T > +struct sptr_greater +{ + bool operator()( const boost::shared_ptr<T>& l, const boost::shared_ptr<T>& r ) const + { + return *l > *r; + } +}; + +// +// one doesn't need to introduce new names or live with long ones +// +typedef boost::shared_ptr<Poly> PolyPtr; + + +void simple_test() +{ + enum { size = 2000 }; + typedef vector<PolyPtr> vector_t; + typedef boost::ptr_vector<Poly> ptr_vector_t; + vector_t svec; + ptr_vector_t pvec; + + for( int i = 0; i < size; ++i ) + { + svec.push_back( PolyPtr( new Poly ) ); + pvec.push_back( new Poly ); // no extra syntax + } + + for( int i = 0; i < size; ++i ) + { + svec[i]->foo(); + pvec[i].foo(); // automatic indirection + svec[i] = PolyPtr( new Poly ); + pvec.replace( i, new Poly ); // direct pointer assignment not possible, original element is deleted + } + + for( vector_t::iterator i = svec.begin(); i != svec.end(); ++i ) + (*i)->foo(); + + for( ptr_vector_t::iterator i = pvec.begin(); i != pvec.end(); ++i ) + i->foo(); // automatic indirection +} + +#include <boost/test/unit_test.hpp> +using boost::unit_test::test_suite; + +test_suite* init_unit_test_suite( int argc, char* argv[] ) +{ + test_suite* test = BOOST_TEST_SUITE( "Pointer Container Test Suite" ); + + test->add( BOOST_TEST_CASE( &simple_test ) ); + + return test; +} + + + + + diff --git a/libs/ptr_container/test/test_data.hpp b/libs/ptr_container/test/test_data.hpp new file mode 100644 index 0000000000..148d78aefd --- /dev/null +++ b/libs/ptr_container/test/test_data.hpp @@ -0,0 +1,326 @@ +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +#include <boost/static_assert.hpp> +#include <boost/type_traits.hpp> +#include <boost/config.hpp> +#include <boost/test/test_tools.hpp> +#include <boost/lexical_cast.hpp> +#include <boost/functional/hash.hpp> +#include <algorithm> +#include <iostream> +#include <string> +#include <utility> +#include <cstdlib> + +using namespace std; +using namespace boost; + +////////////////////////////////////////////////////////////////////////////// +// Test class 1: a class hierarchy +////////////////////////////////////////////////////////////////////////////// + +class Base +{ + Base( const Base& r ) : data1(r.data1), data2(r.data2), + data3(r.data3), data(r.data) + { +#ifdef PTR_CONTAINER_DEBUG + objects++; + std::cout <<"+ " << objects << "\n"; +#endif + } + + Base& operator=( const Base& ); + +public: // for test reasons only + int data1, data2, data3; + string data; + +public: + + Base() : data1(1), data2(2), data3(rand()%256), + data(lexical_cast<string>(rand())) + { +#ifdef PTR_CONTAINER_DEBUG + objects++; + std::cout <<"+ " << objects << "\n"; +#endif + } + + virtual ~Base() + { +#ifdef PTR_CONTAINER_DEBUG + objects--; + std::cout <<"- " << objects << "\n"; + if( objects < 0 ) + terminate(); +#endif + } + + void print( ostream& out ) const { do_print( out); } + Base* clone() const { return do_clone(); } + void foo() { do_foo(); } + + virtual bool less_than( const Base& b ) const + { + return data3 < b.data3; + } + + virtual bool equal( const Base& b ) const + { + return data1 == b.data1 && + data2 == b.data2 && + data3 == b.data3 && + data == b.data; + } + +#ifdef PTR_CONTAINER_DEBUG + static int objects; +#endif + +private: + virtual void do_print( ostream& /*out*/ ) const { }; + virtual Base* do_clone() const { return new Base( *this ); }; + virtual void do_foo() { }; +}; + +#ifdef PTR_CONTAINER_DEBUG +int Base::objects = 0; +#endif + + + +ostream& operator<<( ostream& out, const Base& b ) +{ + b.print( out ); + return out; +} + + +// +// We rely on argument dependent lookup +// for this to be found +// +inline Base* new_clone( const Base& b ) +{ + return b.clone(); +} + + + +inline bool operator<( const Base& l, const Base& r ) +{ + return l.less_than( r ); +} + + + +inline bool operator>( const Base& l, const Base& r ) +{ + return r < l; +} + + + +inline bool operator==( const Base& l, const Base& r ) +{ + return l.equal( r ); +} + + + +inline bool operator!=( const Base& l, const Base& r ) +{ + return !l.equal( r ); +} + + + +inline std::size_t hash_value( const Base& b ) +{ + std::size_t seed = 0; + boost::hash_combine( seed, b.data ); + boost::hash_combine( seed, b.data1 ); + boost::hash_combine( seed, b.data2 ); + boost::hash_combine( seed, b.data3 ); + return seed; +} + + +class Derived_class : public Base +{ +public: // for test reasons only + int i_; + +private: + + virtual void do_print( ostream& out ) const + { + out << i_; + } + + + virtual Base* do_clone() const + { + return new Derived_class; + } + + virtual void do_foo() + { + ++i_; + } + +public: + Derived_class() : i_( rand() ) + { } + + virtual bool less_than( const Base& b ) const + { + const Derived_class& d = dynamic_cast<const Derived_class&>( b ); + return i_ < d.i_; + } +}; + + + +inline std::size_t hash_value( const Derived_class& b ) +{ + std::size_t seed = hash_value( static_cast<const Base&>( b ) ); + boost::hash_combine( seed, b.i_ ); + return seed; +} + +////////////////////////////////////////////////////////////////////////////// +// Test class 2: a value class +////////////////////////////////////////////////////////////////////////////// + +class Value +{ +public: // for test reasons only + string s_; + +public: + + Value() : s_( boost::lexical_cast<string>( rand() ) ) + {} + + ~Value() { /** debug code here */ } + + string name() const + { + return s_; + } +}; + + + +inline bool operator<( const Value& l, const Value& r ) +{ + return l.name() < r.name(); +} + + + +inline bool operator>( const Value& l, const Value& r ) +{ + return l.name() > r.name(); +} + + + +inline bool operator==( const Value& l, const Value& r ) +{ + return l.name() == r.name(); +} + + + +inline bool operator!=( const Value& l, const Value& r ) +{ + return l.name() != r.name(); +} + + + +inline ostream& operator<<( ostream& out, const Value& v ) +{ + return out << v.name() << " "; +} + + + +inline std::size_t hash_value( const Value& v ) +{ + return boost::hash_value( v.s_ ); +} + +// +// used to hide "unused variable" warnings +// +template< class T > +inline void hide_warning( T& /*r*/ ) +{ } + +// +// used to customize tests for circular_buffer +// +template< class Cont > +struct set_capacity +{ + void operator()( Cont& ) const + { } +}; + +// +// transfer() test +// + +template< class Cont1, class Cont2 > +void transfer_test( Cont1& from, Cont2& to ) +{ + BOOST_MESSAGE( "starting container transfer test" ); + BOOST_CHECK( !from.empty() ); + to. BOOST_NESTED_TEMPLATE transfer<Cont1>( from ); + BOOST_CHECK( !to.empty() ); + BOOST_MESSAGE( "finishing container transfer test" ); +} + + +// +// test of copy operations +// + +template< class BaseContainer, class DerivedContainer, class Derived > +void container_assignment_test() +{ + BOOST_MESSAGE( "starting container assignment test" ); + + DerivedContainer derived; + set_capacity<DerivedContainer>()( derived ); + derived.insert( derived.begin(), new Derived ); + derived.insert( derived.begin(), new Derived ); + + BaseContainer base( derived ); + BOOST_CHECK_EQUAL( derived.size(), base.size() ); + base.clear(); + base = derived; + BOOST_CHECK_EQUAL( derived.size(), base.size() ); + BaseContainer base2( base ); + BOOST_CHECK_EQUAL( base2.size(), base.size() ); + base2 = base; + BOOST_CHECK_EQUAL( base2.size(), base.size() ); + base = base; + + BOOST_MESSAGE( "finished container assignment test" ); +} + + diff --git a/libs/ptr_container/test/tree_test.cpp b/libs/ptr_container/test/tree_test.cpp new file mode 100644 index 0000000000..268052715e --- /dev/null +++ b/libs/ptr_container/test/tree_test.cpp @@ -0,0 +1,279 @@ +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +#include "test_data.hpp" +#include <boost/ptr_container/ptr_vector.hpp> +#include <boost/utility.hpp> +#include <boost/lexical_cast.hpp> +#include <algorithm> +#include <iostream> +#include <cstddef> +#include <string> + +using namespace std; +using namespace boost; + +class node; + +class tree +{ + typedef ptr_vector<node> nodes_t; + nodes_t nodes; + +protected: + void swap( tree& r ) + { nodes.swap( r.nodes ); } + +public: + typedef nodes_t::iterator iterator; + typedef nodes_t::const_iterator const_iterator; + +public: + void add_child( node* n ); + void remove( iterator n ); + void write_tree( ostream& os ) const; + size_t size() const; + node& child( size_t idx ); + const node& child( size_t idx ) const; + iterator child_begin(); + const_iterator child_begin() const; + iterator child_end(); + const_iterator child_end() const; + iterator find( const string& match ); +}; + + + +class node : noncopyable +{ + virtual size_t do_node_size() const = 0; + virtual string do_description() const = 0; + virtual void do_write_value( ostream& os ) const = 0; + +public: + virtual ~node() { } + size_t node_size() const { return do_node_size(); } + string description() const { return do_description(); } + void write_value( ostream& os ) const { do_write_value( os ); } +}; + + + +class inner_node : public node, public tree +{ + string name; + + virtual size_t do_node_size() const + { + return tree::size(); + } + + virtual string do_description() const + { + return lexical_cast<string>( name ); + } + + virtual void do_write_value( ostream& os ) const + { + os << " inner node: " << name; + } + + void swap( inner_node& r ) + { + name.swap( r.name ); + tree::swap( r ); + } + +public: + inner_node() : name("inner node") + { } + + inner_node( const string& r ) : name(r) + { } + + inner_node* release() + { + inner_node* ptr( new inner_node ); + ptr->swap( *this ); + return ptr; + } +}; + + + +template< class T > +class leaf : public node +{ + T data; + + virtual size_t do_node_size() const + { + return 1; + } + + virtual string do_description() const + { + return lexical_cast<string>( data ); + } + + virtual void do_write_value( ostream& os ) const + { + os << " leaf: " << data; + } + +public: + leaf() : data( T() ) + { } + + leaf( const T& r ) : data(r) + { } + + void set_data( const T& r ) + { data = r; } +}; + +///////////////////////////////////////////////////////////////////////// +// tree implementation +///////////////////////////////////////////////////////////////////////// + +inline void tree::add_child( node* n ) +{ + nodes.push_back( n ); +} + +inline void tree::remove( iterator n ) +{ + BOOST_ASSERT( n != nodes.end() ); + nodes.erase( n ); +} + +void tree::write_tree( ostream& os ) const +{ + for( const_iterator i = nodes.begin(), + e = nodes.end(); + i != e; ++i ) + { + i->write_value( os ); + if( const inner_node* p = dynamic_cast<const inner_node*>( &*i ) ) + p->write_tree( os ); + } +} + +size_t tree::size() const +{ + size_t res = 1; + + for( const_iterator i = nodes.begin(), + e = nodes.end(); + i != e; ++i ) + { + res += i->node_size(); + } + + return res; +} + +inline node& tree::child( size_t idx ) +{ + return nodes[idx]; +} + +inline const node& tree::child( size_t idx ) const +{ + return nodes[idx]; +} + +inline tree::iterator tree::child_begin() +{ + return nodes.begin(); +} + +inline tree::const_iterator tree::child_begin() const +{ + return nodes.begin(); +} + +inline tree::iterator tree::child_end() +{ + return nodes.end(); +} + +inline tree::const_iterator tree::child_end() const +{ + return nodes.end(); +} + +tree::iterator tree::find( const string& match ) +{ + for( iterator i = nodes.begin(), + e = nodes.end(); + i != e; ++i ) + { + if( i->description() == match ) + return i; + + if( inner_node* p = dynamic_cast<inner_node*>( &*i ) ) + { + iterator j = p->find( match ); + if( j != p->child_end() ) + return j; + } + + } + + return child_end(); +} + +///////////////////////////////////////////////////////////////////////// +// test case +///////////////////////////////////////////////////////////////////////// + +void test_tree() +{ + tree root; + BOOST_CHECK_EQUAL( root.size(), 1u ); + inner_node node1( "node 1" ); + node1.add_child( new leaf<string>( "leaf 1" ) ); + node1.add_child( new leaf<int>( 42 ) ); + inner_node node2( "node 2" ); + node2.add_child( new leaf<float>( 42.0f ) ); + node2.add_child( new leaf<string>( "leaf 4" ) ); + + root.add_child( node1.release() ); + BOOST_CHECK_EQUAL( root.size(), 4u ); + root.add_child( node2.release() ); + root.add_child( new inner_node( "node 3" ) ); + BOOST_CHECK_EQUAL( root.size(), 8u ); + root.add_child( new leaf<string>( "leaf 5" ) ); + BOOST_CHECK_EQUAL( root.size(), 9u ); + + root.write_tree( cout ); + tree::iterator a_leaf = root.find( "42" ); + BOOST_CHECK_EQUAL( a_leaf->description(), "42" ); + leaf<int>& the_leaf = dynamic_cast< leaf<int>& >( *a_leaf ); + the_leaf.set_data( 2*42 ); + BOOST_CHECK_EQUAL( a_leaf->description(), "84" ); + +} + +#include <boost/test/unit_test.hpp> +using boost::unit_test::test_suite; + +test_suite* init_unit_test_suite( int argc, char* argv[] ) +{ + test_suite* test = BOOST_TEST_SUITE( "Pointer Container Test Suite" ); + + test->add( BOOST_TEST_CASE( &test_tree ) ); + + return test; +} + + diff --git a/libs/ptr_container/test/tut1.cpp b/libs/ptr_container/test/tut1.cpp new file mode 100644 index 0000000000..a66f080183 --- /dev/null +++ b/libs/ptr_container/test/tut1.cpp @@ -0,0 +1,353 @@ +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +// +// This example is intended to get you started. +// Notice how the smart container +// +// 1. takes ownership of objects +// 2. transfers ownership +// 3. applies indirection to iterators +// 4. clones objects from other smart containers +// + +// +// First we select which container to use. +// +#include <boost/ptr_container/ptr_deque.hpp> + +// +// we need these later in the example +// +#include <boost/assert.hpp> +#include <string> +#include <exception> + + +// +// Then we define a small polymorphic class +// hierarchy. +// + +class animal : boost::noncopyable +{ + virtual std::string do_speak() const = 0; + std::string name_; + +protected: + // + // Animals cannot be copied... + // + animal( const animal& r ) : name_( r.name_ ) { } + void operator=( const animal& ); + +private: + // + // ...but due to advances in genetics, we can clone them! + // + + virtual animal* do_clone() const = 0; + +public: + animal( const std::string& name ) : name_(name) { } + virtual ~animal() throw() { } + + std::string speak() const + { + return do_speak(); + } + + std::string name() const + { + return name_; + } + + animal* clone() const + { + return do_clone(); + } +}; + +// +// An animal is still not Clonable. We need this last hook. +// +// Notice that we pass the animal by const reference +// and return by pointer. +// + +animal* new_clone( const animal& a ) +{ + return a.clone(); +} + +// +// We do not need to define 'delete_clone()' since +// since the default is to call the default 'operator delete()'. +// + +const std::string muuuh = "Muuuh!"; +const std::string oiink = "Oiiink"; + +class cow : public animal +{ + virtual std::string do_speak() const + { + return muuuh; + } + + virtual animal* do_clone() const + { + return new cow( *this ); + } + +public: + cow( const std::string& name ) : animal(name) { } +}; + +class pig : public animal +{ + virtual std::string do_speak() const + { + return oiink; + } + + virtual animal* do_clone() const + { + return new pig( *this ); + } + +public: + pig( const std::string& name ) : animal(name) { } +}; + +// +// Then we, of course, need a place to put all +// those animals. +// + +class farm +{ + // + // This is where the smart containers are handy + // + typedef boost::ptr_deque<animal> barn_type; + barn_type barn; + + // + // An error type + // + struct farm_trouble : public std::exception { }; + +public: + // + // We would like to make it possible to + // iterate over the animals in the farm + // + typedef barn_type::iterator animal_iterator; + + // + // We also need to count the farm's size... + // + typedef barn_type::size_type size_type; + + // + // And we also want to transfer an animal + // safely around. The easiest way to think + // about '::auto_type' is to imagine a simplified + // 'std::auto_ptr<T>' ... this means you can expect + // + // T* operator->() + // T* release() + // deleting destructor + // + // but not more. + // + typedef barn_type::auto_type animal_transport; + + // + // Create an empty farm. + // + farm() { } + + // + // We need a constructor that can make a new + // farm by cloning a range of animals. + // + farm( animal_iterator begin, animal_iterator end ) + : + // + // Objects are always cloned before insertion + // unless we explicitly add a pointer or + // use 'release()'. Therefore we actually + // clone all animals in the range + // + barn( begin, end ) { } + + // + // ... so we need some other function too + // + + animal_iterator begin() + { + return barn.begin(); + } + + animal_iterator end() + { + return barn.end(); + } + + // + // Here it is quite ok to have an 'animal*' argument. + // The smart container will handle all ownership + // issues. + // + void buy_animal( animal* a ) + { + barn.push_back( a ); + } + + // + // The farm can also be in economical trouble and + // therefore be in the need to sell animals. + // + animal_transport sell_animal( animal_iterator to_sell ) + { + if( to_sell == end() ) + throw farm_trouble(); + + // + // Here we remove the animal from the barn, + // but the animal is not deleted yet...it's + // up to the buyer to decide what + // to do with it. + // + return barn.release( to_sell ); + } + + // + // How big a farm do we have? + // + size_type size() const + { + return barn.size(); + } + + // + // If things are bad, we might choose to sell all animals :-( + // + std::auto_ptr<barn_type> sell_farm() + { + return barn.release(); + } + + // + // However, if things are good, we might buy somebody + // else's farm :-) + // + + void buy_farm( std::auto_ptr<barn_type> other ) + { + // + // This line inserts all the animals from 'other' + // and is guaranteed either to succeed or to have no + // effect + // + barn.transfer( barn.end(), // insert new animals at the end + *other ); // we want to transfer all animals, + // so we use the whole container as argument + // + // You might think you would have to do + // + // other.release(); + // + // but '*other' is empty and can go out of scope as it wants + // + BOOST_ASSERT( other->empty() ); + } + +}; // class 'farm'. + +int main() +{ + // + // First we make a farm + // + farm animal_farm; + BOOST_ASSERT( animal_farm.size() == 0u ); + + animal_farm.buy_animal( new pig("Betty") ); + animal_farm.buy_animal( new pig("Benny") ); + animal_farm.buy_animal( new pig("Jeltzin") ); + animal_farm.buy_animal( new cow("Hanz") ); + animal_farm.buy_animal( new cow("Mary") ); + animal_farm.buy_animal( new cow("Frederik") ); + BOOST_ASSERT( animal_farm.size() == 6u ); + + // + // Then we make another farm...it will actually contain + // a clone of the other farm. + // + farm new_farm( animal_farm.begin(), animal_farm.end() ); + BOOST_ASSERT( new_farm.size() == 6u ); + + // + // Is it really clones in the new farm? + // + BOOST_ASSERT( new_farm.begin()->name() == "Betty" ); + + // + // Then we search for an animal, Mary (the Crown Princess of Denmark), + // because we would like to buy her ... + // + typedef farm::animal_iterator iterator; + iterator to_sell; + for( iterator i = animal_farm.begin(), + end = animal_farm.end(); + i != end; ++i ) + { + if( i->name() == "Mary" ) + { + to_sell = i; + break; + } + } + + farm::animal_transport mary = animal_farm.sell_animal( to_sell ); + + + if( mary->speak() == muuuh ) + // + // Great, Mary is a cow, and she may live longer + // + new_farm.buy_animal( mary.release() ); + else + // + // Then the animal would be destroyed (!) + // when we go out of scope. + // + ; + + // + // Now we can observe some changes to the two farms... + // + BOOST_ASSERT( animal_farm.size() == 5u ); + BOOST_ASSERT( new_farm.size() == 7u ); + + // + // The new farm has however underestimated how much + // it cost to feed Mary and its owner is forced to sell the farm... + // + animal_farm.buy_farm( new_farm.sell_farm() ); + + BOOST_ASSERT( new_farm.size() == 0u ); + BOOST_ASSERT( animal_farm.size() == 12u ); +} diff --git a/libs/ptr_container/test/tut34.cpp b/libs/ptr_container/test/tut34.cpp new file mode 100644 index 0000000000..0716bde31c --- /dev/null +++ b/libs/ptr_container/test/tut34.cpp @@ -0,0 +1,61 @@ +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +#include <boost/ptr_container/ptr_sequence_adapter.hpp> +#include <vector> +#include <boost/ptr_container/ptr_map_adapter.hpp> +#include <map> + +template< class T > +struct my_ptr_vector : + public boost::ptr_sequence_adapter< std::vector<T*> > +{ + +}; + + +template< class Key, class T, class Pred = std::less<Key>, + class Allocator = std::allocator< std::pair<const Key, T> > > +struct my_map : public std::map<Key,T,Pred,Allocator> +{ + explicit my_map( const Pred& pred = Pred(), + const Allocator& alloc = Allocator() ) + { } +}; + +#include <string> +struct Foo {}; + +typedef boost::ptr_map_adapter< my_map<std::string,Foo*> > foo_map; + +template< class Key, class T, class Pred = std::less<Key> > +struct my_ptr_map : public boost::ptr_map_adapter< std::map<Key,T*,Pred> > +{ + +}; + +typedef my_ptr_map<std::string,Foo> foo_map2; + + +int main() +{ + + my_ptr_vector<Foo> vec; + vec.push_back( new Foo ); + foo_map m1; + foo_map2 m2; + std::string s(""); + m1.insert( s, new Foo ); + m2.insert( s, new Foo ); + + +} + diff --git a/libs/ptr_container/test/view_example.cpp b/libs/ptr_container/test/view_example.cpp new file mode 100644 index 0000000000..f1007c36aa --- /dev/null +++ b/libs/ptr_container/test/view_example.cpp @@ -0,0 +1,168 @@ +// +// Boost.Pointer Container +// +// Copyright Thorsten Ottosen 2003-2005. Use, modification and +// distribution is subject to the Boost Software License, Version +// 1.0. (See accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) +// +// For more information, see http://www.boost.org/libs/ptr_container/ +// + +// +// This example is intended to show you how to +// use the 'view_clone_manager'. The idea +// is that we have a container of non-polymorphic +// objects and want to keep then sorted by different +// criteria at the same time. +// + +// +// We'll go for 'ptr_vector' here. Using a node-based +// container would be a waste of space here. +// All container headers will also include +// the Clone Managers. +// +#include <boost/ptr_container/ptr_vector.hpp> +#include <boost/ptr_container/indirect_fun.hpp> + +#include <functional> // For 'binary_fnuction' +#include <cstdlib> // For 'rand()' +#include <algorithm> // For 'std::sort()' +#include <iostream> // For 'std::cout' + +using namespace std; + +// +// This is our simple example data-structure. It can +// be ordered in three ways. +// +struct photon +{ + photon() : color( rand() ), + direction( rand() ), + power( rand() ) + { } + + int color; + int direction; + int power; +}; + +// +// Our big container is a standard vector +// +typedef std::vector<photon> vector_type; + +// +// Now we define our view type by adding a second template argument. +// The 'view_clone_manager' will implements Cloning by taking address +// of objects. +// +// Notice the first template argument is 'photon' and not +// 'const photon' to allow the view container write access. +// +typedef boost::ptr_vector<photon,boost::view_clone_allocator> view_type; + +// +// Our first sort criterium +// +struct sort_by_color : std::binary_function<photon,photon,bool> +{ + bool operator()( const photon& l, const photon& r ) const + { + return l.color < r.color; + } +}; + +// +// Our second sort criterium +// +struct sort_by_direction : std::binary_function<photon,photon,bool> +{ + bool operator()( const photon& l, const photon& r ) const + { + return l.direction < r.direction; + } +}; + + +// +// Our third sort criterium +// +struct sort_by_power : std::binary_function<photon,photon,bool> +{ + bool operator()( const photon& l, const photon& r ) const + { + return l.power < r.power; + } +}; + +// +// This function inserts "Clones" into the +// the view. +// +// We need to pass the first argument +// as a non-const reference to be able to store +// 'T*' instead of 'const T*' objects. Alternatively, +// we might change the declaration of the 'view_type' +// to +// typedef boost::ptr_vector<const photon,boost::view_clone_manager> +// view_type; ^^^^^^ +// +void insert( vector_type& from, view_type& to ) +{ + to.insert( to.end(), + from.begin(), + from.end() ); +} + +int main() +{ + enum { sz = 10, count = 500 }; + + // + // First we create the main container and two views + // + std::vector<vector_type> photons; + view_type color_view; + view_type direction_view; + + // + // Then we fill the main container with some random data + // + for( int i = 0; i != sz; ++i ) + { + photons.push_back( vector_type() ); + + for( int j = 0; j != count; ++j ) + photons[i].push_back( photon() ); + } + + // + // Then we create the two views. + // + for( int i = 0; i != sz; ++i ) + { + insert( photons[i], color_view ); + insert( photons[i], direction_view ); + } + + // + // First we sort the original photons, using one of + // the view classes. This may sound trivial, but consider that + // the objects are scatered all around 'sz' different vectors; + // the view makes them act as one big vector. + // + std::sort( color_view.begin(), color_view.end(), sort_by_power() ); + + // + // And now we can sort the views themselves. Notice how + // we switch to different iterators and different predicates: + // + color_view.sort( sort_by_color() ); + + direction_view.sort( sort_by_direction() ); + + return 0; +} |
