Up

NSAssertionHandler class reference

Authors

Adam Fedor (fedor@boulder.colorado.edu)

Version: 1.25

Date: 2005/02/22 11:22:43

Copyright: (C) 1995, 1996 Free Software Foundation, Inc.


Contents -

  1. Software documentation for the NSAssertionHandler class
  2. Software documentation for the NSException class

Software documentation for the NSAssertionHandler class

NSAssertionHandler : NSObject

Declared in:
Foundation/NSException.h
Standards:

NSAssertionHandler objects are used to raise exceptions on behalf of macros implementing assertions.
Each thread has its own assertion handler instance.

The macros work together with the assertion handler object to produce meaningful exception messages containing the name of the source file, the position within that file, and the name of the ObjC method or C function in which the assertion failed.

An NSAssertionHandler instance is created on demand for each thread and is stored in the thread's dictionary under the key NSAssertionHandler. A custom NSAssertionHandler can be used by adding it to the thread dictionary under this key.

The assertion macros are: NSAssert() , NSCAssert() , NSAssert1() , NSCAssert1() , NSAssert2() , NSCAssert2() , NSAssert3() , NSCAssert3() , NSAssert4() , NSCAssert4() , NSAssert5() , NSCAssert5() , NSParameterAssert() , NSCParameterAssert()

Method summary

currentHandler 

+ (NSAssertionHandler*) currentHandler;

Returns the assertion handler object for the current thread.
If none exists, creates one and returns it.


handleFailureInFunction: file: lineNumber: description: ,...

- (void) handleFailureInFunction: (NSString*)functionName file: (NSString*)fileName lineNumber: (int)line description: (NSString*)format,...;

Handles an assertion failure by using NSLogv() to print an error message built from the supplied arguments, and then raising an NSInternalInconsistencyException


handleFailureInMethod: object: file: lineNumber: description: ,...

- (void) handleFailureInMethod: (SEL)aSelector object: (id)object file: (NSString*)fileName lineNumber: (int)line description: (NSString*)format,...;

Handles an assertion failure by using NSLogv() to print an error message built from the supplied arguments, and then raising an NSInternalInconsistencyException


Software documentation for the NSException class

NSException : NSObject

Declared in:
Foundation/NSException.h
Conforms to:
NSCoding
NSCopying
Standards:

The NSException class helps manage errors in a program. It provides a mechanism for lower-level methods to provide information about problems to higher-level methods, which more often than not, have a better ability to decide what to do about the problems.

Exceptions are typically handled by enclosing a sensitive section of code inside the macros NS_DURING and NS_HANDLER, and then handling any problems after this, up to the NS_ENDHANDLER macro:

   NS_DURING
    code that might cause an exception
   NS_HANDLER
    code that deals with the exception. If this code cannot deal with
    it, you can re-raise the exception like this
    [localException raise]
    so the next higher level of code can handle it
   NS_ENDHANDLER
   

The local variable localException is the name of the exception object you can use in the NS_HANDLER section. The easiest way to cause an exception is using the +raise:format:,... method.


Instance Variables

Method summary

exceptionWithName: reason: userInfo: 

+ (NSException*) exceptionWithName: (NSString*)name reason: (NSString*)reason userInfo: (NSDictionary*)userInfo;

Create an an exception object with a name , reason and a dictionary userInfo which can be used to provide additional information or access to objects needed to handle the exception. After the exception is created you must -raise it.


raise: format: ,...

+ (void) raise: (NSString*)name format: (NSString*)format,...;

Creates an exception with a name and a reason using the format string and any additional arguments. The exception is then raised.


raise: format: arguments: 

+ (void) raise: (NSString*)name format: (NSString*)format arguments: (va_list)argList;

Creates an exception with a name and a reason string using the format string and additional arguments specified as a variable argument list argList. The exception is then raised.


initWithName: reason: userInfo: 

- (id) initWithName: (NSString*)name reason: (NSString*)reason userInfo: (NSDictionary*)userInfo;
This is a designated initialiser for the class.

Initializes a newly allocated NSException object with a name, reason and a dictionary userInfo.


name 

- (NSString*) name;

Returns the name of the exception.


raise 

- (void) raise;

Raises the exception. All code following the raise will not be executed and program control will be transfered to the closest calling method which encapsulates the exception code in an NS_DURING macro, or to the uncaught exception handler if there is no other handling code.


reason 

- (NSString*) reason;

Returns the exception reason.


userInfo 

- (NSDictionary*) userInfo;

Returns the exception userInfo dictionary.




Instance Variables for NSException Class

_e_info

@protected NSDictionary* _e_info;

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.


_e_name

@protected NSString* _e_name;

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.


_e_reason

@protected NSString* _e_reason;

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.






Up