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