Files
ptr_container/doc/reversible_ptr_container.html
Thorsten Jørgen Ottosen 7b71bf7444 *** empty log message ***
[SVN r30827]
2005-09-06 15:26:50 +00:00

431 lines
22 KiB
HTML

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.3.9: http://docutils.sourceforge.net/" />
<title>Boost Pointer Container Library</title>
<link rel="stylesheet" href="default.css" type="text/css" />
</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" id="class-reversible-ptr-container">
<h1><a 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>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
&lt;
class T,
class CloneAllocator,
class VoidPtrContainer
&gt;
class reversible_ptr_container
{
public: // <a class="reference" href="#typedefs">typedefs</a>
typedef T* value_type;
typedef T&amp; reference;
typedef const T&amp; 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();
reversible_ptr_container( auto_ptr&lt;reversible_ptr_container&gt; r );
template&lt; class InputIterator &gt;
reversible_ptr_container( InputIterator first, InputIterator last );
~reversible_ptr_container();
void operator=( std::auto_ptr&lt;reversible_ptr_container&gt; 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&amp; r );
void clear():
public: // <a class="reference" href="#pointer-container-requirements">pointer container requirements</a>
auto_type replace( iterator position, T* x );
std::auto_ptr&lt;reversible_ptr_container&gt; clone() const;
std::auto_ptr&lt;reversible_ptr_container&gt; release();
auto_type release( iterator position );
}; // class 'reversible_ptr_container'
// <a class="reference" href="#comparison">comparison</a>
template &lt; class T, class CA, class VPC &gt;
bool operator==( const reversible_ptr_container&lt;T,CA,VPC&gt;&amp; x,
const reversible_ptr_container&lt;T,CA,VPC&gt;&amp; y);
template &lt; class T, class CA, class VPC &gt;
bool operator&lt;( const reversible_ptr_container&lt;T,CA,VPC&gt;&amp; x,
const reversible_ptr_container&lt;T,CA,VPC&gt;&amp; y);
template &lt; class T, class CA, class VPC &gt;
bool operator!=( const reversible_ptr_container&lt;T,CA,VPC&gt;&amp; x,
const reversible_ptr_container&lt;T,CA,VPC&gt;&amp; y);
template &lt; class T, class CA, class VPC &gt;
bool operator&gt;( const reversible_ptr_container&lt;T,CA,VPC&gt;&amp; x,
const reversible_ptr_container&lt;T,CA,VPC&gt;&amp; y);
template &lt; class T, class CA, class VPC &gt;
bool operator&gt;=( const reversible_ptr_container&lt;T,CA,VPC&gt;&amp; x,
const reversible_ptr_container&lt;T,CA,VPC&gt;&amp; y);
template &lt; class T, class CA, class VPC &gt;
bool operator&lt;=( const reversible_ptr_container&lt;T,CA,VPC&gt;&amp; x,
const reversible_ptr_container&lt;T,CA,VPC&gt;&amp; y);
template&lt; class T, class CA, class VPC &gt;
void swap( reversible_ptr_container&lt;T,CA,VPC&gt;&amp; x,
reversible_ptr_container&lt;T,CA,VPC&gt;&amp; y );
// <a class="reference" href="#clonability">clonability</a>
template&lt; class T, class CA, class VPC &gt;
reversible_ptr_container&lt;T,CA,VPC&gt;*
new_clone( const reversible_ptr_container&lt;T,CA,VPC&gt;&amp; r );
// <a class="reference" href="#null-predicate">null predicate</a>
template&lt; class Iterator &gt;
bool is_null( Iterator i );
} // namespace 'boost'
</pre>
</div>
<div class="section" id="semantics">
<h1><a name="semantics">Semantics</a></h1>
<span id="typedefs"></span><div class="section" id="semantics-typedefs">
<h2><a name="semantics-typedefs">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&amp;</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&amp;</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-&gt;() const;
T&amp; operator*() const;
T* release();
~auto_type();
</pre>
<p>The destructor will delete the stored object. It might help to
think it is just an <tt class="docutils literal"><span class="pre">std::auto_ptr&lt;T&gt;</span></tt>.</p>
</div>
<span id="construct-copy-destroy"></span><div class="section" id="semantics-construct-copy-destroy">
<h2><a name="semantics-construct-copy-destroy">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">std::auto_ptr&lt;</span> <span class="pre">reversible_ptr_container</span> <span class="pre">&gt;</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&lt;</span> <span class="pre">class</span> <span class="pre">InputIterator</span> <span class="pre">&gt;</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</li>
<li>Throws: Nothing</li>
</ul>
</blockquote>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">operator=(</span> <span class="pre">std::auto_ptr&lt;reversible_ptr_container&gt;</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>
<span id="iterators"></span><div class="section" id="semantics-iterators">
<h2><a name="semantics-iterators">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>
<span id="capacity"></span><div class="section" id="semantics-capacity">
<h2><a name="semantics-capacity">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>
<span id="modifiers"></span><div class="section" id="semantics-modifiers">
<h2><a name="semantics-modifiers">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&amp;</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>
</ul>
</div>
<span id="pointer-container-requirements"></span><div class="section" id="semantics-pointer-container-requirements">
<h2><a name="semantics-pointer-container-requirements">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">std::auto_ptr&lt;</span> <span class="pre">reversible_ptr_container</span> <span class="pre">&gt;</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&lt;</span> <span class="pre">reversible_ptr_container</span> <span class="pre">&gt;</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>
<span id="comparison"></span><div class="section" id="semantics-comparison">
<h2><a name="semantics-comparison">Semantics: comparison</a></h2>
<p>These functions compare the underlying range of objects.
So</p>
<pre class="literal-block">
operation( const ptr_container&amp; l, const ptr_container&amp; 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>
<span id="clonability"></span><div class="section" id="semantics-clonability">
<h2><a name="semantics-clonability">Semantics: clonability</a></h2>
<ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">T,</span> <span class="pre">class</span> <span class="pre">CloneAllocator</span> <span class="pre">&gt;</span>
<span class="pre">reversible_ptr_container&lt;T,CA,VPC&gt;*</span>
<span class="pre">new_clone(</span> <span class="pre">const</span> <span class="pre">reversible_ptr_container&lt;T,CA,VPC&gt;&amp;</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>
<span id="null-predicate"></span><div class="section" id="semantics-null-predicate">
<h2><a name="semantics-null-predicate">Semantics: null predicate</a></h2>
<ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">Iterator</span> <span class="pre">&gt;</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>
<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-2005.</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</body>
</html>