Apache C++ Standard Library Reference Guide

## allocator

Library: General utilities

    Does not inherit

- Local Index
- Summary
- Synopsis
- Specializations
- Description
- Interface
- Member Types
- Constructors
- Destructors
- Member Functions
- See Also
- Standards Conformance

### Local Index

#### Members

address() allocate() allocator() construct() | const_pointer const_reference deallocate() destroy() | difference_type max_size() pointer reference | size_type template <class U> struct rebind; value_type ~allocator()

### Summary

The default allocator object for storage management in C++ Standard Library containers

### Synopsis

    #include <memory>

    namespace std {
      template <class T>
      class allocator;
    }

### Specializations

    namespace std {
      template <> class allocator<void>;
    }

### Description

Containers in the C++ Standard Library allow you to control storage management through the use of allocator objects. Each container class has an allocator template parameter specifying the type of allocator to be used. Every constructor, except the copy constructor, has an allocator parameter, allowing you to pass in a specific allocator. A container uses that allocator for all storage management.

The library has a default allocator, called allocator. This allocator uses the global `new()` and `delete()` operators. By default, all containers use this allocator. You can also design your own allocator, but if you do so it must have an appropriate interface.

### Interface

    namespace std {

      template <class T>
      class allocator {
        typedef size_t            size_type;
        typedef ptrdiff_t         difference_type;
        typedef T*                pointer;
        typedef const T*          const_pointer;
        typedef T&                reference;
        typedef const T&          const_reference;
        typedef T                 value_type;

        template <class U> struct rebind {
          typedef allocator<U> other;
        };
        allocator () throw();
        allocator (const allocator&) throw ();
        template <class U>
        allocator(const allocator<U>&) throw();
        template <class U>
        allocator& operator=(const allocator<U>&) throw();
        ~allocator () throw();
        pointer address(reference) const;
        const_pointer address(const_reference) const;
        pointer allocate (size_type,
          typename allocator<void>::const_pointer = 0);
        void deallocate(pointer p, size_type n);
        size_type max_size() const throw();
        void construct(pointer, const T&);
        void destroy(pointer);
      };

      // globals
      template <class T, class U>
      bool operator==(const allocator<T>&,
                      const allocator<U>&) throw();
      template <class T, class U>
      bool operator!=(const allocator<T>&,
                      const allocator<U>&) throw();
    }

### Member Types

    size_type

Type used to hold the size of an allocated block of storage.

    difference_type

Type used to hold values representing distances between storage addresses.

    pointer

Type of pointer returned by allocator.

    const_pointer

`Const` version of `pointer`.

    reference

Type of reference to allocated objects.

    const_reference

`Const` version of `reference`.

    value_type

Type of allocated object.

    template <class U> struct rebind;

Converts an allocator templatized on one type to an allocator templatized on another type. This struct contains a single type member:

`typedef allocator<U> other`

### Constructors

    allocator()

Default constructor.

    template <class U>
    allocator(const allocator<U>&)

Copy constructor.

### Destructors

    ~allocator()

Destructor.

### Member Functions

    pointer
    address(reference x) const;

Returns the address of the reference `x` as a pointer.

    const_pointer
    address(const_reference x) const;

Returns the address of the reference `x` as a `const_pointer`.

    pointer
    allocate(size_type n,
             typename allocator<void>::const_pointer p = 0)

Allocates storage. Returns a pointer to the first element in a block of storage `n*sizeof(T)` bytes in size. The block is aligned appropriately for objects of type `T`. Throws the exception bad_alloc if the storage is unavailable. This function uses operator `new(size_t)`. The second parameter `p` can be used by an allocator to localize memory allocation, but the default allocator does not use it.

    void
    deallocate(pointer p, size_type n)

Deallocates the storage obtained by a call to `allocate()` with arguments `n` and `p`.

    size_type
    max_size() const;

Returns the largest size for which a call to `allocate()` might succeed.

    void
    construct(pointer p, const T& val);

Constructs an object of type `T2` with the initial value of `val` at the location specified by `p`. This function calls the `placement new()` operator.

    void
    destroy(pointer p)

Calls the destructor on the object pointed to by `p`, but does not delete.

### See Also

Containers

### Standards Conformance

ISO/IEC 14882:1998 -- International Standard for Information Systems -- Programming Language C++, Section 20.4.1