# <memory>

<head><title>&lt;memory&gt;</title></head>

# `<memory>`

* * *

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

* * *

Include the [STL](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#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 stdCopy to clipboard

## `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();
        };Copy to clipboard

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`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_memory.html#allocator::pointer)
-- behaves like a pointer to `Ty`
- [`const_pointer`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_memory.html#allocator::const_pointer)
-- behaves like a
const pointer to `Ty`
- [`reference`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_memory.html#allocator::reference)
-- behaves like a reference to `Ty`
- [`const_reference`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_memory.html#allocator::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;Copy to clipboard

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);Copy to clipboard

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();Copy to clipboard

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;Copy to clipboard

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;Copy to clipboard

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);Copy to clipboard

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);Copy to clipboard

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);Copy to clipboard

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

### `allocator::difference_type`

    typedef ptrdiff_t difference_type;Copy to clipboard

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();Copy to clipboard

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);Copy to clipboard

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;Copy to clipboard

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;
        };Copy to clipboard

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)Copy to clipboard

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

    A::rebind<Other>::other::pointerCopy to clipboard

### `allocator::reference`

    typedef Ty& reference;Copy to clipboard

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;Copy to clipboard

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;Copy to clipboard

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>);
        };Copy to clipboard

The class explicitly specializes template class
[allocator](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_memory.html#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`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_memory.html#allocator::const_pointer),
[`pointer`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_memory.html#allocator::pointer),
[`value_type`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_memory.html#allocator::value_type),
and the nested template class
[`rebind`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_memory.html#allocator::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);
        };Copy to clipboard

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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_cont.html#Containers).

### `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();Copy to clipboard

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();Copy to clipboard

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

### `auto_ptr::element_type`

    typedef Ty element_type;Copy to clipboard

The type is a synonym for the template parameter `Ty`.

### `auto_ptr::get`

    Ty *get() const throw();Copy to clipboard

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();Copy to clipboard

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();Copy to clipboard

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

### `auto_ptr::operator->`

    Ty *operator->() const throw();Copy to clipboard

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();Copy to clipboard

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();Copy to clipboard

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

### `auto_ptr::release`

    Ty *release() throw();Copy to clipboard

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);Copy to clipboard

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 {
        };Copy to clipboard

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);Copy to clipboard

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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#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);Copy to clipboard

is replaced by:

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

## `operator!=`

    template<class Ty>
        bool operator!=(const allocator<Ty>& left,
            const allocator<Ty>& right) throw();Copy to clipboard

The template operator returns false.
(All default allocators are equal.)

## `operator==`

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

The template operator returns true.
(All default allocators are equal.)

## `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);
        };Copy to clipboard

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*();Copy to clipboard

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);Copy to clipboard

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);Copy to clipboard

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);Copy to clipboard

The constructor stores `first` as the output iterator
object.

## `return_temporary_buffer`

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

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);Copy to clipboard

The template function effectively executes:

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

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);Copy to clipboard

The template function effectively executes:

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

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);Copy to clipboard

The template function effectively executes:

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

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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#Table%20of%20Contents)** and the
**[Index](https://docs.qualcomm.com/doc/80-N3040-23/topic/_cpp_index.html)**.

*[Copyright](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_crit_pjp.html) © 1992-2006by P.J. Plauger. Portions derived from work[copyright](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_crit_hp.html) © 1994by Hewlett-Packard Company. All rights reserved.*

<!--V5.01:1566-->

Last Published: Oct 06, 2026

Previous Topic
 
<math.h></math.h> Next Topic

<new></new>