Name

auto_ptr class template — Smart pointer to manage ownership of pointers

Synopsis

template <class T> struct auto_ptr_ref {};
template<class T>
class auto_ptr {
public:
  typedef T element_type;
  explicit auto_ptr(T* p = 0) throw(  );
  auto_ptr(auto_ptr&) throw(  );
  template<class U> auto_ptr(auto_ptr<U>&) throw(  );
  auto_ptr(auto_ptr_ref<T>) throw(  );
  ~auto_ptr(  ) throw(  );
  auto_ptr& operator=(auto_ptr&) throw(  );
  template<class U>
  auto_ptr& operator=(auto_ptr<U>&) throw(  );
  auto_ptr& operator=(auto_ptr_ref<T> r) throw(  );
   
  T& operator*(  ) const throw(  );
  T* operator->(  ) const throw(  );
  T* get(  ) const throw(  );
  T* release(  ) throw(  );
  void reset(T* p = 0) throw(  );
   
  template<class U> operator 
                  auto_ptr_ref<U>(  ) throw(  );
  template<class U> operator 
                  auto_ptr<U>(  ) throw(  );
};

The auto_ptr class template implements a smart pointer to manage ownership of pointers. Proper use of auto_ptr ensures that a pointer has exactly one owner (which prevents accidental double deletes), and the owner automatically frees the memory when the owner goes out of scope (which prevents memory leaks). Assignment of auto_ptr values transfers ownership from the source to the target of the assignment.

The auto_ptr_ref type holds a reference to an auto_ptr. Implicit conversions between auto_ptr and auto_ptr_ref facilitate the return of auto_ptr objects from functions. Usually, you can ignore the auto_ptr_ref type and let the implicit conversions handle the details for you. All you need to do is use auto_ptr as a return type. The details of auto_ptr_ref are implementation-defined.

Some of the typical uses for auto_ptr are:

Because you cannot simply copy or assign an auto_ptr, you cannot use auto_ptr objects in a standard container. Another limitation is that auto_ptr cannot hold a pointer to an array. Allocating and freeing a single object (e.g., new int) is different from allocating and freeing an array of objects, (e.g., new int[42]), and auto_ptr is designed to work only with single objects.

The Boost project has additional smart-pointer class templates that permit copying, arrays, and shared ownership. See Appendix B for more information about Boost.

Example 13-31 shows some uses of auto_ptr.

Example

The following are the members of auto_ptr:

explicit auto_ptr (T* p = 0) throw( )

Initializes the auto_ptr object to own the pointer p.

auto_ptr (auto_ptr& x) throw( ), template<class U> auto_ptr (auto_ptr<U>& x) throw( )

Initializes the auto_ptr object with the pointer returned from x.release( ). In the second version, the type U* must be implicitly convertible to T*. Note that x is not const. It is not possible to copy a const auto_ptr because to do so would break the ownership rules.

auto_ptr (auto_ptr_ref<T> r) throw( )

Initializes the auto_ptr object with the pointer obtained from calling release on r's auto_ptr.

~auto_ptr ( ) throw( )

Deletes the owned pointer (e.g., delete get( )).

T* get ( ) const throw( )

Returns the owned pointer.

T* release ( ) throw( )

Returns get( ) and resets the owned pointer to 0.

void reset (T* p = 0) throw( )

Deletes the owned pointer (if it is not equal to p) and saves p as the new owned pointer.

template<class U> operator auto_ptr_ref<U >( ) throw( )

Returns a temporary auto_ptr_ref object that owns the pointer. The pointer must be convertible to U*. Ownership is released and transferred to the new auto_ptr_ref object.

template<class U> operatorauto_ptr<U >( ) throw( )

Returns a new auto_ptr object. The owned pointer is converted to type U*, and ownership is transferred to the new auto_ptr object.

auto_ptr& operator= (auto_ptr& x) throw( ), template<class U>, auto_ptr& operator= (auto_ptr<U>& x) throw( ), auto_ptr& operator= (auto_ptr_ref<T> r) throw( )

Transfers ownership of the pointer that is owned by x or by the auto_ptr object held by r to *this. That is, it calls reset(x.release( )).

T& operator* ( ) const throw( )

Returns *get( ). If the owned pointer is a null pointer, the behavior is undefined.

T* operator ->( ) const throw( )

Returns get( ).