_ASSERT, _ASSERTE Macros
Evaluate an expression and generate a debug report when the result is FALSE (debug version only).
_ASSERT( booleanExpression );
_ASSERTE( booleanExpression );
|_ASSERT||<crtdbg.h>||Win NT, Win 95|
|_ASSERTE||<crtdbg.h>||Win NT, Win 95|
For additional compatibility information, see Compatibility in the Introduction.
|LIBCD.LIB||Single thread static library, debug version|
|LIBCMTD.LIB||Multithread static library, debug version|
|MSVCRTD.LIB||Import library for MSVCRTD.DLL, debug version|
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.
Expression (including pointers) that evaluates to nonzero or 0
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.
* 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.
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
* 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);
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'
See Also _RPT, _RPTF