Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/preprocessor/doc/topics/incompatible.html @ 29

Last change on this file since 29 was 29, checked in by landauf, 16 years ago

updated boost from 1_33_1 to 1_34_1
File size: 6.1 KB
Line 
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>
Note: See TracBrowser for help on using the repository browser.