| 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 bgcolor="#ffffff" text="#000000"> |
|---|
| 8 | <h1><A href="../../index.htm"><img src="../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="277" height="86" |
|---|
| 9 | border="0"></A>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<class T> 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 & <a href="#indirection">operator*</a>() const; // never throws |
|---|
| 48 | T * <a href="#indirection">operator-></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 & b); // never throws |
|---|
| 54 | }; |
|---|
| 55 | |
|---|
| 56 | template<class T> void <a href="#free-swap">swap</a>(scoped_ptr<T> & a, scoped_ptr<T> & 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->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 & 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->() 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 & 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<class T> void swap(scoped_ptr<T> & a, scoped_ptr<T> & 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 <boost/scoped_ptr.hpp> |
|---|
| 113 | #include <iostream> |
|---|
| 114 | |
|---|
| 115 | struct Shoe { ~Shoe() { std::cout << "Buckle my shoe\n"; } }; |
|---|
| 116 | |
|---|
| 117 | class MyClass { |
|---|
| 118 | boost::scoped_ptr<int> 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<Shoe> x(new Shoe); |
|---|
| 127 | MyClass my_instance; |
|---|
| 128 | std::cout << my_instance.add_one() << '\n'; |
|---|
| 129 | std::cout << my_instance.add_one() << '\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<T></b> is equivalent to <b>std::auto_ptr<T> |
|---|
| 153 | const</b>. Ed Brey pointed out, however, that <b>reset</b> will not work on |
|---|
| 154 | a <b>std::auto_ptr<T> 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<></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>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B %Y" startspan --> |
|---|
| 175 | 09 January 2003<!--webbot bot="Timestamp" endspan i-checksum="32310" --></p> |
|---|
| 176 | <p>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler. |
|---|
| 177 | Copyright 2002-2005 Peter Dimov. Permission to copy, use, modify, sell and |
|---|
| 178 | distribute this document is granted provided this copyright notice appears in |
|---|
| 179 | all copies. This document is provided "as is" without express or implied |
|---|
| 180 | warranty, and with no claim as to its suitability for any purpose.</p> |
|---|
| 181 | </body> |
|---|
| 182 | </html> |
|---|
