libs/preprocessor/doc/ref/while_d.html

   1 <html>
   2 <head>
   3         <title>BOOST_PP_WHILE_d</title>
   4         <link rel="stylesheet" type="text/css" href="../styles.css">
   5 </head>
   6 <body>
   7         <div style="margin-left:  0px;">
   8                 The <b>BOOST_PP_WHILE_<i>d</i></b> macro represents a reentry into the <b>BOOST_PP_WHILE</b> looping construct.
   9         </div>
  10         <h4>Usage</h4>
  11                 <div class="code">
  12                         <b>BOOST_PP_WHILE_</b> ## <i>d</i>(<i>pred</i>, <i>op</i>, <i>state</i>)
  13                 </div>
  14         <h4>Arguments</h4>
  15                 <dl>
  16                         <dt>d</dt>
  17                         <dd>
  18                                 The next available <b>BOOST_PP_WHILE</b> iteration.
  19                         </dd>
  20                         <dt>pred</dt>
  21                         <dd>
  22                                 A binary predicate of the form <i>pred</i>(<i>d</i>, <i>state</i>).&nbsp;
  23                                 This predicate is expanded by <b>BOOST_PP_WHILE</b> with the next available
  24                                 iteration <i>d</i> and the current <i>state</i>.&nbsp;
  25                                 This predicate must expand to value in the range of <i>0</i> to <b>BOOST_PP_LIMIT_MAG</b>.
  26                                 The construct continues to loop until this predicate returns <i>0</i>.&nbsp;
  27                                 When this predicate returns <i>0</i>, <b>BOOST_PP_WHILE</b> returns the current <i>state</i>.
  28                         </dd>
  29                         <dt>op</dt>
  30                         <dd>
  31                                 A binary operation of the form <i>op</i>(<i>d</i>, <i>state</i>).&nbsp;
  32                                 This operation is expanded by <b>BOOST_PP_WHILE</b> with the next available
  33                                 iteration <i>d</i> and the current <i>state</i>.&nbsp;
  34                                 This macro is repeatedly applied to the <i>state</i>, each time producing a new <i>state</i>, until <i>pred</i> returns <i>0</i>.
  35                         </dd>
  36                         <dt>state</dt>
  37                         <dd>
  38                                 The initial state.&nbsp;
  39                                 Often this argument is a <i>tuple</i>.
  40                         </dd>
  41                 </dl>
  42         <h4>Remarks</h4>
  43                 <div>
  44                         This macro iterates <i>op</i>(<i>d</i>, <i>state</i>) while <i>pred</i>(<i>d</i>, <i>state</i>) is non-zero.&nbsp;
  45                         In other words expands to:
  46                         <div>
  47                                 <i>op</i>(<i>d</i>, ... <i>op</i>(<i>d</i>, <i>op</i>(<i>d</i>, <i>state</i>)) ... ).
  48                         </div>
  49                 </div>
  50                 <div>
  51                         At certain times, it may be necessary to perform the concatenation with <b>BOOST_PP_CAT</b> rather than the preprocessor token-pasting operator.&nbsp;
  52                         This happens when the <i>d</i> value is a macro invocation itself.&nbsp;
  53                         It needs a delay to allow it to expand.&nbsp;
  54                         The syntax in such a scenario becomes:
  55                         <div>
  56                                 <b>BOOST_PP_CAT</b>(<b>BOOST_PP_WHILE_</b>, <i>d</i>)(<i>pred</i>, <i>op</i>, <i>state</i>).
  57                         </div>
  58                 </div>
  59                 <div>
  60                         Previously, it was possible to concatenate <i>d</i> directly to <b>BOOST_PP_WHILE</b> (without the trailing underscore).&nbsp;
  61                         This is no longer supported.
  62                 </div>
  63         <h4>See Also</h4>
  64                 <ul>
  65                         <li><a href="cat.html">BOOST_PP_CAT</a></li>
  66                         <li><a href="limit_mag.html">BOOST_PP_LIMIT_MAG</a></li>
  67                         <li><a href="while.html">BOOST_PP_WHILE</a></li>
  68                 </ul>
  69         <h4>Requirements</h4>
  70                 <div>
  71                         <b>Header:</b> &nbsp;<a href="../headers/control/while.html">&lt;boost/preprocessor/control/while.hpp&gt;</a>
  72                 </div>
  73         <h4>Sample Code</h4>
  74 <div><pre>
  75 #include &lt;<a href="../headers/arithmetic/add.html">boost/preprocessor/arithmetic/add.hpp</a>&gt;
  76 #include &lt;<a href="../headers/arithmetic/dec.html">boost/preprocessor/arithmetic/dec.hpp</a>&gt;
  77 #include &lt;<a href="../headers/array/elem.html">boost/preprocessor/array/elem.hpp</a>&gt;
  78 #include &lt;<a href="../headers/array/size.html">boost/preprocessor/array/size.hpp</a>&gt;
  79 #include &lt;<a href="../headers/control/while.html">boost/preprocessor/control/while.hpp</a>&gt;
  80 #include &lt;<a href="../headers/tuple/elem.html">boost/preprocessor/tuple/elem.hpp</a>&gt;
  81
  82 #define PRED(d, data) <a href="tuple_elem.html">BOOST_PP_TUPLE_ELEM</a>(3, 1, data)
  83
  84 #define OP(d, data) \
  85    OP_D( \
  86       d, \
  87       <a href="tuple_elem.html">BOOST_PP_TUPLE_ELEM</a>(3, 0, data), \
  88       <a href="tuple_elem.html">BOOST_PP_TUPLE_ELEM</a>(3, 1, data), \
  89       <a href="tuple_elem.html">BOOST_PP_TUPLE_ELEM</a>(3, 2, data) \
  90    ) \
  91    /**/
  92
  93 #define OP_D(d, res, i, array) \
  94    ( \
  95       <a href="add_d.html">BOOST_PP_ADD_D</a>( \
  96          d, res, \
  97          <a href="array_elem.html">BOOST_PP_ARRAY_ELEM</a>(<a href="dec.html">BOOST_PP_DEC</a>(i), array)), \
  98       <a href="dec.html">BOOST_PP_DEC</a>(i), \
  99       array \
 100    ) \
 101    /**/
 102
 103 #define ACCUMULATE_D(d, array) \
 104    <a href="tuple_elem.html">BOOST_PP_TUPLE_ELEM</a>( \
 105       3, 0, \
 106       <a href="while_d.html">BOOST_PP_WHILE_</a> ## d( \
 107          PRED, OP, \
 108          (0, <a href="array_size.html">BOOST_PP_ARRAY_SIZE</a>(array), array) \
 109       ) \
 110    ) \
 111    /**/
 112
 113 #define ARRAY (4, (1, 2, 3, 4))
 114
 115 ACCUMULATE_D(1, ARRAY)// expands to 10
 116 </pre></div>
 117         <hr size="1">
 118         <div style="margin-left: 0px;">
 119                 <i>© Copyright <a href="http://www.housemarque.com" target="_top">Housemarque Oy</a> 2002</i>
 120                 </br><i>© Copyright Paul Mensonides 2002</i>
 121         </div>
 122         <div style="margin-left: 0px;">
 123                 <p><small>Distributed under the Boost Software License, Version 1.0. (See
 124                 accompanying file <a href="../../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
 125                 copy at <a href=
 126                 "http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)</small></p>
 127         </div>
 128 </body>
 129 </html>