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

privacy and legal statement