- Inherits from:
- NSObject
- Conforms to:
- NSObject
- (NSObject)
Declared in:
- Foundation/NSException.h
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.
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.
- Getting the thread's handler
- + currentHandler
- Handling assertion failures
- - handleFailureInFunction:file:lineNumber:description:
- - handleFailureInMethod:object:file:lineNumber:description:
+ (NSAssertionHandler *)currentHandler
- (void)handleFailureInFunction:(NSString
*)functionName
file:(NSString *)fileName
lineNumber:(int)line
description:(NSString *)format,...
NSLog()
)
that includes the name of the function functionName,
the name of the file fileName, and
the line number line. Raises NSInternalInconsistencyException.- (void)handleFailureInMethod:(SEL)selector
object:(id)object
file:(NSString *)fileName
lineNumber:(int)line
description:(NSString *)format,...