boostorg/preprocessor
1
0
Fork 1
mirror of https://github.com/boostorg/preprocessor.git synced 2025-07-23 17:17:12 +02:00
Code Issues Packages Projects Releases Wiki Activity

set -> seq

Browse Source 
[SVN r16151]
This commit is contained in:
Paul Mensonides
2002-11-07 23:41:54 +00:00
parent 5be4c6ee5a
commit 91eba2f11b
2 changed files with 205 additions and 168 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
doc/topics/file_iteration.html
View File

@ -558,10 +558,10 @@ for (int i = start(1); i <= finish(1); ++i) {
<div> <div>
The library also provides macros to access values in dimensions <i>relative</i> The library also provides macros to access values in dimensions <i>relative</i>
to the current dimension (e.g. the <i>previous</i> dimension).&nbsp; These to the current dimension (e.g. the <i>previous</i> dimension).&nbsp; These
macros take an argument that is interpreted as an offseq from the current macros take an argument that is interpreted as an offset from the current
frame.&nbsp; For example, <b>BOOST_PP_RELATIVE_ITERATION</b>(<i>1</i>) always frame.&nbsp; For example, <b>BOOST_PP_RELATIVE_ITERATION</b>(<i>1</i>) always
refers to the outer dimension immediately previous to the current refers to the outer dimension immediately previous to the current
dimension.&nbsp; An argument of <i>0</i> is interpreted as an offseq of <i>0</i> dimension.&nbsp; An argument of <i>0</i> is interpreted as an offset of <i>0</i>
which causes <b>BOOST_PP_RELATIVE_ITERATION</b>(<i>0</i>) to be equivalent to <b>BOOST_PP_ITERATION</b>().&nbsp; which causes <b>BOOST_PP_RELATIVE_ITERATION</b>(<i>0</i>) to be equivalent to <b>BOOST_PP_ITERATION</b>().&nbsp;
<b>BOOST_PP_RELATIVE_ITERATION</b>(<i>2</i>) refers to the iteration value of <b>BOOST_PP_RELATIVE_ITERATION</b>(<i>2</i>) refers to the iteration value of
the dimension immediately preceding the dimension that precedes the current the dimension immediately preceding the dimension that precedes the current

355
doc/topics/reentrancy.html
View File

@ -1,43 +1,51 @@
<html> <html>
<head> <head>
<title>reentrancy.html</title> <title>reentrancy.html</title>
<link rel="stylesheet" type="text/css" href="../styles.css"> <link rel="stylesheet" type="text/css" href="../styles.css">
</head> </head>
<body> <body>
<h4>Reentrancy</h4> <h4>
<div> Reentrancy
Macro expansion in the preprocessor is entirely functional.&nbsp; </h4>
Therefore, there is no iteration.&nbsp; <div>
Unfortunately, the preprocessor also disallows recursion.&nbsp; Macro expansion in the preprocessor is entirely functional.&nbsp; Therefore,
This means that the library must fake iteration or recursion by there is no iteration.&nbsp; Unfortunately, the preprocessor also disallows
defining sets of macros that are implemented similarly.&nbsp; recursion.&nbsp; This means that the library must fake iteration or recursion
</div> by defining seqs of macros that are implemented similarly.&nbsp;
<div> </div>
<div>
To illustrate, here is a simple concatenation macro: To illustrate, here is a simple concatenation macro:
</div> </div>
<div class="code"><pre> <div class="code">
<pre>
#define CONCAT(a, b) CONCAT_D(a, b) #define CONCAT(a, b) CONCAT_D(a, b)
#define CONCAT_D(a, b) a ## b #define CONCAT_D(a, b) a ## b
CONCAT(a, CONCAT(b, c)) // abc CONCAT(a, CONCAT(b, c)) // abc
</pre></div> </pre>
<div> </div>
This is fine for a simple case like the above, but what happens in a scenario like the following: <div>
</div> This is fine for a simple case like the above, but what happens in a scenario
<div class="code"><pre> like the following:
</div>
<div class="code">
<pre>
#define AB(x, y) CONCAT(x, y) #define AB(x, y) CONCAT(x, y)
CONCAT(A, B(p, q)) // CONCAT(p, q) CONCAT(A, B(p, q)) // CONCAT(p, q)
</pre></div> </pre>
<div> </div>
Because there is no recursion, the example above expands to <code>CONCAT(p, q)</code> rather than <code>pq</code>. <div>
</div> Because there is no recursion, the example above expands to <code>CONCAT(p, q)</code>
<div> rather than <code>pq</code>.
There are only two ways to "fix" the above.&nbsp; </div>
First, it can be documented that <code>AB</code> uses <code>CONCAT</code> and disallow usage similar to the above.&nbsp; <div>
Second, multiple concatenation macros can be provided.... There are only two ways to "fix" the above.&nbsp; First, it can be documented
</div> that <code>AB</code> uses <code>CONCAT</code> and disallow usage similar to the
<div class="code"><pre> above.&nbsp; Second, multiple concatenation macros can be provided....
</div>
<div class="code">
<pre>
#define CONCAT_1(a, b) CONCAT_1_D(a, b) #define CONCAT_1(a, b) CONCAT_1_D(a, b)
#define CONCAT_1_D(a, b) a ## b #define CONCAT_1_D(a, b) a ## b
@ -47,68 +55,80 @@ CONCAT(A, B(p, q)) // CONCAT(p, q)
#define AB(x, y) CONCAT_2(x, y) #define AB(x, y) CONCAT_2(x, y)
CONCAT_1(A, B(p, q)) // pq CONCAT_1(A, B(p, q)) // pq
</pre></div> </pre>
<div> </div>
This solves the problem.&nbsp; <div>
However, it is now necessary to know that <code>AB</code> uses, not only <i>a</i> concatenation macro, This solves the problem.&nbsp; However, it is now necessary to know that <code>AB</code>
but <code>CONCAT_2</code> specifically. uses, not only <i>a</i> concatenation macro, but <code>CONCAT_2</code> specifically.
</div> </div>
<div> <div>
A better solution is to abstract <i>which</i> concatenation macro is used.... A better solution is to abstract <i>which</i> concatenation macro is used....
</div> </div>
<div class="code"><pre> <div class="code">
<pre>
#define AB(c, x, y) CONCAT_ ## c(x, y) #define AB(c, x, y) CONCAT_ ## c(x, y)
CONCAT_1(A, B(2, p, q)) // pq CONCAT_1(A, B(2, p, q)) // pq
</pre></div> </pre>
<div> </div>
This is an example of <i>generic reentrance</i>, in this case, into a fictional set of concatenation macros.&nbsp; <div>
The <code>c</code> parameter represents the "state" of the concatenation construct, This is an example of <i>generic reentrance</i>, in this case, into a fictional
and as long as the user keeps track of this state, <code>AB</code> can be used inside of a concatenation macro. seq of concatenation macros.&nbsp; The <code>c</code> parameter represents the
</div> "state" of the concatenation construct, and as long as the user keeps track of
<div> this state, <code>AB</code> can be used inside of a concatenation macro.
The library has the same choices.&nbsp; </div>
It either has to disallow a construct being inside itself or provide multiple, equivalent definitions of a construct <div>
and provide a uniform way to <i>reenter</i> that construct.&nbsp; The library has the same choices.&nbsp; It either has to disallow a construct
There are several contructs that <i>require</i> recursion (such as <b>BOOST_PP_WHILE</b>).&nbsp; being inside itself or provide multiple, equivalent definitions of a construct
Consequently, the library chooses to provide several sets of macros with mechanisms to reenter the set at a macro and provide a uniform way to <i>reenter</i> that construct.&nbsp; There are
that has not already been used. several contructs that <i>require</i> recursion (such as <b>BOOST_PP_WHILE</b>).&nbsp;
</div> Consequently, the library chooses to provide several seqs of macros with
<div> mechanisms to reenter the seq at a macro that has not already been used.
In particular, the library must provide reentrance for <b>BOOST_PP_FOR</b>, <b>BOOST_PP_REPEAT</b>, and <b>BOOST_PP_WHILE</b>.&nbsp; </div>
There are two mechanisms that are used to accomplish this:&nbsp; state parameters (like the above concatenation example) and <i>automatic recursion</i>. <div>
</div> In particular, the library must provide reentrance for <b>BOOST_PP_FOR</b>, <b>BOOST_PP_REPEAT</b>,
<h4>State Parameters</h4> and <b>BOOST_PP_WHILE</b>.&nbsp; There are two mechanisms that are used to
<div> accomplish this:&nbsp; state parameters (like the above concatenation example)
Each of the above constructs (<b>BOOST_PP_FOR</b>, <b>BOOST_PP_REPEAT</b>, and <b>BOOST_PP_WHILE</b>) has an associated state.&nbsp; and <i>automatic recursion</i>.
This state provides the means to reenter the respective construct. </div>
</div> <h4>
<div> State Parameters
Several user-defined macros are passed to each of these constructs (for use as predicates, operations, etc.).&nbsp; </h4>
Every time a user-defined macro is invoked, it is passed the current state of the construct that invoked it so that the macro can reenter <div>
the respective set if necessary. Each of the above constructs (<b>BOOST_PP_FOR</b>, <b>BOOST_PP_REPEAT</b>, and <b>BOOST_PP_WHILE</b>)
</div> has an associated state.&nbsp; This state provides the means to reenter the
<div> respective construct.
These states are used in one of two ways--either by concatenating to or passing to another macro. </div>
</div> <div>
<div> Several user-defined macros are passed to each of these constructs (for use as
There are three types of macros that use these state parameters.&nbsp; predicates, operations, etc.).&nbsp; Every time a user-defined macro is
First, the set itself which is reentered through concatenation.&nbsp; invoked, it is passed the current state of the construct that invoked it so
Second, corresponding sets that act like they are a part of the the primary set.&nbsp; that the macro can reenter the respective seq if necessary.
These are also reentered through concatenation.&nbsp; </div>
And third, macros that internally use the first or second type of macro.&nbsp; <div>
These macros take the state as an additional argument. These states are used in one of two ways--either by concatenating to or passing
</div> to another macro.
<div> </div>
<div>
There are three types of macros that use these state parameters.&nbsp; First,
the seq itself which is reentered through concatenation.&nbsp; Second,
corresponding seqs that act like they are a part of the the primary seq.&nbsp;
These are also reentered through concatenation.&nbsp; And third, macros that
internally use the first or second type of macro.&nbsp; These macros take the
state as an additional argument.
</div>
<div>
The state of <b>BOOST_PP_WHILE</b> is symbolized by the letter <i>D</i>.&nbsp; The state of <b>BOOST_PP_WHILE</b> is symbolized by the letter <i>D</i>.&nbsp;
Two user-defined macros are passed to <b>BOOST_PP_WHILE</b>--a predicate and an operation.&nbsp; Two user-defined macros are passed to <b>BOOST_PP_WHILE</b>--a predicate and an
When <b>BOOST_PP_WHILE</b> expands these macros, it passes along its state so that these macros operation.&nbsp; When <b>BOOST_PP_WHILE</b> expands these macros, it passes
can reenter the <b>BOOST_PP_WHILE</b> set.&nbsp; along its state so that these macros can reenter the <b>BOOST_PP_WHILE</b> seq.&nbsp;
</div> </div>
<div> <div>
Consider the following multiplication implementation that illustrates this technique: Consider the following multiplication implementation that illustrates this
</div> technique:
<div class="code"><pre> </div>
<div class="code">
<pre>
// The addition interface macro. // The addition interface macro.
// The _D signifies that it reenters // The _D signifies that it reenters
// BOOST_PP_WHILE with concatenation. // BOOST_PP_WHILE with concatenation.
@ -175,79 +195,96 @@ CONCAT_1(A, B(2, p, q)) // pq
/**/ /**/
MUL(3, 2) // expands to 6 MUL(3, 2) // expands to 6
</pre></div> </pre>
<div> </div>
There are a couple things to note in the above implementation.&nbsp; <div>
First, note how <code>ADD_D</code> reenters <b>BOOST_PP_WHILE</b> using the <i>d</i> state parameter.&nbsp; There are a couple things to note in the above implementation.&nbsp; First,
Second, note how <code>MUL</code>'s operation, which is expanded by <b>BOOST_PP_WHILE</b>, passes the state note how <code>ADD_D</code> reenters <b>BOOST_PP_WHILE</b> using the <i>d</i> state
on to <code>ADD_D</code>.&nbsp; parameter.&nbsp; Second, note how <code>MUL</code>'s operation, which is
expanded by <b>BOOST_PP_WHILE</b>, passes the state on to <code>ADD_D</code>.&nbsp;
This illustrates state reentrance by both argument and concatenation. This illustrates state reentrance by both argument and concatenation.
</div> </div>
<div> <div>
For every macro in the library that uses <b>BOOST_PP_WHILE</b>, For every macro in the library that uses <b>BOOST_PP_WHILE</b>, there is a
there is a state reentrant variant.&nbsp; state reentrant variant.&nbsp; If that variant uses an argument rather than
If that variant uses an argument rather than concatenation, it is suffixed by <code>_D</code> to symbolize its concatenation, it is suffixed by <code>_D</code> to symbolize its method of
method of reentrance.&nbsp; reentrance.&nbsp; Examples or this include the library's own <b>BOOST_PP_ADD_D</b>
Examples or this include the library's own <b>BOOST_PP_ADD_D</b> and <b>BOOST_PP_MUL_D</b>.&nbsp; and <b>BOOST_PP_MUL_D</b>.&nbsp; If the variant uses concatenation, it is
If the variant uses concatenation, it is suffixed by an underscore.&nbsp; suffixed by an underscore.&nbsp; It is completed by concatenation of the
It is completed by concatenation of the state.&nbsp; state.&nbsp; This includes <b>BOOST_PP_WHILE</b> itself with <b>BOOST_PP_WHILE_</b>
This includes <b>BOOST_PP_WHILE</b> itself with <b>BOOST_PP_WHILE_</b> ## <i>d</i> and, for example, ## <i>d</i> and, for example, <b>BOOST_PP_LIST_FOLD_LEFT</b> with <b>BOOST_PP_LIST_FOLD_LEFT_</b>
<b>BOOST_PP_LIST_FOLD_LEFT</b> with <b>BOOST_PP_LIST_FOLD_LEFT_</b> ## <i>d</i>. ## <i>d</i>.
</div> </div>
<div> <div>
The same set of conventions are used for <b>BOOST_PP_FOR</b> and <b>BOOST_PP_REPEAT</b>, but with the letters The same seq of conventions are used for <b>BOOST_PP_FOR</b> and <b>BOOST_PP_REPEAT</b>,
<i>R</i> and <i>Z</i>, respectively, to symbolize their states. but with the letters <i>R</i> and <i>Z</i>, respectively, to symbolize their
</div> states.
<div> </div>
Also note that the above <code>MUL</code> implementation, though not immediately obvious, is using <i>all three</i> <div>
types of reentrance.&nbsp; Also note that the above <code>MUL</code> implementation, though not
Not only is it using both types of <i>state</i> reentrance, it is also using <i>automatic recursion</i>.... immediately obvious, is using <i>all three</i> types of reentrance.&nbsp; Not
</div> only is it using both types of <i>state</i> reentrance, it is also using <i>automatic
<h4>Automatic Recursion</h4> recursion</i>....
<div> </div>
Automatic recursion is a technique that vastly simplifies the use of reentrant constructs.&nbsp; <h4>
It is used by simply <i>not</i> using any state parameters at all. Automatic Recursion
</div> </h4>
<div> <div>
The <code>MUL</code> example above uses automatic recursion when it uses <b>BOOST_PP_WHILE</b> by itself.&nbsp; Automatic recursion is a technique that vastly simplifies the use of reentrant
In other words, <code>MUL</code> can <i>still</i> be used inside <b>BOOST_PP_WHILE</b> even though it doesn't constructs.&nbsp; It is used by simply <i>not</i> using any state parameters at
reenter <b>BOOST_PP_WHILE</b> by concatenating the state to <b>BOOST_PP_WHILE_</b>. all.
</div> </div>
<div> <div>
To accomplish this, the library uses a "trick."&nbsp; The <code>MUL</code> example above uses automatic recursion when it uses <b>BOOST_PP_WHILE</b>
Despite what it looks like, the macro <b>BOOST_PP_WHILE</b> does not take three arguments.&nbsp; by itself.&nbsp; In other words, <code>MUL</code> can <i>still</i> be used
In fact, it takes no arguments at all.&nbsp; inside <b>BOOST_PP_WHILE</b> even though it doesn't reenter <b>BOOST_PP_WHILE</b>
Instead, the <b>BOOST_PP_WHILE</b> macro expands <i>to</i> a macro that takes three arguments.&nbsp; by concatenating the state to <b>BOOST_PP_WHILE_</b>.
It simply detects what the next available <b>BOOST_PP_WHILE_</b> ## <i>d</i> macro is and returns it.&nbsp; </div>
This detection process is somewhat involved, so I won't go into <i>how</i> it works here, <div>
but suffice to say it <i>does</i> work. To accomplish this, the library uses a "trick."&nbsp; Despite what it looks
</div> like, the macro <b>BOOST_PP_WHILE</b> does not take three arguments.&nbsp; In
<div> fact, it takes no arguments at all.&nbsp; Instead, the <b>BOOST_PP_WHILE</b> macro
Using automatic recursion to reenter various sets of macros is obviously much simpler.&nbsp; expands <i>to</i> a macro that takes three arguments.&nbsp; It simply detects
It completely hides the underlying implementation details.&nbsp; what the next available <b>BOOST_PP_WHILE_</b> ## <i>d</i> macro is and returns
So, if it is so much easier to use, why do the state parameters still exist?&nbsp; it.&nbsp; This detection process is somewhat involved, so I won't go into <i>how</i>
The reason is simple as well.&nbsp; it works here, but suffice to say it <i>does</i> work.
When state parameters are used, the state is <i>known</i> at all times.&nbsp; </div>
This is not the case when automatic recursion is used.&nbsp; <div>
The automatic recursion mechanism has to <i>deduce</i> the state at each point that it is used.&nbsp; Using automatic recursion to reenter various seqs of macros is obviously much
This implies a cost in macro complexity that in some situations--notably at deep macro depths--will slow simpler.&nbsp; It completely hides the underlying implementation details.&nbsp;
So, if it is so much easier to use, why do the state parameters still
exist?&nbsp; The reason is simple as well.&nbsp; When state parameters are
used, the state is <i>known</i> at all times.&nbsp; This is not the case when
automatic recursion is used.&nbsp; The automatic recursion mechanism has to <i>deduce</i>
the state at each point that it is used.&nbsp; This implies a cost in macro
complexity that in some situations--notably at deep macro depths--will slow
some preprocessors to a crawl. some preprocessors to a crawl.
</div> </div>
<h4>Conclusion</h4> <h4>
<div> Conclusion
It is really a tradeoff whether to use state parameters or automatic recursion for reentrancy.&nbsp; </h4>
The strengths of automatic recursion are ease of use and implementation encapsulation.&nbsp; <div>
These come at a performance cost on some preprocessors in some situations.&nbsp; It is really a tradeoff whether to use state parameters or automatic recursion
The primary strength of state parameters, on the other hand, is efficiency.&nbsp; for reentrancy.&nbsp; The strengths of automatic recursion are ease of use and
Use of the state parameters is the only way to achieve <i>maximum</i> efficiency.&nbsp; implementation encapsulation.&nbsp; These come at a performance cost on some
This efficiency comes at the cost of both code complexity and exposition of implementation. preprocessors in some situations.&nbsp; The primary strength of state
</div> parameters, on the other hand, is efficiency.&nbsp; Use of the state parameters
<h4>See Also</h4> is the only way to achieve <i>maximum</i> efficiency.&nbsp; This efficiency
<ul> comes at the cost of both code complexity and exposition of implementation.
<li><a href="../ref/for.html">BOOST_PP_FOR</a></li> </div>
<li><a href="../ref/repeat.html">BOOST_PP_REPEAT</a></li> <h4>
<li><a href="../ref/while.html">BOOST_PP_WHILE</a></li> See Also
</ul> </h4>
<div class="sig">- Paul Mensonides</div> <ul>
</body> <li>
<a href="../ref/for.html">BOOST_PP_FOR</a></li>
<li>
<a href="../ref/repeat.html">BOOST_PP_REPEAT</a></li>
<li>
<a href="../ref/while.html">BOOST_PP_WHILE</a></li>
</ul>
<div class="sig">
- Paul Mensonides
</div>
</body>
</html> </html>