Apache C++ Standard Library Reference Guide

## auto_ptr

Library: General utilities

    Does not inherit

- Local Index
- Summary
- Synopsis
- Description
- Interface
- Struct auto_ptr_ref
- Typedef
- Constructors
- Destructors
- Operators
- Member Functions
- Example
- Standards Conformance

### Local Index

#### Members

auto_ptr() auto_ptr_ref element_type | get() operator auto_ptr<Y>() operator auto_ptr_ref<Y>() | operator*() operator->() operator=() | release() reset() ~auto_ptr()

### Summary

A simple smart pointer class

### Synopsis

    #include <memory>

    namespace std {
      template <class X> class auto_ptr;
    }

### Description

The class template specialization auto_ptr holds onto a pointer obtained via `new()` and then deletes that object when the auto_ptr object itself is destroyed. 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

    namespace std {

      template <class Y> struct auto_ptr_ref {};
      template <class X> class auto_ptr {
         public:
           typedef X element_type;

           // construct/copy/destroy
           explicit auto_ptr (X* p = 0) throw();
           auto_ptr(auto_ptr<X>&) throw ();
           template <class Y>
           auto_ptr(auto_ptr<Y>&) throw();
           auto_ptr<X>& operator=(auto_ptr<X>&) throw();
           template <class Y>
           auto_ptr<X>& operator= (auto_ptr<Y>&) throw();
           ~auto_ptr() throw();

           // members
           X& operator* () const throw();
           X* operator-> () const throw();
           X* get () const throw();
           X* release() throw();
           void reset(X* p = 0) throw();

           // conversions
           auto_ptr(auto_ptr_ref<X>) throw();
           template <class Y> operator auto_ptr_ref<Y>() throw();
           template <class Y> operator auto_ptr<Y>() throw();
      };
    }

### Struct auto_ptr_ref

    template <class Y>
    struct auto_ptr_ref;

A namespace-scope struct template that holds a reference to an auto_ptr. An auto_ptr_ref can only be constructed within an auto_ptr using a reference to an auto_ptr. It prevents unsafe copying.

### Typedef

    typedef X element_type;

The type of element pointed to by auto_ptr.

### Constructors

    explicit
    auto_ptr (X* p = 0) throw();

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`, a class derived from `X` for which `delete p` is defined and accessible, or `p` must be a null pointer.

    auto_ptr (auto_ptr<X>& a) throw();
    template <class Y>
    auto_ptr (auto_ptr<Y>& a) throw();

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.

For the constructor template, each specialization requires that a pointer to `Y` be implicitly convertible to pointer to `element_type`.

    auto_ptr (auto_ptr_ref<X> r) throw();

Constructs an auto_ptr from an auto_ptr_ref.

### Destructors

    ~auto_ptr () throw();

Deletes the underlying pointer.

### Operators

    auto_ptr<X>& operator=(auto_ptr<X>& a) throw();
    template <class Y>
    auto_ptr<X>& operator=(auto_ptr<Y>& a) throw();

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, that pointer is deleted first. The argument `a` is reset to zero.

For the function template, each specialization requires that a pointer to `Y` be implicitly convertible to pointer to `element_type`.

    X&
    operator*() const throw();

Returns a reference to the object to which the underlying pointer points.

    X*
    operator->() const throw();

Returns the underlying pointer.

    template <class Y>
    operator auto_ptr_ref<Y>() throw();

Constructs an auto_ptr_ref from `*this` and returns it.

    template <class Y>
    operator auto_ptr<Y>() throw();

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 throw();

Returns the underlying pointer.

    X*
    release() throw();

Releases ownership of the underlying pointer and returns that pointer. The `*this` object is left holding a null pointer.

    void
    reset(X* p = 0) throw();

Sets the underlying pointer to `p`. If non-null, deletes the old underlying pointer.

### Example

    //
    // auto_ptr.cpp
    //

    #include <iostream>   // for cout, endl
    #include <memory>     // for auto_ptr

    // A simple structure.
    class X
    {
        int i_;

    public:

        X (int i) : i_ (i) {
            std::cout << "X::X (" << i_ << ')' << std::endl;
        }

        ~X () {
            std::cout << "X::~X [" << i_ << ']' << std::endl;
        }

        int get () const { return i_; }
    };

    int main ()
    {
        // a implicitly initialized to 0 (the null pointer)
        std::auto_ptr<X> a;

        // Establish a scope.
        if (1) {
            // b will hold a pointer to an X.
            std::auto_ptr<X> b (new X (12345));

            // a will now be the owner of
            // the underlying pointer.
            a = b;
        }

        std::cout << "b destroyed" << std::endl;

            // Output the value contained by
            // the underlying pointer.
    #ifndef _RWSTD_NO_NONCLASS_ARROW_RETURN
            std::cout << a->get () << std::endl;
    #else
            std::cout << (*a).get () << std::endl;
    #endif

        // The pointer will be deleted when a is destroyed
        // on leaving scope.
        return 0;
    }

    Program Output:

X::X (12345)

b destroyed

12345

X::~X [12345]

### Standards Conformance

ISO/IEC 14882:1998 -- International Standard for Information Systems -- Programming Language C++, Section 20.4.5