<memory>

Description
Synopsis
Classes
Functions
Operators

Description

Include the STL standard header <memory> to define a class, an operator, and several templates that help allocate and free objects. As well, <memory> defines the smart pointer templates auto_ptr, shared_ptr, and weak_ptr to assist in the management of dynamically allocated objects.

Note:
Additional functionality has been added to this header for TR1. To enable this functionality, you must define the macro __IBMCPP_TR1__ .

Synopsis

namespace std {
template<class Ty>
    class allocator;
template<>
    class allocator<void>;
template<class FwdIt, class Ty>
    class raw_storage_iterator;
template<class Ty>
    class auto_ptr;
template<class Ty>
    class auto_ptr_ref;

        // TEMPLATE OPERATORS
template<class Ty>
    bool operator==(const allocator<Ty>& left,
        const allocator<Ty>& right);
template<class Ty>
    bool operator!=(const allocator<Ty>& left,
        const allocator<Ty>& right);

        // TEMPLATE FUNCTIONS
template<class Ty>
    pair<Ty *, ptrdiff_t>
        get_temporary_buffer(ptrdiff_t count);
template<class Ty>
    void return_temporary_buffer(Ty *pbuf);
template<class InIt, class FwdIt>
    FwdIt uninitialized_copy(InIt first, InIt last,
        FwdIt dest);
template<class FwdIt, class Ty>
    void uninitialized_fill(FwdIt first, FwdIt last,
        const Ty& val);
template<class FwdIt, class Size, class Ty>
    void uninitialized_fill_n(FwdIt first, Size count,
        const Ty& val);
    }

Classes

allocator
allocator<void>
auto_ptr
bad_weak_ptr
enable_shared_from_this
raw_storage_iterator
shared_ptr
weak_ptr

allocator

Description
Synopsis
Constructor
allocator::allocator
Types
allocator::const_pointer
allocator::const_reference
allocator::difference_type
allocator::pointer
allocator::reference
allocator::size_type
allocator::value_type
Member classes
allocator::rebind
Member functions
allocator::address
allocator::allocate
allocator::construct
allocator::deallocate
allocator::destroy
allocator::max_size
Operators
allocator::operator=
Description

The template class describes an object that manages storage allocation and freeing for arrays of objects of non-const, non-reference, object type Ty. An object of class allocator is the default allocator object specified in the constructors for several container template classes in the Standard C++ library.

Template class allocator supplies several type definitions that are rather pedestrian. They hardly seem worth defining. But another class with the same members might choose more interesting alternatives. Constructing a container with an allocator object of such a class gives individual control over allocation and freeing of elements controlled by that container.

For example, an allocator object might allocate storage on a private heap. Or it might allocate storage on a far heap, requiring nonstandard pointers to access the allocated objects. Or it might specify, through the type definitions it supplies, that elements be accessed through special accessor objects that manage shared memory, or perform automatic garbage collection. Hence, a class that allocates storage using an allocator object should use these types religiously for declaring pointer and reference objects (as do the containers in the Standard C++ library).

Thus, an allocator defines the types (among others):

These types specify the form that pointers and references must take for allocated elements. (allocator::pointer is not necessarily the same as Ty * for all allocator objects, even though it has this obvious definition for class allocator.)

Related information

Synopsis
template<class Ty>
    class allocator {
    typedef size_t size_type;
    typedef ptrdiff_t difference_type;
    typedef Ty *pointer;
    typedef const Ty *const_pointer;
    typedef Ty& reference;
    typedef const Ty& const_reference;
    typedef Ty value_type;
    pointer address(reference val) const;
    const_pointer address(const_reference val) const;
    template<class Other>
        struct rebind;
    allocator() throw();
    template<class Other>
        allocator(const allocator<Other>& right) throw();
    template<class Other>
        allocator& operator=(const allocator<Other>& right);
    pointer allocate(size_type count,
        typename allocator<void>::const_pointer *hint = 0);
    void deallocate(pointer ptr, size_type count);
    void construct(pointer ptr, const Ty& val);
    void construct(pointer ptr, Ty&& val);
    void destroy(pointer ptr);
    size_type max_size() const throw();
    };
Constructor
allocator::allocator

allocator() throw();
template<class Other>
    allocator(const allocator<Other>& right) throw();

The constructor does nothing. In general, however, an allocator object constructed from another allocator object should compare equal to it (and hence permit intermixing of object allocation and freeing between the two allocator objects).

Types
allocator::const_pointer

typedef const Ty *pointer;

The pointer type describes an object ptr that can designate, via the expression *ptr, any const object that an object of template class allocator can allocate.

allocator::const_reference

typedef const Ty& const_reference;

The reference type describes an object that can designate any const object that an object of template class allocator can allocate.

allocator::difference_type

typedef ptrdiff_t difference_type;

The signed integer type describes an object that can represent the difference between the addresses of any two elements in a sequence that an object of template class allocator can allocate.

allocator::pointer

typedef Ty *pointer;

The pointer type describes an object ptr that can designate, via the expression *ptr, any object that an object of template class allocator can allocate.

allocator::reference

typedef Ty& reference;

The reference type describes an object that can designate any object that an object of template class allocator can allocate.

allocator::size_type

typedef size_t size_type;

The unsigned integer type describes an object that can represent the length of any sequence that an object of template class allocator can allocate.

allocator::value_type

typedef Ty value_type;

The type is a synonym for the template parameter Ty.

Member classes
allocator::rebind

template<class Other>
    struct rebind {
    typedef allocator<Other> other;
    };

The member template class defines the type other. Its sole purpose is to provide the type name allocator<Other> given the type name allocator<Ty>.

For example, given an allocator object al of type A, you can allocate an object of type Other with the expression:

A::rebind<Other>::other(al).allocate(1, (Other *)0)

Or, you can simply name its pointer type by writing the type:

A::rebind<Other>::other::pointer
Member functions
allocator::address

pointer address(reference val) const;
const_pointer address(const_reference x) const;

The member functions return the address of val, in the form that pointers must take for allocated elements.

allocator::allocate

pointer allocate(size_type count,
    typename allocator<void>::const_pointer *hint = 0);

The member function allocates storage for an array of count elements of type Ty, by calling operator new(count). It returns a pointer to the allocated object. The hint argument helps some allocators in improving locality of reference — a valid choice is the address of an object earlier allocated by the same allocator object, and not yet deallocated. To supply no hint, use a null pointer argument instead.

allocator::construct

void construct(pointer ptr, const Ty& val);
void construct(pointer ptr, Ty&& val);

The first member function constructs an object of type Ty at ptr by evaluating the placement new expression new ((void *)ptr) Ty(val).

The second member function is the same as the first one, but with an (rvalue reference).

allocator::deallocate

void deallocate(pointer ptr, size_type count);

The member function frees storage for the array of count objects of type Ty beginning at ptr, by calling operator delete(ptr). The pointer ptr must have been earlier returned by a call to allocate for an allocator object that compares equal to *this, allocating an array object of the same size and type. deallocate never throws an exception.

allocator::destroy

void destroy(pointer ptr);

The member function destroys the object designated by ptr, by calling the destructor ptr->Ty::~Ty().

allocator::max_size

size_type max_size() const throw();

The member function returns the length of the longest sequence of elements of type Ty that an object of class allocator might be able to allocate.

Operators
allocator::operator=

template<class Other>
    allocator& operator=(const allocator<Other>& right);

The template assignment operator does nothing. In general, however, an allocator object assigned to another allocator object should compare equal to it (and hence permit intermixing of object allocation and freeing between the two allocator objects).

allocator<void>

template<>
    class allocator<void> {
    typedef void *pointer;
    typedef const void *const_pointer;
    typedef void value_type;
    template<class Other>
        struct rebind;
    allocator() throw();
    template<class Other>
        allocator(const allocator<Other>) throw();
    template<class Other>
        allocator<void>& operator=(const allocator<Other>);
    };

The class explicitly specializes template class allocator for type void. Its constructors and assignment operator behave the same as for the template class, but it defines only the types const_pointer, pointer, value_type, and the nested template class rebind.

auto_ptr

Description
Synopsis
Constructor
auto_ptr::auto_ptr
Destructor
auto_ptr::~auto_ptr
Types
auto_ptr::element_type
Classes
auto_ptr_ref
Member functions
auto_ptr::get
auto_ptr::reset
Operators
auto_ptr::operator=
auto_ptr::operator*
auto_ptr::operator->
auto_ptr::operator auto_ptr<Other>
auto_ptr::operator auto_ptr_ref<Other>
Members
auto_ptr::release
Description

The class describes an object that stores a pointer to an allocated object myptr of type Ty *. The stored pointer must either be null or designate an object allocated by a new expression. An object constructed with a non-null pointer owns the pointer. It transfers ownership if its stored value is assigned to another object. (It replaces the stored value after a transfer with a null pointer.) The destructor for auto_ptr<Ty> deletes the allocated object if it owns it. Hence, an object of class auto_ptr<Ty> ensures that an allocated object is automatically deleted when control leaves a block, even via a thrown exception. You should not construct two auto_ptr<Ty> objects that own the same object.

You can pass an auto_ptr<Ty> object by value as an argument to a function call. You can return such an object by value as well. (Both operations depend on the implicit construction of intermediate objects of class auto_ptr_ref<Ty>, by various subtle conversion rules.) You cannot, however, reliably manage a sequence of auto_ptr<Ty> objects with an STL container.

Synopsis
template<class Ty>
    class auto_ptr {
public:
    typedef Ty element_type;
    explicit auto_ptr(Ty *ptr = 0) throw();
    auto_ptr(auto_ptr<Ty>& right) throw();
    template<class Other>
        auto_ptr(auto_ptr<Other>& right) throw();
    auto_ptr(auto_ptr_ref<Ty> right) throw();
    ~auto_ptr();
    template<class Other>
        operator auto_ptr<Other>() throw();
    template<class Other>
        operator auto_ptr_ref<Other>() throw();
    template<class Other>
        auto_ptr<Ty>& operator=(auto_ptr<Other>& right) throw();
    auto_ptr<Ty>& operator=(auto_ptr<Ty>& right) throw();
    auto_ptr<Ty>& operator=(auto_ptr_ref<Ty>& right) throw();
    Ty& operator*() const throw();
    Ty *operator->() const throw();
    Ty *get() const throw();
    Ty *release() throw();
    void reset(Ty *ptr = 0);
    };
Constructor
auto_ptr::auto_ptr

explicit auto_ptr(Ty *ptr = 0) throw();
auto_ptr(auto_ptr<Ty>& right) throw();
auto_ptr(auto_ptr_ref<Ty> right) throw();
template<class Other>
    auto_ptr(auto_ptr<Other>& right) throw();

The first constructor stores ptr in myptr, the stored pointer to the allocated object. The second constructor transfers ownership of the pointer stored in right, by storing right.release(). in myptr. The third constructor behaves the same as the second, except that it stores right.ref.release() in myptr, where ref is the reference stored in right.

The template constructor behaves the same as the second constructor, provided that a pointer to Other can be implicitly converted to a pointer to Ty.

Destructor
auto_ptr::~auto_ptr

~auto_ptr();

The destructor evaluates the expression delete myptr to delete the object designated by the stored pointer.

Types
auto_ptr::element_type

typedef Ty element_type;

The type is a synonym for the template parameter Ty.

Classes
auto_ptr_ref

template<Class Ty>
    struct auto_ptr_ref {
    };

The class describes an object that stores a reference to an object of class auto_ptr<Ty> It is used as a helper class for auto_ptr<Ty> You should not have an occasion to construct an auto_ptr_ref<Ty> object directly.

Member functions
auto_ptr::get

Ty *get() const throw();

The member function returns the stored pointer myptr.

auto_ptr::reset

void reset(Ty *ptr = 0);

The member function evaluates the expression delete myptr, but only if the stored pointer value myptr changes as a result of function call. It then replaces the stored pointer with ptr.

Operators
auto_ptr::operator=

template<class Other>
    auto_ptr<Ty>& operator=(auto_ptr<Other>& right) throw();
auto_ptr<Ty>& operator=(auto_ptr<>& right) throw();
auto_ptr<Ty>& operator=(auto_ptr_ref<>& right) throw();

The assignment evaluates the expression delete myptr, but only if the stored pointer myptr changes as a result of the assignment. It then transfers ownership of the pointer designated by right, by storing right.release() in myptr. (The last assignment behaves as if right designates the reference it stores.) The function returns *this.

auto_ptr::operator*

Ty& operator*() const throw();

The indirection operator returns *get(). Hence, the stored pointer must not be null.

auto_ptr::operator->

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

The selection operator returns get(), so that the expression ap->member behaves the same as (ap.get())->member, where ap is an object of class auto_ptr<Ty>. Hence, the stored pointer must not be null, and Ty must be a class, structure, or union type with a member member.

auto_ptr::operator auto_ptr<Other>

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

The type cast operator returns auto_ptr<Other>(*this).

auto_ptr::operator auto_ptr_ref<Other>

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

The type cast operator returns auto_ptr_ref<Other>(*this).

Members
auto_ptr::release

Ty *release() throw();

The member replaces the stored pointer myptr with a null pointer and returns the previously stored pointer.

bad_weak_ptr

class bad_weak_ptr
    : public std::exception {
public:
    bad_weak_ptr();
    const char *what() throw();
    };

[Added with TR1]

The class describes an exception that can be thrown from the shared_ptr constructor that takes an argument of type weak_ptr. The member function what returns “tr1::bad_weak_ptr”.

enable_shared_from_this

Description
Synopsis
Member functions
enable_shared_from_this::shared_from_this
Description

[Added with TR1]

The template class can be used as a public base class to simplify creating shared_ptr objects that own objects of the derived type:

class derived
    : public enable_shared_from_this<derived>
    {
    };

shared_ptr<derived> sp0 = new derived;
shared_ptr<derived> sp1 = sp0->shared_from_this();

The constructors, destructor, and assignment operator are protected to help prevent accidental misuse. The template argument type Ty must be the type of the derived class.

Synopsis
template<class Ty>
    class enable_shared_from_this {
public:
    shared_ptr<Ty> shared_from_this();
    shared_ptr<const Ty> shared_from_this() const;

protected:
    enable_shared_from_this();
    enable_shared_from_this(const enable_shared_from_this&);
    enable_shared_from_this& operator=(const enable_shared_from_this&);
    ~enable_shared_from_this();
    };
Member functions
enable_shared_from_this::shared_from_this

shared_ptr<Ty> shared_from_this();
shared_ptr<const Ty> shared_from_this() const;

The member functions each return a shared_ptr object that owns *(Ty*)this.

raw_storage_iterator

Description
Synopsis
Constructor
raw_storage_iterator::raw_storage_iterator
Operators
raw_storage_iterator::operator*
raw_storage_iterator::operator=
raw_storage_iterator::operator++
Description

The class describes an output iterator that constructs objects of type Ty in the sequence it generates. An object of class raw_storage_iterator<FwdIt, Ty> accesses storage through a forward iterator object, of class FwdIt, that you specify when you construct the object. For an object first of class FwdIt, the expression &*first must designate unconstructed storage for the next object (of type Ty) in the generated sequence.

Synopsis
template<class FwdIt, class Ty>
    class raw_storage_iterator
         : public iterator<output_iterator_tag,
             void, void, void, void> {
public:
    explicit raw_storage_iterator(FwdIt first);
    raw_storage_iterator<FwdIt, Ty>& operator*();
    raw_storage_iterator<FwdIt, Ty>&
        operator=(const Ty& val);
    raw_storage_iterator<FwdIt, Ty>& operator++();
    raw_storage_iterator<FwdIt, Ty> operator++(int);
    };
Constructor
raw_storage_iterator::raw_storage_iterator

explicit raw_storage_iterator(FwdIt first);

The constructor stores first as the output iterator object.

Operators
raw_storage_iterator::operator*

raw_storage_iterator<FwdIt, Ty>& operator*();

The indirection operator returns *this (so that operator=(const Ty&) can perform the actual store in an expression such as *ptr = val).

raw_storage_iterator::operator=

raw_storage_iterator<FwdIt, Ty>& operator=(const Ty& val);

The assignment operator constructs the next object in the output sequence using the stored iterator value first, by evaluating the placement new expression new ((void *)&*first) Ty(val). The function returns *this.

raw_storage_iterator::operator++

raw_storage_iterator<FwdIt, Ty>& operator++();
raw_storage_iterator<FwdIt, Ty> operator++(int);

The first (preincrement) operator increments the stored output iterator object, then returns *this.

The second (postincrement) operator makes a copy of *this, increments the stored output iterator object, then returns the copy.

shared_ptr

Description
Synopsis
Constructor
shared_ptr::shared_ptr
Destructor
shared_ptr::~shared_ptr
Types
shared_ptr::element_type
Member functions
shared_ptr::get
shared_ptr::reset
shared_ptr::swap
shared_ptr::unique
shared_ptr::use_count
Operators
shared_ptr::operator=
shared_ptr::operator*
shared_ptr::operator->
shared_ptr::operator boolean-type
Description

[Added with TR1]

The template class describes an object that uses reference counting to manage resources. Each shared_ptr object effectively holds a pointer to the resource that it owns or holds a null pointer. A resource can be owned by more than one shared_ptr object; when the last shared_ptr object that owns a particular resource is destroyed the resource is freed.

The template argument Ty may be an incomplete type except as noted for certain operand sequences.

When a shared_ptr<Ty> object is constructed from a resource pointer of type D* or from a shared_ptr<D>, the pointer type D* must be convertible to Ty*. If it is not, the code will not compile. For example:

class B {};
class D : public B {};

// okay, template parameter D and argument D*
shared_ptr<D> sp0(new D);

// okay, template parameter D and argument shared_ptr<D>
shared_ptr<D> sp1(sp0);

// okay, D* convertible to B*
shared_ptr<B> sp2(new D);

 // okay, template parameter B and argument shared_ptr<D>
shared_ptr<B> sp3(sp0);

// okay, template parameter B and argument shared_ptr<B>
shared_ptr<B> sp4(sp2);

// error, D* not convertible to int* 
shared_ptr<int> sp4(new D);

// error, template parameter int and argument shared_ptr<B>
shared_ptr<int> sp5(sp2);   

A shared_ptr object owns a resource:

All the shared_ptr objects that own a single resource share a control block which holds the number of shared_ptr objects that own the resource, the number of weak_ptr objects that point to the resource, and the deleter for that resource if it has one. A shared_ptr object that was initialized with a null pointer has a control block; thus it is not an (empty shared_ptr). After a shared_ptr object releases a resource it no longer owns that resource. After a weak_ptr object releases a resource it no longer points to that resource. When the number of shared_ptr objects that own a resource becomes zero the resource is freed, either by deleting it or by passing its address to a deleter, depending on how ownership of the resource was originally created. When the number of shared_ptr objects that own a resource is zero and the number of weak_ptr objects that point to that resource is zero the control block is freed.

An empty shared_ptr object does not own any resources and has no control block.

A deleter is a function pointer or an object of a type with a member function operator(). Its type must be copy constructible and its copy constructor and destructor must not throw exceptions. A deleter is bound to a shared_ptr object with an operand sequence of the form ptr, dtor.

Some functions take an operand sequence that defines properties of the resulting shared_ptr<Ty> or weak_ptr<Ty> object. You can specify such an operand sequence several ways:

In all cases, the pointer type Other* must be convertible to Ty*.

Synopsis
template<class Ty>
    class shared_ptr {
public:
    typedef Ty element_type;

    shared_ptr();
    template<class Other>
        explicit shared_ptr(Other*);
    template<class Other, class D>
        shared_ptr(Other*, D);
    shared_ptr(const shared_ptr&);
    template<class Other>
        shared_ptr(const shared_ptr<Other>&);
    template<class Other>
        shared_ptr(const weak_ptr<Other>&);
    template<class &>
        shared_ptr(const std::auto_ptr<Other>&);
    ~shared_ptr();

    shared_ptr& operator=(const shared_ptr&);
    template<class Other>
        shared_ptr& operator=(const shared_ptr<Other>&);
    template<class Other>
        shared_ptr& operator=(auto_ptr<Other>&);

    void swap(shared_ptr&);
    void reset();
    template<class Other>
        void reset(Other*);
    template<class Other, class D>
        void reset(Other*, D);

    Ty *get() const;
    Ty& operator*() const;
    Ty *operator->() const;
    long use_count() const;
    bool unique() const;
    operator boolean-type() const;
    };
Constructor
shared_ptr::shared_ptr

shared_ptr();

template<class Other>
    explicit shared_ptr(Other *ptr);
template<class Other, class D>
    shared_ptr(Other *ptr, D dtor);
shared_ptr(const shared_ptr& sp);
template<class Other>
    shared_ptr(const shared_ptr<Other>& sp);
template<class Other>
    shared_ptr(const weak_ptr<Other>& wp);
template<class Other>
    shared_ptr(const std::auto_ptr<Other>& ap);

The constructors each construct an object that owns the resource named by the (operand sequence). The constructor shared_ptr(const weak_ptr<Other>& wp) throws an exception object of type bad_weak_ptr if wp.expired().

Destructor
shared_ptr::~shared_ptr

~shared_ptr();

The destructor releases the resource owned by *this.

Types
shared_ptr::element_type

typedef Ty element_type;

The type is a synonym for the template parameter Ty.

Member functions
shared_ptr::get

Ty *get() const;

The member function returns the address of the owned resource. If the object does not own a resource it returns 0.

shared_ptr::reset

void reset();
template<class Other>
    void reset(Other *ptr;);
template<class Other, class D>
    void reset(Other *ptr, D dtor);

The member functions all release the resource currently owned by *this and assign ownership of the resource named by the (operand sequence) to *this. If a member function fails it leaves *this unchanged.

shared_ptr::swap

void swap(shared_ptr& sp);

The member function leaves the resource originally owned by *this subsequently owned by sp, and the resource originally owned by sp subsequently owned by *this. The function does not change the reference counts for the two resources and it does not throw any exceptions.

shared_ptr::unique

bool unique() const;

The member function returns true if no other shared_ptr object owns the resource that is owned by *this, otherwise false.

shared_ptr::use_count

long use_count() const;

The member function returns the number of shared_ptr objects that own the resource that is owned by *this.

Operators
shared_ptr::operator=

shared_ptr& operator=(const shared_ptr& sp);
template<class Other>
    shared_ptr& operator=(const shared_ptr<Other>& sp);
template<class Other>
    shared_ptr& operator=(auto_ptr<Other>& ap);

The operators all release the resource currently owned by *this and assign ownership of the resource named by the operand sequence to *this. If an operator fails it leaves *this unchanged.

shared_ptr::operator*

Ty& operator*() const;

The indirection operator returns *get(). Hence, the stored pointer must not be null.

shared_ptr::operator->

Ty *operator->() const;

The selection operator returns get(), so that the expression sp->member behaves the same as (sp.get())->member where sp is an object of class shared_ptr<Ty>. Hence, the stored pointer must not be null, and Ty must be a class, structure, or union type with a member member.

shared_ptr::operator boolean-type

operator boolean-type() const;

The operator returns a value of a type that is convertible to bool. The result of the conversion to bool is true when get() != 0, otherwise false.

weak_ptr

Description
Synopsis
Constructor
weak_ptr::weak_ptr
Types
weak_ptr::element_type
Member functions
weak_ptr::expired
weak_ptr::lock
weak_ptr::reset
weak_ptr::swap
weak_ptr::use_count
Operators
weak_ptr::operator=
Description

[Added with TR1]

The template class describes an object that points to a resource that is managed by one or more shared_ptr objects. The weak_ptr objects that point to a resource do not affect the resource's reference count. Thus, when the last shared_ptr object that manages that resource is destroyed the resource will be freed, even if there are weak_ptr objects pointing to that resource. This is essential for avoiding cycles in data structures.

A weak_ptr object points to a resource if it was constructed from a shared_ptr object that owns that resource, if it was constructed from a weak_ptr object that points to that resource, or if that resource was assigned to it with operator=. A weak_ptr object does not provide direct access to the resource that it points to. Code that needs to use the resource does so through a shared_ptr object that owns that resource, created by calling the member function lock. A weak_ptr object has expired when the resource that it points to has been freed because all of the shared_ptr objects that own the resource have been destroyed. Calling lock on a weak_ptr object that has expired creates an empty shared_ptr object.

An empty weak_ptr object does not point to any resources and has no control block. Its member function lock returns an empty shared_ptr object.

A cycle occurs when two or more resources controlled by shared_ptr objects hold mutually referencing shared_ptr objects. For example, a circular linked list with three elements has a head node N0; that node holds a shared_ptr object that owns the next node, N1; that node holds a shared_ptr object that owns the next node, N2; that node, in turn, holds a shared_ptr object that owns the head node, N0, closing the cycle. In this situation, none of the reference counts will every become zero, and the nodes in the cycle will not be freed. To eliminate the cycle, the last node N2 should hold a weak_ptr object pointing to N0 instead of a smart_ptr object. Since the weak_ptr object does not own N0 it doesn't affect N0's reference count, and when the program's last reference to the head node is destroyed the nodes in the list will also be destroyed.

Synopsis
template<class Ty> class weak_ptr {
public:
    typedef Ty element_type;

    weak_ptr();
    weak_ptr(const weak_ptr&);
    template<class Other>
        weak_ptr(const weak_ptr<Other>&);
    template<class Other>
        weak_ptr(const shared_ptr<Other>&);

    weak_ptr& operator=(const weak_ptr&);
    template<class Other>
        weak_ptr& operator=(const weak_ptr<Other>&);
    template<class Other>
        weak_ptr& operator=(shared_ptr<Other>&);

    void swap(weak_ptr&);
    void reset();

    long use_count() const;
    bool expired() const;
    shared_ptr<Ty> lock() const;
    };
Constructor
weak_ptr::weak_ptr

weak_ptr();
weak_ptr(const weak_ptr& wp);
template<class Other>
    weak_ptr(const weak_ptr<Other>& wp);
template<class Other>
    weak_ptr(const shared_ptr<Other>& sp);

The constructors each construct an object that points to the resource named by the operand sequence.

Types
weak_ptr::element_type

typedef Ty element_type;

The type is a synonym for the template parameter Ty.

Member functions
weak_ptr::expired

bool expired() const;

The member function returns true if *this has expired, otherwise false.

weak_ptr::lock

shared_ptr<Ty> lock() const;

The member function returns an empty shared_ptr object if *this has expired; otherwise it returns a shared_ptr<Ty> object that owns the resource that *this points to.

weak_ptr::reset

void reset();

The member function releases the resource pointed to by *this and converts *this to an empty weak_ptr object.

weak_ptr::swap

void swap(weak_ptr& wp);

The member function leaves the resource originally pointed to by *this subsequently pointed to by wp, and the resource originally pointed to by wp subsequently pointed to by *this. The function does not change the reference counts for the two resources and it does not throw any exceptions.

weak_ptr::use_count

long use_count() const;

The member function returns the number of shared_ptr objects that own the resource pointed to by *this.

Operators
weak_ptr::operator=

weak_ptr& operator=(const weak_ptr& wp);
template<class Other>
    weak_ptr& operator=(const weak_ptr<Other>& wp);
template<class Other>
    weak_ptr& operator=(const shared_ptr<Other>& sp);

The operators all release the resource currently pointed to by *this and assign ownership of the resource named by the operand sequence to *this. If an operator fails it leaves *this unchanged.

Functions

const_pointer_cast
dynamic_pointer_cast
get_deleter
get_temporary_buffer
operator<
operator<<
return_temporary_buffer
static_pointer_cast
swap
uninitialized_copy
uninitialized_fill
uninitialized_fill_n

const_pointer_cast

template <class Ty, class Other>
    shared_ptr<Ty> const_pointer_cast(const shared_ptr<Other>& sp);

[Added with TR1]

The template function returns an empty shared_ptr object if const_cast<Ty*>(sp.get()) returns a null pointer; otherwise it returns a shared_ptr<Ty> object that owns the resource that is owned by sp. The expression const_cast<Ty*>(sp.get()) must be valid.

dynamic_pointer_cast

template <class Ty, class Other>
    shared_ptr<Ty> dynamic_pointer_cast(const shared_ptr<Other>& sp);

[Added with TR1]

The template function returns an empty shared_ptr object if dynamic_cast<Ty*>(sp.get()) returns a null pointer; otherwise it returns a shared_ptr<Ty> object that owns the resource that is owned by sp. The expression dynamic_cast<Ty*>(sp.get()) must be valid.

get_deleter

template<class D, class Ty>
    D *get_deleter(const shared_ptr<Ty>& sp);

[Added with TR1]

The template function returns a pointer to the deleter of type D that belongs to the shared_ptr object sp. If sp has no deleter or if its deleter is not of type D the function returns 0.

get_temporary_buffer

template<class Ty>
    pair<Ty *, ptrdiff_t>
        get_temporary_buffer(ptrdiff_t count);

The template function allocates storage for a sequence of at most count elements of type Ty, from an unspecified source (which may well be the standard heap used by operator new). It returns a value pr, of type pair<Ty *, ptrdiff_t>. If the function allocates storage, pr.first designates the allocated storage and pr.second is the number of elements in the longest sequence the storage can hold. Otherwise, pr.first is a null pointer.

In this implementation, if a translator does not support member template functions, the template:

template<class Ty>
    pair<Ty *, ptrdiff_t>
        get_temporary_buffer(ptrdiff_t count);

is replaced by:

template<class Ty>
    pair<Ty *, ptrdiff_t>
        get_temporary_buffer(ptrdiff_t count, Ty *);

operator<

template<class Ty1, class Ty2>
    bool operator<(const shared_ptr<Ty1>& left, const shared_ptr<Ty2>& right);
template<class Ty1, class Ty2>
    bool operator<(const weak_ptr<Ty1>& left, const weak_ptr<Ty2>& right);

[Added with TR1]

The template functions impose a strict weak ordering on objects of their respective types. The actual ordering is implementation-specific, except that !(left < right) && !(right < left) is true only when left and right own or point to the same resource. The ordering imposed by these functions enables the use of shared_ptr and weak_ptr objects as keys in associative containers.

operator<<

template<class Elem, class Tr, class Ty>
    std::basic_ostream<Elem, Tr>& operator<<(std::basic_ostream<Elem, Tr>& out, 
    shared_ptr<Ty>& sp);

[Added with TR1]

The template function returns out << sp.get().

return_temporary_buffer

template<class Ty>
    void return_temporary_buffer(Ty *pbuf);

The template function frees the storage designated by pbuf, which must be earlier allocated by a call to get_temporary_buffer.

static_pointer_cast

template <class Ty, class Other>
    shared_ptr<Ty> static_pointer_cast(const shared_ptr<Other>& sp);

[Added with TR1]

The template function returns an empty shared_ptr object if sp is an empty shared_ptr object; otherwise it returns a shared_ptr<Ty> object that owns the resource that is owned by sp. The expression static_cast<Ty*>(sp.get()) must be valid.

swap

template<class Ty, class Other>
    void swap(shared_ptr<Ty>& left, shared_ptr<Other>& right);
template<class Ty, class Other>
    void swap(weak_ptr<Ty>& left, weak_ptr<Other>& right);

[Added with TR1]

The template functions call left.swap(right).

uninitialized_copy

template<class InIt, class FwdIt>
    FwdIt uninitialized_copy(InIt first, InIt last,
        FwdIt dest);

The template function effectively executes:

while (first != last)
    new ((void *)&*dest++)
        iterator_traits<InIt>::value_type(*first++);
return first;

unless the code throws an exception. In that case, all constructed objects are destroyed and the exception is rethrown.

uninitialized_fill

template<class FwdIt, class Ty>
    void uninitialized_fill(FwdIt first, FwdIt last,
        const Ty& val);

The template function effectively executes:

while (first != last)
    new ((void *)&*first++)
        iterator_traits<FwdIt>::value_type(val);

unless the code throws an exception. In that case, all constructed objects are destroyed and the exception is rethrown.

uninitialized_fill_n

template<class FwdIt, class Size, class Ty>
    void uninitialized_fill_n(FwdIt first, Size count,
        const Ty& val);

The template function effectively executes:

while (0 < count--)
    new ((void *)&*first++)
        iterator_traits<FwdIt>::value_type(val);

unless the code throws an exception. In that case, all constructed objects are destroyed and the exception is rethrown.

Operators

operator!=
operator==

operator!=

template<class Ty>
    bool operator!=(const allocator<Ty>& left,
        const allocator<Ty>& right) throw();
template<class Ty1, class Ty2>
    bool operator!=(const shared_ptr<Ty1>& left,
        const shared_ptr<Ty2>& right);

The first template operator returns false. (All default allocators are equal.) The second template operator returns !(left == right).

operator==

template<class Ty>
    bool operator==(const allocator<Ty>& left,
        const allocator<Ty>& right) throw();
template<class Ty1, class Ty2>
    bool operator==(const shared_ptr<Ty1>& left,
        const shared_ptr<Ty2>& right);

The first template operator returns true. (All default allocators are equal.) The second template operator returns left.get() == right.get().

Copyright note

Certain materials included or referred to in this document are copyright P.J. Plauger and/or Dinkumware, Ltd. or are based on materials that are copyright P.J. Plauger and/or Dinkumware, Ltd.

Certain materials included or referred to in this document are copyright Hewlett-Packard Company or are based on materials that are copyright Hewlett-Packard Company.

Notwithstanding the meta-data for this document, copyright information for this document is as follows:

Copyright © IBM Corp. 1999, 2010. & Copyright © P.J. Plauger and/or Dinkumware, Ltd. 1992-2006. & Copyright © 1994 Hewlett-Packard Company.