|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r77902 - in trunk: boost/utility libs/utility/identity_type/doc libs/utility/identity_type/doc/html
From: lorcaminiti_at_[hidden]
Date: 2012-04-10 17:53:28
Author: lcaminiti
Date: 2012-04-10 17:53:28 EDT (Tue, 10 Apr 2012)
New Revision: 77902
URL: http://svn.boost.org/trac/boost/changeset/77902
Log:
Updated IdentityType docs.
Text files modified:
trunk/boost/utility/identity_type.hpp | 11 ++--
trunk/libs/utility/identity_type/doc/html/index.html | 85 +++++++++++++++++++--------------------
trunk/libs/utility/identity_type/doc/identity_type.qbk | 43 ++++++++------------
3 files changed, 64 insertions(+), 75 deletions(-)
Modified: trunk/boost/utility/identity_type.hpp
==============================================================================
--- trunk/boost/utility/identity_type.hpp (original)
+++ trunk/boost/utility/identity_type.hpp 2012-04-10 17:53:28 EDT (Tue, 10 Apr 2012)
@@ -28,14 +28,15 @@
}
@EndParams
-This macro works on any C++03 compiler (it does not require variadic macros).
+This macro works on any C++03 compiler (it does not use variadic macros).
This macro must be prefixed by <c>typename</c> when used within templates.
-However, the compiler will not be able to automatically determine function template parameters when they are wrapped with this macro (these parameters need to
-be explicitly specified when calling the function template).
+Note that the compiler will not be able to automatically determine function
+template parameters when they are wrapped with this macro (these parameters
+need to be explicitly specified when calling the function template).
-On some compilers (like GCC), using this macro on an abstract types requires to
-add and remove a reference to the type.
+On some compilers (like GCC), using this macro on abstract types requires to
+add and remove a reference to the specified type.
*/
#define BOOST_IDENTITY_TYPE(parenthesized_type) \
/* must NOT prefix this with `::` to work with parenthesized syntax */ \
Modified: trunk/libs/utility/identity_type/doc/html/index.html
==============================================================================
--- trunk/libs/utility/identity_type/doc/html/index.html (original)
+++ trunk/libs/utility/identity_type/doc/html/index.html 2012-04-10 17:53:28 EDT (Tue, 10 Apr 2012)
@@ -2,8 +2,7 @@
Caminiti</p></div><div><div class="legalnotice" title="Legal Notice"><a name="boost_utility_identitytype.legal"></a><p>
Distributed under the Boost Software License, Version 1.0 (see accompanying
file LICENSE_1_0.txt or a copy at http://www.boost.org/LICENSE_1_0.txt)
- </p></div></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section">Motivation</span></dt><dt><span class="section">Solution</span></dt><dt><span class="section">Templates</span></dt><dt><span class="section">Abstract Types</span></dt><dt><span class="section"><a href="#boost_utility_identitytype.compilers_and_platforms">Compilers
- and Platforms</a></span></dt><dt><span class="section">Annex: Usage</span></dt><dt><span class="section"><a href="#boost_utility_identitytype.annex__implementation">Annex:
+ </p></div></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section">Motivation</span></dt><dt><span class="section">Solution</span></dt><dt><span class="section">Templates</span></dt><dt><span class="section">Abstract Types</span></dt><dt><span class="section">Annex: Usage</span></dt><dt><span class="section"><a href="#boost_utility_identitytype.annex__implementation">Annex:
Implementation</a></span></dt><dt><span class="section">Reference</span></dt></dl></div><p>
This library allows to wrap type expressions within round parenthesis so they
can be passed to macros even when they contain commas.
@@ -37,21 +36,23 @@
<code class="computeroutput"><span class="number">2</span></code>
</li></ol></div><p>
Note that, differently from the compiler, the preprocessor only recognizes
- round parameters <code class="computeroutput"><span class="special">()</span></code>. Angular
- <code class="computeroutput"><span class="special"><></span></code> or squared <code class="computeroutput"><span class="special">[]</span></code> parenthesis are not used by the preprocessor
- when parsing the macro parameters.
+ round parenthesis <code class="computeroutput"><span class="special">()</span></code>. Angular
+ <code class="computeroutput"><span class="special"><></span></code> and squared <code class="computeroutput"><span class="special">[]</span></code> parenthesis are not recognized by the preprocessor
+ when parsing macro parameters.
</p></div><div class="section boost_utility_identitytype_solution" title="Solution"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="boost_utility_identitytype.solution"></a><a class="link" href="#boost_utility_identitytype.solution" title="Solution">Solution</a></h2></div></div></div><p>
In some cases, it might be possible to workaround this issue by avoiding to
- pass the type expression to the macro all together. For example, in some cases
- a <code class="computeroutput"><span class="keyword">typedef</span></code> can be used to specify
- the type expression with the commas outside the macro (see also var.cpp):
+ pass the type expression to the macro all together. For example, in the case
+ above a <code class="computeroutput"><span class="keyword">typedef</span></code> could have been
+ used to specify the type expression with the commas outside the macro (see
+ also var.cpp):
</p><p>
</p><pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">char</span><span class="special">></span> <span class="identifier">map_type</span><span class="special">;</span>
<span class="identifier">VAR</span><span class="special">(</span><span class="identifier">map_type</span><span class="special">,</span> <span class="number">3</span><span class="special">);</span> <span class="comment">// OK.</span>
</pre><p>
</p><p>
- When this is not possible or desired (e.g., see the function template <code class="computeroutput"><span class="identifier">f</span></code> in the section below), the library header
- <code class="computeroutput"><a class="link" href="#header.boost.utility.identity_type_hpp" title="Header <boost/utility/identity_type.hpp>">boost/utility/identity_type.hpp</a></code>
+ When this is neither possible nor desired (e.g., see the function template
+ <code class="computeroutput"><span class="identifier">f</span></code> in the section below), this
+ library header <code class="computeroutput"><a class="link" href="#header.boost.utility.identity_type_hpp" title="Header <boost/utility/identity_type.hpp>">boost/utility/identity_type.hpp</a></code>
defines a macro <code class="computeroutput"><a class="link" href="#BOOST_IDENTITY_TYPE" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code>
which can be used to workaround the issue while keeping the type expression
as one of the macro parameters (see also var.cpp).
@@ -61,15 +62,21 @@
<span class="identifier">VAR</span><span class="special">(</span><span class="identifier">BOOST_IDENTITY_TYPE</span><span class="special">((</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">char</span><span class="special">>)),</span> <span class="number">4</span><span class="special">);</span> <span class="comment">// OK.</span>
</pre><p>
</p><p>
- This macro expands to an expression that evaluates (at compile-time) to the
- specified type. The specified type is never split into multiple macro parameters
- because it is always wrapped by a set of extra round parenthesis <code class="computeroutput"><span class="special">()</span></code>. In fact, a total of two sets of round parenthesis
- must be used: The parenthesis to invoke the macro <code class="computeroutput"><span class="identifier">BOOST_IDENTITY_TYPE</span><span class="special">(...)</span></code> plus the inner parenthesis to wrap the
+ The <code class="computeroutput"><a class="link" href="#BOOST_IDENTITY_TYPE" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code> macro
+ expands to an expression that evaluates (at compile-time) to the specified
+ type. The specified type is never split into multiple macro parameters because
+ it is always wrapped by a set of extra round parenthesis <code class="computeroutput"><span class="special">()</span></code>.
+ In fact, a total of two sets of round parenthesis must be used: The parenthesis
+ to invoke the macro <code class="computeroutput"><span class="identifier">BOOST_IDENTITY_TYPE</span><span class="special">(...)</span></code> plus the inner parenthesis to wrap the
type passed to the macro <code class="computeroutput"><span class="identifier">BOOST_IDENTITY_TYPE</span><span class="special">((...))</span></code>.
</p><p>
This macro works on any C++03
- compiler (because it does not use <a href="http://en.wikipedia.org/wiki/Variadic_macro" target="_top">variadic
- macros</a>). <sup>[<a name="boost_utility_identitytype.solution.f0" href="#ftn.boost_utility_identitytype.solution.f0" class="footnote">1</a>]</sup>
+ compiler (and it does not use <a href="http://en.wikipedia.org/wiki/Variadic_macro" target="_top">variadic
+ macros</a>). <sup>[<a name="boost_utility_identitytype.solution.f0" href="#ftn.boost_utility_identitytype.solution.f0" class="footnote">1</a>]</sup> The authors originally developed and tested this library using
+ GNU Compiler Collection (GCC) C++ 4.5.3 (with and without C++11 features enabled
+ <code class="computeroutput"><span class="special">-</span><span class="identifier">std</span><span class="special">=</span><span class="identifier">c</span><span class="special">++</span><span class="number">0</span><span class="identifier">x</span></code>) on Cygwin
+ and Miscrosoft Visual C++ (MSVC) 8.0 on Windows 7. See the library <a href="http://www.boost.org/development/tests/release/developer/utility-identity_type.html" target="_top">regressions
+ test results</a> for more information on supported compilers and platforms.
</p></div><div class="section boost_utility_identitytype_templates" title="Templates"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="boost_utility_identitytype.templates"></a><a class="link" href="#boost_utility_identitytype.templates" title="Templates">Templates</a></h2></div></div></div><p>
This macro must be prefixed by <code class="computeroutput"><span class="keyword">typename</span></code>
when used within templates. For example, let's program a macro that declares
@@ -95,11 +102,12 @@
</pre><p>
</p><p>
However, note that the template parameter <code class="computeroutput"><span class="keyword">char</span></code>
- must be manually specified when invoking the function <code class="computeroutput"><span class="identifier">f</span><span class="special"><</span><span class="keyword">char</span><span class="special">>(</span><span class="identifier">a</span><span class="special">)</span></code>. In fact,
+ must be manually specified when invoking the function as in <code class="computeroutput"><span class="identifier">f</span><span class="special"><</span><span class="keyword">char</span><span class="special">>(</span><span class="identifier">a</span><span class="special">)</span></code>. In fact,
when the <code class="computeroutput"><a class="link" href="#BOOST_IDENTITY_TYPE" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code>
macro is used to wrap a function template parameter, the template parameter
can no longer be automatically deduced by the compiler form the function call
- as in <code class="computeroutput"><span class="identifier">f</span><span class="special">(</span><span class="identifier">a</span><span class="special">)</span></code>. <sup>[<a name="boost_utility_identitytype.templates.f0" href="#ftn.boost_utility_identitytype.templates.f0" class="footnote">2</a>]</sup> (This limitation does not apply to class templates because class
+ as <code class="computeroutput"><span class="identifier">f</span><span class="special">(</span><span class="identifier">a</span><span class="special">)</span></code> would
+ have done. <sup>[<a name="boost_utility_identitytype.templates.f0" href="#ftn.boost_utility_identitytype.templates.f0" class="footnote">2</a>]</sup> (This limitation does not apply to class templates because class
template parameters must always be explicitly specified.) In other words, without
using the <code class="computeroutput"><a class="link" href="#BOOST_IDENTITY_TYPE" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code>
macro, C++ would normally be able to automatically deduce the function template
@@ -119,8 +127,7 @@
</p></div><div class="section boost_utility_identitytype_abstract_types" title="Abstract Types"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="boost_utility_identitytype.abstract_types"></a><a class="link" href="#boost_utility_identitytype.abstract_types" title="Abstract Types">Abstract Types</a></h2></div></div></div><p>
On some compilers (e.g., GCC), using this macro on abstract types (i.e., classes
with one or more pure virtual functions) generates a compiler error. This can
- be worked around by manipulating the type adding and removing a reference to
- it.
+ be avoided by manipulating the type adding and removing a reference to it.
</p><p>
Let's program a macro that performs a static assertion on a <a href="http://en.wikipedia.org/wiki/Template_metaprogramming" target="_top">Template
Meta-Programming</a> (TMP) meta-function (similarly to Boost.MPL BOOST_MPL_ASSERT). The <code class="computeroutput"><a class="link" href="#BOOST_IDENTITY_TYPE" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code> macro can be used
@@ -148,25 +155,13 @@
<span class="special">>::</span><span class="identifier">type</span>
<span class="special">);</span>
</pre><p>
- </p></div><div class="section boost_utility_identitytype_compilers_and_platforms" title="Compilers and Platforms"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="boost_utility_identitytype.compilers_and_platforms"></a><a class="link" href="#boost_utility_identitytype.compilers_and_platforms" title="Compilers and Platforms">Compilers
- and Platforms</a></h2></div></div></div><p>
- The authors originally developed and tested the library on:
- </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
- GNU Compiler Collection (GCC) C++ 4.5.3 (with and without C++11 features
- enabled <code class="computeroutput"><span class="special">-</span><span class="identifier">std</span><span class="special">=</span><span class="identifier">c</span><span class="special">++</span><span class="number">0</span><span class="identifier">x</span></code>) on
- Cygwin.
- </li><li class="listitem">
- Miscrosoft Visual C++ (MSVC) 8.0 on Windows 7.
- </li></ol></div><p>
- See the library <a href="http://www.boost.org/development/tests/release/developer/utility-identity_type.html" target="_top">regressions
- test results</a> for detailed information on supported compilers and platforms.
</p></div><div class="section boost_utility_identitytype_annex__usage" title="Annex: Usage"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="boost_utility_identitytype.annex__usage"></a><a class="link" href="#boost_utility_identitytype.annex__usage" title="Annex: Usage">Annex: Usage</a></h2></div></div></div><p>
The <code class="computeroutput"><a class="link" href="#BOOST_IDENTITY_TYPE" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code> macro
can be used either when calling a user-defined macro (as shown by the examples
- so far), or internally in the definition of a user-defined macro (as shown
- below). When <code class="computeroutput"><a class="link" href="#BOOST_IDENTITY_TYPE" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code>
- is used in the user macro definition, the call of the user macro will only
- have to specify the extra parenthesis (see also paren.cpp):
+ so far), or internally when implementing a user-defined macro (as shown below).
+ When <code class="computeroutput"><a class="link" href="#BOOST_IDENTITY_TYPE" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code> is
+ used in the implementation of the user-defined macro, the caller of the user
+ macro will have to specify the extra parenthesis (see also paren.cpp):
</p><p>
</p><pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">TMP_ASSERT_PAREN</span><span class="special">(</span><span class="identifier">parenthesized_metafunction</span><span class="special">)</span> <span class="special">\</span>
<span class="comment">/* use `BOOST_IDENTITY_TYPE` in macro definition instead of invocation */</span> <span class="special">\</span>
@@ -182,7 +177,7 @@
<span class="identifier">TMP_ASSERT</span><span class="special">(</span><span class="identifier">BOOST_IDENTITY_TYPE</span><span class="special">((</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">is_const</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">char</span><span class="special">></span> <span class="keyword">const</span><span class="special">>)));</span>
</pre><p>
</p><p>
- However, note that the user will <span class="emphasis"><em>always</em></span> have to specify
+ However, note that the caller will <span class="emphasis"><em>always</em></span> have to specify
the extra parenthesis even when the macro parameters contain no comma:
</p><p>
</p><pre class="programlisting"><span class="identifier">TMP_ASSERT_PAREN</span><span class="special">((</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">is_const</span><span class="special"><</span><span class="keyword">int</span> <span class="keyword">const</span><span class="special">>));</span> <span class="comment">// Always extra `((...))`.</span>
@@ -191,8 +186,8 @@
</pre><p>
</p><p>
In some cases, using <code class="computeroutput"><a class="link" href="#BOOST_IDENTITY_TYPE" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code>
- within the user macro definition might provide the best syntax for the user.
- For example, this is the case for <code class="computeroutput"><span class="identifier">BOOST_MPL_ASSERT</span></code>
+ in the implementation of the user-defined macro might provide the best syntax
+ for the caller. For example, this is the case for <code class="computeroutput"><span class="identifier">BOOST_MPL_ASSERT</span></code>
because the majority of template meta-programming expressions contain unwrapped
commas so it is less confusing for the user to always specify the extra parenthesis
<code class="computeroutput"><span class="special">((...))</span></code> instead of using <code class="computeroutput"><a class="link" href="#BOOST_IDENTITY_TYPE" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code>:
@@ -215,7 +210,9 @@
Instead requiring the user to specify <code class="computeroutput"><a class="link" href="#BOOST_IDENTITY_TYPE" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code>
only when needed allows for the more natural syntax <code class="computeroutput"><span class="identifier">BOOST_LOCAL_FUNCTION</span><span class="special">(</span><span class="keyword">int</span><span class="special">&</span>
<span class="identifier">x</span><span class="special">,</span> <span class="keyword">int</span><span class="special">&</span> <span class="identifier">y</span><span class="special">)</span></code> in the common cases when the parameter types
- contain no comma.
+ contain no comma (while still allowing to specify parameter types with commas
+ as special cases using <code class="computeroutput"><span class="identifier">BOOST_LOCAL_FUNCTION</span><span class="special">(</span><span class="identifier">BOOST_IDENTITY_TYPE</span><span class="special">((</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">char</span><span class="special">>))&</span>
+ <span class="identifier">x</span><span class="special">,</span> <span class="keyword">int</span><span class="special">&</span> <span class="identifier">y</span><span class="special">)</span></code>).
</p></div><div class="section boost_utility_identitytype_annex__implementation" title="Annex: Implementation"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="boost_utility_identitytype.annex__implementation"></a><a class="link" href="#boost_utility_identitytype.annex__implementation" title="Annex: Implementation">Annex:
Implementation</a></h2></div></div></div><p>
The implementation of this library macro is equivalent to the following: <sup>[<a name="boost_utility_identitytype.annex__implementation.f0" href="#ftn.boost_utility_identitytype.annex__implementation.f0" class="footnote">3</a>]</sup>
@@ -239,8 +236,8 @@
<a class="link" href="#BOOST_IDENTITY_TYPE" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a>(parenthesized_type)</pre><div class="refentry" title="Macro BOOST_IDENTITY_TYPE"><a name="BOOST_IDENTITY_TYPE"></a><div class="titlepage"></div><div class="refnamediv"><h2><span class="refentrytitle">Macro BOOST_IDENTITY_TYPE</span></h2><p>BOOST_IDENTITY_TYPE — This macro allows to wrap the specified type expression within extra round parenthesis so the type can be passed as a single macro parameter even if it contains commas (not already wrapped within round parenthesis). </p></div><h2 class="refsynopsisdiv-title">Synopsis</h2><div class="refsynopsisdiv"><pre class="synopsis"><span class="comment">// In header: <<a class="link" href="#header.boost.utility.identity_type_hpp" title="Header <boost/utility/identity_type.hpp>">boost/utility/identity_type.hpp</a>>
-</span>BOOST_IDENTITY_TYPE(parenthesized_type)</pre></div><div class="refsect1" title="Description"><a name="id558453"></a><h2>Description</h2><p><span class="bold"><strong>Parameters:</strong></span> </p><div class="informaltable"><table class="table"><colgroup><col><col></colgroup><tbody><tr><td><span class="bold"><strong><code class="computeroutput">parenthesized_type</code></strong></span></td><td>The type expression to be passed as macro parameter wrapped by a single set of round parenthesis <code class="computeroutput">(...)</code>. This type expression can contain an arbitrary number of commas. </td></tr></tbody></table></div><p>
-</p><p>This macro works on any C++03 compiler (it does not require variadic macros).</p><p>This macro must be prefixed by <code class="computeroutput">typename</code> when used within templates. However, the compiler will not be able to automatically determine function template parameters when they are wrapped with this macro (these parameters need to be explicitly specified when calling the function template).</p><p>On some compilers (like GCC), using this macro on an abstract types requires to add and remove a reference to the type. </p></div></div></div></div><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p><sup>[<a id="ftn.boost_utility_identitytype.solution.f0" href="#boost_utility_identitytype.solution.f0" class="para">1</a>] </sup>
+</span>BOOST_IDENTITY_TYPE(parenthesized_type)</pre></div><div class="refsect1" title="Description"><a name="id569282"></a><h2>Description</h2><p><span class="bold"><strong>Parameters:</strong></span> </p><div class="informaltable"><table class="table"><colgroup><col><col></colgroup><tbody><tr><td><span class="bold"><strong><code class="computeroutput">parenthesized_type</code></strong></span></td><td>The type expression to be passed as macro parameter wrapped by a single set of round parenthesis <code class="computeroutput">(...)</code>. This type expression can contain an arbitrary number of commas. </td></tr></tbody></table></div><p>
+</p><p>This macro works on any C++03 compiler (it does not use variadic macros).</p><p>This macro must be prefixed by <code class="computeroutput">typename</code> when used within templates. Note that the compiler will not be able to automatically determine function template parameters when they are wrapped with this macro (these parameters need to be explicitly specified when calling the function template).</p><p>On some compilers (like GCC), using this macro on abstract types requires to add and remove a reference to the specified type. </p></div></div></div></div><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p><sup>[<a id="ftn.boost_utility_identitytype.solution.f0" href="#boost_utility_identitytype.solution.f0" class="para">1</a>] </sup>
Using variadic macros, it would be possible to require a single set of extra
parenthesis <code class="computeroutput"><span class="identifier">BOOST_IDENTITY_TYPE</span><span class="special">(</span></code><code class="literal"><span class="emphasis"><em>type</em></span></code><code class="computeroutput"><span class="special">)</span></code> instead of two <code class="computeroutput"><span class="identifier">BOOST_IDENTITY_TYPE</span><span class="special">((</span></code><code class="literal"><span class="emphasis"><em>type</em></span></code><code class="computeroutput"><span class="special">))</span></code> but variadic macros are not part of C++03
(even if nowadays they are supported by most modern compilers and they are
@@ -250,6 +247,6 @@
wraps the specified type within a meta-function.
</p></div><div class="footnote"><p><sup>[<a id="ftn.boost_utility_identitytype.annex__implementation.f0" href="#boost_utility_identitytype.annex__implementation.f0" class="para">3</a>] </sup>
There is absolutely no guarantee that the macro is actually implemented using
- the code listed in this documentation. This code is for explanatory purposes
- only.
+ the code listed in this documentation. The listed code is for explanatory
+ purposes only.
</p></div></div></div></body></html>
Modified: trunk/libs/utility/identity_type/doc/identity_type.qbk
==============================================================================
--- trunk/libs/utility/identity_type/doc/identity_type.qbk (original)
+++ trunk/libs/utility/identity_type/doc/identity_type.qbk 2012-04-10 17:53:28 EDT (Tue, 10 Apr 2012)
@@ -47,30 +47,32 @@
# `char>`
# `2`
-Note that, differently from the compiler, the preprocessor only recognizes round parameters `()`.
-Angular `<>` or squared `[]` parenthesis are not used by the preprocessor when parsing the macro parameters.
+Note that, differently from the compiler, the preprocessor only recognizes round parenthesis `()`.
+Angular `<>` and squared `[]` parenthesis are not recognized by the preprocessor when parsing macro parameters.
[endsect]
[section Solution]
In some cases, it might be possible to workaround this issue by avoiding to pass the type expression to the macro all together.
-For example, in some cases a `typedef` can be used to specify the type expression with the commas outside the macro (see also [@../../test/var.cpp =var.cpp=]):
+For example, in the case above a `typedef` could have been used to specify the type expression with the commas outside the macro (see also [@../../test/var.cpp =var.cpp=]):
[var_typedef]
-When this is not possible or desired (e.g., see the function template `f` in the section below), the library header [headerref boost/utility/identity_type.hpp] defines a macro [macroref BOOST_IDENTITY_TYPE] which can be used to workaround the issue while keeping the type expression as one of the macro parameters (see also [@../../test/var.cpp =var.cpp=]).
+When this is neither possible nor desired (e.g., see the function template `f` in the section below), this library header [headerref boost/utility/identity_type.hpp] defines a macro [macroref BOOST_IDENTITY_TYPE] which can be used to workaround the issue while keeping the type expression as one of the macro parameters (see also [@../../test/var.cpp =var.cpp=]).
[var_ok]
-This macro expands to an expression that evaluates (at compile-time) to the specified type.
+The [macroref BOOST_IDENTITY_TYPE] macro expands to an expression that evaluates (at compile-time) to the specified type.
The specified type is never split into multiple macro parameters because it is always wrapped by a set of extra round parenthesis `()`.
In fact, a total of two sets of round parenthesis must be used: The parenthesis to invoke the macro `BOOST_IDENTITY_TYPE(...)` plus the inner parenthesis to wrap the type passed to the macro `BOOST_IDENTITY_TYPE((...))`.
-This macro works on any [@http://www.open-std.org/JTC1/SC22/WG21/docs/standards C++03] compiler (because it does not use [@http://en.wikipedia.org/wiki/Variadic_macro variadic macros]).
+This macro works on any [@http://www.open-std.org/JTC1/SC22/WG21/docs/standards C++03] compiler (and it does not use [@http://en.wikipedia.org/wiki/Variadic_macro variadic macros]).
[footnote
Using variadic macros, it would be possible to require a single set of extra parenthesis `BOOST_IDENTITY_TYPE(`[^['type]]`)` instead of two `BOOST_IDENTITY_TYPE((`[^['type]]`))` but variadic macros are not part of C++03 (even if nowadays they are supported by most modern compilers and they are also part of C++11).
]
+The authors originally developed and tested this library using GNU Compiler Collection (GCC) C++ 4.5.3 (with and without C++11 features enabled `-std=c++0x`) on Cygwin and Miscrosoft Visual C++ (MSVC) 8.0 on Windows 7.
+See the library [@http://www.boost.org/development/tests/release/developer/utility-identity_type.html regressions test results] for more information on supported compilers and platforms.
[endsect]
@@ -82,8 +84,8 @@
[template_f_decl]
[template_f_call]
-However, note that the template parameter `char` must be manually specified when invoking the function `f<char>(a)`.
-In fact, when the [macroref BOOST_IDENTITY_TYPE] macro is used to wrap a function template parameter, the template parameter can no longer be automatically deduced by the compiler form the function call as in `f(a)`.
+However, note that the template parameter `char` must be manually specified when invoking the function as in `f<char>(a)`.
+In fact, when the [macroref BOOST_IDENTITY_TYPE] macro is used to wrap a function template parameter, the template parameter can no longer be automatically deduced by the compiler form the function call as `f(a)` would have done.
[footnote
This is because the implementation of [macroref BOOST_IDENTITY_TYPE] wraps the specified type within a meta-function.
]
@@ -98,7 +100,7 @@
[section Abstract Types]
On some compilers (e.g., GCC), using this macro on abstract types (i.e., classes with one or more pure virtual functions) generates a compiler error.
-This can be worked around by manipulating the type adding and removing a reference to it.
+This can be avoided by manipulating the type adding and removing a reference to it.
Let's program a macro that performs a static assertion on a [@http://en.wikipedia.org/wiki/Template_metaprogramming Template Meta-Programming] (TMP) meta-function (similarly to Boost.MPL [@http://www.boost.org/doc/libs/1_36_0/libs/mpl/doc/refmanual/assert.html `BOOST_MPL_ASSERT`]).
The [macroref BOOST_IDENTITY_TYPE] macro can be used to pass a meta-function with multiple template parameters to the assert macro (so to handle the commas separating the template parameters).
@@ -108,29 +110,18 @@
[endsect]
-[section Compilers and Platforms]
-
-The authors originally developed and tested the library on:
-
-# GNU Compiler Collection (GCC) C++ 4.5.3 (with and without C++11 features enabled `-std=c++0x`) on Cygwin.
-# Miscrosoft Visual C++ (MSVC) 8.0 on Windows 7.
-
-See the library [@http://www.boost.org/development/tests/release/developer/utility-identity_type.html regressions test results] for detailed information on supported compilers and platforms.
-
-[endsect]
-
[section Annex: Usage]
-The [macroref BOOST_IDENTITY_TYPE] macro can be used either when calling a user-defined macro (as shown by the examples so far), or internally in the definition of a user-defined macro (as shown below).
-When [macroref BOOST_IDENTITY_TYPE] is used in the user macro definition, the call of the user macro will only have to specify the extra parenthesis (see also [@../../test/paren.cpp =paren.cpp=]):
+The [macroref BOOST_IDENTITY_TYPE] macro can be used either when calling a user-defined macro (as shown by the examples so far), or internally when implementing a user-defined macro (as shown below).
+When [macroref BOOST_IDENTITY_TYPE] is used in the implementation of the user-defined macro, the caller of the user macro will have to specify the extra parenthesis (see also [@../../test/paren.cpp =paren.cpp=]):
[paren]
-However, note that the user will /always/ have to specify the extra parenthesis even when the macro parameters contain no comma:
+However, note that the caller will /always/ have to specify the extra parenthesis even when the macro parameters contain no comma:
[paren_always]
-In some cases, using [macroref BOOST_IDENTITY_TYPE] within the user macro definition might provide the best syntax for the user.
+In some cases, using [macroref BOOST_IDENTITY_TYPE] in the implementation of the user-defined macro might provide the best syntax for the caller.
For example, this is the case for `BOOST_MPL_ASSERT` because the majority of template meta-programming expressions contain unwrapped commas so it is less confusing for the user to always specify the extra parenthesis `((...))` instead of using [macroref BOOST_IDENTITY_TYPE]:
BOOST_MPL_ASSERT(( // Natural syntax.
@@ -147,7 +138,7 @@
return x + y;
} BOOST_LOCAL_FUNCTION_NAME(add)
-Instead requiring the user to specify [macroref BOOST_IDENTITY_TYPE] only when needed allows for the more natural syntax `BOOST_LOCAL_FUNCTION(int& x, int& y)` in the common cases when the parameter types contain no comma.
+Instead requiring the user to specify [macroref BOOST_IDENTITY_TYPE] only when needed allows for the more natural syntax `BOOST_LOCAL_FUNCTION(int& x, int& y)` in the common cases when the parameter types contain no comma (while still allowing to specify parameter types with commas as special cases using `BOOST_LOCAL_FUNCTION(BOOST_IDENTITY_TYPE((std::map<int, char>))& x, int& y)`).
[endsect]
@@ -156,7 +147,7 @@
The implementation of this library macro is equivalent to the following:
[footnote
There is absolutely no guarantee that the macro is actually implemented using the code listed in this documentation.
-This code is for explanatory purposes only.
+The listed code is for explanatory purposes only.
]
#include <boost/type_traits/function_traits.hpp>
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