NSAssertionHandler Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.0 and later.
Companion guide
Assertions and Logging
Declared in
NSException.h

Overview

NSAssertionHandler objects are automatically created to handle false assertions. Assertion macros, such as NSAssert and NSCAssert, 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 assertion handler prints an error message that includes the method and class (or function) containing the assertion and raises an NSInternalInconsistencyException.

You create assertions only using the assertion macros—you rarely need to invoke NSAssertionHandler methods directly. The macros for use inside methods and functions 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. See NSAssertionHandlerKey if you need to customize the behavior of NSAssertionHandler.

Tasks

Handling Assertion Failures

Class Methods

currentHandler

Returns the NSAssertionHandler object associated with the current thread.

+ (NSAssertionHandler *)currentHandler
Return Value

The NSAssertionHandler object associated with the current thread.

Discussion

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSException.h

Instance Methods

handleFailureInFunction:file:lineNumber:description:

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

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

The function that failed.

object

The object that failed.

fileName

The name of the source file.

line

The line in which the failure occurred.

format,...

A format string followed by a comma-separated list of arguments to substitute into the format string. See Formatting String Objects for more information.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSException.h

handleFailureInMethod:object:file:lineNumber:description:

Logs (using NSLog) an error message that includes the name of the method that failed, the class name of the object, the name of the source file, and the line number.

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

The selector for the method that failed

object

The object that failed.

fileName

The name of the source file.

line

The line in which the failure occurred.

format,...

A format string followed by a comma-separated list of arguments to substitute into the format string. See Formatting String Objects for more information.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSException.h

Constants

The string constants for exceptions are listed and described in the Exceptions section of the Foundation Constants Reference.

NSAssertionHandlerKey

This constant refers to a key in the thread dictionary of the per-thread assertion handler object

NSString * const NSAssertionHandlerKey;
Constants
NSAssertionHandlerKey

A key with a corresponding value in the thread dictionary.

If you need to customize the behavior of NSAssertionHandler, create a subclass, overriding handleFailureInMethod:object:file:lineNumber:description: and handleFailureInFunction:file:lineNumber:description:, and install your instance into the current thread’s attributes dictionary with this key.