Compaq C++ User Documentation

| United States

cxxlstd$help.HLP

##

##

##

##

##

##

##

##

##

##

##

##

    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 statement and legal notices