Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r76923 - sandbox/local_function/libs/utility/identity_type/doc/html
From: lorcaminiti_at_[hidden]
Date: 2012-02-06 17:10:53

Author: lcaminiti
Date: 2012-02-06 17:10:51 EST (Mon, 06 Feb 2012)
New Revision: 76923
URL: http://svn.boost.org/trac/boost/changeset/76923

Log:
Adding docs.
Added:
sandbox/local_function/libs/utility/identity_type/doc/html/
sandbox/local_function/libs/utility/identity_type/doc/html/index.html (contents, props changed)

Added: sandbox/local_function/libs/utility/identity_type/doc/html/index.html
==============================================================================
--- (empty file)
+++ sandbox/local_function/libs/utility/identity_type/doc/html/index.html 2012-02-06 17:10:51 EST (Mon, 06 Feb 2012)
@@ -0,0 +1,227 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Boost.Utility/IdentityType 1.0.0</title><link rel="stylesheet" type="text/css" href="../../../../../doc/src/boostbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Boost.Utility/IdentityType 1.0.0"><div class="titlepage"><div><div><h2 class="title"><a name="boost_utility_identitytype"></a>Boost.Utility/IdentityType 1.0.0</h2></div><div><div class="author"><h3 class="author">Lorenzo Caminiti <code class="email"><<a class="email" href="mailto:lorcaminiti_at_[hidden]">lorcaminiti_at_[hidden]</a>></code></h3></div></div><div>Copyright © 2009-2012 Lorenzo
+ Caminiti</div><div><div class="legalnotice" title="Legal Notice"><a name="boost_utility_identitytype.legal"></a>
+ Distributed under the Boost Software License, Version 1.0 (see accompanying
+ file LICENSE_1_0.txt or a copy at <a class="ulink" href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt>)
+ </div></div></div></div><div class="toc">Table of Contents<dl><dt>Motivation</dt><dt>Solution</dt><dt>Templates</dt><dt>Abstract Types</dt><dt>Annex: Usages</dt><dt><a href="#boost_utility_identitytype.annex__implementation">Annex:
+ Implementation</a></dt><dt>Reference</dt></dl></div>
+ This library allows to wrap type expressions within round parenthesis so they
+ can be passed to macros even when they contain commas.
+ <div class="section" title="Motivation"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="boost_utility_identitytype.motivation"></a><a class="link" href="#boost_utility_identitytype.motivation" title="Motivation">Motivation</a></h2></div></div></div>
+ Consider the following macro which declares a variable named <code class="computeroutput">var</code>n with the specified
+ type (see also <a class="ulink" href="../../test/var_err.cpp" target="_top"><code class="literal">var_err.cpp</code></a>):
+ 
+<pre class="programlisting">#define VAR(type, n) type var ## n
+
+VAR( int, 1 ); // OK.
+VAR( std::map<int, char>, 2 ); // Error.
+</pre>
+ 
+ The first macro invocation works correctly declaring a variable named <code class="computeroutput">var1</code> of type <code class="computeroutput">int</code>.
+ However, the second macro invocation fails generating a preprocessor error
+ similar to the following:
+ <pre class="programlisting">error: macro "VAR" passed 3 arguments, but takes just 2
+</pre>
+ That is because the <code class="computeroutput">std::map</code> type passed as the first macro parameter
+ contains a comma <code class="computeroutput">,</code> not wrapped
+ by round parenthesis <code class="computeroutput">()</code>. The preprocessor
+ interprets that unwrapped comma as a separation between macro parameters concluding
+ that a total of three (and not two) parameters are passed to the macro in the
+ following order:
+ <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
+ <code class="computeroutput">std::map<int</code>
+ </li><li class="listitem">
+ <code class="computeroutput">char></code>
+ </li><li class="listitem">
+ <code class="computeroutput">2</code>
+ </li></ol></div>
+ Note that, differently from the compiler, the preprocessor only recognizes
+ round parameters <code class="computeroutput">()</code>. Angular
+ <code class="computeroutput"><></code> or squared <code class="computeroutput">[]</code> parenthesis are not used by the preprocessor
+ when parsing the macro parameters.
+ </div><div class="section" 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>
+ 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">typedef</code> can be used to specify
+ the type expression with the commas outside the macro (see also <a class="ulink" href="../../test/var.cpp" target="_top"><code class="literal">var.cpp</code></a>):
+ 
+<pre class="programlisting">typedef std::map<int, char> map_type;
+VAR( map_type, 3 ); // OK.
+</pre>
+ 
+ When this is not possible or desired (e.g., see the function template <code class="computeroutput">f</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>
+ 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 <a class="ulink" href="../../test/var.cpp" target="_top"><code class="literal">var.cpp</code></a>).
+ 
+<pre class="programlisting">#include <boost/utility/identity_type.hpp>
+
+VAR( BOOST_IDENTITY_TYPE((std::map<int, char>)), 4 ); // OK.
+</pre>
+ 
+ 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">()</code>. In fact, a total of two sets of round parenthesis
+ must be used: The parenthesis to invoke the macro <code class="computeroutput">BOOST_IDENTITY_TYPE(...)</code> plus the inner parenthesis to wrap the
+ type passed to the macro <code class="computeroutput">BOOST_IDENTITY_TYPE((...))</code>.
+ 
+ This macro works on any <a class="ulink" href="http://www.open-std.org/JTC1/SC22/WG21/docs/standards" target="_top">C++03</a>
+ compiler (because it does not use <a class="ulink" href="http://en.wikipedia.org/wiki/Variadic_macro" target="_top">variadic
+ macros</a>). [<a name="boost_utility_identitytype.solution.f0" href="#ftn.boost_utility_identitytype.solution.f0" class="footnote">1</a>]
+ </div><div class="section" 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>
+ This macro must be prefixed by <code class="computeroutput">typename</code>
+ when used within templates. For example, let's program a macro that declares
+ a function parameter named <code class="computeroutput">arg</code>n
+ with the specified type (see also <a class="ulink" href="../../test/template.cpp" target="_top"><code class="literal">template.cpp</code></a>):
+ 
+<pre class="programlisting">#define ARG(type, n) type arg ## n
+
+template<typename T>
+void f( // Prefix macro with `typename` in templates.
+ ARG( typename BOOST_IDENTITY_TYPE((std::map<int, T>)), 1 )
+) {
+ std::cout << arg1[0] << std::endl;
+}
+</pre>
+ 
+<pre class="programlisting">std::map<int, char> a;
+a[0] = 'a';
+
+f<char>(a); // OK.
+// f(a); // But error.
+</pre>
+ 
+ However, note that the template parameter type <code class="computeroutput">char</code>
+ must be explicitly specified when invoking the function <code class="computeroutput">f<char>(a)</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 implicitly determined by the compiler form the function call
+ as in <code class="computeroutput">f(a)</code>. (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 implicitly deduce the function template parameter as shown
+ below:
+ 
+<pre class="programlisting">template<typename T>
+void g(
+ std::map<int, T> arg1
+) {
+ std::cout << arg1[0] << std::endl;
+}
+</pre>
+ 
+<pre class="programlisting">g<char>(a); // OK.
+g(a); // Also OK.
+</pre>
+ </div><div class="section" 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>
+ On some compilers (e.g., GCC), using this macro on abstract types (i.e., a
+ class 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.
+ 
+ Let's program a macro that performs a static assertion on a <a class="ulink" href="http://en.wikipedia.org/wiki/Template_metaprogramming" target="_top">Template
+ Meta-Programming</a> (TMP) meta-function (similarly to Boost.MPL <a class="ulink" href="http://www.boost.org/doc/libs/1_36_0/libs/mpl/doc/refmanual/assert.html" target="_top"><code class="computeroutput">BOOST_MPL_ASSERT</code></a>). 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
+ to pass a meta-function with multiple template parameters to the assert macro
+ (so to handle the commas separating the template parameters). In this case,
+ if the meta-function is an abstract type, it needs to be manipulated adding
+ and removing a reference to it (see also <a class="ulink" href="../../test/tmp_assert.cpp" target="_top"><code class="literal">tmp_assert.cpp</code></a>):
+ 
+<pre class="programlisting">#define TMP_ASSERT(metafunction) \
+ BOOST_STATIC_ASSERT(metafunction::value)
+
+template<typename T, bool b>
+struct abstract {
+ static const bool value = b;
+ virtual void f(T const& x) = 0;
+};
+
+TMP_ASSERT(
+ boost::remove_reference< // Add and remove
+ BOOST_IDENTITY_TYPE(( // reference for
+ boost::add_reference< // abstract type.
+ abstract<int, true>
+ >::type
+ ))
+ >::type
+);
+</pre>
+ </div><div class="section" title="Annex: Usages"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="boost_utility_identitytype.annex__usages"></a><a class="link" href="#boost_utility_identitytype.annex__usages" title="Annex: Usages">Annex: Usages</a></h2></div></div></div>
+ 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 in the call of the user-defined macro (as shown by the examples
+ so far), or internally to the definition of the user macro. When <code class="computeroutput"><a class="link" href="#BOOST_IDENTITY_TYPE" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code> is used internally,
+ the call of the user macro will only have to specify the extra parenthesis
+ (see also <a class="ulink" href="../../test/tmp_assert.cpp" target="_top"><code class="literal">tmp_assert.cpp</code></a>):
+ 
+<pre class="programlisting">#define TMP_ASSERT_PAREN(parenthesized_metafunction) \
+ /* use `BOOST_IDENTITY_TYPE` in macro definition instead of invocation */ \
+ BOOST_STATIC_ASSERT(BOOST_IDENTITY_TYPE(parenthesized_metafunction)::value)
+
+TMP_ASSERT_PAREN(( boost::is_const<std::map<int, char> const> ));
+TMP_ASSERT( BOOST_IDENTITY_TYPE((boost::is_const<std::map<int, char> const>)) );
+</pre>
+ 
+ However, note that the user will always have to specify
+ the extra parenthesis even when the macro parameters contain no comma:
+ 
+<pre class="programlisting">TMP_ASSERT_PAREN(( boost::is_const<int const> )); // Always extra `()`.
+TMP_ASSERT( boost::is_const<int const> ); // No extra `()` and no macro.
+</pre>
+ 
+ In some cases, using <code class="computeroutput"><a class="link" href="#BOOST_IDENTITY_TYPE" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code>
+ internally might provide the best syntax for the user. For example, this is
+ the case for <code class="computeroutput">BOOST_MPL_ASSERT</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">((...))</code> instead of using <code class="computeroutput"><a class="link" href="#BOOST_IDENTITY_TYPE" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code>:
+ <pre class="programlisting">BOOST_MPL_ASSERT(( // Natural syntax.
+ boost::mpl::and_<
+ boost::is_const<T>
+ , boost::is_reference<T>
+ >
+));
+</pre>
+ However, in other situations it might be preferable to not require the extra
+ parenthesis in common cases and handle commas as special cases using the <code class="computeroutput"><a class="link" href="#BOOST_IDENTITY_TYPE" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code>. For example, this
+ is the case for <code class="computeroutput">BOOST_LOCAL_FUNCTION</code>
+ for which always requiring the extra parenthesis <code class="computeroutput">((...))</code>
+ around the types would lead to an unnatural syntax for the local function parameter
+ types:
+ <pre class="programlisting">int BOOST_LOCAL_FUNCTION( ((int)) x, ((int)) y ) { // Unnatural syntax.
+ return x + y;
+} BOOST_LOCAL_FUNCTION_NAME(add)
+</pre>
+ 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>
+ when needed allows for the more natural syntax <code class="computeroutput">BOOST_LOCAL_FUNCTION(int x, int y)</code> in the common cases when the parameter types
+ contain no comma.
+ </div><div class="section" 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>
+ The implementation of this library macro is equivalent to the following: [<a name="boost_utility_identitytype.annex__implementation.f0" href="#ftn.boost_utility_identitytype.annex__implementation.f0" class="footnote">2</a>]
+ <pre class="programlisting">#include <boost/type_traits/function_traits.hpp>
+
+#define BOOST_IDENTITY_TYPE(parenthesized_type) \
+ boost::function_traits<void parenthesized_type>::arg1_type
+</pre>
+ Essentially, the type is wrapped between round parenthesis <code class="computeroutput">(std::map<int,
+ char>)</code>
+ so it can be passed as a macro parameter even if it contain commas. Then the
+ parenthesized type is transformed into the type of a function returning <code class="computeroutput">void</code> and with the specified type as the type
+ of the first and only argument <code class="computeroutput">void
+ (std::map<int, char>)</code>. Finally, the type of the first argument
+ <code class="computeroutput">arg1_type</code> is extracted therefore
+ obtaining the original type from the parenthesized type (effectively stripping
+ the parenthesis from around the type).
+ </div><div class="section" title="Reference"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="reference"></a>Reference</h2></div></div></div><div class="section" title="Header <boost/utility/identity_type.hpp>"><div class="titlepage"><div><div><h3 class="title"><a name="header.boost.utility.identity_type_hpp"></a>Header <<a class="ulink" href="../../../../../boost/utility/identity_type.hpp" target="_top">boost/utility/identity_type.hpp</a>></h3></div></div></div>Wrap type expressions with round parenthesis so they can be passed to macros even if they contain commas. <pre class="synopsis">
+
+<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>Macro BOOST_IDENTITY_TYPE</h2>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). </div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><pre class="synopsis">// 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>>
+
+BOOST_IDENTITY_TYPE(parenthesized_type)</pre></div><div class="refsect1" title="Description"><a name="id476456"></a><h2>Description</h2>Parameters: <div class="informaltable"><table border="1"><colgroup><col><col></colgroup><tbody><tr><td><code class="computeroutput">parenthesized_type</code></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>
+This macro works on any C++03 compiler (it does not require variadic macros).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).On some compilers (like GCC), using this macro on an abstract types requires to add and remove a reference to the type. </div></div></div></div><div class="footnotes"> <hr width="100" align="left"><div class="footnote">[<a id="ftn.boost_utility_identitytype.solution.f0" href="#boost_utility_identitytype.solution.f0" class="para">1</a>] 
+ Using variadic macros, it would be possible to use a single set of parenthesis
+ <code class="computeroutput">BOOST_IDENTITY_TYPE(</code>type<code class="computeroutput">)</code> instead of two <code class="computeroutput">BOOST_IDENTITY_TYPE((</code>type<code class="computeroutput">))</code>
+ 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).
+ </div><div class="footnote">[<a id="ftn.boost_utility_identitytype.annex__implementation.f0" href="#boost_utility_identitytype.annex__implementation.f0" class="para">2</a>] 
+ 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.
+ </div></div></div></body></html>

Date view	Thread view	Subject view	Author view

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