_ASSERT, _ASSERTE Macros

Evaluate an expression and generate a debug report when the result is FALSE (debug version only).

_ASSERT( booleanExpression );

_ASSERTE( booleanExpression );

For additional compatibility information, see Compatibility in the Introduction.

Libraries

Although _ASSERT and _ASSERTE are macros and are obtained by including CRTDBG.H, the application must link with one of the libraries listed above because these macros call other run-time functions.

Return Value

None

Parameter

booleanExpression

Expression (including pointers) that evaluates to nonzero or 0

Remarks

The _ASSERT and _ASSERTE macros provide an application with a clean and simple mechanism for checking assumptions during the debugging process. They are very flexible because they do not need to be enclosed in #ifdef statements to prevent them from being called in a retail build of an application. This flexibility is achieved by using the _DEBUG macro. _ASSERT and _ASSERTE are only available when _DEBUG is defined. When _DEBUG is not defined, calls to these macros are removed during preprocessing.

_ASSERT and _ASSERTE evaluate their booleanExpression argument and when the result is FALSE (0), they print a diagnostic message and call _CrtDbgReport to generate a debug report. The _ASSERT macro prints a simple diagnostic message, while _ASSERTE includes a string representation of the failed expression in the message. These macros do nothing when booleanExpression evaluates to nonzero.

Because the _ASSERTE macro specifies the failed expression in the generated report, it enables users to identify the problem without referring to the application source code. However, a disadvantage exists in that every expression evaluated by _ASSERTE must be included in the debug version of your application as a string constant. Therefore, if a large number of calls are made to _ASSERTE, these expressions can take up a significant amount of space.

_CrtDbgReport generates the debug report and determines its destination(s), based on the current report mode(s) and file defined for the _CRT_ASSERT report type. By default, assertion failures and errors are directed to a debug message window. The _CrtSetReportMode and _CrtSetReportFile functions are used to define the destination(s) for each report type.

When the destination is a debug message window and the user chooses the Retry button, _CrtDbgReport returns 1, causing the _ASSERT and _ASSERTE macros to start the debugger, provided that “just-in-time” (JIT) debugging is enabled. See Debug Reporting Functions of the C Run-Time Library for an example of an assert message box under Windows NT.

For more information about the reporting process, see the _CrtDbgReport function and the section Debug Reporting Functions of the C Run-Time Library. For more information about resolving assertion failures and using these macros as a debugging error handling mechanism, see Using Macros for Verification and Reporting.

The _RPT, _RPTF debug macros are also available for generating a debug report, but they do not evaluate an expression. The _RPT macros generate a simple report and the _RPTF macros include the source file and line number where the report macro was called, in the generated report. In addition to the _ASSERTE macros, the ANSI assert routine can also be used to verify program logic. This routine is available in both the debug and release versions of the libraries.

Example

/*

 * DBGMACRO.C

 * In this program, calls are made to the _ASSERT and _ASSERTE

 * macros to test the condition 'string1 == string2'.  If the

 * condition fails, these macros print a diagnostic message.

 * The _RPTn and _RPTFn group of macros are also exercised in

 * this program, as an alternative to the printf function.

 */

#include <stdio.h>

#include <string.h>

#include <malloc.h>

#include <crtdbg.h>

int main()

{

char *p1, *p2;

/*

* The Reporting Mode and File must be specified

* before generating a debug report via an assert

* or report macro.

* This program sends all report types to STDOUT

*/

_CrtSetReportMode(_CRT_WARN, _CRTDBG_MODE_FILE);

_CrtSetReportFile(_CRT_WARN, _CRTDBG_FILE_STDOUT);

_CrtSetReportMode(_CRT_ERROR, _CRTDBG_MODE_FILE);

_CrtSetReportFile(_CRT_ERROR, _CRTDBG_FILE_STDOUT);

_CrtSetReportMode(_CRT_ASSERT, _CRTDBG_MODE_FILE);

_CrtSetReportFile(_CRT_ASSERT, _CRTDBG_FILE_STDOUT);

/*

* Allocate and assign the pointer variables

*/

p1 = (char *)malloc(10);

strcpy(p1, "I am p1");

p2 = (char *)malloc(10);

strcpy(p2, "I am p2");

/*

* Use the report macros as a debugging

* warning mechanism, similar to printf.

*

* Use the assert macros to check if the

* p1 and p2 variables are equivalent.

*

* If the expression fails, _ASSERTE will

* include a string representation of the

* failed expression in the report.

* _ASSERT does not include the

* expression in the generated report.

*/

_RPT0(_CRT_WARN, "\n\n Use the assert macros to evaluate the expression p1 == p2.\n");

_RPTF2(_CRT_WARN, "\n Will _ASSERT find '%s' == '%s' ?\n", p1, p2);

_ASSERT(p1 == p2);

_RPTF2(_CRT_WARN, "\n\n Will _ASSERTE find '%s' == '%s' ?\n", p1, p2);

_ASSERTE(p1 == p2);

_RPT2(_CRT_ERROR, "\n \n '%s' != '%s'\n", p1, p2);

free(p2);

free(p1);

return 0;

}

Output

Use the assert macros to evaluate the expression p1 == p2.

dbgmacro.c(54) : Will _ASSERT find 'I am p1' == 'I am p2' ?
dbgmacro.c(55) : Assertion failed


dbgmacro.c(57) : Will _ASSERTE find 'I am p1' == 'I am p2' ?
dbgmacro.c(58) : Assertion failed: p1 == p2


'I am p1' != 'I am p2'

Debug Functions

See Also   _RPT, _RPTF