The ASSERT Macro

This topic explains how to check assumptions made by your functions, using the ASSERT macro.

Note   As of MFC version 4.0, MFC uses the same assertion mechanisms as the C Run-time Library. This means that the message format has changed somewhat.

For more information on the _ASSERT, _ASSERTE, _RPT, and _RPTF macros, see Using Macros for Verification and Reporting.

The most typical use of the ASSERT macro is to identify program errors during development. The argument given to ASSERT should be chosen so that it holds true only if the program is operating as intended. The macro evaluates the ASSERT argument and, if the argument expression is false (0), alerts the user and halts program execution. No action is taken if the argument is true (nonzero).

When an assertion fails, a message box appears with the following text:

assertion failed in file <name> in line <num>
Abort Retry Ignore

where <name> is the name of the source file and <num> is the line number of the assertion that failed.

If you choose Abort, program execution terminates. If you choose Ignore, program execution continues. It is possible to break into the debugger after an ASSERT by clicking Retry. Neither Abort nor Ignore will activate a debugger, so they provide no way to examine the call stack.

If you are running under the debugger and choose Retry, a call to AfxDebugBreak embedded in the code causes a break into the debugger. At this point, you can examine the call stack. To view the call stack, on the View menu, click Debug Windows and Call Stack. If you have enabled Just-in-time debugging, this will work even if the application is not being debugged.

The following example shows how the ASSERT macro could be used to check the validity of a function’s return value:

int x = SomeFunc(y);
ASSERT(x >= 0);   //  Assertion fails if x is negative

ASSERT can also be used in combination with the IsKindOf function to provide extra checking for function arguments, such as in the following example:

ASSERT( pObject1->IsKindOf( RUNTIME_CLASS( CPerson ) ) );

The liberal use of assertions throughout your programs can catch errors during development. A good rule of thumb is that you should write assertions for any assumptions you make. For example, if you assume that an argument is not NULL, use an assertion statement to check for that condition.

The ASSERT macro will catch program errors only when you are using the debug version of the Microsoft Foundation Class Library during development. It will be turned off (and produce no code) when you build your program with the release version of the library.

Note   The expression argument to ASSERT will not be evaluated in the release version of your program. If you want the expression to be evaluated in both debug and release versions, use the VERIFY macro instead of ASSERT. In debug versions, VERIFY is the same as ASSERT. In release versions, VERIFY evaluates the expression argument but does not check the result.

See Also   Using the ASSERT_VALID Macro