_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.
In Visual C++ 2005, _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. In Visual C++ 2005, 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