Why use apparently meaningless do-while and if-else statements in macros?

Solution 1:

The do ... while and if ... else are there to make it so that a semicolon after your macro always means the same thing. Let's say you had something like your second macro.

#define BAR(X) f(x); g(x)

Now if you were to use BAR(X); in an if ... else statement, where the bodies of the if statement were not wrapped in curly brackets, you'd get a bad surprise.

if (corge)
  BAR(corge);
else
  gralt();

The above code would expand into

if (corge)
  f(corge); g(corge);
else
  gralt();

which is syntactically incorrect, as the else is no longer associated with the if. It doesn't help to wrap things in curly braces within the macro, because a semicolon after the braces is syntactically incorrect.

if (corge)
  {f(corge); g(corge);};
else
  gralt();

There are two ways of fixing the problem. The first is to use a comma to sequence statements within the macro without robbing it of its ability to act like an expression.

#define BAR(X) f(X), g(X)

The above version of bar BAR expands the above code into what follows, which is syntactically correct.

if (corge)
  f(corge), g(corge);
else
  gralt();

This doesn't work if instead of f(X) you have a more complicated body of code that needs to go in its own block, say for example to declare local variables. In the most general case the solution is to use something like do ... while to cause the macro to be a single statement that takes a semicolon without confusion.

#define BAR(X) do { \
  int i = f(X); \
  if (i > 4) g(i); \
} while (0)

You don't have to use do ... while, you could cook up something with if ... else as well, although when if ... else expands inside of an if ... else it leads to a "dangling else", which could make an existing dangling else problem even harder to find, as in the following code.

if (corge)
  if (1) { f(corge); g(corge); } else;
else
  gralt();

The point is to use up the semicolon in contexts where a dangling semicolon is erroneous. Of course, it could (and probably should) be argued at this point that it would be better to declare BAR as an actual function, not a macro.

In summary, the do ... while is there to work around the shortcomings of the C preprocessor. When those C style guides tell you to lay off the C preprocessor, this is the kind of thing they're worried about.

Solution 2:

Macros are copy/pasted pieces of text the pre-processor will put in the genuine code; the macro's author hopes the replacement will produce valid code.

There are three good "tips" to succeed in that:

Help the macro behave like genuine code

Normal code is usually ended by a semi-colon. Should the user view code not needing one...

doSomething(1) ;
DO_SOMETHING_ELSE(2)  // <== Hey? What's this?
doSomethingElseAgain(3) ;

This means the user expects the compiler to produce an error if the semi-colon is absent.

But the real real good reason is that at some time, the macro's author will perhaps need to replace the macro with a genuine function (perhaps inlined). So the macro should really behave like one.

So we should have a macro needing semi-colon.

Produce a valid code

As shown in jfm3's answer, sometimes the macro contains more than one instruction. And if the macro is used inside a if statement, this will be problematic:

if(bIsOk)
   MY_MACRO(42) ;

This macro could be expanded as:

#define MY_MACRO(x) f(x) ; g(x)

if(bIsOk)
   f(42) ; g(42) ; // was MY_MACRO(42) ;

The g function will be executed regardless of the value of bIsOk.

This means that we must have to add a scope to the macro:

#define MY_MACRO(x) { f(x) ; g(x) ; }

if(bIsOk)
   { f(42) ; g(42) ; } ; // was MY_MACRO(42) ;

Produce a valid code 2

If the macro is something like:

#define MY_MACRO(x) int i = x + 1 ; f(i) ;

We could have another problem in the following code:

void doSomething()
{
    int i = 25 ;
    MY_MACRO(32) ;
}

Because it would expand as:

void doSomething()
{
    int i = 25 ;
    int i = 32 + 1 ; f(i) ; ; // was MY_MACRO(32) ;
}

This code won't compile, of course. So, again, the solution is using a scope:

#define MY_MACRO(x) { int i = x + 1 ; f(i) ; }

void doSomething()
{
    int i = 25 ;
    { int i = 32 + 1 ; f(i) ; } ; // was MY_MACRO(32) ;
}

The code behaves correctly again.

Combining semi-colon + scope effects?

There is one C/C++ idiom that produces this effect: The do/while loop:

do
{
    // code
}
while(false) ;

The do/while can create a scope, thus encapsulating the macro's code, and needs a semi-colon in the end, thus expanding into code needing one.

The bonus?

The C++ compiler will optimize away the do/while loop, as the fact its post-condition is false is known at compile time. This means that a macro like:

#define MY_MACRO(x)                                  \
do                                                   \
{                                                    \
    const int i = x + 1 ;                            \
    f(i) ; g(i) ;                                    \
}                                                    \
while(false)

void doSomething(bool bIsOk)
{
   int i = 25 ;

   if(bIsOk)
      MY_MACRO(42) ;

   // Etc.
}

will expand correctly as

void doSomething(bool bIsOk)
{
   int i = 25 ;

   if(bIsOk)
      do
      {
         const int i = 42 + 1 ; // was MY_MACRO(42) ;
         f(i) ; g(i) ;
      }
      while(false) ;

   // Etc.
}

and is then compiled and optimized away as

void doSomething(bool bIsOk)
{
   int i = 25 ;

   if(bIsOk)
   {
      f(43) ; g(43) ;
   }

   // Etc.
}

Solution 3:

@jfm3 - You have a nice answer to the question. You might also want to add that the macro idiom also prevents the possibly more dangerous (because there's no error) unintended behavior with simple 'if' statements:

#define FOO(x)  f(x); g(x)

if (test) FOO( baz);

expands to:

if (test) f(baz); g(baz);

which is syntactically correct so there's no compiler error, but has the probably unintended consequence that g() will always be called.

Solution 4:

The above answers explain the meaning of these constructs, but there is a significant difference between the two that was not mentioned. In fact, there is a reason to prefer the do ... while to the if ... else construct.

The problem of the if ... else construct is that it does not force you to put the semicolon. Like in this code:

FOO(1)
printf("abc");

Although we left out the semicolon (by mistake), the code will expand to

if (1) { f(X); g(X); } else
printf("abc");

and will silently compile (although some compilers may issue a warning for unreachable code). But the printf statement will never be executed.

do ... while construct does not have such problem, since the only valid token after the while(0) is a semicolon.

Solution 5:

While it is expected that compilers optimize away the do { ... } while(false); loops, there is another solution which would not require that construct. The solution is to use the comma operator:

#define FOO(X) (f(X),g(X))

or even more exotically:

#define FOO(X) g((f(X),(X)))

While this will work well with separate instructions, it will not work with cases where variables are constructed and used as part of the #define :

#define FOO(X) (int s=5,f((X)+s),g((X)+s))

With this one would be forced to use the do/while construct.