_ASSERT, _ASSERTE Macros
Evaluate an expression and generate a debug report when the result is False (debug version only).
_ASSERT(
booleanExpression
);
_ASSERTE(
booleanExpression
);
Parameters
- 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 _CrtDbgReportW 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.
_ASSERT and _ASSERTE invoke _CrtDbgReportW, which causes all output to be in wide characters, and _ASSERTE properly prints Unicode characters in booleanExpression.
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 is included in the output (debug version) file of your application as a string constant. Therefore, if a large number of calls are made to _ASSERTE, these expressions can greatly increase the size of your output file.
Unless you specify otherwise with the _CrtSetReportMode and _CrtSetReportFile functions, messages appear in a pop-up dialog box equivalent to setting:
_CrtSetReportMode(CRT_ASSERT, _CRTDBG_MODE_WNDW);
_CrtDbgReport or _CrtDbgReportW generates the debug report and determines its destination or destinations, based on the current report mode or modes 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 destinations for each report type.
When the destination is a debug message window and the user clicks the Retry button, _CrtDbgReport or _CrtDbgReportW returns 1, causing the _ASSERT and _ASSERTE macros to start the debugger provided that just-in-time (JIT) debugging is enabled.
For more information about the reporting process, see the _CrtDbgReport, _CrtDbgReportW function. 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. 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 be used to verify program logic. This routine is available in both the debug and release versions of the libraries. Wide character versions of these macros are available (_RPTWn, _RPTFWn). The wide character versions are identical to the narrow character versions except that wide character strings are used for all string parameters and output.
Although _ASSERT and _ASSERTE are macros and are obtained by including Crtdbg.h, the application must link with one of the following libraries because these macros call other run-time functions.
Libcmtd.lib
Multithread static library, debug version.Msvcrtd.lib
Import library for Msvcr90d.dll, debug version.
Requirements
Macro |
Required header |
|---|---|
_ASSERT |
<crtdbg.h> |
_ASSERTE |
<crtdbg.h> |
Example
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 is also exercised in this program, as an alternative to the printf function.
// crt_ASSERT_macro.c
// compile with: /D_DEBUG /MTd /Od /Zi /link /verbose:lib /debug
//
// This program uses the _ASSERT and _ASSERTE debugging macros.
//
#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_s(p1, 10, "I am p1");
p2 = (char *)malloc(10);
strcpy_s(p2, 10, "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,
"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, "'%s' != '%s'\n", p1, p2);
free(p2);
free(p1);
return 0;
}
Use the assert macros to evaluate the expression p1 == p2. crt_ASSERT_macro.c(54) : Will _ASSERT find 'I am p1' == 'I am p2' ? crt_ASSERT_macro.c(55) : Assertion failed! crt_ASSERT_macro.c(58) : Will _ASSERTE find 'I am p1' == 'I am p2' ? crt_ASSERT_macro.c(59) : Assertion failed: p1 == p2 'I am p1' != 'I am p2'
.NET Framework Equivalent
System::Diagnostics::Debug::Assert