DIGITAL logo   C++ Graphic
    Updated: 21 November 1998
  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 DIGITAL 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

   
Burgundy bar
DIGITAL Home Feedback Search Sitemap Subscribe Help
Legal