On Programming

When looking for X-Macros on Google, the only reference I came across was this one (ddj.com), which is also the place where I happened across X-Macros by accident (in the printed version of the magazine). I have since put them to great use in production code. What are X-Macros? They are basically a clever way to avoid code duplication, using the C/C++ preprocessor. They come in very handy whenever you would normally need to hunt down and hand-edit multiple places in your code after expanding or modifying some lower level layer which this code depends upon. Let's look at some examples to find out what X-Macros might be able to do for you.

The "Enum Example"

Let's say you have an enum, and you would like to associate a string with each element, to provide a readable name. A common way to do this is as follows:

The output of this program is:

ID0 -> ID 0
ID1 -> ID 1
ID2 -> ID 2

Now, whenever you add an element to IDs you will have to remember to add an element to idStrings. The compiler wont tell you about your omission, and things could get nasty only very late at runtime. Even more so, if you have code that operates on all members of the enum, you have to add to this code as well, as you would have to in the above example, where we output all the string names on standard output.

X-Macros relieve you of all that. Let's rewrite our code like this:

Let's examine what is happening here. At (1) we define a macro which expands to a set of "X-Macros". In our case, the X-Macro has 2 Parameters. At this point in the code, they are not expanded. Note that this uses the fact that the preprocessor will not expand macros embedded in other macros, before the "parent" macro is expanded. Therefore it does not matter that, at this point, X is not defined to anything. At (2) the whole magic happens. The X-Macro is defined. It will expand to its first parameter (ID0, ID1, ID2) and a colon.
Now, inside the enum definition, we expand GENERATE_IDS. This will now also expand the current definition of our X-Macro, and, voila, an enum is generated. At (3) we do the same thing, only this time, we expand the X-Macro to something else, namely, it's second parameter and a colon, resulting in a list of strings generated by GENERATE_IDS, fitting nicely into our array definition. Note that the definition of X had to be undefined before we could define it again.
Now, whenever we want to add an enum, all we have to do is add a line to the definition of GENERATE_IDS, with the enum value, and the enum string name. There is no need to edit multiple places in the code any longer. The output of the new program will be exactly the same as the first one.

Beyond Enums

While the above example demonstrates a useful technique to avoid code duplication in a particular implementation, X-Macros can be put to use in many different scenarios. I would like to give one more example in this post. Let's say you want to have a class which has many different data members, and the frequency of adding, removing, or changing those members is currently very high. Here is how I would implement such a class using X-Macros:

In this more elaborate example, X-Macros are used to generate a considerable amount of code. All members of a class Properties are defined, as well as getters and setters for them. The code that initializes all members to their type-default is also generated within the constructor. Since I got tired of manually checking the correctness of the output, I also introduced a minimal testing "framework" in this example - assertEquals will report an error if it's two arguments are not equal. Before the program terminates, it will report any of these discrepancies.
Now adding a new member to Properties in the above code is simply a matter of adding a line to the generation macro at (1), thus completely eliminating the need to hunt around in the code for places that need to be adapted or expanded (or even reduced!).

By the way, X-Macros can of course also be used in tests. Testing "some" of the members (see (5)) is not satisfactory, neither is adding a new line in the test whenever a new member is defined (precisely what we want to avoid for the production code!). One way of automatically testing the correctness of the generated code is adding a test value as the third parameter to the X-Macro. The generation macro would then look like so:

Now of course all the places where X is expanded have to be adapted, to include the new parameter. In the code we have seen so far, this parameter is ignored. However, in the test, we can do something like this:

Now, (5) expands to code that first tests the default value of a member, then sets it's value to the test value given in the third parameter (tv) of our X-Macro, and then tests that the getter returns the same value. No new code has to be added here when a new member is defined.

A few words of warning

As always, there is a flipside of the coin. X-Macros degrade readability of cour code. When introducing an X-Macro, it is well worth spending some time figuring out how to keep the code that is eventually in an X-Macro as short as possible. Sometimes one jumps the gun and wraps too much code into it, while some static elements could still be extracted. Long macros make it hard to debug the code within them. On the other hand, do you see a reason to ever need to debug the Property class above, assuming that it's feature set will not change?

I have put X-Macros to great use in great code, and I encourage you to do the same, and to discover many more uses for this surprisingly simple yet effective technique.

You can download the code used in the examples here:
XMacros_Enum.cpp
XMacros_Properties.cpp

This entry was posted on Sunday, June 18th, 2006 at 3:30 and is filed under Preprocessor, Programming, TDD, X-Macros, c++. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.