<memory>namespace std {
// TEMPLATE CLASSES
template<class T>
class allocator;
template<>
class allocator<void>;
template<class FwdIt, class T>
class raw_storage_iterator;
template<class T>
class auto_ptr;
// TEMPLATE OPERATORS
template<class T>
bool operator==(allocator<T>& lhs,
allocator<T>& rhs);
template<class T>
bool operator!=(allocator<T>& lhs,
allocator<T>& rhs);
// TEMPLATE FUNCTIONS
template<class T>
pair<T *, ptrdiff_t>
get_temporary_buffer(ptrdiff_t n);
template<class T>
void return_temporary_buffer(T *p);
template<class InIt, class FwdIt>
FwdIt uninitialized_copy(InIt first, InIt last,
FwdIt result);
template<class FwdIt, class T>
void uninitialized_fill(FwdIt first, FwdIt last,
const T& x);
template<class FwdIt, class Size, class T>
void uninitialized_fill_n(FwdIt first, Size n,
const T& x);
};
Include the STL
standard header <memory> to define a
class, an operator, and several templates that help allocate and
free objects.
allocatortemplate<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;
pointer address(reference x) const;
const_pointer address(const_reference x) const;
template<class U>
struct rebind;
allocator();
template<class U>
allocator(const allocator<U>& x);
template<class U>
allocator& operator=(const allocator<U>& x);
template<class U>
pointer allocate(size_type n, const U *hint);
void deallocate(pointer p, size_type n);
void construct(pointer p, const T& val);
void destroy(pointer p);
size_type max_size() const;
};
The template class describes an object that manages storage
allocation and freeing for arrays of objects of type T.
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 T const_pointer
-- behaves like a const pointer to T reference
-- behaves like a reference to T const_reference
-- behaves like a const reference to T These types specify the form that pointers and references must
take for allocated elements. (allocator::pointer is
not necessarily the same as T * for all allocator
objects, even though it has this obvious definition for class allocator.)
allocator::addresspointer address(reference x) const; const_pointer address(const_reference x) const;
The member functions return the address of x, in
the form that pointers must take for allocated elements.
allocator::allocatetemplate<class U>
pointer allocate(size_type n, const U *hint);
The member function allocates storage for an array of n
elements of type T, by calling operator new(n).
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::allocatorallocator();
template<class U>
allocator(const allocator<U>& x);
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_pointertypedef const T *pointer;
The pointer type describes an object p that can
designate, via the expression *p, any const object
that an object of template class allocator can
allocate.
allocator::const_referencetypedef const T& const_reference;
The reference type describes an object x that can
designate any const object that an object of template class allocator
can allocate.
allocator::constructvoid construct(pointer p, const T& val);
The member function constructs an object of type T
at p by evaluating the placement new
expression new ((void *)p) T(val).
allocator::deallocatevoid deallocate(pointer p, size_type n);
The member function frees storage for the array of n
objects of type T beginning at p, by
calling operator delete(p). The pointer p
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::destroyvoid destroy(pointer p);
The member function destroys the object designated by p,
by calling p->T::~T().
allocator::difference_typetypedef 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_sizesize_type max_size() const;
The member function returns the length of the longest sequence
of elements of type T that an object of class allocator
might be able to allocate.
allocator::operator=template<class U>
allocator& operator=(const allocator<U>& x);
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::pointertypedef T *pointer;
The pointer type describes an object p that can
designate, via the expression *p, any object that an
object of template class allocator can allocate.
allocator::rebindtemplate<class U>
struct rebind {
typedef allocator<U> other;
};
The member template class defines the type other. Its sole purpose is
to provide the type name allocator<U> given
the type name allocator<T>.
For example, given an allocator object al of type
A, you can allocate an object of type U
with the expression:
A::rebind<U>::other(al).allocate(1, (U *)0)
Or, you can simply name its pointer type by writing the type:
A::rebind<U>::other::pointer
allocator::referencetypedef T& reference;
The reference type describes an object x that can
designate any object that an object of template class allocator
can allocate.
allocator::size_typetypedef 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_typetypedef T value_type;
The type is a synonym for the template parameter T.
allocator<void>template<>
class allocator<void> {
typedef void *pointer;
typedef const void *const_pointer;
typedef void value_type;
template<class U>
struct rebind;
allocator();
template<class U>
allocator(const allocator<U>);
template<class U>
operator=(const allocator<U>);
};
The class explicitly specializes template class allocator
for type void. It defines only the types const_pointer,
pointer,
value_type,
and the nested template class rebind.
auto_ptrtemplate<class T>
class auto_ptr {
public:
typedef T element_type;
explicit auto_ptr(T *p = 0) throw();
auto_ptr(const auto_ptr<T>& rhs) throw();
template<class U>
auto_ptr(const auto_ptr<U>& rhs) throw();
template<class U>
auto_ptr<T>& operator=(auto_ptr<U>& rhs) throw();
auto_ptr<T>& operator=(auto_ptr<T>& rhs) throw();
~auto_ptr();
T& operator*() const throw();
T *operator->() const throw();
T *get() const throw();
T *release() const throw();
};
The class describes an object that stores a pointer to an
allocated object of type T. The stored pointer must
either be null or designate an object allocated by a new
expression. The object also stores an ownership indicator. An object
constructed with a non-null pointer owns the pointer. It
transfers ownership if its stored value is assigned to another
object. The destructor for auto_ptr<T> deletes
the allocated object if it owns it. Hence, an object of class auto_ptr<T>
ensures that an allocated object is automatically deleted when
control leaves a block, even via a thrown excepiton.
auto_ptr::auto_ptrexplicit auto_ptr(T *p = 0) throw();
auto_ptr(const auto_ptr(auto_ptr<T>& rhs) throw();
template<class U>
auto_ptr(const auto_ptr(auto_ptr<U>& rhs) throw();
The first constructor stores p as the pointer to
the allocated object. It stores true as the ownership indicator
only if p != 0. The second constructor transfers
ownership of the pointer stored in rhs, by storing
both the pointer value and the ownership indicator from rhs
in the constructed object. It effectively releases the pointer by
calling rhs.release().
auto_ptr::~auto_ptr~auto_ptr();
If the ownership indicator
is true, the destructor deletes the object designated by the
stored pointer p by evaluating the delete
expression delete p.
auto_ptr::element_typetypedef T element_type;
The type is a synonym for the template parameter T.
auto_ptr::getT *get() const throw();
The member function returns the stored pointer.
auto_ptr::operator=template<class U>
auto_ptr<T>& operator=(auto_ptr<U>& rhs) throw();
auto_ptr<T>& operator=(auto_ptr<>& rhs) throw();
The assignment operator deletes any pointer p
that it owns, by evaluating the delete expression delete
p. It then transfers ownership of the pointer stored in rhs,
by storing both the pointer value and the ownership indicator
from rhs in *this. It effectively
releases the pointer by calling rhs.release(). The
function returns *this.
auto_ptr::operator*T& operator*() const throw();
The indirection operator effectively returns *get().
Hence, the stored pointer must not be null.
auto_ptr::operator->T *operator->() const throw();
The selection operator effectively returns get(),
so that the expression al->m behaves the same as (al.get())->m,
where al is an object of class auto_ptr<T>.
Hence, the stored pointer must not be null, and T
must be a class, structure, or union type.
auto_ptr::releaseT *release() throw();
The member function sets the ownership indicator to false, then returns the stored pointer.
get_temporary_buffertemplate<class T>
pair<T *, ptrdiff_t>
get_temporary_buffer(ptrdiff_t n);
The template function allocates storage for a sequence of at
most n elements of type T, from an
unspecified source (which may well be the standard heap used by operator
new). It returns a value pr, of type pair<T *, 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.
operator!=template<class T>
bool operator!=(allocator<T>& lhs,
allocator<T>& rhs);
The template operator returns false.
operator==template<class T>
bool operator==(allocator<T>& lhs,
allocator<T>& rhs);
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_iteratortemplate<class FwdIt, class T>
class raw_storage_iterator
: public iterator<output_iterator_tag,
void, void, void, void> {
public:
typedef FwdIt iter_type;
typedef T element_type;
explicit raw_storage_iterator(FwdIt it);
raw_storage_iterator<FwdIt, T>& operator*();
raw_storage_iterator<FwdIt, T>&
operator=(const T& val);
raw_storage_iterator<FwdIt, T>& operator++();
raw_storage_iterator<FwdIt, T> operator++(int);
};
The class describes an output iterator that constructs objects
of type T in the sequence it generates. An object of
class raw_storage_iterator<FwdIt, T> accesses
storage through a forward iterator object, of class FwdIt,
that you specify when you construct the object. For an object it
of class FwdIt, the expression &*it
must designate unconstructed storage for the next object (of type
T) in the generated sequence.
raw_storage_iterator::element_typetypedef T element_type;
The type is a synonym for the template parameter T.
raw_storage_iterator::iter_typetypedef FwdIt iter_type;
The type is a synonym for the template parameter FwdIt.
raw_storage_iterator::operator*raw_storage_iterator<FwdIt, T>& operator*();
The indirection operator returns *this (so that operator=(const
T&) can perform the actual store in an expression such
as *x = val).
raw_storage_iterator::operator=raw_storage_iterator<FwdIt, T>& operator=(const T& val);
The assignment operator constructs the next object in the
output sequence using the stored iterator value it,
by evaluating the placement new expression new
((void *)&*it) T(val). The function returns *this.
raw_storage_iterator::operator++raw_storage_iterator<FwdIt, T>& operator++(); raw_storage_iterator<FwdIt, T> 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_iteratorexplicit raw_storage_iterator(FwdIt it);
The constructor stores it as the output iterator
object.
return_temporary_buffertemplate<class T>
void return_temporary_buffer(T *p);
The template function frees the storage designated by p,
which must be earlier allocated by a call to get_temporary_buffer.
uninitialized_copytemplate<class InIt, class FwdIt>
FwdIt uninitialized_copy(InIt first, InIt last,
FwdIt result);
The template function effectively executes:
while (first != last)
new ((void *)&*result++) U(*first++);
where U is the type of *first.
uninitialized filltemplate<class FwdIt, class T>
void uninitialized_fill(FwdIt first, FwdIt last,
const T& x);
The template function effectively executes:
while (first != last)
new ((void *)&*first++) U(x);
where U is the type of *first.
uninitialized_fill_ntemplate<class FwdIt, class Size, class T>
void uninitialized_fill_n(FwdIt first, Size n,
const T& x);
The template function effectively executes:
while (0 < n--)
new ((void *)&*first++) U(x);
where U is the type of *first.
See also the Table of Contents .
Copyright © 1992-1996 by P.J. Plauger. Portions derived from work copyright © 1994 by Hewlett-Packard Company. All rights reserved.