auto_ptr

auto_ptr is a class template available in the C++ Standard Library (declared in the <memory> header file) that provides some basic RAII features for C++ raw pointers.

The auto_ptr template class describes an object that stores a pointer to a single allocated object of type Type* that ensures that the object to which it points gets destroyed automatically when control leaves a scope.

The shared_ptr template class defined in C++11, and available in the Boost library, can be used as an alternative to auto_ptr for collections with ownership semantics.

The current C++ standard, C++11, made auto_ptr deprecated, replacing it with the unique_ptr class template.

Declaration

The auto_ptr class is declared in ISO/IEC 14882, section 20.4.5 as:

namespace std {
 
    template <class Y> struct auto_ptr_ref {};
 
    template <class X>
    class auto_ptr {
    public:
        typedef X element_type;
 
        // 20.4.5.1 construct/copy/destroy:
        explicit           auto_ptr(X* p =0) throw();
                           auto_ptr(auto_ptr&) throw();
        template <class Y> auto_ptr(auto_ptr<Y>&) throw();
 
        auto_ptr&                      operator=(auto_ptr&) throw();
        template <class Y> auto_ptr&   operator=(auto_ptr<Y>&) throw();
        auto_ptr&                      operator=(auto_ptr_ref<X>) throw();
 
        ~auto_ptr() throw();
 
        // 20.4.5.2 members:
        X&     operator*() const throw();
        X*     operator->() const throw();
        X*     get() const throw();
        X*     release() throw();
        void   reset(X* p =0) throw();
 
        // 20.4.5.3 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();
    };
 
}

Semantics

The auto_ptr has semantics of strict ownership, meaning that the auto_ptr instance is the sole entity responsible for the object's lifetime. If an auto_ptr is copied, the source loses the reference. For example:

#include <iostream>
#include <memory>
using namespace std;
 
int main(int argc, char **argv)
{
    int *i = new int;
    auto_ptr<int> x(i);
    auto_ptr<int> y;
 
    y = x;
 
    cout << x.get() << endl; // Print NULL
    cout << y.get() << endl; // Print non-NULL address i
 
    return 0;
}

This code will print a NULL address for the first auto_ptr object and some non-NULL address for the second, showing that the source object lost the reference during the assignment (=). The raw pointer i in the example should not be deleted, as it will be deleted by the auto_ptr that owns the reference. In fact, new int could be passed directly into x, eliminating the need for i.

Notice that the object pointed by an auto_ptr is destroyed using operator delete; this means that you should only use auto_ptr for pointers obtained with operator new. This excludes pointers returned by malloc/calloc/realloc, and pointers to arrays (because arrays are allocated by operator new[] and must be deallocated by operator delete[]).

Because of its copy semantics, auto_ptr may not be used in STL containers that may perform element copies in their operations.

However, an auto_ptr containing an STL container may be used to prevent further modification of the container.

#include <iostream>
#include <vector>
#include <memory> 
#include <map>
 
using namespace std;
 
typedef int ContainedType;
 
int main() {
 
    auto_ptr<vector<ContainedType> > open_vec(new vector<ContainedType>);
 
    open_vec->push_back(5);
    open_vec->push_back(3);
    open_vec->push_back(1);
 
    // Transfers control, but now the vector cannot be changed:
    auto_ptr<const vector<ContainedType> > closed_vec(open_vec); 
 
    // closed_vec->push_back(8); // Can no longer modify 
 
    // Safe during the lifetime of the autoptr:
    map<string, const ContainedType *> nmap;
 
    nmap["First"]  = & closed_vec->at(0);
    nmap["Second"] = & closed_vec->at(1);
    nmap["Third"]  = & closed_vec->at(2);
 
    for (map<string, const ContainedType *>::iterator it = nmap.begin(); it != nmap.end(); ++it) {
        cout << it->first << " -> " << *(it->second) << std::endl;
    }
 
    return 0;
}

See also

• Smart pointer
• Generic programming

External links

• Using auto_ptr effectively
• Avoiding Memory Leaks with auto_ptr
• Article "Using the auto_ptr Class Template to Facilitate Dynamic Memory Management" by Danny Kalev
• Article "Container of auto_ptr" by Zeeshan Amjad
• Article "Update on auto_ptr" by Scott Meyers
• auto_ptr Class Template Reference from GNU libstdc++
• auto_ptr reference from Rogue Wave