mirror of
https://github.com/boostorg/smart_ptr.git
synced 2025-10-28 06:11:38 +01:00
136 lines
6.3 KiB
HTML
136 lines
6.3 KiB
HTML
<html>
|
||
|
||
<head>
|
||
<title>scoped_ptr</title>
|
||
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
|
||
<meta name="ProgId" content="FrontPage.Editor.Document">
|
||
</head>
|
||
|
||
<body bgcolor="#FFFFFF" text="#000000">
|
||
|
||
<h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="center" width="277" height="86">Class
|
||
<a name="scoped_ptr">scoped_ptr</a></h1>
|
||
<p>Class <strong>scoped_ptr</strong> stores a pointer to a dynamically allocated
|
||
object. (Dynamically allocated objects are allocated with the C++ <tt>new</tt>
|
||
expression.) The object pointed to is guaranteed to be deleted,
|
||
either on destruction of the <strong>scoped_ptr</strong>, or via an explicit <strong>scoped_ptr::reset()</strong>.
|
||
See <a href="#scoped_ptr_example">example</a>.</p>
|
||
<p>Class<strong> scoped_ptr</strong> is a simple solution for simple
|
||
needs. It supplies a basic "resource acquisition is
|
||
initialization" facility, without shared-ownership or transfer-of-ownership
|
||
semantics. Both its name and enforcement of semantics (by being <a href="../utility/utility.htm#class noncopyable">noncopyable</a>)
|
||
signal its intent to retain ownership solely within the current scope. By
|
||
being <a href="../utility/utility.htm#class noncopyable">noncopyable</a>, it is
|
||
safer than <b>shared_ptr</b> or std::auto_ptr for pointers which should not be
|
||
copied.</p>
|
||
<p>Because <strong>scoped_ptr</strong> is so simple, in its usual implementation
|
||
every operation is as fast as for a built-in pointer and it has no more space overhead
|
||
that a built-in pointer.</p>
|
||
<p>Class<strong> scoped_ptr</strong> cannot be used in C++ Standard Library containers. See <a href="shared_ptr.htm"><strong>shared_ptr</strong></a>
|
||
or std::auto_ptr if <strong>scoped_ptr</strong> does not meet your needs.</p>
|
||
<p>Class<strong> scoped_ptr</strong> cannot correctly hold a pointer to a
|
||
dynamically allocated array. See <a href="scoped_array.htm"><strong>scoped_array</strong></a>
|
||
for that usage.</p>
|
||
<p>The class is a template parameterized on <tt>T</tt>, the type of the object
|
||
pointed to. <tt>T</tt> must meet the smart pointer <a href="smart_ptr.htm#Common requirements">common
|
||
requirements</a>.</p>
|
||
<h2>Class scoped_ptr Synopsis</h2>
|
||
<pre>#include <boost/smart_ptr.hpp>
|
||
namespace boost {
|
||
|
||
template<typename T> class scoped_ptr : <a href="../utility/utility.htm#class noncopyable">noncopyable</a> {
|
||
|
||
public:
|
||
typedef T <a href="#scoped_ptr_element_type">element_type</a>;
|
||
|
||
explicit <a href="#scoped_ptr_ctor">scoped_ptr</a>( T* p=0 ); // never throws
|
||
<strong> </strong><a href="#scoped_ptr_~scoped_ptr">~scoped_ptr</a>();
|
||
|
||
void <a href="#scoped_ptr_reset">reset</a>( T* p=0 );
|
||
|
||
T& <a href="#scoped_ptr_operator*">operator*</a>() const; // never throws
|
||
T* <a href="#scoped_ptr_operator->">operator-></a>() const; // never throws
|
||
T* <a href="#scoped_ptr_get">get</a>() const; // never throws
|
||
};
|
||
}</pre>
|
||
<h2>Class scoped_ptr Members</h2>
|
||
<h3>scoped_ptr <a name="scoped_ptr_element_type">element_type</a></h3>
|
||
<pre>typedef T element_type;</pre>
|
||
<p>Provides the type of the stored pointer.</p>
|
||
<h3><a name="scoped_ptr_ctor">scoped_ptr constructors</a></h3>
|
||
<pre>explicit scoped_ptr( T* p=0 ); // never throws</pre>
|
||
<p>Constructs a <tt>scoped_ptr</tt>, storing a copy of <tt>p</tt>, which must
|
||
have been allocated via a C++ <tt>new</tt> expression or be 0..</p>
|
||
<h3><a name="scoped_ptr_~scoped_ptr">scoped_ptr destructor</a></h3>
|
||
<pre>~scoped_ptr();</pre>
|
||
<p>Deletes the object pointed to by the stored pointer. Note that in C++, <tt>delete</tt>
|
||
on a pointer with a value of 0 is harmless.</p>
|
||
<p>Does not throw exceptions.</p>
|
||
<h3>scoped_ptr <a name="scoped_ptr_reset">reset</a></h3>
|
||
<pre>void reset( T* p=0 );</pre>
|
||
<p>If p is not equal to the stored pointer, deletes the object pointed to by the
|
||
stored pointer and then stores a copy of p, which must have been allocated via a
|
||
C++ <tt>new</tt> expression or be 0.</p>
|
||
<p>Does not throw exceptions.</p>
|
||
<h3>scoped_ptr <a name="scoped_ptr_operator*">operator*</a></h3>
|
||
<pre>T& operator*() const; // never throws</pre>
|
||
<p>Returns a reference to the object pointed to by the stored pointer.</p>
|
||
<h3>scoped_ptr <a name="scoped_ptr_operator->">operator-></a> and <a name="scoped_ptr_get">get</a></h3>
|
||
<pre>T* operator->() const; // never throws
|
||
T* get() const; // never throws</pre>
|
||
<p>Both return the stored pointer.</p>
|
||
<h2>Class <a name="scoped_ptr_example">scoped_ptr example</a>s</h2>
|
||
<pre>#include <iostream>
|
||
#include <boost/smart_ptr.h>
|
||
|
||
struct Shoe { ~Shoe(){ std::cout << "Buckle my shoe" << std::endl; } };
|
||
|
||
class MyClass {
|
||
boost::scoped_ptr<int> ptr;
|
||
public:
|
||
MyClass() : ptr(new int) { *ptr = 0; }
|
||
int add_one() { return ++*ptr; }
|
||
};
|
||
|
||
void main() {
|
||
boost::scoped_ptr<Shoe> x(new Shoe);
|
||
MyClass my_instance;
|
||
std::cout << my_instance.add_one() << std::endl;
|
||
std::cout << my_instance.add_one() << std::endl;
|
||
}</pre>
|
||
<p>The example program produces the beginning of a child's nursery rhyme as
|
||
output:</p>
|
||
<blockquote>
|
||
<pre>1
|
||
2
|
||
Buckle my shoe</pre>
|
||
</blockquote>
|
||
<h2>Handle/Body Idiom</h2>
|
||
<p>One common usage of <b>shared_pointer</b> is to implement a handle/body
|
||
structure which avoids exposing the body (implementation) in the header file:</p>
|
||
<pre>class handle
|
||
{
|
||
public: // simple forwarding functions to the body class
|
||
void f();
|
||
void g(int);
|
||
private:
|
||
friend class body; //incomplete class hides implementation
|
||
boost::scoped_ptr<body> imp;
|
||
};</pre>
|
||
<p>This code requires that <code>class body</code> have a trivial destructor to
|
||
avoid undefined behavior. This is because the definition of <code>class
|
||
body</code> is not visible at the time scoped_ptr<> deletes it. See ISO
|
||
5.3.5/5. Note that some compilers will issue a warning even though the
|
||
above code is well defined.</p>
|
||
<hr>
|
||
<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B %Y" startspan -->10 May 2001<!--webbot bot="Timestamp" endspan i-checksum="15101" --></p>
|
||
<p><EFBFBD> Copyright Greg Colvin and Beman Dawes 1999. Permission to copy, use,
|
||
modify, sell and distribute this document is granted provided this copyright
|
||
notice appears in all copies. This document is provided "as is"
|
||
without express or implied warranty, and with no claim as to its suitability for
|
||
any purpose.</p>
|
||
|
||
</body>
|
||
|
||
</html>
|