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 accessible, 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
 

Rogue Wave Software  —  Last change: 02 Apr 1998