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 <i>� Copyright <a href="http://www.housemarque.com" target="_top">Housemarque Oy</a> 2002</i> 131 </br><i>� Copyright Paul Mensonides 2002</i> 132 </div> 133 <div style="margin-left: 0px;"> 134 <p><small>Distributed under the Boost Software License, Version 1.0. (See 135 accompanying file <a href="../../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or 136 copy at <a href= 137 "http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)</small></p> 138 </div> 139</body> 140</html> 141