incompatible.html

#### 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

- BOOST_PP_FOR
- BOOST_PP_LIST_FOLD_RIGHT
- BOOST_PP_REPEAT
- BOOST_PP_WHILE

- Paul Mensonides

© Copyright Housemarque Oy 2002 © Copyright Paul Mensonides 2002

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at www.boost.org/LICENSE_1_0.txt)