## auto_ptr

    Memory Management

- Summary
- Data Type and Member Function Indexes
- Synopsis
- Description
- Interface
- Types
- Constructors
- Destructors
- Operators
- Member Functions
- Example

### Summary

A simple, smart pointer class.

### Data Type and Member Function Indexes
(exclusive of constructors and destructors)

Data Types
auto_ptr_ref operator

Member Functions
get() operator*() operator->() operator=() release() reset() |

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

Copyright (c) 1998, Rogue Wave Software, Inc.
Send mail to report errors or comment on the documentation.
OEM Release, June 1998