<memory>

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

allocator

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

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 stored in right, by storing right.release() in myptr. 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 {
    auto_ptr_ref(auto_ptr<Ty>& right);
    };

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.

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!=(allocator<Ty>& left,
        allocator<Ty>& right) throw();

The template operator returns false.

operator==

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

The template operator returns true. (Two allocator objects should compare equal only if an object allocated through one can be deallocated through the other. If the value of one object is determined from another by assignment or by construction, the two object should compare equal.)

raw_storage_iterator

template<class FwdIt, class Ty>
    class raw_storage_iterator
         : public iterator<output_iterator_tag,
             void, void, void, void> {
public:
    typedef FwdIt iter_type;
    typedef Ty element_type;
    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::element_type

typedef Ty element_type;

The type is a synonym for the template parameter Ty.

raw_storage_iterator::iter_type

typedef FwdIt iter_type;

The type is a synonym for the template parameter FwdIt.

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.

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.

See also the Table of Contents and the Index.

Copyright © 1994-2002 by P.J. Plauger. Portions derived from work copyright © 1994 by Hewlett-Packard Company. All rights reserved.