Class scoped_ptr stores a pointer to a dynamically allocated object. (Dynamically allocated objects are allocated with the C++ new expression.) The object pointed to is guaranteed to be deleted, either on destruction of the scoped_ptr, or via an explicit scoped_ptr::reset(). See example.
Class scoped_ptr is a simple solution for simple needs. It cannot be used in C++ Standard Library containers. See shared_ptr or std::auto_ptr if scoped_ptr does not meet your needs.
Class scoped_ptr cannot correctly hold a pointer to a dynamically allocated array. See scoped_array for that usage.
Because scoped_ptr is so simple, in its usual implementation every operation is as fast as a built-in pointer and has no more space overhead that a built-in pointer.
The class is a template parameterized on T, the type of the object pointed to. T must meet the smart pointer common requirements.
#include <boost/smart_ptr.hpp> namespace boost { template<typename T> class scoped_ptr : noncopyable { public: typedef T element_type; explicit scoped_ptr( T* p=0 ); // never throws ~scoped_ptr(); void reset( T* p=0 ); T& operator*() const; // never throws T* operator->() const; // never throws T* get() const; // never throws }; }
typedef T element_type;
Provides the type of the stored pointer.
explicit scoped_ptr( T* p=0 ); // never throws
Constructs a scoped_ptr, storing a copy of p, which must have been allocated via a C++ new expression or be 0..
~scoped_ptr();
Deletes the object pointed to by the stored pointer. Note that in C++, delete on a pointer with a value of 0 is harmless.
Does not throw exceptions.
void reset( T* p=0 );
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++ new expression or be 0.
Does not throw exceptions.
T& operator*() const; // never throws
Returns a reference to the object pointed to by the stored pointer.
T* operator->() const; // never throws T* get() const; // never throws
Both return the stored pointer.
#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; }
The example program produces the beginning of a child's nursery rhyme as output:
1 2 Buckle my shoe
One common usage of shared_pointer is to implement a handle/body structure which avoids exposing the body (implementation) in the header file:
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; };
This code requires that class body
have a trivial destructor to
avoid undefined behavior. This is because the definition of class
body
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.
Revised 27 July 2000
© 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.