PATH  Documentation > Mac OS X > Foundation Reference: Objective-C



Table of Contents

NSAssertionHandler


Inherits from:
NSObject
Conforms to:
NSObject
(NSObject)
Declared in:
Foundation/NSException.h




Class Description


NSAssertionHandler objects are automatically created to handle false assertions. Assertion macros are used to evaluate a condition and, if the condition evaluates to false, the macros pass a string to an NSAssertionHandler object describing the failure. Each thread has its own NSAssertionHandler object. When invoked, an NSAssertionHandler prints an error message that includes the method and class (or function) containing the assertion, and raises an NSInternalInconsistencyException.

You use an assortment of macros to evaluate a condition-these macros serve as a front end to NSAssertionHandler. These macros fall into two categories: those you use in Objective-C methods, and those you use in C functions. For example, NSAssert() is for use within methods and NSCAssert() is for use within functions. Each macro has two arguments: the condition, an expression that evaluates to true or false, and the NSString describing the failure. Other macros are available if more arguments are needed for a printf()-style description. For example, NSAssert1() is used within methods if an additional argument is needed as in:

NSAssert1((0 <= component) && (component <= 255),
    @"Value %i out of range!", component);

For more details on these macros see NSAssert().

You create assertions only using the above macros-you rarely need to invoke NSAssertionHandler methods directly. The macros for use inside methods and functions will send handleFailureInMethod:object:file:lineNumber:description: and handleFailureInFunction:file:lineNumber:description: messages respectively to the current assertion handler. The assertion handler for the current thread is obtained using the currentHandler class method.

Assertions are not compiled into code if the preprocessor macro NS_BLOCK_ASSERTIONS is defined.


Using a Custom Assertion Handler


In some cases, you might want to define your own assertion handler to print error messages to a different error console or to raise custom exceptions, instead of the generic NSInternalInconsistencyException. To implement these features, you must define a subclass of NSAssertionHandler and override its handleFailureInMethod:object:file:lineNumber:description: and handleFailureInFunction:file:lineNumber:description: methods to handle assertions in methods and functions, respectively.

To add your assertion handler to a thread, you must add the assertion handler to the thread's attributes dictionary. Use the thread's threadDictionary method to retrieve the dictionary. Add your assertion-handler object to the dictionary using the key NSAssertionHandler.

Typically, you should add your assertion handler to the thread dictionary immediately after creating the thread. However, a default assertion handler is not created until an assertion macro is encountered and you can always replace the existing assertion handler in the thread dictionary. If your assertion handler already exists in the thread dictionary, it is used in place of the default assertion handler.




Method Types


Getting the thread's handler
+ currentHandler
Handling assertion failures
- handleFailureInFunction:file:lineNumber:description:
- handleFailureInMethod:object:file:lineNumber:description:


Class Methods



currentHandler

+ (NSAssertionHandler *)currentHandler

Returns the NSAssertionHandler object associated with the current thread. If no assertion handler is associated with the current thread, this method creates one and assigns it to the thread.


Instance Methods



handleFailureInFunction:file:lineNumber:description:

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

Logs an error message (using NSLog()) that includes the name of the function functionName, the name of the file fileName, and the line number line. Raises NSInternalInconsistencyException.

handleFailureInMethod:object:file:lineNumber:description:

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

Logs an error message (using NSLog()) that includes the selector, object's class name, the name of the file fileName, and the line number line. Raises NSInternalInconsistencyException.


Table of Contents