_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

See Also

Concepts

Debug Routines

_RPT, _RPTF, _RPTW, _RPTFW Macros