_ASSERT, _ASSERTE Macros

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

_ASSERT( 
   booleanExpression 
);
_ASSERTE( 
   booleanExpression 
);

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 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);).

If _CrtDbgReport 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 destination(s) for each report type.

When the destination is a debug message window and the user clicks 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.

For more information about the reporting process, see the _CrtDbgReport 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 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.

Requirements

For additional compatibility information, see Compatibility in the Introduction.

Libraries

Debug versions of C run-time libraries only.

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.

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 are also exercised in this program, as an alternative to the printf function.

// crt_dbgmacro.c
// compile with: /D_DEBUG /MTd /Od /Zi /W3 /link /verbose:lib /debug
#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, "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;
}

Sample Output

Use the assert macros to evaluate the expression p1 == p2.
crt_dbgmacro.c(55) : 
 Will _ASSERT find 'I am p1' == 'I am p2' ?
crt_dbgmacro.c(56) : Assertion failed!
crt_dbgmacro.c(58) : 

 Will _ASSERTE find 'I am p1' == 'I am p2' ?
crt_dbgmacro.c(59) : Assertion failed: p1 == p2
'I am p1' != 'I am p2'

See Also

_Debug Functions | RPT, _RPTF | Run-Time Routines and .NET Framework Equivalents