Return to the Alphabetic Index
Return to the Class Browser
Return to the Picture Browser
Copyright (c) 1994 by NeXT Computer, Inc. All Rights Reserved.


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

Handling Failures