Standard C++	Library
 		 Copyright 1996, Rogue Wave Software, Inc.

 NAME

   allocator - The default allocator object for storage management in
   Standard Library containers.

 SYNOPSIS

   #include <memory>
   template <class T>
   class	allocator;

 DESCRIPTION

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

   The library provides 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 provide an
   appropriate  interface.  The standard interface is specified below.

 STANDARD INTERFACE

   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;
    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);
    size_type max_size () const;
    void	construct (pointer, const T&);
    void	destroy	(pointer);
   };

   // specialize	for void:
    template <> class allocator<void> {
    public:
      typedef size_t	 size_type;
      typedef ptrdiff_t	 difference_type;
      typedef void*	 pointer;
      typedef const void* const_pointer;
       //  reference-to-void members are	impossible.
      typedef void  value_type;
      template <class U>
        struct rebind { typedef allocator<U> other; };

      allocator() throw();
      template <class U>
        allocator(const allocator<U>&) throw();
      template <class U>
        allocator operator=(const allocator<U>&)	throw();
      ~allocator() throw();

      pointer allocate(size_type, const void* hint);
      void deallocate(pointer p);
      size_type max_size() const	throw();
     };

   // globals
   template <class T>
    void* operator new(size_t N,	allocator<T>& a);
   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();

 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;
      Provides a	way to convert an allocator templated on one type to
      an	allocator templated on	another	type.  This struct contains a
      single type member:  typedef allocator<U> other.

 OPERATIONS

   allocator()
      Default constructor.

   template <class U>
   allocator(const allocator<U>&)
      Copy constructor.

   template <class U>
   allocator& operator=(const allocator<U>&) throw()>&)
      Assignment	operator.

   ~allocator()
      Destructor.

   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  will
      be 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)
      Deallocates the storage indicated by p.  The storage must have
      been obtained by a call	to allocate.

   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 the container section of the Class Reference for a further
   description of how to use	the alternate allocator	within a
   user-defined container.

 SEE ALSO

   container

 STANDARDS CONFORMANCE
   ANSI X3J16/ISO WG21 Joint C++	Committee