<new>
Include the standard header <new>
to define several types and functions that control allocation and
freeing of storage under program control.
Some of the functions declared in this header are replaceable. The implementation supplies a default version, whose behavior is described in this document. A program can, however, define a function with the same signature to replace the default version at link time. The replacement version must satisfy the requirements described in this document.
// DECLARATIONS typedef void (*new_handler)(); class bad_alloc; class nothrow_t; extern const nothrow_t nothrow; // FUNCTIONS new_handler set_new_handler(new_handler pnew) throw(); // OPERATORS void operator delete(void *ptr) throw(); // REPLACEABLE void operator delete(void *, void *) throw(); void operator delete(void *ptr, // REPLACEABLE const nothrow_t&) throw(); void operator delete[](void *ptr) throw(); // REPLACEABLE void operator delete[](void *, void *) throw(); void operator delete[](void *ptr, // REPLACEABLE const nothrow_t&) throw(); void *operator new(size_t count) // REPLACEABLE throw(bad_alloc); void *operator new(size_t count, // REPLACEABLE const nothrow_t&) throw(); void *operator new(size_t count, void *ptr) throw(); void *operator new[](size_t count) // REPLACEABLE throw(bad_alloc); void *operator new[](size_t count, // REPLACEABLE const nothrow_t&) throw(); void *operator new[](size_t count, void *ptr) throw(); // END OF DECLARATIONS
bad_alloc
class bad_alloc : public exception { };
The class describes an exception thrown to indicate that
an allocation request did not succeed. The value returned by
what()
is an implementation-defined
C string.
None of the member functions throw any exceptions.
new_handler
typedef void (*new_handler)();
The type describes a pointer object that designates a function suitable for use as a new handler.
nothrow
extern const nothrow_t nothrow;
The object is used as a function argument to
match the parameter type
nothrow_t
.
nothrow_t
class nothrow_t {};
The class is used as a function parameter to
operator new
to indicate that the function should
return a null pointer to report an allocation failure,
rather than throw an exception.
operator delete
void operator delete(void *ptr) throw(); // REPLACEABLE void operator delete(void *, void *) throw(); void operator delete(void *ptr, // REPLACEABLE const nothrow_t&) throw();
The first function is called by a
delete
expression
to render the value of ptr
invalid.
The program can define a function with this function signature that
replaces
the default version defined by the
Standard C++ library. The required behavior is to accept a value of
ptr
that is null or that was returned by an earlier call to
operator new(size_t)
.
The default behavior for a null value of ptr
is
to do nothing. Any other value of ptr
must be a value returned
earlier by a call as described above.
The default behavior for such a non-null value of ptr
is to
reclaim storage allocated by the earlier call.
It is unspecified under what conditions part or all
of such reclaimed storage is allocated by a subsequent call to
operator new(size_t)
,
or to any of
calloc(size_t)
,
malloc(size_t)
, or
realloc(void*, size_t)
.
The second function is called by a
placement
delete
expression corresponding to a
new
expression
of the form
new(size_t)
.
It does nothing.
The third function is called by a placement
delete
expression corresponding to a
new
expression of the form
new(size_t, const nothrow_t&)
.
The program can define a function with this function signature that
replaces
the default version defined by the
Standard C++ library. The required behavior is to accept a value of
ptr
that is null or that was returned by an earlier call to
operator new(size_t)
.
The default behavior is to evaluate delete(ptr)
.
operator delete[]
void operator delete[](void *ptr) throw(); // REPLACEABLE void operator delete[](void *, void *) throw(); void operator delete[](void *ptr, // REPLACEABLE const nothrow_t&) throw();
The first function is called by a
delete[]
expression
to render the value of ptr
invalid.
The program can define a function with this function signature that
replaces
the default version defined by the
Standard C++ library.
The required behavior is to accept a value of ptr
that is null or that was returned by an earlier call to
operator new[](size_t)
.
The default behavior is to evaluate delete(ptr)
.
The second function is called by a
placement
delete[]
expression corresponding to a
new[]
expression of the form
new[](size_t)
.
It does nothing.
The third function is called by a placement
delete
expression corresponding to a
new[]
expression of the form
new[](size_t, const nothrow_t&)
.
The program can define a function with this function signature that
replaces
the default version defined by the
Standard C++ library. The required behavior is to accept a value of
ptr
that is null or that was returned by an earlier call to
operator new[](size_t)
.
The default behavior is to call
operator delete(ptr, nothrow)
.
operator new
void *operator new(size_t count) throw(bad_alloc); // REPLACEABLE void *operator new(size_t count, const nothrow_t&) throw(); // REPLACEABLE void *operator new(size_t count, void *ptr) throw();
The first function is called by a
new
expression
to allocate count
bytes of storage
suitably aligned to represent any object of that size.
The program can define a function with this function signature that
replaces
the default version defined by the Standard C++ library.
The required behavior is to return a non-null pointer only
if storage can be allocated as requested. Each such allocation
yields a pointer to storage disjoint from any other allocated storage.
The order and contiguity of storage allocated by successive calls
is unspecified. The initial stored value is unspecified.
The returned pointer designates the start (lowest
byte address) of the allocated storage. If count
is zero, the
value returned does not compare equal to any other value returned
by the function.
The default behavior is to execute a loop. Within the loop,
the function first attempts to allocate the requested storage. Whether
the attempt involves a call to
malloc(size_t)
is unspecified. If the attempt is successful, the function returns
a pointer to the allocated storage.
Otherwise, the function calls the designated
new handler. If the
called function returns, the loop repeats. The loop terminates when
an attempt to allocate the requested storage is successful or when
a called function does not return.
The required behavior of a new handler is to perform one of the following operations:
abort()
or
exit(int)
bad_alloc
The default behavior of a
new handler is to throw an object of type
bad_alloc
. A null pointer designates the default
new handler.
The order and contiguity of storage allocated by successive
calls to operator new(size_t)
is unspecified,
as are the initial values stored there.
The second function:
void *operator new(size_t count, const nothrow_t&) throw();
is called by a
placement
new
expression
to allocate count
bytes of storage
suitably aligned to represent any object of that size.
The program can define a function with this function signature that
replaces
the default version defined by the Standard C++ library.
The default behavior is to return
operator new(count)
if that
function succeeds. Otherwise, it returns a null pointer.
The third function:
void *operator new(size_t count, void *ptr) throw();
is called by a
placement new
expression,
of the form new (args) T
.
Here, args
consists of a single object pointer.
The function returns ptr
.
operator new[]
void *operator new[](size_t count) throw(bad_alloc); // REPLACEABLE void *operator new[](size_t count, // REPLACEABLE const nothrow_t&) throw(); void *operator new[](size_t count, void *ptr) throw();
The first function is called by a
new[]
expression
to allocate count
bytes of storage
suitably aligned to represent any array object of
that size or smaller. The program can define a function
with this function signature that
replaces
the default version defined by the Standard C++ library.
The required behavior is the same as for
operator new(size_t)
.
The default behavior is to return
operator new(count)
.
The second function is called by a
placement
new[]
expression
to allocate count
bytes of storage
suitably aligned to represent any array object of that size.
The program can define a function with this function signature that
replaces
the default version defined by the Standard C++ library.
The default behavior is to return
operator new(count)
if that
function succeeds. Otherwise, it returns a null pointer.
The third function is called by a
placement
new[]
expression,
of the form new (args) T[N]
.
Here, args
consists of a single object pointer.
The function returns ptr
.
set_new_handler
new_handler set_new_handler(new_handler pnew) throw();
The function stores pnew
in a static
new handler pointer
that it maintains, then returns the value previously
stored in the pointer. The new handler is used by
operator new(size_t)
.
See also the Table of Contents and the Index.
Copyright © 1992-2002 by P.J. Plauger. All rights reserved.