NSAssertionHandler

Inherits From: NSObject

Conforms To: NSObject (NSObject)

Declared In: Foundation/NSExceptions.h

Class Description

An assertion is a statement about conditions during the execution of program code, such as the relationship between variables, the state of a boolean variable, the value of an expression, and so on. If the statement about the conditions proves false, the assertion is said to have failed, and usually some action must be taken to report the failed assertion. Application programmers wishing to provide more detailed control over assertion failures than provided by the macros defined below would use the methods of NSAssertionHandler to report assertion failures.

NSAssertionHandler provides a mechanism whereby each distinct thread of execution can have a separate handler to deal with failed assertions in code. The fileName and line arguments to the methods described below can be obtained by using the __FILE__ and __LINE__ macros that are pre-defined in the C pre-processor.

The Foundation/NSExceptions.h header file contains a collection of macros that can be used to state assertions within methods, and contains a parallel collection of macros that can be used to state assertions within regular C functions. If the condition tested in any of these macros fails, the current assertion handler is invoked with one of the methods defined below, depending on whether the macro is one of the NSAssertN or one of the NSCAssertN macros. Separate macros have from 1 to 5 arguments. Macros for dealing with assertion failures within methods are:

NSAssert1(condition, description, argument1);

NSAssert2(condition, description, argument1, argument2);

NSAssert3(condition, description, argument1, argument2, argument3);

NSAssert4(condition, description, argument1, argument2, argument3, argument4);

NSAssert5(condition, description, argument1, argument2, argument3, argument4, argument5);

In each case, condition is the statement to be tested (for example, index < length), description is a description of the reason for the failure (in the form of a printf-style format NSString), and each argN is an argument to be formatted according to the description string.

The parallel set of macros for dealing with failed assertions from within C functions have names of the form NSCAssertN instead of NSAssertN. The arguments are otherwise the same as the NSAssertN macros.

Getting the Current Handler

• + (NSAssertionHandler *)currentHandler Returns the assertion handler for the current thread.

• - (void)handleFailureInFunction:(NSString *)functionName file:(NSString *)fileName Logs an error message that includes functionName; lineNumber:(int)line the source file fileName and the line number where description:(NSString *)format,... the failure occured; and a short description of the failure, described by format. It then raises an NSInternalInconsistencyException.
• - (void)handleFailureInMethod:(SEL)selector Logs an error message that includes the method (selector) object:(id)object and object associated with the failure; file:(NSString *)fileName the source file fileName and lineNumber:(int)line line number in that file where the failure occured; description:(NSString *)format,... and a short description of the failure, described by format. It then raises an NSInternalInconsistencyException.