NDEBUG

#define assert(ignore) ((void)0)

#include <assert.h>
void assert(int expression);

[Footnote 97: The message written might be of the form

Assertion failed: expression, file xyz, line nnn]

It then calls the abort function.

Forward references: the abort function (§4.10.4.1).

#include <assert.h>

.....

assert(0<=idx &&
     idx < sizeof a/sizeof a[0]);
   /*  a[idx] is now safe */

Please note that this is hardly the best way to write production code. It is generally ill-advised for a program in the field to terminate abnormally. No matter how revealing the accompanying message may be to you the programmer, it is assuredly cryptic to the user. Some form of error recovery and continuation is almost always preferred. Any diagnostics should be in terms that the user can understand.

What you want is some way to introduce assertions during debugging. That lets you catch the worst logic errors and document the assertions you need early on. Later, you might add code to recover from errors that truly can occur during execution. You want to leave the assertions in as documentation, but you want them to generate no code.

<assert.h> gives you just this behavior. You can define the macro NDEBUG to alter the way assert expands. If NDEBUG is not defined at the point where you include <assert.h>, the header defines the active form of the macro assert. It expands to an expression that tests the assertion and prints an error message if the assertion is false.

If NDEBUG is defined, however, the header defines the passive form of the macro. It expands to a placeholder expression that does nothing. In either case, assert behaves essentially like a function that takes a single int argument and returns a void result.

How you control the macro expansion is a matter of taste. One style of programming is to change the source code. Once you believe that assertions should be disabled, just add a line before you include the header:

#define NDEBUG/* disable assertions */
#include <assert.h>

Many implementations support a somewhat more flexible approach. They let you define one or more macros outside any C source files. You specify these definitions in a command script or make file that rebuilds the program. A make file can be a better place to document that assertions are to be disabled, and can also be an easier file to replicate and alter when you must revert to more primitive debugging phases. <assert.h> is designed with such a capability in mind, though nothing in the C standard requires it.

This header has an additional peculiarity. All other headers are idempotent. Including any of them two or more times has the same effect as including the header just once. In the case of <assert.h>, however, its behavior can vary each time you include it. The header alters the definition of assert to agree with the current definition status of NDEBUG.

The net effect is that you can control assertions in different ways throughout a source file. Performance may suffer dramatically, for example, when assertions occur inside frequently executed loops. Or an earlier assertion may terminate execution before you get to the revealing parts. In either case, you may need to turn assertions on and off at various places throughout a source file.

So to turn assertions on, you write

#undef NDEBUG
#include <assert.h>

#define NDEBUG
#include <assert.h>

#under assert  /*  remove any
          existing definition */
#ifdef NDEBUG
#define assert(test) ((void(0)
          /*  passive version */
#else
#define assert(test) <active version>
#endif

All that remains is to write the active version of the macro. An obvious but naive way to provide the needed functionality is to write the active version as:

#define assert(test) if (!(test)) \
   fprintf(stderr, \
"Assertion failed: %s, file %s, line %i\n", \
   #test, __FILE__, __LINE__) UNACCEPTABLE

• The macro must not directly call any of the library output functions, such as fprintf. Nor may it refer to the macro stderr. These names are properly defined only in the standard header <stdio. h>. The program may not have included that header, and the standard header <assert.h> must not. A program can define macros that rename any or all of the names from another header, provided it doesn't include that header. That mandates a function with a secret name to do the actual output.
• The macro must expand to a void expression. The program can contain an expression such as (assert(0 < x), x < y). That rules out use of the if statement, for example. Any testing must make use of one of the conditional operators within an expression.
• The macro should expand to fairly efficient and compact code. Otherwise, programmers will tend to avoid writing enough assertions. This version involves a function call with five arguments, a space waster that can be avoided.

Say the first argument to the function captures the result of the test:

void _Assert (test, <other parameters>);
#define assert(test) _Assert(test, <other arguments>)

Alternatively, the test can be performed inline:

void _Assert (<parameters>);
#define assert(test) ((test) || _Assert(<arguments>))

It is hard to say in general which form generates more compact code. That depends strongly on the implementation. The first form, however, results in a function call on every execution. A rather ambitious global optimizer might eliminate some calls, but don't count on it. The second calls the function at most once, when the program is about to terminate.

I favor the second form, with the inline test, despite the weaker checking. (The checking is no worse than what the passive version of the macro supplies.) Many current optimizers can check a broad range of assertions at translation time. They can often eliminate all of the code for an obviously true assertion.

The remaining issue is how best to encode the diagnostic message. Here, the string creation operator #x really pays off. The trick is to form all the information into string literals at translation time. Then string literal concatenation merges the pieces to produce a single argument.

One nuisance is that the built-in macro __LINE__ is not a string literal, but a decimal constant. To convert it to the proper form requires an additional layer of processing. That is performed by adding to the header a secret macro _STR.