mirror of
https://github.com/boostorg/preprocessor.git
synced 2025-07-01 23:11:00 +02:00
108 lines
4.8 KiB
HTML
108 lines
4.8 KiB
HTML
|
<HTML><HEAD><TITLE>Boost PREPROCESSOR library</TITLE><BODY bgcolor="#FFFFFF">
|
||
|
|
|
||
|
|
<a href="index.htm"><IMG height=86 alt="c++boost.gif (8819 bytes)" src="../../../../c++boost.gif" width=277 align=center></a>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
|
||
|
|
<H1>#include <<a href="../../../../boost/preprocessor/while.hpp">boost/preprocessor/while.hpp</a>></H1>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
|
||
|
|
<H2><a name="BOOST_PP_WHILE">#define BOOST_PP_WHILE</a>(C,F,X)</H2>
|
||
|
|
<P>Iterates F(D,X) while C(D,X) is true.</P>
|
||
|
|
|
||
|
|
<P>In other words, expands to:</P>
|
||
|
|
|
||
|
|
<PRE>
|
||
|
|
F(D, ... F(D, F(D,X) ) ... )
|
||
|
|
</PRE>
|
||
|
|
|
||
|
|
<P>The depth of iteration is determined by C(D,X).</P>
|
||
|
|
|
||
|
|
<H3>Legend</H3>
|
||
|
|
<UL>
|
||
|
|
<LI><B>X</B> is the current state of iteration. The state is usually a tuple.
|
||
|
|
<LI><B>C</B> is the condition for iteration. It must expand to a decimal
|
||
|
|
integer literal.
|
||
|
|
<LI><B>F</B> is the iterated macro. Note that if the state is a tuple, then
|
||
|
|
F(D,X) usually expands to a tuple of the same number of elements.
|
||
|
|
<LI><B>D</B> is the recursion depth and should only be used as a parameter
|
||
|
|
to other macros using <a href="while.htm#BOOST_PP_WHILE">BOOST_PP_WHILE</a>(). Such macros include
|
||
|
|
<a href="arithmetic_add.htm#BOOST_PP_ADD">BOOST_PP_ADD</a>() and other arithmetic operations. For each macro using
|
||
|
|
<a href="while.htm#BOOST_PP_WHILE">BOOST_PP_WHILE</a>(), there is a version of the macro, distinguished by the
|
||
|
|
D suffix (e.g. BOOST_PP_ADD_D()), that accepts an additional recursion
|
||
|
|
depth as the first parameter. This technique is necessary to avoid
|
||
|
|
recursively expanding the same macro again, which is not permitted by the
|
||
|
|
C++ preprocessor.
|
||
|
|
</UL>
|
||
|
|
|
||
|
|
<P>NOTE: The value of the D parameter may exceed <a href="limits.htm#BOOST_PP_LIMIT_MAG">BOOST_PP_LIMIT_MAG</a>.</P>
|
||
|
|
|
||
|
|
<H3>Caveat</H3>
|
||
|
|
|
||
|
|
<P>Using <a href="while.htm#BOOST_PP_WHILE">BOOST_PP_WHILE</a>() is a bit tricky. This is due to the C++ preprocessor
|
||
|
|
limitations. It is recommended to take a look at the implementations of the
|
||
|
|
various PREPROCESSOR library primitives such as <a href="arithmetic_add.htm#BOOST_PP_ADD">BOOST_PP_ADD</a>() for additional
|
||
|
|
examples.</P>
|
||
|
|
|
||
|
|
<H3>Example</H3>
|
||
|
|
<UL>
|
||
|
|
<LI><a href="../../example/count_down.c">count_down.c</a>
|
||
|
|
</UL>
|
||
|
|
|
||
|
|
<P>For a more complex example, let's take a look at an implementation of
|
||
|
|
<a href="arithmetic_mul.htm#BOOST_PP_MUL">BOOST_PP_MUL</a>().</P>
|
||
|
|
|
||
|
|
<PRE>
|
||
|
|
#define <a href="arithmetic_mul.htm#BOOST_PP_MUL">BOOST_PP_MUL</a>(X,Y) BOOST_PP_MUL_D(0,X,Y)
|
||
|
|
// Since the macro is implemented using WHILE, the actual implementation
|
||
|
|
// takes a depth as a parameter so that it can be called inside a WHILE.
|
||
|
|
// The above easy-to-use version simply uses 0 as the depth and can not be
|
||
|
|
// called inside a WHILE.
|
||
|
|
|
||
|
|
#define BOOST_PP_MUL_D(D,X,Y)\
|
||
|
|
<a href="tuple_elem.htm#BOOST_PP_TUPLE_ELEM">BOOST_PP_TUPLE_ELEM</a>(3,0,<a href="while.htm#BOOST_PP_WHILE">BOOST_PP_WHILE</a>##D(BOOST_PP_MUL_C,BOOST_PP_MUL_F,(0,X,Y)))
|
||
|
|
// ^^^ ^^^ ^^ ^^ ^^^^^^^
|
||
|
|
// #1 #2 #3 #3 #1
|
||
|
|
//
|
||
|
|
// #1) The state is a 3-tuple. After the iteration is finished, the first
|
||
|
|
// element of the tuple is the result.
|
||
|
|
//
|
||
|
|
// #2) The WHILE primitive is "invoked" directly. <a href="while.htm#BOOST_PP_WHILE">BOOST_PP_WHILE</a>(D,...)
|
||
|
|
// can't be used because it would not be expanded by the C++ preprocessor.
|
||
|
|
//
|
||
|
|
// #3) ???_C is the condition and ???_F is the iteration macro.
|
||
|
|
|
||
|
|
#define BOOST_PP_MUL_C(D,P)\
|
||
|
|
<a href="tuple_elem.htm#BOOST_PP_TUPLE_ELEM">BOOST_PP_TUPLE_ELEM</a>(3,2,P)
|
||
|
|
// Iteration is finished when the counter reaches 0.
|
||
|
|
|
||
|
|
#define BOOST_PP_MUL_F(D,P)\
|
||
|
|
( BOOST_PP_ADD_D(D,<a href="tuple_elem.htm#BOOST_PP_TUPLE_ELEM">BOOST_PP_TUPLE_ELEM</a>(3,0,P),<a href="tuple_elem.htm#BOOST_PP_TUPLE_ELEM">BOOST_PP_TUPLE_ELEM</a>(3,1,P))\
|
||
|
|
, <a href="tuple_elem.htm#BOOST_PP_TUPLE_ELEM">BOOST_PP_TUPLE_ELEM</a>(3,1,P)\
|
||
|
|
, <a href="dec.htm#BOOST_PP_DEC">BOOST_PP_DEC</a>(<a href="tuple_elem.htm#BOOST_PP_TUPLE_ELEM">BOOST_PP_TUPLE_ELEM</a>(3,2,P))\
|
||
|
|
)
|
||
|
|
// ( The result is increased by the multiplier.
|
||
|
|
// , The multiplier is retained without change.
|
||
|
|
// , The counter is decreased.
|
||
|
|
// )
|
||
|
|
</PRE>
|
||
|
|
|
||
|
|
<H3>Implementation rationale</H3>
|
||
|
|
<UL>
|
||
|
|
<LI>The maximum iteration depth is greater than 2*<a href="limits.htm#BOOST_PP_LIMIT_MAG">BOOST_PP_LIMIT_MAG</a> to make
|
||
|
|
it possible to compute N*N functions.
|
||
|
|
</UL>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
|
||
|
|
<p>(C) Copyright Housemarque Oy 2002</p>
|
||
|
|
|
||
|
|
<p>Permission to copy, use, modify, sell and distribute this document is granted
|
||
|
|
provided this copyright notice appears in all copies. This document is provided
|
||
|
|
"as is" without express or implied warranty, and with no claim as to its suitability
|
||
|
|
for any purpose.</p>
|
||
|
|
|
||
|
|
<p>Generated: <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %b %Y" startspan --><!--webbot bot="Timestamp" endspan i-checksum="15246" --></p>
|
||
|
|
|
||
|
|
</BODY></HTML>
|