1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
<html>
<head>
<title>incompatible.html</title>
<link rel="stylesheet" type="text/css" href="../styles.css">
</head>
<body>
<h4>Incompatibilities</h4>
<div>
There are several incompatibilities with the previous Boost release (1.28).
These fall into roughly three categories:
</div>
<ul>
<li>the horizontal repetition primitives based on <b>BOOST_PP_REPEAT</b></li>
<li>the reentrancy syntax</li>
<li><i>list</i> folding</li>
</ul>
<h4>Repetition Targets</h4>
<div>
First, and probably the most commonly used, is the target macros passed into <b>BOOST_PP_REPEAT</b> and the horizontal repetition contructs that use <b>BOOST_PP_REPEAT</b>.
This includes all of the <b>BOOST_PP_REPEAT_</b>* primitives and all of the <b>BOOST_PP_ENUM_</b>* primitives that require a target macro.
</div>
<div>
The incompatiblity is trivial, but it will require that the source be updated.
</div>
<div>
These target macros must now except a <i>third</i> parameter.
This extra parameter becomes the <i>first</i> parameter in every target macro.
It represents the next repetition dimension and brings <b>BOOST_PP_REPEAT</b> inline with rest of the library.
</div>
<div>
So, what once was:
</div>
<div class="code">
#define <i>macro</i>(<i>n</i>, <i>data</i>) ...<br>
<b>BOOST_PP_REPEAT</b>(<i>5</i>, <i>macro</i>, <i>data</i>)
</div>
<div>
...is now:
</div>
<div class="code">
#define <i>macro</i>(<i>z</i>, <i>n</i>, <i>data</i>) ...<br>
<b>BOOST_PP_REPEAT</b>(<i>5</i>, <i>macro</i>, <i>data</i>)
</div>
<div>
This parameter can be used for highly efficient reentrance into the <b>BOOST_PP_REPEAT</b> mechanism.
However, it is not necessary to use it as the library can automatically detect the next available repetition dimension.
</div>
<h4>Dimensional Ordering</h4>
<div>
Because of this detection, however, it is unsafe to use <b>BOOST_PP_REPEAT_1ST</b>, <b>BOOST_PP_REPEAT_2ND</b>, and <b>BOOST_PP_REPEAT_3RD</b> out of order.
These macros bypass the <i>automatic-recursion</i> mechanism, and the <i>automatic-recursion</i> mechanism relies on macros being used in the proper order.
To clarify, if you use these bypass macros, the outer-most repetition <i>must</i> be <b>BOOST_PP_REPEAT_1ST</b>, then <b>BOOST_PP_REPEAT_2ND</b>, and finally <b>BOOST_PP_REPEAT_3RD</b>.
Any other usage is not supported by the library.
Sometimes it may work, and other times it won't.
</div>
<h4>Reentrancy Syntax</h4>
<div>
<i>Automatic-recursion</i> brings with it another issue as well. Previously, the reentrancy syntax for <b>BOOST_PP_WHILE</b> (and similarly for <b>BOOST_PP_FOR</b>) was:
</div>
<div class="code">
<b>BOOST_PP_WHILE</b> ## <i>d</i>(<i>pred</i>, <i>op</i>, <i>state</i>)
</div>
<div>
...or:
</div>
<div class="code">
<b>BOOST_PP_CAT</b>(<b>BOOST_PP_WHILE</b>, <i>d</i>)(<i>pred</i>, <i>op</i>, <i>state</i>)
</div>
<div>
Under the <i>automatic-recursion</i> model, the <b>BOOST_PP_CAT</b> version breaks.
This is because <b>BOOST_PP_CAT</b> allows its arguments to expand prior to concatenation,
and <b>BOOST_PP_WHILE</b> is a macro that expands without arguments.
The library makes it appear that it takes three parameters, but that is the trick of <i>automatic-recursion</i>.
It works similarly to the following:
</div>
<div class="code">
#define A(x, y) ...<br>
#define B A<br>
// ...<br>
B(2, 3)
</div>
<div>
The syntax makes it look like the <i>B</i> macro above takes two arguments, but it doesn't.
The <i>automatic-recursion</i> mechanism works in this fashion, except that the "<i>B</i>" macro deduces the next available "<i>A</i>" macro.
</div>
<div>
Because some preprocessors are still slow, direct reentrancy (sans <i>automatic-recursion</i>) is still necessary in non-trivial cases.
Consequently, the library uses a new syntax to handle reentrancy:
</div>
<div class="code">
<b>BOOST_PP_FOR_</b> ## <i>r</i>(<i>state</i>, <i>pred</i>, <i>op</i>, <i>macro</i>)<br>
<b>BOOST_PP_REPEAT_</b> ## <i>z</i>(<i>count</i>, <i>macro</i>, <i>data</i>)<br>
<b>BOOST_PP_WHILE_</b> ## <i>d</i>(<i>pred</i>, <i>op</i>, <i>state</i>)
</div>
<h4>Folding</h4>
<div>
Previously, the <b>BOOST_PP_LIST_FOLD_RIGHT</b> macros' arguments were the reverse of <b>BOOST_PP_LIST_FOLD_LEFT</b>.
Also, the accumulation macro passed into <b>BOOST_PP_LIST_FOLD_RIGHT</b> was called with reversed parameters as well.
This discrepancy has been eliminated.
</div>
<div>
To illustrate, <b>BOOST_PP_LIST_FOLD_RIGHT</b> used to be used like this:
</div>
<div class="code">
#define <i>macro</i>(<i>d</i>, <u><i>elem</i></u>, <u><i>state</i></u>)<br>
<b>BOOST_PP_LIST_FOLD_RIGHT</b>(<i>macro</i>, <u><i>list</i></u>, <u><i>state</i></u>)
</div>
<div>
This signature has been replaced by...
</div>
<div class="code">
#define <i>macro</i>(<i>d</i>, <u><i>state</i></u>, <u><i>elem</i></u>)<br>
<b>BOOST_PP_LIST_FOLD_RIGHT</b>(<i>macro</i>, <u><i>state</i></u>, <u><i>list</i></u>)
</div>
<h4>Summary</h4>
<div>
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 <i>must</i> change for code to be compatible with this new release.
</div>
<h4>See Also</h4>
<ul>
<li><a href="../ref/for.html">BOOST_PP_FOR</a></li>
<li><a href="../ref/list_fold_right.html">BOOST_PP_LIST_FOLD_RIGHT</a></li>
<li><a href="../ref/repeat.html">BOOST_PP_REPEAT</a></li>
<li><a href="../ref/while.html">BOOST_PP_WHILE</a></li>
</ul>
<div class="sig">- Paul Mensonides</div>
</body>
</html>
|
