ceph/src/boost/libs/preprocessor/doc/topics/incompatible.html

   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).&nbsp;
  10                 These fall into roughly three categories:&nbsp;
  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>.&nbsp;
  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.&nbsp;
  24         </div>
  25         <div>
  26                 These target macros must now except a <i>third</i> parameter.&nbsp;
  27                 This extra parameter becomes the <i>first</i> parameter in every target macro.&nbsp;
  28                 It represents the next repetition dimension and brings <b>BOOST_PP_REPEAT</b> inline with rest of the library.&nbsp;
  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.&nbsp;
  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.&nbsp;
  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.&nbsp;
  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>.&nbsp;
  53                 Any other usage is not supported by the library.&nbsp;
  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.&nbsp;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.&nbsp;
  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.&nbsp;
  73                 The library makes it appear that it takes three parameters, but that is the trick of <i>automatic-recursion</i>.&nbsp;
  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.&nbsp;
  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.&nbsp;
  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>.&nbsp;
  98                 Also, the accumulation macro passed into <b>BOOST_PP_LIST_FOLD_RIGHT</b> was called with reversed parameters as well.&nbsp;
  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.&nbsp;
 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>