|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r66032 - in sandbox/variadic_macro_data/libs/variadic_macro_data/doc: . html html/the_variadic_macro_data_library
From: eldiener_at_[hidden]
Date: 2010-10-17 00:32:15
Author: eldiener
Date: 2010-10-17 00:32:08 EDT (Sun, 17 Oct 2010)
New Revision: 66032
URL: http://svn.boost.org/trac/boost/changeset/66032
Log:
Updated docs and added history and version
Added:
sandbox/variadic_macro_data/libs/variadic_macro_data/doc/history.txt (contents, props changed)
sandbox/variadic_macro_data/libs/variadic_macro_data/doc/version.txt (contents, props changed)
Text files modified:
sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDComparison.qbk | 53 ++++++++++++++++++++++++++++-
sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDIntroduction.qbk | 2 +
sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_DATA_ELEM.html | 2
sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_DATA_SIZE.html | 2
sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_DATA_TO_PP_ARRAY.html | 2
sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_DATA_TO_PP_LIST.html | 2
sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_DATA_TO_PP_SEQ.html | 2
sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_DATA_TO_PP_TUPLE.html | 2
sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_ARRAY_TO_DATA.html | 2
sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_LIST_TO_DATA.html | 2
sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_SEQ_TO_DATA.html | 2
sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_TUPLE_ELEM.html | 2
sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_TUPLE_REM_CTOR.html | 2
sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_TUPLE_REVERSE.html | 2
sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_TUPLE_SIZE.html | 2
sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_TUPLE_TO_DATA.html | 2
sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_TUPLE_TO_LIST.html | 2
sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_TUPLE_TO_SEQ.html | 2
sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/index.html | 9 +++-
sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/the_variadic_macro_data_library/vmd_comparison.html | 72 ++++++++++++++++++++++++++++++++++++---
20 files changed, 141 insertions(+), 27 deletions(-)
Modified: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDComparison.qbk
==============================================================================
--- sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDComparison.qbk (original)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDComparison.qbk 2010-10-17 00:32:08 EDT (Sun, 17 Oct 2010)
@@ -37,7 +37,7 @@
functionality to do just that with its macros which convert from
variadic macro data to Boost PP data types.
-[section:vmd_comp_example Use-case example]
+[section:vmd_comp_example An example design]
A typical situation is designing a macro for end-users which
takes variadic data as its argument. Let's call this macro,
@@ -81,13 +81,62 @@
The end-user would pass data to this macro in this way:
- ENDUSER_MACRO(a,b,c,d,e)
+ ENDUSER_MACRO(a,b,c,d,e) // etc. with each token being somma-separated from each other
I think this last way of passing variadic data is more
natural to an end-user than using a Boost PP sequence
directly, but of course it depends on compiler variadic
macro support.
+One decision to be made is whether to support, for any given variadic data
+macro functionality, a single macro or two macros with slightly different
+names.
+
+Single macro design:
+
+In our example, if we wish to support a single macro, for compilers that
+both support or do not support variadic macros, the code would be:
+
+ #if defined(BOOST_NO_VARIADIC_MACROS)
+ #define ENDUSER_MACRO(ppSequence) ENDUSER_DETAIL_MACRO(ppSequence)
+ #else
+ #define ENDUSER_MACRO(...) ENDUSER_DETAIL_MACRO(VMD_DATA_TO_PP_SEQ(__VA_ARGS__))
+ #endif
+
+We would now have a single macro which would be used slightly differently by the
+end-user depending on whether the compiler being used supported variadic macros
+or not. This might not be best if the end-user's code needed to work for different
+compilers, some of which support variadic macros and some of which do not. In that
+latter case, a dual macro design ( see below ) might be better.
+
+Another solution supporting a single macro is to just ignore variadic macros,
+and then our solution would be:
+
+ #define ENDUSER_MACRO(ppSequence) ENDUSER_DETAIL_MACRO(ppSequence)
+
+We could also ignore any compilers which do not support variadic macros,
+and then our solution would be:
+
+ #if !defined(BOOST_NO_VARIADIC_MACROS)
+ #define ENDUSER_MACRO(...) ENDUSER_DETAIL_MACRO(VMD_DATA_TO_PP_SEQ(__VA_ARGS__))
+ #endif
+
+Dual macro design:
+
+Perhaps best is to provide two macros with slightly different names. Our solution
+would then be:
+
+ #define ENDUSER_MACRO(ppSequence) ENDUSER_DETAIL_MACRO(ppSequence)
+ #if !defined(BOOST_NO_VARIADIC_MACROS)
+ #define ENDUSER_MACRO_VM(...) ENDUSER_DETAIL_MACRO(VMD_DATA_TO_PP_SEQ(__VA_ARGS__))
+ #endif
+
+Here I have attached an '_VM' to the name of the macro which supports
+variadic macros.
+
+In an ideal world, once the new C++ standard is ratified, all compilers
+will support variadic macros.
+
[endsect]
[endsect]
Modified: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDIntroduction.qbk
==============================================================================
--- sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDIntroduction.qbk (original)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDIntroduction.qbk 2010-10-17 00:32:08 EDT (Sun, 17 Oct 2010)
@@ -1,5 +1,7 @@
[section:vmd_intro Introduction]
+Welcome to the variadic macro data library version 1.1 .
+
The variadic macro data library, or VMD for short, is a library
of macros which provide important functionality for variadic
macros as well as integrating variadic macros with the Boost
Added: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/history.txt
==============================================================================
--- (empty file)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/history.txt 2010-10-17 00:32:08 EDT (Sun, 17 Oct 2010)
@@ -0,0 +1,8 @@
+Version 1.1
+
+1) Added better documentation for using
+ variadic data with Boost PP and VMD.
+
+Version 1.0
+
+Initial version of the libary.
\ No newline at end of file
Modified: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_DATA_ELEM.html
==============================================================================
--- sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_DATA_ELEM.html (original)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_DATA_ELEM.html 2010-10-17 00:32:08 EDT (Sun, 17 Oct 2010)
@@ -33,7 +33,7 @@
</span>VMD_DATA_ELEM(n, ...)</pre></div>
<div class="refsect1">
-<a name="id938660"></a><h2>Description</h2>
+<a name="id924464"></a><h2>Description</h2>
<p>n = number of the variadic macro data argument. The number starts from 0 to the number of variadic macro data arguments - 1. The maximum number for n is 63.</p>
<p>... = variadic macro data.</p>
<p>returns = the particular macro data argument as specified by n. The argument returned can be any valid preprocessing token. </p>
Modified: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_DATA_SIZE.html
==============================================================================
--- sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_DATA_SIZE.html (original)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_DATA_SIZE.html 2010-10-17 00:32:08 EDT (Sun, 17 Oct 2010)
@@ -33,7 +33,7 @@
</span>VMD_DATA_SIZE(...)</pre></div>
<div class="refsect1">
-<a name="id938621"></a><h2>Description</h2>
+<a name="id924425"></a><h2>Description</h2>
<p>... = variadic macro data.</p>
<p>returns = the number of comma-separated variadic macro data arguments being passed to it.</p>
<p>The value returned can be between 1 and 64. </p>
Modified: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_DATA_TO_PP_ARRAY.html
==============================================================================
--- sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_DATA_TO_PP_ARRAY.html (original)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_DATA_TO_PP_ARRAY.html 2010-10-17 00:32:08 EDT (Sun, 17 Oct 2010)
@@ -33,7 +33,7 @@
</span>VMD_DATA_TO_PP_ARRAY(...)</pre></div>
<div class="refsect1">
-<a name="id938736"></a><h2>Description</h2>
+<a name="id924541"></a><h2>Description</h2>
<p>... = variadic macro data.</p>
<p>returns = a Boost PP library array data type.</p>
<p>You can use the result of this macro whenever you need to pass a Boost PP library array as data to a Boost PP library macro. </p>
Modified: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_DATA_TO_PP_LIST.html
==============================================================================
--- sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_DATA_TO_PP_LIST.html (original)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_DATA_TO_PP_LIST.html 2010-10-17 00:32:08 EDT (Sun, 17 Oct 2010)
@@ -33,7 +33,7 @@
</span>VMD_DATA_TO_PP_LIST(...)</pre></div>
<div class="refsect1">
-<a name="id938775"></a><h2>Description</h2>
+<a name="id924579"></a><h2>Description</h2>
<p>... = variadic macro data.</p>
<p>returns = a Boost PP library list data type.</p>
<p>You can use the result of this macro whenever you need to pass a Boost PP library list as data to a Boost PP library macro. </p>
Modified: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_DATA_TO_PP_SEQ.html
==============================================================================
--- sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_DATA_TO_PP_SEQ.html (original)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_DATA_TO_PP_SEQ.html 2010-10-17 00:32:08 EDT (Sun, 17 Oct 2010)
@@ -33,7 +33,7 @@
</span>VMD_DATA_TO_PP_SEQ(...)</pre></div>
<div class="refsect1">
-<a name="id938813"></a><h2>Description</h2>
+<a name="id924617"></a><h2>Description</h2>
<p>... = variadic macro data.</p>
<p>returns = a Boost PP library sequence data type.</p>
<p>You can use the result of this macro whenever you need to pass a Boost PP library sequence as data to a Boost PP library macro. </p>
Modified: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_DATA_TO_PP_TUPLE.html
==============================================================================
--- sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_DATA_TO_PP_TUPLE.html (original)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_DATA_TO_PP_TUPLE.html 2010-10-17 00:32:08 EDT (Sun, 17 Oct 2010)
@@ -33,7 +33,7 @@
</span>VMD_DATA_TO_PP_TUPLE(...)</pre></div>
<div class="refsect1">
-<a name="id938698"></a><h2>Description</h2>
+<a name="id924502"></a><h2>Description</h2>
<p>... = variadic macro data.</p>
<p>returns = a Boost PP library tuple data type.</p>
<p>You can use the result of this macro whenever you need to pass a Boost PP library tuple as data to a Boost PP library macro. </p>
Modified: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_ARRAY_TO_DATA.html
==============================================================================
--- sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_ARRAY_TO_DATA.html (original)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_ARRAY_TO_DATA.html 2010-10-17 00:32:08 EDT (Sun, 17 Oct 2010)
@@ -33,7 +33,7 @@
</span>VMD_PP_ARRAY_TO_DATA(array)</pre></div>
<div class="refsect1">
-<a name="id939142"></a><h2>Description</h2>
+<a name="id924946"></a><h2>Description</h2>
<p>array = a Boost PP library array data type.</p>
<p>returns = variadic macro data whose arguments are the same as the elements of an array that is inputted.</p>
<p>The variadic macro data that is returned is in the form of of comma separated arguments. The variadic macro data can be passed to any macro which takes variadic macro data in the form of a final variadic macro data '...' macro parameter. </p>
Modified: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_LIST_TO_DATA.html
==============================================================================
--- sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_LIST_TO_DATA.html (original)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_LIST_TO_DATA.html 2010-10-17 00:32:08 EDT (Sun, 17 Oct 2010)
@@ -33,7 +33,7 @@
</span>VMD_PP_LIST_TO_DATA(list)</pre></div>
<div class="refsect1">
-<a name="id939180"></a><h2>Description</h2>
+<a name="id924985"></a><h2>Description</h2>
<p>list = a Boost PP library list data type.</p>
<p>returns = variadic macro data whose arguments are the same as the elements of a list that is inputted.</p>
<p>The variadic macro data that is returned is in the form of of comma separated arguments. The variadic macro data can be passed to any macro which takes variadic macro data in the form of a final variadic macro data '...' macro parameter. </p>
Modified: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_SEQ_TO_DATA.html
==============================================================================
--- sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_SEQ_TO_DATA.html (original)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_SEQ_TO_DATA.html 2010-10-17 00:32:08 EDT (Sun, 17 Oct 2010)
@@ -33,7 +33,7 @@
</span>VMD_PP_SEQ_TO_DATA(seq)</pre></div>
<div class="refsect1">
-<a name="id939219"></a><h2>Description</h2>
+<a name="id925023"></a><h2>Description</h2>
<p>seq = a Boost PP library sequence data type.</p>
<p>returns = variadic macro data whose arguments are the same as the elements of a sequence that is inputted.</p>
<p>The variadic macro data that is returned is in the form of of comma separated arguments. The variadic macro data can be passed to any macro which takes variadic macro data in the form of a final variadic macro data '...' macro parameter. </p>
Modified: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_TUPLE_ELEM.html
==============================================================================
--- sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_TUPLE_ELEM.html (original)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_TUPLE_ELEM.html 2010-10-17 00:32:08 EDT (Sun, 17 Oct 2010)
@@ -33,7 +33,7 @@
</span>VMD_PP_TUPLE_ELEM(n, tuple)</pre></div>
<div class="refsect1">
-<a name="id938890"></a><h2>Description</h2>
+<a name="id924694"></a><h2>Description</h2>
<p>n = number of the tuple element. The number starts from 0 to the size of the tuple - 1.</p>
<p>tuple = a Boost PP library tuple data type.</p>
<p>returns = the particular tuple element as specified by n.</p>
Modified: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_TUPLE_REM_CTOR.html
==============================================================================
--- sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_TUPLE_REM_CTOR.html (original)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_TUPLE_REM_CTOR.html 2010-10-17 00:32:08 EDT (Sun, 17 Oct 2010)
@@ -33,7 +33,7 @@
</span>VMD_PP_TUPLE_REM_CTOR(tuple)</pre></div>
<div class="refsect1">
-<a name="id938934"></a><h2>Description</h2>
+<a name="id924739"></a><h2>Description</h2>
<p>tuple = a Boost PP library tuple data type.</p>
<p>returns = a series of comma-separated tokens equivalent to removing the parentheses from a tuple.</p>
<p>This result is actually equivalent to the form of variadic macro data and can be used as an alternative to VMD_PP_TUPLE_TO_DATA to convert the tuple to variadic macro data.</p>
Modified: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_TUPLE_REVERSE.html
==============================================================================
--- sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_TUPLE_REVERSE.html (original)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_TUPLE_REVERSE.html 2010-10-17 00:32:08 EDT (Sun, 17 Oct 2010)
@@ -33,7 +33,7 @@
</span>VMD_PP_TUPLE_REVERSE(tuple)</pre></div>
<div class="refsect1">
-<a name="id938979"></a><h2>Description</h2>
+<a name="id924783"></a><h2>Description</h2>
<p>tuple = a Boost PP library tuple data type.</p>
<p>returns = a tuple whose elements are in reversed order from the original tuple.</p>
<p>In the Boost PP library there is no way to calculate the size of a tuple, so that the size must be known in order to be used by Boost PP library tuple macros. With variadic macros the size of a tuple can be calculated from the tuple itself.</p>
Modified: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_TUPLE_SIZE.html
==============================================================================
--- sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_TUPLE_SIZE.html (original)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_TUPLE_SIZE.html 2010-10-17 00:32:08 EDT (Sun, 17 Oct 2010)
@@ -33,7 +33,7 @@
</span>VMD_PP_TUPLE_SIZE(tuple)</pre></div>
<div class="refsect1">
-<a name="id938852"></a><h2>Description</h2>
+<a name="id924656"></a><h2>Description</h2>
<p>tuple = a Boost PP library tuple data type.</p>
<p>returns = the number of elements in the tuple, commonly referred to as the tuple size.</p>
<p>In the Boost PP library there is no way to calculate the size of a tuple, so that the size must be known in order to be used by Boost PP library tuple macros. With variadic macros the size of a tuple can be calculated from the tuple itself. </p>
Modified: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_TUPLE_TO_DATA.html
==============================================================================
--- sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_TUPLE_TO_DATA.html (original)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_TUPLE_TO_DATA.html 2010-10-17 00:32:08 EDT (Sun, 17 Oct 2010)
@@ -33,7 +33,7 @@
</span>VMD_PP_TUPLE_TO_DATA(tuple)</pre></div>
<div class="refsect1">
-<a name="id939104"></a><h2>Description</h2>
+<a name="id924908"></a><h2>Description</h2>
<p>tuple = a Boost PP library tuple data type.</p>
<p>returns = variadic macro data whose arguments are the same as the elements of a tuple that is inputted.</p>
<p>The variadic macro data that is returned is in the form of of comma separated arguments. The variadic macro data can be passed to any macro which takes variadic macro data in the form of a final variadic macro data '...' macro parameter. </p>
Modified: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_TUPLE_TO_LIST.html
==============================================================================
--- sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_TUPLE_TO_LIST.html (original)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_TUPLE_TO_LIST.html 2010-10-17 00:32:08 EDT (Sun, 17 Oct 2010)
@@ -33,7 +33,7 @@
</span>VMD_PP_TUPLE_TO_LIST(tuple)</pre></div>
<div class="refsect1">
-<a name="id939021"></a><h2>Description</h2>
+<a name="id924825"></a><h2>Description</h2>
<p>tuple = a Boost PP library tuple data type.</p>
<p>returns = a list whose elements are the same as the tuple that is inputted.</p>
<p>In the Boost PP library there is no way to calculate the size of a tuple, so that the size must be known in order to be used by Boost PP library tuple macros. With variadic macros the size of a tuple can be calculated from the tuple itself.</p>
Modified: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_TUPLE_TO_SEQ.html
==============================================================================
--- sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_TUPLE_TO_SEQ.html (original)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/VMD_PP_TUPLE_TO_SEQ.html 2010-10-17 00:32:08 EDT (Sun, 17 Oct 2010)
@@ -33,7 +33,7 @@
</span>VMD_PP_TUPLE_TO_SEQ(tuple)</pre></div>
<div class="refsect1">
-<a name="id939063"></a><h2>Description</h2>
+<a name="id924867"></a><h2>Description</h2>
<p>tuple = a Boost PP library tuple data type.</p>
<p>returns = a sequence whose elements are the same as the tuple that is inputted.</p>
<p>In the Boost PP library there is no way to calculate the size of a tuple, so that the size must be known in order to be used by Boost PP library tuple macros. With variadic macros the size of a tuple can be calculated from the tuple itself.</p>
Modified: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/index.html
==============================================================================
--- sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/index.html (original)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/index.html 2010-10-17 00:32:08 EDT (Sun, 17 Oct 2010)
@@ -55,8 +55,8 @@
</dl></dd>
<dt><span class="section"><a href="the_variadic_macro_data_library/vmd_comparison.html">VMD and
Boost PP</a></span></dt>
-<dd><dl><dt><span class="section"><a href="the_variadic_macro_data_library/vmd_comparison.html#the_variadic_macro_data_library.vmd_comparison.vmd_comp_example">Use-case
- example</a></span></dt></dl></dd>
+<dd><dl><dt><span class="section"><a href="the_variadic_macro_data_library/vmd_comparison.html#the_variadic_macro_data_library.vmd_comparison.vmd_comp_example">An
+ example design</a></span></dt></dl></dd>
<dt><span class="section">Design</span></dt>
<dt><span class="section">Compilers</span></dt>
<dt><span class="section">Limitations</span></dt>
@@ -68,6 +68,9 @@
<a name="the_variadic_macro_data_library.vmd_intro"></a><a class="link" href="index.html#the_variadic_macro_data_library.vmd_intro" title="Introduction">Introduction</a>
</h2></div></div></div>
<p>
+ Welcome to the variadic macro data library version 1.1 .
+ </p>
+<p>
The variadic macro data library, or VMD for short, is a library of macros which
provide important functionality for variadic macros as well as integrating
variadic macros with the Boost preprocessor library ( Boost PP ). It integrates
@@ -102,7 +105,7 @@
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left"><p><small>Last revised: October 15, 2010 at 23:10:12 GMT</small></p></td>
+<td align="left"><p><small>Last revised: October 17, 2010 at 04:29:22 GMT</small></p></td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>
Modified: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/the_variadic_macro_data_library/vmd_comparison.html
==============================================================================
--- sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/the_variadic_macro_data_library/vmd_comparison.html (original)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/html/the_variadic_macro_data_library/vmd_comparison.html 2010-10-17 00:32:08 EDT (Sun, 17 Oct 2010)
@@ -27,8 +27,8 @@
<a name="the_variadic_macro_data_library.vmd_comparison"></a><a class="link" href="vmd_comparison.html" title="VMD and Boost PP">VMD and
Boost PP</a>
</h2></div></div></div>
-<div class="toc"><dl><dt><span class="section"><a href="vmd_comparison.html#the_variadic_macro_data_library.vmd_comparison.vmd_comp_example">Use-case
- example</a></span></dt></dl></div>
+<div class="toc"><dl><dt><span class="section"><a href="vmd_comparison.html#the_variadic_macro_data_library.vmd_comparison.vmd_comp_example">An
+ example design</a></span></dt></dl></div>
<p>
Boost PP already has the ability to pass variadic data as a single macro argument
through any of its data types. It may then be reasonably asked why there is
@@ -81,8 +81,8 @@
</p>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
-<a name="the_variadic_macro_data_library.vmd_comparison.vmd_comp_example"></a><a class="link" href="vmd_comparison.html#the_variadic_macro_data_library.vmd_comparison.vmd_comp_example" title="Use-case example">Use-case
- example</a>
+<a name="the_variadic_macro_data_library.vmd_comparison.vmd_comp_example"></a><a class="link" href="vmd_comparison.html#the_variadic_macro_data_library.vmd_comparison.vmd_comp_example" title="An example design">An
+ example design</a>
</h3></div></div></div>
<p>
A typical situation is designing a macro for end-users which takes variadic
@@ -132,13 +132,73 @@
<p>
The end-user would pass data to this macro in this way:
</p>
-<pre class="programlisting"><span class="identifier">ENDUSER_MACRO</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span><span class="identifier">b</span><span class="special">,</span><span class="identifier">c</span><span class="special">,</span><span class="identifier">d</span><span class="special">,</span><span class="identifier">e</span><span class="special">)</span>
-</pre>
+<pre class="programlisting"><span class="identifier">ENDUSER_MACRO</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span><span class="identifier">b</span><span class="special">,</span><span class="identifier">c</span><span class="special">,</span><span class="identifier">d</span><span class="special">,</span><span class="identifier">e</span><span class="special">)</span> <span class="comment">// etc. with each token being somma-separated from each other
+</span></pre>
<p>
I think this last way of passing variadic data is more natural to an end-user
than using a Boost PP sequence directly, but of course it depends on compiler
variadic macro support.
</p>
+<p>
+ One decision to be made is whether to support, for any given variadic data
+ macro functionality, a single macro or two macros with slightly different
+ names.
+ </p>
+<p>
+ Single macro design:
+ </p>
+<p>
+ In our example, if we wish to support a single macro, for compilers that
+ both support or do not support variadic macros, the code would be:
+ </p>
+<pre class="programlisting"><span class="preprocessor">#if</span> <span class="identifier">defined</span><span class="special">(</span><span class="identifier">BOOST_NO_VARIADIC_MACROS</span><span class="special">)</span>
+ <span class="preprocessor">#define</span> <span class="identifier">ENDUSER_MACRO</span><span class="special">(</span><span class="identifier">ppSequence</span><span class="special">)</span> <span class="identifier">ENDUSER_DETAIL_MACRO</span><span class="special">(</span><span class="identifier">ppSequence</span><span class="special">)</span>
+<span class="preprocessor">#else</span>
+ <span class="preprocessor">#define</span> <span class="identifier">ENDUSER_MACRO</span><span class="special">(...)</span> <span class="identifier">ENDUSER_DETAIL_MACRO</span><span class="special">(</span><span class="identifier">VMD_DATA_TO_PP_SEQ</span><span class="special">(</span><span class="identifier">__VA_ARGS__</span><span class="special">))</span>
+<span class="preprocessor">#endif</span>
+</pre>
+<p>
+ We would now have a single macro which would be used slightly differently
+ by the end-user depending on whether the compiler being used supported variadic
+ macros or not. This might not be best if the end-user's code needed to work
+ for different compilers, some of which support variadic macros and some of
+ which do not. In that latter case, a dual macro design ( see below ) might
+ be better.
+ </p>
+<p>
+ Another solution supporting a single macro is to just ignore variadic macros,
+ and then our solution would be:
+ </p>
+<pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">ENDUSER_MACRO</span><span class="special">(</span><span class="identifier">ppSequence</span><span class="special">)</span> <span class="identifier">ENDUSER_DETAIL_MACRO</span><span class="special">(</span><span class="identifier">ppSequence</span><span class="special">)</span>
+</pre>
+<p>
+ We could also ignore any compilers which do not support variadic macros,
+ and then our solution would be:
+ </p>
+<pre class="programlisting"><span class="preprocessor">#if</span> <span class="special">!</span><span class="identifier">defined</span><span class="special">(</span><span class="identifier">BOOST_NO_VARIADIC_MACROS</span><span class="special">)</span>
+ <span class="preprocessor">#define</span> <span class="identifier">ENDUSER_MACRO</span><span class="special">(...)</span> <span class="identifier">ENDUSER_DETAIL_MACRO</span><span class="special">(</span><span class="identifier">VMD_DATA_TO_PP_SEQ</span><span class="special">(</span><span class="identifier">__VA_ARGS__</span><span class="special">))</span>
+<span class="preprocessor">#endif</span>
+</pre>
+<p>
+ Dual macro design:
+ </p>
+<p>
+ Perhaps best is to provide two macros with slightly different names. Our
+ solution would then be:
+ </p>
+<pre class="programlisting"> <span class="preprocessor">#define</span> <span class="identifier">ENDUSER_MACRO</span><span class="special">(</span><span class="identifier">ppSequence</span><span class="special">)</span> <span class="identifier">ENDUSER_DETAIL_MACRO</span><span class="special">(</span><span class="identifier">ppSequence</span><span class="special">)</span>
+<span class="preprocessor">#if</span> <span class="special">!</span><span class="identifier">defined</span><span class="special">(</span><span class="identifier">BOOST_NO_VARIADIC_MACROS</span><span class="special">)</span>
+ <span class="preprocessor">#define</span> <span class="identifier">ENDUSER_MACRO_VM</span><span class="special">(...)</span> <span class="identifier">ENDUSER_DETAIL_MACRO</span><span class="special">(</span><span class="identifier">VMD_DATA_TO_PP_SEQ</span><span class="special">(</span><span class="identifier">__VA_ARGS__</span><span class="special">))</span>
+<span class="preprocessor">#endif</span>
+</pre>
+<p>
+ Here I have attached an '_VM' to the name of the macro which supports variadic
+ macros.
+ </p>
+<p>
+ In an ideal world, once the new C++ standard is ratified, all compilers will
+ support variadic macros.
+ </p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
Added: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/version.txt
==============================================================================
--- (empty file)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/version.txt 2010-10-17 00:32:08 EDT (Sun, 17 Oct 2010)
@@ -0,0 +1 @@
+Version 1.1
\ No newline at end of file
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk