<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.