new
Standard C++ Library
NAME
new - The new operators (used to allocate dynamic storage in a program)
are declared in the header <new>.
SYNOPSIS
#include <new>
void *operator new(size_t n) throw(std::bad_alloc);
void *operator new(size_t n, const std::nothrow_t&) throw();
void *operator new(size_t n, void *p) throw();
void *operator new[](size_t n) throw(std::bad_alloc);
void *operator new[](size_t n,const std::nothrow_t&) throw();
void *operator new[](size_t n, void *p) throw();
DESCRIPTION
void *operator new(size_t n) throw(std::bad_alloc);
void *operator new(size_t n, const std::nothrow_t&) throw()
These versions of new are called to allocate n bytes of suitably
aligned storage to represent an object of that size. A C++ program
can define a function with either of these signatures which is
intended to replace the implementation provided default provided
by the Standard C++ Library. Both return a non-null pointer when
memory allocation succeeds. The first function throws
bad_alloc on memory allocation failure. The second or nothrow
version of operator new returns null on memory allocation failure.
void *operator new(size_t n, void *p) throw();
This function is called by a placement new expression which looks
like new (p) T, where p is a pointer to an object. The function
returns p.
void *operator new[](size_t n) throw(std::bad_alloc); void *operator
new[](size_t n,const std::nothrow_t&) throw();
The next two functions are called by a new[] expression i.e. by the
array form of a new expression. They are called to allocate n
bytes of suitably aligned storage to represent an array object
of that or smaller size. A C++ program can define a function with
either of these signatures which is intended to replace the default
implementation provided by the Standard C++ Library. Both return
a non-null pointer when memory allocation succeeds. The first
function throws bad_alloc on memory allocation failure. The
second or nothrow version of operator new returns null on memory
allocation failure.
void *operator new[](size_t n, void *p) throw();
This function is called by a placement array new expression which
looks like new (p) T[n], where p is a pointer to an object. The
function returns p.
SEE ALSO
delete, bad_alloc, no_throw
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
new_handler
Standard C++ Library
NAME
new_handler, set_new_handler - new_handler is the type of a function
called by operator new() or operator new []() when a request for
storage can not be met. set_new_handler() is a function
which sets the current new_handler.
SYNOPSIS
#include <new>
namespace std {
typedef void (*new_handler)();
new_handler set_new_handler(new_handler new_h) throw();
}
DESCRIPTION
set_new_handler() sets the current new_handler to the the function
passed in as its new_handler input parameter. It returns the
previous new_handler.
A function of type new_handler is required to do one of the
following:
o make more storage available for allocation and return
o throw an exception of type bad_alloc or a class derived from
bad_alloc
o call abort() or exit()
The Standard C++ Library provides a default new_handler which throws
an exception of type bad_alloc. The implementation provided
new_handler is called by default.
SEE ALSO
new, bad_alloc
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
delete
Standard C++ Library
NAME delete - The delete operators (used to deallocate dynamic
storage in a program) are declared in the header <new>.
SYNOPSIS
#include <new>
void operator delete(void* ptr) throw();
void operator delete(void* ptr, const std::nothrow_t&) throw();
void operator delete(void *p, void*) throw();
void operator delete[](void *p) throw();
void operator delete[](void* ptr ,const std::nothrow_t&) throw();
void operator delete[](void* ptr, void*) throw();
DESCRIPTION
void *operator delete(void* ptr) throw();
void *operator delete(void* ptr, const std::nothrow_t&) throw()
These versions of delete are called by a delete expression to
deallocate storeage pointed to by ptr. A C++ program can define
a function with either of these signatures which is intended to
replace the implementation provided default provided by the
Standard C++ Library. These functions accept a value for
ptr which is null or that was returned by a previous call to
operator new(std::size_t) or operator new (std::size_t, const
std::nothrow_t&). For a null ptr value, these functions do
nothing.
void operator delete(void * ptr, void *) throw();
This function is called by a placement delete expression. It
complements default placement new and performs no action.
void operator delete[](void* ptr) throw();
void operator delete[](void* ptr,const std::nothrow_t&) throw();
The next two functions are called by a delete[] expression i.e. by
the forarray form of a delete expression. They are called with
a value of ptr which is null or that was returned by a
previous call to operator new[](size_t) or operator
new[](size_t, const std::nothrow_t&). For a null ptr value, these
functions do nothing. A C++ program can define a function with
either of these signatures which is intended to replace the
default implementation provided by the Standard C++ Library.
void operator delete[](void* ptr, void *) throw();
This function is called by a placement array delete expression. It
complements default array placement new and performs no action.
SEE ALSO
new, no_throw
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
NOTES
Placement delete and delete applied to an array allocated with
placement new is not supported in C++ Version 6.0.
bad_alloc
Standard C++ Library
NAME
bad_alloc - is the type of the class which describes the exception
thrown when a request for storage allocation fails.
SYNOPSIS
#include <new>
namespace std {
class bad_alloc : public exception {
public:
bad_alloc() throw();
bad_alloc(const bad_alloc&) throw();
bad_alloc& operator=(const bad_alloc&) throw();
virtual ~bad_alloc() throw();
virtual const char* what() const throw();
};
}
DESCRIPTION
bad_alloc() throw();
This function constructs an object of class bad_alloc.
bad_alloc(const bad_alloc&) throw();
bad_alloc& operator=(const bad_alloc&) throw();
These functions copy an object of class bad_alloc.
virtual const char* what() const throw();
what() returns a string providing information about the error. The
string returned by what() is implementation defined.
SEE ALSO
new, exception, new_handler
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
type_info
Standard C++ Library
NAME
type_info - type_info is a class which describes type information
generated by the implementation. Objects of class type_info store a
pointer to a name for the type and an encoded value used to
compare two types for equality or collating order. The names,
encoding rule, and collating sequence for types are
unspecified and may differ between programs.
You can not copy or assign objects of class type_info. This is
because the copy constructor and assignment operator are private.
You construct a type_info object by: typeid o;
SYNOPSIS
#include <exception>
namespace std {
class type_info {
public:
virtual ~type_info();
bool operator==(const type_info& rhs) const;
bool operator!=(const type_info& rhs) const;
bool before(const type_info& rhs) const;
const char *name() const;
private:
type_info(const type_info& rhs);
type_info& operator=(const type_info& rhs);
};
}
DESCRIPTION
bool operator==(const type_info& rhs) const;
This function compares the current object with rhs. It returns true
if the two values describe the same type.
bool operator!=(const type_info& rhs) const;
This function compares the current object with rhs. It returns true
if the two values do not describe the same type.
bool before(const type_info& rhs) const;
This function compares the current object with rhs. It returns true
if *this precedes rhs in the implementation's collation order.
cp const char *name() const;
This function returns a null terminated string which contains the
name of the type. The return value is implementation defined.
type_info(const type_info& rhs);
type_info& operator=(const type_info& rhs);
These functions copy a type_info object. Because they are private
objects of type type_info can not be copied.
SEE ALSO
typeid
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
bad_cast
Standard C++ Library
NAME
bad_cast - defines the type of object thrown by the implementation
as an exception to report execution of an invalid
dynamic-cast expression.
SYNOPSIS
#include <typeinfo>
namespace std {
class bad_cast : public exception {
public:
bad_cast() throw();
bad_cast(const bad_cast&) throw();
bad_cast& operator=(const bad_cast&) throw();
virtual ~bad_cast() throw();
virtual const char* what() const throw();
};
}
DESCRIPTION
bad_cast() throw();
This function constructs an object of class bad_cast.
bad_cast(const bad_cast&) throw();
bad_cast& operator=(const bad_cast&) throw();
These functions copy an object of class bad_cast.
virtual const char* what() const throw();
what() returns a string providing information about the error. The
string returned by what() is implementation defined.
SEE ALSO
exception, dynamic_cast
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
bad_exception
Standard C++ Library
NAME
bad_exception - defines the type of object thrown from an unexpected
handler.
SYNOPSIS
#include <exception>
namespace std {
class bad_exception : public exception {
public:
bad_exception() throw();
bad_exception(const bad_exception&) throw();
bad_exception& operator=(const bad_exception&) throw();
virtual ~bad_exception() throw();
virtual const char* what() const throw();
};
}
DESCRIPTION
bad_exception() throw();
This function constructs an object of class bad_exception.
bad_exception(const bad_exception&) throw();
bad_exception& operator=(const bad_exception&) throw();
These functions copy an object of class bad_exception.
virtual const char* what() const throw();
what() returns a string providing information about the error. The
string returned by what() is implementation defined.
SEE ALSO
exception, unexpected_handler
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
bad_typeid
Standard C++ Library
NAME
bad_typeid - defines the type of object thrown by the implementation
as an exception to report a null pointer in a typeid expression.
SYNOPSIS
#include <typeinfo>
namespace std {
class bad_typeid : public exception {
public:
bad_typeid() throw();
bad_typeid(const bad_typeid&) throw();
bad_typeid& operator=(const bad_typeid&) throw();
virtual ~bad_typeid() throw();
virtual const char* what() const throw();
};
}
DESCRIPTION
bad_typeid() throw();
This function constructs an object of class bad_typeid.
bad_typeid(const bad_typeid&) throw();
bad_typeid& operator=(const bad_typeid&) throw();
These functions copy an object of class bad_typeid.
virtual const char* what() const throw();
what() returns a string providing information about the error. The
string returned by what() is implementation defined.
SEE ALSO
exception, typeid
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
exception
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
exception,logic_error,domain_error,invalid_argument,length_error,
out_of_range,runtime_error,range_error,overflow_error,underflow_error-
Classes supporting logic and runtime errors.
SYNOPSIS
#include <exception>
class exception;
DESCRIPTION
The class exception defines the base class for the types of objects
thrown as exceptions by Standard C++ Library components, and
certain expressions, to report errors detected during program
execution. Users can also use these exceptions to report errors in
their own programs.
INTERFACE
class exception {
public:
exception () throw();
exception (const exception&) throw();
exception& operator= (const exception&) throw();
virtual ~exception () throw();
virtual const char* what () const throw();
};
class logic_error : public exception {
public:
logic_error (const string& what_arg);
};
class domain_error : public logic_error {
public:
domain_error (const string& what_arg);
};
class invalid_argument : public logic_error {
public:
invalid_argument (const string& what_arg);
};
class length_error : public logic_error {
public:
length_error (const string& what_arg);
};
class out_of_range : public logic_error {
public:
out_of_range (const string& what_arg);
};
class runtime_error : public exception {
public:
runtime_error (const string& what_arg);
};
class range_error : public runtime_error {
public:
range_error (const string& what_arg);
};
class overflow_error : public runtime_error {
public:
overflow_error (const string& what_arg);
};
class underflow_error : public runtime_error {
public:
underflow_error (const string& what_arg);
};
CONSTRUCTORS
exception()
throws();
Constructs an object of class exception.
exception(const exception&)
throws();
The copy constructor. Copies an exception object.
DESTRUCTOR
virtual
~exception()
throws();
Destroys an object of class exception.
OPERATORS
exception&
operator=(const exception&)
throws();
The assignment operator. Copies an exception object.
MEMBER FUNCTION
virtual const char* what()const throws(); Returns an
implementation-defined, null-terminated byte string
representing a human-readable message describing the exception.
The message may be a null-terminated multibyte string, suitable for
conversion and display as a wstring.
CONSTRUCTORS FOR DERIVED CLASSES
logic_error::logic_error(const string& what_arg);
Constructs an object of class logic_error.
domain_error::domain_error(const string& what_arg);
Constructs an object of class domain_error.
invalid_argument::invalid_argument(const string& what_arg);
Constructs an object of class invalid_argument.
length_error::length_error(const string& what_arg);
Constructs an object of class length_error.
out_of_range::out_of_range(const string& what_arg);
Constructs an object of class out_of_range.
runtime_error::runtime_error(const string& what_arg);
Constructs an object of class runtime_error.
range_error::range_error(const string& what_arg);
Constructs an object of class range_error.
overflow_error::overflow_error(const string& what_arg);
Constructs an object of class overflow_error.
underflow_error::underflow_error(
const string& what_arg);
Constructs an object of class underflow_error.
EXAMPLE
//
// exception.cpp
//
#include <iostream.h>
#include <stdexcept>
static void f() { throw runtime_error("a runtime error"); }
int main ()
{
//
// By wrapping the body of main in a try-catch block
// we can be assured that we'll catch all exceptions
// in the exception hierarchy. You can simply catch
// exception as is done below, or you can catch each
// of the exceptions in which you have an interest.
//
try
{
f();
}
catch (const exception& e)
{
cout << "Got an exception: " << e.what() << endl;
}
return 0;
}
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
nothrow
Standard C++ Library
NAME
nothrow, nothrow_t - nothrow is an object of type nothrow_t used as
an argument to new()/delete() functions to indicate that those
functions never throw an exception.
SYNOPSIS
#include <new>
namespace std {
class nothrow_t;
extern const nothrow_t nothrow;
}
DESCRIPTION
nothrow_t is of type:
class nothrow_t {};
nothrow_t is the type of a function argument to new()/delete() which
indicates that the function should never throw an exception.
nothrow is an object of type nothrow_t declared in the Standard
Library which is passed as a function argument (matching the type
nothrow_t parameter) to new()/delete().
SEE ALSO
new, delete
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
terminate_handler
Standard C++ Library
NAME
terminate_handler, set_terminate, terminate - The type
terminate_handler and functions set_terminate() and terminate()
support abnormal program termination.
SYNOPSIS
#include <exception>
namespace std {
typedef void (*terminate_handler)();
terminate_handler set_terminate(terminate_handler new_h) throw();
void terminate();
}
DESCRIPTION
typedef void (*terminate_handler)();
terminate_handler is the type of handler function called by
terminate() when terminating exception processing. The required
behavior of a terminate_handler is to terminate program
expansion without returning to the caller. The Standard C++
Library provides a terminate_handler which is called by
default. The library provided terminate_handler calls abort().
terminate_handler set_terminate(terminate_handler new_h) throw();
set_terminate() sets the current terminate_handler to the function
passed in as its terminate_handler input parameter. It returns the
previous terminate_handler. The function is not allowed to be
a null pointer.
void terminate();
terminate() is called by the implementation when exception handling
must be abandoned. It may be directly called by a user program. If
called by the implementation, terminate() calls the terminate_handler
function in effect after evaluating the throw-expression. If called
by the program, terminate() calls the current terminate_handler
function.
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
unexpected_handler
Standard C++ Library
NAME unexpected_handler, set_unexpected, unexpected,
uncaught_exception The type unexpected_handler and functions
set_unexpected(), unexpected(), and uncaught_exception support
abnormal program termination.
SYNOPSIS
#include <exception>
namespace std {
typedef void (*unexpected_handler)();
unexpected_handler set_unexpected(unexpected_handler new_h) throw();
void unexpected();
bool uncaught_exception();
}
DESCRIPTION
typedef void (*unexpected_handler)();
unexpected_handler is the type of a handler function called by
unexpected() when a function attempts to throw an exception not
listed in its exception-specification. The required behavior of an
unexpected_handler is to throw an exception or terminate program
execution without returning to the caller. The unexpected_handler
may perform any of the following:
o throw an exception that satisfies the exception specification
(if the call to unexpected() is from the program not from
the implementation any exception may be thrown)
o throw an exception of class bad_exception or of any
class directly or indirectly derived from bad_exception.
o call terminate()
o call abort() or exit()
The Standard C++ Library provides a unexpected_handler which is
called by default. The library provided unexpected_handler
calls terminate().
unexpected_handler set_unexpected(unexpected_handler new_h) throw();
set_unexpected() sets the current unexpected_handler to the function
passed in as its unexpected_handler input parameter. It returns
the previous unexpected_handler. The function is not allowed to
be a null pointer.
void unexpected();
unexpected() is called by the implementation when a function exits
by an exception not allowed by its exception specification. It
may be directly called by a user program. If called by the
implementation, unexpected() calls the unexpected_handler function
in effect after evaluating the throw-expression. If called by the
program, unexpected() calls the current unexpected_handler
function.
bool uncaught_exception();
uncaught_exception() returns true if a thrown exception is currently
being processed.
SEE ALSO
bad_exception, terminate
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
