Using the Assertion Macros

This document describes how to use the Assert (and related) macros to evaluate a condition and create an assertion.

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 one or more arguments are needed for a printf-style description. For example, NSAssert1 is used within methods if one 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 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 NSAssertionHandler currentHandler class method.

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