Incompatibilities
There are several incompatibilities with the previous Boost release (1.28).
These fall into roughly three categories:
- the horizontal repetition primitives based on BOOST_PP_REPEAT
- the reentrancy syntax
- list folding
Repetition Targets
First, and probably the most commonly used, is the target macros passed into BOOST_PP_REPEAT and the horizontal repetition contructs that use BOOST_PP_REPEAT.
This includes all of the BOOST_PP_REPEAT_* primitives and all of the BOOST_PP_ENUM_* primitives that require a target macro.
The incompatiblity is trivial, but it will require that the source be updated.
These target macros must now except a third parameter.
This extra parameter becomes the first parameter in every target macro.
It represents the next repetition dimension and brings BOOST_PP_REPEAT inline with rest of the library.
So, what once was:
#define macro(n, data) ...
BOOST_PP_REPEAT(5, macro, data)
...is now:
#define macro(z, n, data) ...
BOOST_PP_REPEAT(5, macro, data)
This parameter can be used for highly efficient reentrance into the BOOST_PP_REPEAT mechanism.
However, it is not necessary to use it as the library can automatically detect the next available repetition dimension.
Dimensional Ordering
Because of this detection, however, it is unsafe to use BOOST_PP_REPEAT_1ST, BOOST_PP_REPEAT_2ND, and BOOST_PP_REPEAT_3RD out of order.
These macros bypass the automatic-recursion mechanism, and the automatic-recursion mechanism relies on macros being used in the proper order.
To clarify, if you use these bypass macros, the outer-most repetition must be BOOST_PP_REPEAT_1ST, then BOOST_PP_REPEAT_2ND, and finally BOOST_PP_REPEAT_3RD.
Any other usage is not supported by the library.
Sometimes it may work, and other times it won't.
Reentrancy Syntax
Automatic-recursion brings with it another issue as well. Previously, the reentrancy syntax for BOOST_PP_WHILE (and similarly for BOOST_PP_FOR) was:
BOOST_PP_WHILE ## d(pred, op, state)
...or:
BOOST_PP_CAT(BOOST_PP_WHILE, d)(pred, op, state)
Under the automatic-recursion model, the BOOST_PP_CAT version breaks.
This is because BOOST_PP_CAT allows its arguments to expand prior to concatenation,
and BOOST_PP_WHILE is a macro that expands without arguments.
The library makes it appear that it takes three parameters, but that is the trick of automatic-recursion.
It works similarly to the following:
#define A(x, y) ...
#define B A
// ...
B(2, 3)
The syntax makes it look like the B macro above takes two arguments, but it doesn't.
The automatic-recursion mechanism works in this fashion, except that the "B" macro deduces the next available "A" macro.
Because some preprocessors are still slow, direct reentrancy (sans automatic-recursion) is still necessary in non-trivial cases.
Consequently, the library uses a new syntax to handle reentrancy:
BOOST_PP_FOR_ ## r(state, pred, op, macro)
BOOST_PP_REPEAT_ ## z(count, macro, data)
BOOST_PP_WHILE_ ## d(pred, op, state)
Folding
Previously, the BOOST_PP_LIST_FOLD_RIGHT macros' arguments were the reverse of BOOST_PP_LIST_FOLD_LEFT.
Also, the accumulation macro passed into BOOST_PP_LIST_FOLD_RIGHT was called with reversed parameters as well.
This discrepancy has been eliminated.
To illustrate, BOOST_PP_LIST_FOLD_RIGHT used to be used like this:
#define macro(d, elem, state)
BOOST_PP_LIST_FOLD_RIGHT(macro, list, state)
This signature has been replaced by...
#define macro(d, state, elem)
BOOST_PP_LIST_FOLD_RIGHT(macro, state, list)
Summary
The library has many new features not present in the 1.28 release, and this list does not attempt to enumerate them.
This is simply a list of things that must change for code to be compatible with this new release.
See Also
- Paul Mensonides