Standard C++ Library
Copyright 1998, Rogue Wave Software, Inc.
NAME
auto_ptr
- A simple, smart pointer class.
SYNOPSIS
#include <memory>
template <class X> class auto_ptr;
DESCRIPTION
The template class auto_ptr holds onto a pointer obtained
via new 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.
INTERFACE
template <class X> class auto_ptr {
template <class Y> class auto_ptr_ref {
public:
const auto_ptr<Y>& p;
auto_ptr_ref (const auto_ptr<Y>&);
};
public:
typedef X element_type;
// constructor/copy/destroy
explicit auto_ptr (X* = 0) throw();
auto_ptr (const auto_ptr<X>&) throw ();
template <class Y>
auto_ptr (const auto_ptr<Y>&) throw();
void operator=(const auto_ptr<X>&) throw():
template <class Y>
void operator= (const auto_ptr<Y>&) throw();
~auto_ptr ();
// members
X& operator* () const throw();
X* operator-> () const throw();
X* get () const throw();
X* release () throw();
void reset (X*=0) throw();
auto_ptr(auto_ptr_ref<X>) throw();
template <class Y>
operator auto_ptr_ref<Y>() throw();
template <class Y>
operator auto_ptr<Y>() throw();
};
TYPES
template <class Y>
class auto_ptr_ref;
A private class template that holds a reference to an
auto_ptr. It can only be constructed within an auto_ptr
using a reference to an auto_ptr. It prevents unsafe
copying.
CONSTRUCTORS
explicit
auto_ptr (X* p = 0);
Constructs an object of class auto_ptr<X>, initializing
the held pointer to p, and acquiring ownership of that
pointer. p must point to an object of class X or a class
derived from X for which delete p is defined and accessi-
ble, or p must be a null pointer.
auto_ptr (const auto_ptr<X>& a);
template <class Y>
auto_ptr (const auto_ptr<Y>& a);
Constructs an object of class auto_ptr<X>, and copies the
argument a to *this. If a owned the underlying pointer,
then *this becomes the new owner of that pointer.
auto_ptr (const auto_ptr_ref<X> r);
Constructs an auto_ptr from an auto_ptr_ref.
DESTRUCTORS
~auto_ptr ();
Deletes the underlying pointer.
OPERATORS
void operator= (const auto_ptr<X>& a);
template <class Y>
void operator= (const auto_ptr<Y>& a);
Copies the argument a to *this. If a owned the underlying
pointer, then *this becomes the new owner of that
pointer. If *this already owned a pointer, then that
pointer is deleted first.
X&
operator* () const;
Returns a reference to the object to which the underlying
pointer points.
X*
operator-> () const;
Returns the underlying pointer.
template <class Y>
operator auto_ptr_ref<Y> ();
Constructs an auto_ptr_ref from *this and returns it.
template <class Y>
operator auto_ptr<Y> ();
Constructs a new auto_ptr using the underlying pointer
held by *this. Calls release() on *this, so *this no
longer possesses the pointer. Returns the new auto_ptr.
MEMBER FUNCTIONS
X*
get () const;
Returns the underlying pointer.
X*
release();
Releases ownership of the underlying pointer. Returns
that pointer.
void
reset(X* p)
Sets the underlying pointer to p. If non-null, deletes
the old underlying pointer.
EXAMPLE
//
// auto_ptr.cpp
//
#include <iostream>
#include <memory>
using namespace std;
//
// A simple structure.
//
struct X
{
X (int i = 0) : m_i(i) { }
int get() const { return m_i; }
int m_i;
};
int main ()
{
//
// b will hold a pointer to an X.
//
auto_ptr<X> b(new X(12345));
//
// a will now be the owner of the underlying pointer.
//
auto_ptr<X> a = b;
//
// Output the value contained by
// the underlying pointer.
//
cout << a->get() << endl;
//
// The pointer will be deleted when a is destroyed on
// leaving scope.
//
return 0;
}
Program Output
12345