.\" ident @(#)auto_ptr.3 .\" Standard Template Library .\" $$RW_INSERT_HEADER "slyrs.man" .TH auto_ptr 3C++ "02 Apr 1998" "Rogue Wave Software" "-" .ce2 Standard C++ Library Copyright 1998, Rogue Wave Software, Inc. .SH NAME \f2auto_ptr\fP \ - A simple, smart pointer class. .SH SYNOPSIS .RE .RS 0 #include .br template class auto_ptr; .SH DESCRIPTION The template class auto_ptr holds onto a pointer obtained via \f2new\fP and deletes that object when the auto_ptr object itself is destroyed (such as when leaving block scope). auto_ptr can be used to make calls to operator new exception-safe. The auto_ptr class has semantics of strict ownership: an object may be safely pointed to by only one auto_ptr, so copying an auto_ptr copies the pointer and transfers ownership to the destination if the source had already had ownership. .SH INTERFACE .br template class auto_ptr { .br template class auto_ptr_ref { .RE .RS 2 public: .RE .RS 4 const auto_ptr& p; .br auto_ptr_ref (const auto_ptr&); .RE .RS 0 }; .RE .RS 2 public: .RE .RS 4 typedef X element_type; .RE .RS 5 // constructor/copy/destroy .RE .RS 0 .RE .RS 4 explicit auto_ptr (X* = 0) throw(); .br auto_ptr (const auto_ptr&) throw (); .br template .RE .RS 6 auto_ptr (const auto_ptr&) throw(); .RE .RS 4 void operator=(const auto_ptr&) throw(): .br template .RE .RS 6 void operator= (const auto_ptr&) throw(); .RE .RS 5 ~auto_ptr (); .RE .RS 0 .RE .RS 5 // members .RE .RS 0 .RE .RS 4 X& operator* () const throw(); .br X* operator-> () const throw(); .br X* get () const throw(); .br X* release () throw(); .br void reset (X*=0) throw(); .br auto_ptr(auto_ptr_ref) throw(); .br template .br operator auto_ptr_ref() throw(); .br template .br operator auto_ptr() throw(); .RE .RS 1 }; .SH TYPES .RE .RS 0 template .br class auto_ptr_ref; .RE .RS 3 A private class template that holds a reference to an \f2auto_ptr\fP. It can only be constructed within an \f2auto_ptr\fP using a reference to an \f2auto_ptr\fP. It prevents unsafe copying. .RE .SH CONSTRUCTORS .br explicit .br auto_ptr (X* p = 0); .RE .RS 3 Constructs an object of class \f2auto_ptr\fP, initializing the held pointer to \f2p\fP, and acquiring ownership of that pointer. \f2p\fP must point to an object of class \f2X\fP or a class derived from \f2X\fP for which \f2delete p\fP is defined and accessible, or \f2p\fP must be a null pointer. .RE .br auto_ptr (const auto_ptr& a); .br template .br auto_ptr (const auto_ptr& a); .RE .RS 3 Constructs an object of class \f2auto_ptr\fP, and copies the argument \f2a\fP to \f2*this\fP. If \f2a\fP owned the underlying pointer, then \f2*this\fP becomes the new owner of that pointer. .RE .br auto_ptr (const auto_ptr_ref r); .RE .RS 3 Constructs an \f2auto_ptr\fP from an \f2auto_ptr_ref\fP. .RE .SH DESTRUCTORS .br ~auto_ptr (); .RE .RS 3 Deletes the underlying pointer. .RE .SH OPERATORS .br void operator= (const auto_ptr& a); .br template .br void operator= (const auto_ptr& a); .RE .RS 3 Copies the argument \f2a\fP to \f2*this\fP. If \f2a\fP owned the underlying pointer, then \f2*this\fP becomes the new owner of that pointer. If \f2*this\fP already owned a pointer, then that pointer is deleted first. .RE .br X& .br operator* () const; .RE .RS 3 Returns a reference to the object to which the underlying pointer points. .RE .br X* .br operator-> () const; .RE .RS 3 Returns the underlying pointer. .RE .br template .br operator auto_ptr_ref (); .RE .RS 3 Constructs an \f2auto_ptr_ref\fP from \f2*this\fP and returns it. .RE .br template .br operator auto_ptr (); .RE .RS 3 Constructs a new \f2auto_ptr\fP using the underlying pointer held by \f2*this\fP. Calls \f2release()\fP on \f2*this\fP, so \f2*this\fP no longer possesses the pointer. Returns the new \f2auto_ptr\fP. .RE .SH MEMBER FUNCTIONS .br X* .br get () const; .RE .RS 3 Returns the underlying pointer. .RE .br X* .br release(); .RE .RS 3 Releases ownership of the underlying pointer. Returns that pointer. .RE .br void .br reset(X* p) .RE .RS 3 Sets the underlying pointer to \f2p\fP. If non-null, deletes the old underlying pointer. .RE .SH EXAMPLE .RE .RS 3 // .br // auto_ptr.cpp .br // .br #include .br #include .RE .RS 2 using namespace std; .RE .RS 0 .RE .RS 3 // .br // A simple structure. .br // .RE .RS 2 struct X .RE .RS 3 { .RE .RS 6 X (int i = 0) : m_i(i) { } .br int get() const { return m_i; } .br int m_i; .RE .RS 3 }; .RE .RS 0 .RE .RS 2 int main () .RE .RS 3 { .RE .RS 6 // .br // b will hold a pointer to an X. .br // .RE .RS 5 auto_ptr b(new X(12345)); .RE .RS 6 // .br // a will now be the owner of the underlying pointer. .br // .RE .RS 5 auto_ptr a = b; .RE .RS 6 // .br // Output the value contained by .br // the underlying pointer. .br // .RE .RS 5 cout << a->get() << endl; .RE .RS 6 // .br // The pointer will be deleted when a is destroyed on .br // leaving scope. .br // .RE .RS 5 return 0; .RE .RS 3 } .br .RE .RS 0 Program Output .RE .RS 0 .br 12345