Compleat

Embedded

Searching...

`<memory>`

allocator · auto_ptr · auto_ptr_ref · get_temporary_buffer · operator!== · operator== · raw_storage_iterator · uninitialized_copy · uninitialized_fill · uninitialized_fill_n

bad_weak_ptr · const_pointer_cast · dynamic_pointer_cast · enable_shared_from_this · get_deleter · operator< · operator<< · shared_ptr · static_pointer_cast · swap · weak_ptr

Include the STL standard header <memory> to define a class, an operator, and several templates that help allocate and free objects.

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==(allocator<Ty>& left,
        allocator<Ty>& right);
template<class Ty>
    bool operator!=(allocator<Ty>& left,
        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);

    namespace tr1 {  [added with TR1]
        // TEMPLATE SHARED POINTERS
template<class Ty>
    class shared_ptr;

template<class Ty1, class Ty2>
    bool operator==(const shared_ptr<Ty1>&,
        const shared_ptr<Ty2>&);
template<class Ty1, class Ty2>
    bool operator!=(const shared_ptr<Ty1>&,
        const shared_ptr<Ty2>&);
template<class Ty1, class Ty2>
    bool operator<(const shared_ptr<Ty1>&,
        const shared_ptr<Ty2>&);
template<class Elem, class Tr, class Ty>
    std::basic_ostream<Elem, Tr>& operator<<(
        std::basic_ostream<Elem, Tr>&, const shared_ptr<Ty>&);
template<class Ty>
    void swap(shared_ptr<Ty>&, shared_ptr<Ty>&);
template<class D, class Ty>
    D *get_deleter(const shared_ptr<Ty>&);

        // TEMPLATE WEAK POINTERS
template<class Ty>
    class weak_ptr;

template<class Ty1, class Ty2>
    bool operator<(const weak_ptr<Ty1>&,
        const weak_ptr<Ty2>&);
template<class Ty>
    void swap(weak_ptr<Ty>&, weak_ptr<Ty>&);

        // UTILITY TEMPLATE CLASSES
template<class Ty>
    class enable_shared_from_this;
class bad_weak_ptr;

        // TEMPLATE FUNCTIONS
template<class Ty, class Other>
    shared_ptr<Ty> const_pointer_cast(const shared_ptr<Other>&);
template<class Ty, class Other>
    shared_ptr<Ty> dynamic_pointer_cast(const shared_ptr<Other>&);
template<class Ty, class Other>
    shared_ptr<Ty> static_pointer_cast(const shared_ptr<Other>&);
    } // namespace tr1
}  // namespace std

`allocator`

template<class Ty>
    class allocator {
public:
    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, allocator<void>::const_pointer Other *hint = 0);
    void deallocate(pointer ptr, size_type count);
    void construct(pointer ptr, const Ty& val);
    void destroy(pointer ptr);
    size_type max_size() const throw();
    };

The template class describes an object that manages storage allocation and freeing for arrays of objects of 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):

pointer -- behaves like a pointer to Ty
const_pointer -- behaves like a const pointer to Ty
reference -- behaves like a reference to Ty
const_reference -- behaves like a const reference to Ty

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.)

`allocator::address`

pointer address(reference val) const;
const_pointer address(const_reference val) 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, 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::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).

`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::construct`

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

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

`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::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::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.

`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::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::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

`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.

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

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() const throw();
    void reset(Ty *ptr = 0);
    };

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 excepiton. 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.

`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.

`auto_ptr::~auto_ptr`

~auto_ptr();

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

`auto_ptr::element_type`

typedef Ty element_type;

The type is a synonym for the template parameter Ty.

`auto_ptr::get`

Ty *get() const throw();

The member function returns the stored pointer myptr.

`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).

`auto_ptr::release`

Ty *release() throw();

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

`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.

`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.

`bad_weak_ptr`

class bad_weak_ptr  [added with TR1]
    : public std::exception {
public:
    bad_weak_ptr();
    const char *what() throw();
    };

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".

`const_pointer_cast`

template <class Ty, class Other>  [added with TR1]
    shared_ptr<Ty> const_pointer_cast(const shared_ptr<Other>& sp);

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>  [added with TR1]
    shared_ptr<Ty> dynamic_pointer_cast(const shared_ptr<Other>& sp);

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.

`enable_shared_from_this`

template<class Ty>  [added with TR1]
    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();
    };

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 assigment operator are protected to help prevent accidental misuse. The template argument type Ty must be the type of the derived class.

`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.

`get_deleter`

template<class D, class Ty>  [added with TR1]
    D *get_deleter(const shared_ptr<Ty>& sp);

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 Ty>
    bool operator!=(const allocator<Ty>& left,
        const allocator<Ty>& right) throw();
template<class Ty1, class Ty2>  [added with TR1]
    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>  [added with TR1]
    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().

`operator<`

template<class Ty1, class Ty2>  [added with TR1]
    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);

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>  [added with TR1]
    std::basic_ostream<Elem, Tr>& operator<<(std::basic_ostream<Elem, Tr>& out, shared_ptr<Ty>& sp);

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

`raw_storage_iterator`

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);
    };

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.

`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.

`raw_storage_iterator::raw_storage_iterator`

explicit raw_storage_iterator(FwdIt first);

The constructor stores first as the output iterator object.

`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.

`shared_ptr`

template<class Ty>
    class shared_ptr {  [added with TR1]
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;
    };

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 {};

shared_ptr<D> sp0(new D);   // okay, template parameter D and argument D*
shared_ptr<D> sp1(sp0);     // okay, template parameter D and argument shared_ptr<D>
shared_ptr<B> sp2(new D);   // okay, D* convertible to B*
shared_ptr<B> sp3(sp0);     // okay, template parameter B and argument shared_ptr<D>
shared_ptr<B> sp4(sp2);     // okay, template parameter B and argument shared_ptr<B>
shared_ptr<int> sp4(new D); // error, D* not convertible to int*
shared_ptr<int> sp5(sp2);   // error, template parameter int and argument shared_ptr<B>

A shared_ptr object owns a resource:

if it was constructed with a pointer to that 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 ownership of that resource was assigned to it, either with operator= or by calling the member function reset.

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:

no arguments -- the resulting object is an empty shared_ptr object or an empty weak_ptr object.
ptr -- a pointer of type Other* to the resource to be managed. Ty must be a complete type. If the function fails it evaluates the expression delete ptr.
ptr, dtor -- a pointer of type Other* to the resource to be managed and a deleter for that resource. If the function fails it calls dtor(ptr), which must be well defined.
sp -- a shared_ptr<Other> object that owns the resource to be managed.
wp -- a weak_ptr<Other> object that points to the resource to be managed.
ap -- an auto_ptr<Other> object that holds a pointer to the resource to be managed. If the function succeeds it calls ap.release(); otherwise it leaves ap unchanged.

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

`shared_ptr::element_type`

typedef Ty element_type;

The type is a synonym for the template parameter Ty.

`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::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.

`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::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().

`shared_ptr::~shared_ptr`

~shared_ptr();

The destructor releases the resource owned by *this.

`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.

`static_pointer_cast`

template <class Ty, class Other>  [added with TR1]
    shared_ptr<Ty> static_pointer_cast(const shared_ptr<Other>& sp);

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>  [added with TR1]
    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);

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.

`weak_ptr`

template<class Ty> class weak_ptr {  [added with TR1]
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;
    };

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.

`weak_ptr::element_type`

typedef Ty element_type;

The type is a synonym for the template parameter Ty.

`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::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.

`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.

`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.

See also the Table of Contents and the Index.