mirror of
https://github.com/boostorg/smart_ptr.git
synced 2026-04-29 18:44:15 +02:00
Documentation and example program improvements
[SVN r10220]
This commit is contained in:
Beman Dawes
+27
-22
@@ -34,7 +34,7 @@ object A dangling with a use_count() of 1.</p>
|
||||
pointed to. <tt>T</tt> must meet the smart pointer <a href="smart_ptr.htm#Common requirements">Common
|
||||
requirements</a>.</p>
|
||||
<h2>Class shared_ptr Synopsis</h2>
|
||||
<pre>#include <boost/smart_ptr.hpp>
|
||||
<pre>#include <<a href="../../boost/smart_ptr.hpp">boost/smart_ptr.hpp</a>>
|
||||
namespace boost {
|
||||
|
||||
template<typename T> class shared_ptr {
|
||||
@@ -118,8 +118,6 @@ the macro name BOOST_NO_MEMBER_TEMPLATES is defined.</p>
|
||||
<p>Provides the type of the stored pointer.</p>
|
||||
<h3><a name="shared_ptr_ctor">shared_ptr constructors</a></h3>
|
||||
<pre>explicit shared_ptr( T* p=0 );</pre>
|
||||
<p><b>T</b> is required be a complete type at point of instantiation. See <a href="smart_ptr.htm#Common requirements">Common
|
||||
Requirements</a>.</p>
|
||||
<p>Constructs a <strong>shared_ptr</strong>, storing a copy of <tt>p</tt>, which
|
||||
must have been allocated via a C++ <tt>new</tt> expression or be 0. Afterwards, <strong>use_count()</strong>
|
||||
is 1 (even if p==0; see <a href="#shared_ptr_~shared_ptr">~shared_ptr</a>).</p>
|
||||
@@ -130,8 +128,6 @@ template<typename Y>
|
||||
shared_ptr(const shared_ptr<Y>& r); // never throws
|
||||
template<typename Y>
|
||||
shared_ptr(std::auto_ptr<Y>& r);</pre>
|
||||
<p><b>T</b> is not required be a complete type at point of instantiation.
|
||||
See <a href="smart_ptr.htm#Common requirements">Common Requirements</a>.</p>
|
||||
<p>Constructs a <strong>shared_ptr</strong>, as if by storing a copy of the
|
||||
pointer stored in <strong>r</strong>. Afterwards, <strong>use_count()</strong>
|
||||
for all copies is 1 more than the initial <strong>r.use_count()</strong>, or 1
|
||||
@@ -142,8 +138,6 @@ is <tt>std::bad_alloc</tt>. If an exception is thrown, that
|
||||
constructor has no effect.</p>
|
||||
<h3><a name="shared_ptr_~shared_ptr">shared_ptr destructor</a></h3>
|
||||
<pre>~shared_ptr();</pre>
|
||||
<p><b>T</b> is required be a complete type at point of instantiation. See <a href="smart_ptr.htm#Common requirements">Common
|
||||
Requirements</a>.</p>
|
||||
<p>If <strong>use_count()</strong> == 1, deletes the object pointed to by the
|
||||
stored pointer. Otherwise, <strong>use_count()</strong> for any remaining
|
||||
copies is decremented by 1. Note that in C++ <tt>delete</tt> on a pointer
|
||||
@@ -155,8 +149,6 @@ template<typename Y>
|
||||
shared_ptr& operator=(const shared_ptr<Y>& r);
|
||||
template<typename Y>
|
||||
shared_ptr& operator=(std::auto_ptr<Y>& r);</pre>
|
||||
<p><b>T</b> is required be a complete type at point of instantiation. See <a href="smart_ptr.htm#Common requirements">Common
|
||||
Requirements</a>.</p>
|
||||
<p>First, if <strong>use_count()</strong> == 1, deletes the object pointed to by
|
||||
the stored pointer. Otherwise, <strong>use_count()</strong> for any
|
||||
remaining copies is decremented by 1. Note that in C++ <tt>delete</tt> on
|
||||
@@ -172,8 +164,6 @@ is <tt>std::bad_alloc</tt>. If an exception is thrown, the function
|
||||
has no effect.</p>
|
||||
<h3>shared_ptr <a name="shared_ptr_reset">reset</a></h3>
|
||||
<pre>void reset( T* p=0 );</pre>
|
||||
<p><b>T</b> is required be a complete type at point of instantiation. See <a href="smart_ptr.htm#Common requirements">Common
|
||||
Requirements</a>.</p>
|
||||
<p>First, if <strong>use_count()</strong> == 1, deletes the object pointed to by
|
||||
the stored pointer. Otherwise, <strong>use_count()</strong> for any
|
||||
remaining copies is decremented by 1. </p>
|
||||
@@ -186,32 +176,26 @@ on a pointer with a value of 0 is harmless.</p>
|
||||
an exception is thrown, <tt>delete p</tt> is called.</p>
|
||||
<h3>shared_ptr <a name="shared_ptr_operator*">operator*</a></h3>
|
||||
<pre>T& operator*() const; // never throws</pre>
|
||||
<p><b>T</b> is required be a complete type at point of instantiation. See <a href="smart_ptr.htm#Common requirements">Common
|
||||
Requirements</a>.</p>
|
||||
<p>Returns a reference to the object pointed to by the stored pointer.</p>
|
||||
<h3>shared_ptr <a name="shared_ptr_operator->">operator-></a> and <a name="shared_ptr_get">get</a></h3>
|
||||
<pre>T* operator->() const; // never throws
|
||||
T* get() const; // never throws</pre>
|
||||
<p><b>T</b> is required be a complete type at point of instantiation of
|
||||
operator->(). See <a href="smart_ptr.htm#Common requirements">Common
|
||||
Requirements</a>.</p>
|
||||
<p><b>T</b> is not required be a complete type at point of instantiation of
|
||||
get(). See <a href="smart_ptr.htm#Common requirements">Common Requirements</a>.</p>
|
||||
<p><b>T</b> is not required by get() to be a complete type . See <a href="smart_ptr.htm#Common requirements">Common Requirements</a>.</p>
|
||||
<p>Both return the stored pointer.</p>
|
||||
<h3>shared_ptr<a name="shared_ptr_use_count"> use_count</a></h3>
|
||||
<p><tt>long use_count() const; // never throws</tt></p>
|
||||
<p><b>T</b> is not required be a complete type at point of instantiation.
|
||||
<p><b>T</b> is not required be a complete type.
|
||||
See <a href="smart_ptr.htm#Common requirements">Common Requirements</a>.</p>
|
||||
<p>Returns the number of <strong>shared_ptrs</strong> sharing ownership of the
|
||||
stored pointer.</p>
|
||||
<h3>shared_ptr <a name="shared_ptr_unique">unique</a></h3>
|
||||
<p><tt>bool unique() const; // never throws</tt></p>
|
||||
<p><b>T</b> is not required be a complete type at point of instantiation.
|
||||
<p><b>T</b> is not required be a complete type.
|
||||
See <a href="smart_ptr.htm#Common requirements">Common Requirements</a>.</p>
|
||||
<p>Returns <strong>use_count()</strong> == 1.</p>
|
||||
<h3><a name="shared_ptr_swap">shared_ptr swap</a></h3>
|
||||
<p><code>void swap( shared_ptr<T>& other ) throw()</code></p>
|
||||
<p><b>T</b> is not required be a complete type at point of instantiation.
|
||||
<p><b>T</b> is not required be a complete type.
|
||||
See <a href="smart_ptr.htm#Common requirements">Common Requirements</a>.</p>
|
||||
<p>Swaps the two smart pointers, as if by std::swap.</p>
|
||||
<h2>Class <a name="shared_ptr_example">shared_ptr example</a></h2>
|
||||
@@ -224,8 +208,29 @@ at various times while push_back() and insert() container operations are perform
|
||||
More complicated yet, the container operations may throw exceptions under a
|
||||
variety of circumstances. Without using a smart pointer, memory and
|
||||
exception management would be a nightmare.</p>
|
||||
<h2><a name="Handle/Body">Handle/Body</a> Idiom</h2>
|
||||
<p>One common usage of <b>shared_ptr</b> is to implement a handle/body (also
|
||||
called pimpl) idiom which avoids exposing the body (implementation) in the header
|
||||
file.</p>
|
||||
<p>The <a href="shared_ptr_example2_test.cpp">shared_ptr_example2_test.cpp</a>
|
||||
sample program includes a header file, <a href="shared_ptr_example2.hpp">shared_ptr_example2.hpp</a>,
|
||||
which uses a <b>shared_ptr<></b> to an incomplete type to hide the
|
||||
implementation. The
|
||||
instantiation of member functions which require a complete type occurs in the <a href="shared_ptr_example2.cpp">shared_ptr_example2.cpp</a>
|
||||
implementation file.</p>
|
||||
<h2>FAQ</h2>
|
||||
<p><b>Q</b>. Why doesn't <b>shared_ptr</b> have template parameters supplying
|
||||
traits or policies to allow extensive user customization?<br>
|
||||
<b>A</b>. Parameterization discourages users. <b>Shared_ptr</b> is
|
||||
carefully crafted to meet common needs without extensive parameterization.
|
||||
Someday a highly configurable smart pointer may be invented that is also very
|
||||
easy to use and very hard to misuse. Until then, <b>shared_ptr</b> is the
|
||||
smart pointer of choice for a wide range of applications.</p>
|
||||
<p><b>Q</b>. Why don't <b>shared_ptr</b> (and the other Boost smart pointers)
|
||||
supply an automatic conversion to <b>T*</b>?<br>
|
||||
<b>A</b>. Automatic conversion is believed to be too error prone.</p>
|
||||
<hr>
|
||||
<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->22 May, 2001<!--webbot bot="Timestamp" endspan i-checksum="13960" -->
|
||||
<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->24 May, 2001<!--webbot bot="Timestamp" endspan i-checksum="13964" -->
|
||||
</p>
|
||||
<p>© Copyright Greg Colvin and Beman Dawes 1999. Permission to copy, use,
|
||||
modify, sell and distribute this document is granted provided this copyright
|
||||
|
||||
Reference in New Issue
Block a user