libs/smart_ptr/scoped_ptr.htm

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3     <head>
   4         <title>scoped_ptr</title>
   5         <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   6     </head>
   7         <body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
   8         <h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
   9             width="277" align="middle" border="0">scoped_ptr class template</h1>
  10         <p>The <b>scoped_ptr</b> class template stores a pointer to a dynamically allocated
  11             object. (Dynamically allocated objects are allocated with the C++ <b>new</b> expression.)
  12             The object pointed to is guaranteed to be deleted, either on destruction of the <b>scoped_ptr</b>,
  13             or via an explicit <b>reset</b>. See the <a href="#example">example</a>.</p>
  14         <p>The <b>scoped_ptr</b> template is a simple solution for simple needs. It
  15             supplies a basic "resource acquisition is initialization" facility, without
  16             shared-ownership or transfer-of-ownership semantics. Both its name and
  17             enforcement of semantics (by being <a href="../utility/utility.htm#Class_noncopyable">
  18             noncopyable</a>) signal its intent to retain ownership solely within the
  19             current scope. Because it is <a href="../utility/utility.htm#Class_noncopyable">noncopyable</a>,
  20             it is safer than <b>shared_ptr</b> or <b>std::auto_ptr</b> for pointers which
  21             should not be copied.</p>
  22         <p>Because <b>scoped_ptr</b> is simple, in its usual implementation every operation
  23             is as fast as for a built-in pointer and it has no more space overhead that a
  24             built-in pointer.</p>
  25         <p><STRONG>scoped_ptr</STRONG> cannot be used in C++ Standard Library containers.
  26             Use <a href="shared_ptr.htm"><b>shared_ptr</b></a> if you need a smart pointer
  27             that can.</p>
  28         <p><STRONG>scoped_ptr</STRONG> cannot correctly hold a pointer to a dynamically
  29             allocated array. See <a href="scoped_array.htm"><b>scoped_array</b></a> for
  30             that usage.</p>
  31         <p>The class template is parameterized on <b>T</b>, the type of the object pointed
  32             to. <b>T</b> must meet the smart pointer <a href="smart_ptr.htm#common_requirements">
  33             common requirements</a>.</p>
  34         <h2>Synopsis</h2>
  35         <pre>namespace boost {
  36
  37   template&lt;class T&gt; class scoped_ptr : <a href="../utility/utility.htm#Class_noncopyable">noncopyable</a> {
  38
  39    public:
  40      typedef T <a href="#element_type">element_type</a>;
  41
  42      explicit <a href="#constructors">scoped_ptr</a>(T * p = 0); // never throws
  43      <a href="#destructor">~scoped_ptr</a>(); // never throws
  44
  45      void <a href="#reset">reset</a>(T * p = 0); // never throws
  46
  47      T &amp; <a href="#indirection">operator*</a>() const; // never throws
  48      T * <a href="#indirection">operator-&gt;</a>() const; // never throws
  49      T * <a href="#get">get</a>() const; // never throws
  50
  51      operator <A href="#conversions" ><i>unspecified-bool-type</i></A>() const; // never throws
  52
  53      void <a href="#swap">swap</a>(scoped_ptr &amp; b); // never throws
  54   };
  55
  56   template&lt;class T&gt; void <a href="#free-swap">swap</a>(scoped_ptr&lt;T&gt; &amp; a, scoped_ptr&lt;T&gt; &amp; b); // never throws
  57
  58 }</pre>
  59         <h2>Members</h2>
  60         <h3><a name="element_type">element_type</a></h3>
  61         <pre>typedef T element_type;</pre>
  62         <p>Provides the type of the stored pointer.</p>
  63         <h3><a name="constructors">constructors</a></h3>
  64         <pre>explicit scoped_ptr(T * p = 0); // never throws</pre>
  65         <p>Constructs a <b>scoped_ptr</b>, storing a copy of <b>p</b>, which must have been
  66             allocated via a C++ <b>new</b> expression or be 0. <b>T</b> is not required be
  67             a complete type. See the smart pointer <a href="smart_ptr.htm#common_requirements">common
  68             requirements</a>.</p>
  69         <h3><a name="destructor">destructor</a></h3>
  70         <pre>~scoped_ptr(); // never throws</pre>
  71         <p>Destroys the object pointed to by the stored pointer, if any, as if by using <tt>delete
  72             this-&gt;get()</tt>.</p>
  73         <P>
  74             The guarantee that this does not throw exceptions depends on the requirement
  75             that the deleted object's destructor does not throw exceptions. See the smart
  76             pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</P>
  77         <h3><a name="reset">reset</a></h3>
  78         <pre>void reset(T * p = 0); // never throws</pre>
  79         <p>
  80             Deletes the object pointed to by the stored pointer and then stores a copy of
  81             p, which must have been allocated via a C++ <b>new</b> expression or be 0. The
  82             guarantee that this does not throw exceptions depends on the requirement that
  83             the deleted object's destructor does not throw exceptions. See the smart
  84             pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</p>
  85         <h3><a name="indirection">indirection</a></h3>
  86         <pre>T &amp; operator*() const; // never throws</pre>
  87         <p>Returns a reference to the object pointed to by the stored pointer. Behavior is
  88             undefined if the stored pointer is 0.</p>
  89         <pre>T * operator-&gt;() const; // never throws</pre>
  90         <p>Returns the stored pointer. Behavior is undefined if the stored pointer is 0.</p>
  91         <h3><a name="get">get</a></h3>
  92         <pre>T * get() const; // never throws</pre>
  93         <p>Returns the stored pointer. <b>T</b> need not be a complete type. See the smart
  94             pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</p>
  95         <h3><a name="conversions">conversions</a></h3>
  96         <pre>operator <i>unspecified-bool-type</i> () const; // never throws</pre>
  97         <p>Returns an unspecified value that, when used in boolean contexts, is equivalent
  98             to <code>get() != 0</code>.</p>
  99         <h3><a name="swap">swap</a></h3>
 100         <pre>void swap(scoped_ptr &amp; b); // never throws</pre>
 101         <p>Exchanges the contents of the two smart pointers. <b>T</b> need not be a
 102             complete type. See the smart pointer <a href="smart_ptr.htm#common_requirements">common
 103             requirements</a>.</p>
 104         <h2><a name="functions">Free Functions</a></h2>
 105         <h3><a name="free-swap">swap</a></h3>
 106         <pre>template&lt;class T&gt; void swap(scoped_ptr&lt;T&gt; &amp; a, scoped_ptr&lt;T&gt; &amp; b); // never throws</pre>
 107         <p>Equivalent to <b>a.swap(b)</b>. Matches the interface of <b>std::swap</b>.
 108             Provided as an aid to generic programming.</p>
 109         <h2><a name="example">Example</a></h2>
 110         <p>Here's an example that uses <b>scoped_ptr</b>.</p>
 111         <blockquote>
 112             <pre>#include &lt;boost/scoped_ptr.hpp&gt;
 113 #include &lt;iostream&gt;
 114
 115 struct Shoe { ~Shoe() { std::cout &lt;&lt; "Buckle my shoe\n"; } };
 116
 117 class MyClass {
 118     boost::scoped_ptr&lt;int&gt; ptr;
 119   public:
 120     MyClass() : ptr(new int) { *ptr = 0; }
 121     int add_one() { return ++*ptr; }
 122 };
 123
 124 int main()
 125 {
 126     boost::scoped_ptr&lt;Shoe&gt; x(new Shoe);
 127     MyClass my_instance;
 128     std::cout &lt;&lt; my_instance.add_one() &lt;&lt; '\n';
 129     std::cout &lt;&lt; my_instance.add_one() &lt;&lt; '\n';
 130 }</pre>
 131         </blockquote>
 132         <p>The example program produces the beginning of a child's nursery rhyme:</p>
 133         <blockquote>
 134             <pre>1
 135 2
 136 Buckle my shoe</pre>
 137         </blockquote>
 138         <h2>Rationale</h2>
 139         <p>The primary reason to use <b>scoped_ptr</b> rather than <b>auto_ptr</b> is to
 140             let readers of your code know that you intend "resource acquisition is
 141             initialization" to be applied only for the current scope, and have no intent to
 142             transfer ownership.</p>
 143         <p>A secondary reason to use <b>scoped_ptr</b> is to prevent a later maintenance
 144             programmer from adding a function that transfers ownership by returning the <b>auto_ptr</b>,
 145             because the maintenance programmer saw <b>auto_ptr</b>, and assumed ownership
 146             could safely be transferred.</p>
 147         <p>Think of <b>bool</b> vs <b>int</b>. We all know that under the covers <b>bool</b>
 148             is usually just an <b>int</b>. Indeed, some argued against including <b>bool</b>
 149             in the C++ standard because of that. But by coding <b>bool</b> rather than <b>int</b>,
 150             you tell your readers what your intent is. Same with <b>scoped_ptr</b>; by
 151             using it you are signaling intent.</p>
 152         <p>It has been suggested that <b>scoped_ptr&lt;T&gt;</b> is equivalent to <b>std::auto_ptr&lt;T&gt;
 153             const</b>. Ed Brey pointed out, however, that <b>reset</b> will not work on
 154             a <b>std::auto_ptr&lt;T&gt; const.</b></p>
 155         <h2><a name="Handle/Body">Handle/Body</a> Idiom</h2>
 156         <p>One common usage of <b>scoped_ptr</b> is to implement a handle/body (also called
 157             pimpl) idiom which avoids exposing the body (implementation) in the header
 158             file.</p>
 159         <p>The <a href="example/scoped_ptr_example_test.cpp">scoped_ptr_example_test.cpp</a>
 160             sample program includes a header file, <a href="example/scoped_ptr_example.hpp">scoped_ptr_example.hpp</a>,
 161             which uses a <b>scoped_ptr&lt;&gt;</b> to an incomplete type to hide the
 162             implementation. The instantiation of member functions which require a complete
 163             type occurs in the <a href="example/scoped_ptr_example.cpp">scoped_ptr_example.cpp</a>
 164             implementation file.</p>
 165         <h2>Frequently Asked Questions</h2>
 166         <p><b>Q</b>. Why doesn't <b>scoped_ptr</b> have a release() member?<br>
 167             <b>A</b>. When reading source code, it is valuable to be able to draw
 168             conclusions about program behavior based on the types being used. If <STRONG>scoped_ptr</STRONG>
 169             had a release() member, it would become possible to transfer ownership of the
 170             held pointer, weakening its role as a way of limiting resource lifetime to a
 171             given context. Use <STRONG>std::auto_ptr</STRONG> where transfer of ownership
 172             is required. (supplied by Dave Abrahams)</p>
 173         <hr>
 174         <p>$Date</p>
 175         <p><small>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
 176             Copyright 2002-2005 Peter Dimov. Distributed under the Boost Software License, Version
 177             1.0. See accompanying file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or
 178             copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p>
 179     </body>
 180 </html>