Class scoped_ptr

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 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 noncopyable) signal its intent to retain ownership solely within the current scope.  By being noncopyable, it is safer than shared_ptr or std::auto_ptr for pointers which should not be copied.

Because scoped_ptr 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.

Class scoped_ptr 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.

The class is a template parameterized on T, the type of the object pointed to.   T must meet the smart pointer common requirements.

Class scoped_ptr Synopsis

#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
   };
}

Class scoped_ptr Members

scoped_ptr element_type

typedef T element_type;

Provides the type of the stored pointer.

scoped_ptr constructors

explicit scoped_ptr( T* p=0 );  // never throws

T is not required be a complete type at point of instantiation.  See Common Requirements.

Constructs a scoped_ptr, storing a copy of p, which must have been allocated via a C++ new expression or be 0.

scoped_ptr destructor

~scoped_ptr();

T is required be a complete type at point of instantiation.  See Common Requirements.

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.

scoped_ptr reset

void reset( T* p=0 );

T is required be a complete type at point of instantiation.  See Common Requirements.

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.

scoped_ptr operator*

T& operator*() const;  // never throws

T is required be a complete type at point of instantiation.  See Common Requirements.

Returns a reference to the object pointed to by the stored pointer.

scoped_ptr operator-> and get

T* operator->() const;  // never throws
T* get() const;  // never throws

T is required be a complete type at point of instantiation of operator->().  See Common Requirements.

T is not required be a complete type at point of instantiation of get().  See Common Requirements.

Both return the stored pointer.

Class scoped_ptr examples

#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

Handle/Body Idiom

One common usage of scoped_ptr is to implement a handle/body idiom which avoids exposing the body (implementation) in the header file.

The scoped_ptr_example_test.cpp sample program includes a header file, scoped_ptr_example.hpp, which uses a scoped_ptr<> to an incomplete type to hide the implementation.   The instantiation of member functions which require a complete type occurs in the scoped_ptr_example.cpp implementation file. 

Revised 22 May 2001

© 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.