Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r69818 - in sandbox/local: . boost/local/aux_/function_macros/code_ libs/local/doc libs/local/doc/html libs/local/doc/html/boost/local libs/local/doc/html/boost_local libs/local/doc/qbk libs/local/example
From: lorcaminiti_at_[hidden]
Date: 2011-03-10 09:22:16

Next message: lorcaminiti_at_[hidden]: "[Boost-commit] svn:boost r69819 - in sandbox/local/libs/local: doc/html/boost_local doc/qbk example"
Previous message: john_at_[hidden]: "[Boost-commit] svn:boost r69817 - trunk/boost/config/platform"

Author: lcaminiti
Date: 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
New Revision: 69818
URL: http://svn.boost.org/trac/boost/changeset/69818

Log:
Updating the docs.
Added:
   sandbox/local/libs/local/example/add_x_y.cpp
      - copied, changed from r69597, /sandbox/local/libs/local/example/add_num.cpp
   sandbox/local/libs/local/example/add_x_y_va.cpp
      - copied, changed from r69597, /sandbox/local/libs/local/example/add_num_va.cpp
Removed:
   sandbox/local/libs/local/doc/qbk/grammar.qbk
   sandbox/local/libs/local/doc/qbk/rationale.00.qbk
   sandbox/local/libs/local/doc/qbk/rationale.qbk
   sandbox/local/libs/local/example/add_num.cpp
   sandbox/local/libs/local/example/add_num_va.cpp
   sandbox/local/libs/local/example/scope_guards_se.cpp
Text files modified:
   sandbox/local/TODO.txt | 7
   sandbox/local/boost/local/aux_/function_macros/code_/functor.hpp | 2
   sandbox/local/libs/local/doc/Jamfile.jam | 5
   sandbox/local/libs/local/doc/html/BOOST_IDENTITY_TYPE.html | 2
   sandbox/local/libs/local/doc/html/BOOST_IDENTITY_VALUE.html | 8
   sandbox/local/libs/local/doc/html/BOOST_LOCAL_BLOCK_END.html | 2
   sandbox/local/libs/local/doc/html/BOOST_LOCAL_CONFIG_FUNCTION_ARITY_MAX.html | 7
   sandbox/local/libs/local/doc/html/BOOST_LOCAL_CONFIG_THIS_PARAM_NAME.html | 2
   sandbox/local/libs/local/doc/html/BOOST_LOCAL_EXIT_END.html | 2
   sandbox/local/libs/local/doc/html/boost/local/function.html | 2
   sandbox/local/libs/local/doc/html/boost_local/Advanced.html | 1184 ++++++++++++++++++++---------
   sandbox/local/libs/local/doc/html/boost_local/Alternatives.html | 8
   sandbox/local/libs/local/doc/html/boost_local/Examples.html | 8
   sandbox/local/libs/local/doc/html/boost_local/Grammar.html | 6
   sandbox/local/libs/local/doc/html/boost_local/Rationale.html | 8
   sandbox/local/libs/local/doc/html/boost_local/Releases.html | 6
   sandbox/local/libs/local/doc/html/boost_local/Starting.html | 28
   sandbox/local/libs/local/doc/html/boost_local/Tutorial.html | 1536 +++++++++++++++++++++++++--------------
   sandbox/local/libs/local/doc/html/index.html | 118 +-
   sandbox/local/libs/local/doc/html/standalone_HTML.manifest | 5
   sandbox/local/libs/local/doc/qbk/advanced.qbk | 328 ++++---
   sandbox/local/libs/local/doc/qbk/introduction.qbk | 51
   sandbox/local/libs/local/doc/qbk/local.qbk | 42
   sandbox/local/libs/local/doc/qbk/starting.qbk | 11
   sandbox/local/libs/local/doc/qbk/tutorial.qbk | 448 +++++------
   sandbox/local/libs/local/example/add_block_va.cpp | 2
   sandbox/local/libs/local/example/add_template_va.cpp | 2
   sandbox/local/libs/local/example/add_x_y.cpp | 8
   sandbox/local/libs/local/example/add_x_y_va.cpp | 8
   sandbox/local/libs/local/example/print_map.cpp | 12
   sandbox/local/libs/local/example/print_map_va.cpp | 14
   sandbox/local/libs/local/example/scope_guards_errno.cpp | 10
   sandbox/local/libs/local/example/scope_guards_except.cpp | 64 -
   sandbox/local/libs/local/example/transform.cpp | 4
   sandbox/local/libs/local/example/transform_va.cpp | 4
   35 files changed, 2427 insertions(+), 1527 deletions(-)

Modified: sandbox/local/TODO.txt
==============================================================================
--- sandbox/local/TODO.txt (original)
+++ sandbox/local/TODO.txt 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -8,13 +8,6 @@

* Docs: `this` can never be bound by ref (as usual in C++).

-* Docs: If `, default ...` syntax seems strange for C99, programmers can always use `#define WITH_DEFAULT(x) , default x` or similar macro instead.
-
-* Docs: Add D-Stype Scope Guards examples to docs.
-
-* Docs: Document that nesting is (now) possible.
-
-
* Code: Optimize macro expansion code for C++0x, C++03, etc. From John Bytheway:
> Yes, in C++0x local structs can be passed as template parameters.
> Obviously, in C++0x there are lambdas too, so you might think your

Modified: sandbox/local/boost/local/aux_/function_macros/code_/functor.hpp
==============================================================================
--- sandbox/local/boost/local/aux_/function_macros/code_/functor.hpp (original)
+++ sandbox/local/boost/local/aux_/function_macros/code_/functor.hpp 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -189,7 +189,7 @@
         /* these types are qualified with extra eventual const and/or & if */ \
         /* their variables are bound by const and/or & (this is because */ \
         /* it is difficult strip the eventual & given that the var name is */ \
- /* alwasy attached to the & symbol plus programmers can always */ \
+ /* always attached to the & symbol plus programmers can always */ \
         /* remove const& using type traits) */ \
         /* const bind typeof types */ \
         BOOST_PP_LIST_FOR_EACH_I( \

Modified: sandbox/local/libs/local/doc/Jamfile.jam
==============================================================================
--- sandbox/local/libs/local/doc/Jamfile.jam (original)
+++ sandbox/local/libs/local/doc/Jamfile.jam 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -30,10 +30,9 @@
 <dependency>qbk/tutorial.qbk
 <dependency>qbk/advanced.qbk
 <dependency>reference
- <dependency>qbk/grammar.qbk
- <dependency>qbk/alternatives.qbk
 <dependency>qbk/examples.qbk
- <dependency>qbk/rationale.qbk
+ <dependency>qbk/alternatives.qbk
+ <dependency>qbk/implementation.qbk
 <dependency>qbk/releases.qbk
 <dependency>qbk/bibliography.qbk
 <dependency>qbk/acknowledgements.qbk

Modified: sandbox/local/libs/local/doc/html/BOOST_IDENTITY_TYPE.html
==============================================================================
--- sandbox/local/libs/local/doc/html/BOOST_IDENTITY_TYPE.html (original)
+++ sandbox/local/libs/local/doc/html/BOOST_IDENTITY_TYPE.html 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -33,7 +33,7 @@

BOOST_IDENTITY_TYPE(parenthesized_type)</pre></div>
<div class="refsect1">
-<a name="id888292"></a><h2>Description</h2>
+<a name="id900741"></a><h2>Description</h2>
This macro expands to an expression that can be passed as a single macro parameter even if it contains commas and that evaluates to the specified type at compile-time (see the <a class="link" href="boost_local/Advanced.html" title="Advanced">Advanced</a> section).
For example <code class="computeroutput">BOOST_IDENTITY_TYPE((std::map<int, double>))</code> can be passed as a single macro parameter when instead <code class="computeroutput">std::map<int, double></code> cannot (because it contains a comma not wrapped by round parenthesis so it will be interpreted as two separate macro parameters by the preprocessor).
Parameters:

Modified: sandbox/local/libs/local/doc/html/BOOST_IDENTITY_VALUE.html
==============================================================================
--- sandbox/local/libs/local/doc/html/BOOST_IDENTITY_VALUE.html (original)
+++ sandbox/local/libs/local/doc/html/BOOST_IDENTITY_VALUE.html 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -7,7 +7,7 @@
<link rel="home" href="index.html" title="Boost.Local 0.1.1">
<link rel="up" href="reference.html#header.boost.utility.identity_hpp" title="Header <boost/utility/identity.hpp>">
<link rel="prev" href="BOOST_IDENTITY_TYPE.html" title="Macro BOOST_IDENTITY_TYPE">
-<link rel="next" href="boost_local/Grammar.html" title="Appendix: Grammar">
+<link rel="next" href="boost_local/Examples.html" title="Appendix: Examples">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
@@ -20,7 +20,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="BOOST_IDENTITY_TYPE.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="reference.html#header.boost.utility.identity_hpp"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="boost_local/Grammar.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
+<a accesskey="p" href="BOOST_IDENTITY_TYPE.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="reference.html#header.boost.utility.identity_hpp"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="boost_local/Examples.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="refentry">
<a name="BOOST_IDENTITY_VALUE"></a><div class="titlepage"></div>
@@ -33,7 +33,7 @@

BOOST_IDENTITY_VALUE(parenthesized_value)</pre></div>
<div class="refsect1">
-<a name="id888432"></a><h2>Description</h2>
+<a name="id900882"></a><h2>Description</h2>
This macro expands to an expression that can be passed as a single macro parameter even if it contains commas and that evaluates to the specified value at run-time (see the <a class="link" href="boost_local/Advanced.html" title="Advanced">Advanced</a> section).
For example <code class="computeroutput">BOOST_IDENTITY_VALUE((key_size<int, double>::value))</code> can be passed as a single macro parameter when instead <code class="computeroutput">key_size<int, double>::value</code> cannot (because it contains a comma not wrapped by round parenthesis so it will be interpreted as two separate macro parameters by the preprocessor).
Parameters: 
@@ -62,7 +62,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="BOOST_IDENTITY_TYPE.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="reference.html#header.boost.utility.identity_hpp"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="boost_local/Grammar.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
+<a accesskey="p" href="BOOST_IDENTITY_TYPE.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="reference.html#header.boost.utility.identity_hpp"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="boost_local/Examples.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

Modified: sandbox/local/libs/local/doc/html/BOOST_LOCAL_BLOCK_END.html
==============================================================================
--- sandbox/local/libs/local/doc/html/BOOST_LOCAL_BLOCK_END.html (original)
+++ sandbox/local/libs/local/doc/html/BOOST_LOCAL_BLOCK_END.html 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -33,7 +33,7 @@

BOOST_LOCAL_BLOCK_END</pre></div>
<div class="refsect1">
-<a name="id886235"></a><h2>Description</h2>
+<a name="id898654"></a><h2>Description</h2>
This macro must follow the local block body code <code class="computeroutput">{ ... }</code> as shown in the <code class="computeroutput">CONTRACT_DETAIL_LOCAL_BLOCK</code> documentation.
See: <code class="computeroutput">CONTRACT_DETAIL_LOCAL_BLOCK</code>, <a class="link" href="boost_local/Tutorial.html" title="Tutorial">Tutorial</a> section. 
</div>

Modified: sandbox/local/libs/local/doc/html/BOOST_LOCAL_CONFIG_FUNCTION_ARITY_MAX.html
==============================================================================
--- sandbox/local/libs/local/doc/html/BOOST_LOCAL_CONFIG_FUNCTION_ARITY_MAX.html (original)
+++ sandbox/local/libs/local/doc/html/BOOST_LOCAL_CONFIG_FUNCTION_ARITY_MAX.html 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -26,14 +26,17 @@
<a name="BOOST_LOCAL_CONFIG_FUNCTION_ARITY_MAX"></a><div class="titlepage"></div>
<div class="refnamediv">
<h2>Macro BOOST_LOCAL_CONFIG_FUNCTION_ARITY_MAX</h2>
-BOOST_LOCAL_CONFIG_FUNCTION_ARITY_MAX — Maximum number of function parameters supported for the local functions. 
+BOOST_LOCAL_CONFIG_FUNCTION_ARITY_MAX — Force to use C++ standard feature only. 
</div>
<h2 xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="refsynopsisdiv-title">Synopsis</h2>
<div xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="refsynopsisdiv"><pre class="synopsis">// In header: <<a class="link" href="reference.html#header.boost.local.config_hpp" title="Header <boost/local/config.hpp>">boost/local/config.hpp</a>>

BOOST_LOCAL_CONFIG_FUNCTION_ARITY_MAX</pre></div>
<div class="refsect1">
-<a name="id886367"></a><h2>Description</h2>
+<a name="id898787"></a><h2>Description</h2>
+Note: If programmers leave this macro undefined, its default value is undefined.
+If this macro is defined, variadic macros and empty macro parameters are not supported. Variadic macros, are supported by most recent compilers (like MSVC and GCC) and they were first introduced by the C99 preprocessor. However, they are not part of the official ISO C++ standard.
+See: <a class="link" href="boost_local/Tutorial.html" title="Tutorial">Tutorial</a> section. Maximum number of function parameters supported for the local functions.
Note: If programmers leave this macro undefined, its default value is <code class="computeroutput">5</code>.
This only refers to the number of local function parameters and not to the number of bound variables in scope (the limit on the number of bound variables is instead the maximum size allowed for a Boost.Preprocessor sequences).
Warning: Increasing this number will increase compilation time.

Modified: sandbox/local/libs/local/doc/html/BOOST_LOCAL_CONFIG_THIS_PARAM_NAME.html
==============================================================================
--- sandbox/local/libs/local/doc/html/BOOST_LOCAL_CONFIG_THIS_PARAM_NAME.html (original)
+++ sandbox/local/libs/local/doc/html/BOOST_LOCAL_CONFIG_THIS_PARAM_NAME.html 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -33,7 +33,7 @@

BOOST_LOCAL_CONFIG_THIS_PARAM_NAME</pre></div>
<div class="refsect1">
-<a name="id886467"></a><h2>Description</h2>
+<a name="id898920"></a><h2>Description</h2>
Note: If programmers leave this macro undefined, the default symbol used is <code class="computeroutput">this_</code>.
Warning: Programmers should not define this macro unless it is absolutely necessary (e.g., to avoid name clashes with another library which cannot be changed). Changing the symbol <code class="computeroutput">this_</code> effectively changes the public API of this library.
See: <a class="link" href="boost_local/Starting.html" title="Starting">Starting</a> section.

Modified: sandbox/local/libs/local/doc/html/BOOST_LOCAL_EXIT_END.html
==============================================================================
--- sandbox/local/libs/local/doc/html/BOOST_LOCAL_EXIT_END.html (original)
+++ sandbox/local/libs/local/doc/html/BOOST_LOCAL_EXIT_END.html 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -33,7 +33,7 @@

BOOST_LOCAL_EXIT_END</pre></div>
<div class="refsect1">
-<a name="id886690"></a><h2>Description</h2>
+<a name="id899144"></a><h2>Description</h2>
This macro must follow the local exit body code <code class="computeroutput">{ ... }</code> as shown in the <code class="computeroutput">CONTRACT_DETAIL_LOCAL_EXIT</code> documentation.
See: <code class="computeroutput">CONTRACT_DETAIL_LOCAL_EXIT</code>, <a class="link" href="boost_local/Tutorial.html" title="Tutorial">Tutorial</a> section. 
</div>

Modified: sandbox/local/libs/local/doc/html/boost/local/function.html
==============================================================================
--- sandbox/local/libs/local/doc/html/boost/local/function.html (original)
+++ sandbox/local/libs/local/doc/html/boost/local/function.html 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -35,7 +35,7 @@
struct <a class="link" href="function.html" title="Struct template function">function</a> {
};</pre></div>
<div class="refsect1">
-<a name="id887031"></a><h2>Description</h2>
+<a name="id899480"></a><h2>Description</h2>
This template defines several specializations to handle a generic number <code class="computeroutput">N</code> of function parameters some of which can have default values. The number of supported function parameters goes from <code class="computeroutput">0</code> (for a function with no parameter) to a maximum of <code class="computeroutput"><a class="link" href="../../BOOST_LOCAL_CONFIG_FUNCTION_ARITY_MAX.html" title="Macro BOOST_LOCAL_CONFIG_FUNCTION_ARITY_MAX">BOOST_LOCAL_CONFIG_FUNCTION_ARITY_MAX</a></code>.
Each template specialization defines call operators <code class="computeroutput">operator()(...)</code> with a different set of parameters to handle the number of default parameters specified by <code class="computeroutput">defaults</code> (see <a class="link" href="../../boost_local/Advanced.html" title="Advanced">Advanced</a> section): 
<pre class="programlisting"> template<typename Result, typename Arg1, ..., typename ArgN, size_t defaults = 0>

Modified: sandbox/local/libs/local/doc/html/boost_local/Advanced.html
==============================================================================
--- sandbox/local/libs/local/doc/html/boost_local/Advanced.html (original)
+++ sandbox/local/libs/local/doc/html/boost_local/Advanced.html 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -27,38 +27,37 @@
<a name="boost_local.Advanced"></a><a class="link" href="Advanced.html" title="Advanced">Advanced</a>
</h2></div></div></div>
<div class="toc"><dl>
-<dt><a href="Advanced.html#boost_local.Advanced.commas_in_macro_parameters">Commas
- in Macro Parameters</a></dt>
-<dt><a href="Advanced.html#boost_local.Advanced.recursive_local_functions">Recursive
+<dt><a href="Advanced.html#boost_local.Advanced.commas_and_symbols_in_macro_parameters">Commas
+ and Symbols in Macro Parameters</a></dt>
+<dt><a href="Advanced.html#boost_local.Advanced.deducing_bound_types">Deducing Bound
+ Types</a></dt>
+<dt><a href="Advanced.html#boost_local.Advanced.passing_local_functions">Passing
 Local Functions</a></dt>
<dt><a href="Advanced.html#boost_local.Advanced.exception_specifications">Exception
 Specifications</a></dt>
-<dt><a href="Advanced.html#boost_local.Advanced.optimizers___inline____auto___and__register_">Optimizers:
- <code class="computeroutput">inline</code>, <code class="computeroutput">auto</code>,
- and <code class="computeroutput">register</code></a></dt>
-<dt><a href="Advanced.html#boost_local.Advanced.references_to_local_functions">References
- to Local Functions</a></dt>
-<dt><a href="Advanced.html#boost_local.Advanced.renaming_local_functions">Renaming
+<dt><a href="Advanced.html#boost_local.Advanced.storage_classifiers__auto__and__register_">Storage
+ Classifiers <code class="computeroutput">auto</code> and <code class="computeroutput">register</code></a></dt>
+<dt><a href="Advanced.html#boost_local.Advanced.recursive_local_functions">Recursive
 Local Functions</a></dt>
-<dt><a href="Advanced.html#boost_local.Advanced.limitations__overloading__nesting__operators__etc">Limitations:
- Overloading, Nesting, Operators, Etc</a></dt>
+<dt>Nested Declarations</dt>
+<dt><a href="Advanced.html#boost_local.Advanced.limitations__overloading_and_operators">Limitations:
+ Overloading and Operators</a></dt>
</dl></div>

- This section illustrates advanced usages of this library. At the end of this
- section there is also a list of limitations of this library.
+ This section illustrates advanced usage of this library. At the end of this
+ section there is also a list of knwon limitations of this library.
 
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
-<a name="boost_local.Advanced.commas_in_macro_parameters"></a><a class="link" href="Advanced.html#boost_local.Advanced.commas_in_macro_parameters" title="Commas in Macro Parameters">Commas
- in Macro Parameters</a>
+<a name="boost_local.Advanced.commas_and_symbols_in_macro_parameters"></a><a class="link" href="Advanced.html#boost_local.Advanced.commas_and_symbols_in_macro_parameters" title="Commas and Symbols in Macro Parameters">Commas
+ and Symbols in Macro Parameters</a>
</h3></div></div></div>

 The C++ preprocessor does not allow commas "<code class="computeroutput">,</code>"
 within macro parameters unless they are wrapped by the round parenthesis
- <code class="computeroutput">()</code>. The elements of the parenthesized
- signature are internally used as macro parameters while they are being processed
- by the parsing macros. Therefore, commas within parenthesized signature elements
- will generate (cryptic) preprocessor errors unless they are wrapped within
+ <code class="computeroutput">()</code>. Therefore, using commas
+ the local function parameters and bindings passed to this library macros
+ ill generate (cryptic) preprocessor errors unless they are wrapped within
 extra round parenthesis <code class="computeroutput">()</code> as
 explained here.
 
@@ -73,223 +72,771 @@
 are fine (function calls, etc). However, macro parameters with commas that
 are not wrapped by round parenthesis need to be wrapped by an extra set
 of round parenthesis <code class="computeroutput">()</code> as
- described here. Therefore, also macro parameters with commas wrapped by
- angular parenthesis <code class="computeroutput"><></code>
- (templates, etc) or square parenthesis <code class="computeroutput">[]</code>
- (multidimensional array access, etc) need to be wrapped by the extra round
- parenthesis <code class="computeroutput">()</code> as explained
- here (this is because the preprocessor only recognizes the round parenthesis
- and it does not recognize angular, square, or any other type of parenthesis).
+ described here. Also macro parameters with commas wrapped by angular parenthesis
+ <code class="computeroutput"><></code> (templates, etc)
+ or square parenthesis <code class="computeroutput">[]</code> (multidimensional
+ array access, etc) need to be wrapped by the extra round parenthesis <code class="computeroutput">()</code> as explained here (this is because the
+ preprocessor only recognizes the round parenthesis and it does not recognize
+ angular, square, or any other type of parenthesis).
 </td></tr>
</table></div>

- For example, let's consider the following parenthesized signature (see the
- complete example code later in this section):
+ In addition, local function parameter types cannot start with non-alphanumeric
+ symbols (alphanumeric symbols are <code class="computeroutput">A-Z</code>, <code class="computeroutput">a-z</code>,
+ and <code class="computeroutput">0-9</code>). [<a name="id880579" href="#ftn.id880579" class="footnote">15</a>] The library will generate (cryptic) preprocessor errors if a
+ parameter type starts with a non-alphanumeric symbol.
+ 
+
+ Let's consider the following example:
 
-<pre class="programlisting">(void) (print)(
- (const std::map<std::string, size_t>&)(m) // (1) Error.
- (const size_t&)(factor)(default)
- (key_size<std::string, size_t>::value) // (2) Error.
- (const std::string&)(separator)(default)(cat(":", " ")) // (3) OK.
- (::sign_t)(sign)(default)(-1) // (4) Error.
- )
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Variadic Macro Syntax (C99 and later compilers)
+ 
+ </th>
+<th>
+ 
+ Sequencing Macro Syntax (all C++ compilers)
+ 
+ </th>
+</tr></thead>
+<tbody><tr>
+<td>
+ 
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a class="link" href="../BOOST_LOCAL_FUNCTION_PARAMS.html" title="Macro BOOST_LOCAL_FUNCTION_PARAMS">BOOST_LOCAL_FUNCTION_PARAMS</a></code>(
+ const std::map<std::string, size_t>& m, // (1) Error.
+ ::sign_t sign, // (2) Error.
+ const size_t& factor, default
+ key_size<std::string, size_t>::value, // (3) Error.
+ const std::string& separator, default cat(":", " "), // (4) OK.
+)
+</pre>
+
+ 
+ </td>
+<td>
+ 
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a class="link" href="../BOOST_LOCAL_FUNCTION_PARAMS.html" title="Macro BOOST_LOCAL_FUNCTION_PARAMS">BOOST_LOCAL_FUNCTION_PARAMS</a></code>(
+ (const std::map<std::string, size_t>& m) // (1) Error.
+ (::sign_t sign) // (2) Error.
+ (const size_t& factor)(default
+ key_size<std::string, size_t>::value) // (3) Error.
+ (const std::string& separator)(default cat(":", " ")) // (4) OK.
+)
</pre>

- (1) The parenthesized signature element
- <code class="computeroutput">const std::map<std::string, size_t>&</code> contains a comma "<code class="computeroutput">,</code>" after the first template parameter
+ 
+ </td>
+</tr></tbody>
+</table></div>
+
+ (1) The parameter type <code class="computeroutput">const
+ std::map<std::string, size_t>&</code> contains a comma "<code class="computeroutput">,</code>" after the first template parameter
 <code class="computeroutput">std::string</code>. This comma is not wrapped by any
 round parenthesis <code class="computeroutput">()</code> (the outer
- parenthesis <code class="computeroutput">()</code> that make this
- a parenthesized signature element do not count) thus it will cause a preprocessor
- error. The macro <code class="computeroutput"><a class="link" href="../BOOST_IDENTITY_TYPE.html" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a>(</code>parenthesized-type<code class="computeroutput">)</code> can be used to wrap a type within extra
+ parenthesis <code class="computeroutput">()</code> that make the
+ sequencing macro syntax do not count) thus it will cause a preprocessor error.
+ The macro <code class="computeroutput"><a class="link" href="../BOOST_IDENTITY_TYPE.html" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a>(</code>parenthesized-type<code class="computeroutput">)</code> can be used to wrap a type within extra
 parenthesis <code class="computeroutput">()</code> so to overcome
 this issue:
 
-<pre class="programlisting">(void) (print)(
- (<code class="computeroutput"><a class="link" href="../BOOST_IDENTITY_TYPE.html" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code>((const std::map<std::string, size_t>&)))(m) // OK.
- ...
- )
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Variadic Macro Syntax (C99 and later compilers)
+ 
+ </th>
+<th>
+ 
+ Sequencing Macro Syntax (all C++ compilers)
+ 
+ </th>
+</tr></thead>
+<tbody><tr>
+<td>
+ 
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a class="link" href="../BOOST_LOCAL_FUNCTION_PARAMS.html" title="Macro BOOST_LOCAL_FUNCTION_PARAMS">BOOST_LOCAL_FUNCTION_PARAMS</a></code>(
+ <code class="computeroutput"><a class="link" href="../BOOST_IDENTITY_TYPE.html" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code>((const std::map<std::string, size_t>&)) m, // OK.
+ ...
+)
+</pre>
+
+ 
+ </td>
+<td>
+ 
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a class="link" href="../BOOST_LOCAL_FUNCTION_PARAMS.html" title="Macro BOOST_LOCAL_FUNCTION_PARAMS">BOOST_LOCAL_FUNCTION_PARAMS</a></code>(
+ (<code class="computeroutput"><a class="link" href="../BOOST_IDENTITY_TYPE.html" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code>((const std::map<std::string, size_t>&)) m) // OK.
+ ...
+)
</pre>

+ 
+ </td>
+</tr></tbody>
+</table></div>
+
 This macro expands to an expression that evaluates (at compile-time) exactly
- to the specified type. Note that a total of three set of parenthesis <code class="computeroutput">()</code> are needed:
+ to the specified type. Note that a total of two set of parenthesis <code class="computeroutput">()</code> are added:
 
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
- Parenthesis to wrap the parenthesized signature element.
- </li>
-<li class="listitem">
- Parenthesis to call the <code class="computeroutput"><a class="link" href="../BOOST_IDENTITY_TYPE.html" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code>
+ Parenthesis to invoke the <code class="computeroutput"><a class="link" href="../BOOST_IDENTITY_TYPE.html" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code>
 macro.
 </li>
<li class="listitem">
 Parenthesis to wrap the type expression (and therefore any commas "<code class="computeroutput">,</code>" that it contains) passed as parameter
 to the <code class="computeroutput"><a class="link" href="../BOOST_IDENTITY_TYPE.html" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code>
- macro.
+ macro. [<a name="id881869" href="#ftn.id881869" class="footnote">16</a>]
 </li>
</ol></div>

- (2) The parenthesized signature element
- <code class="computeroutput">key_size<std::string, size_t>::value</code>
+ (2) The parameter type <code class="computeroutput">::sign_t</code> start with the non-alphanumeric
+ symbols "<code class="computeroutput">::</code>" thus
+ it cannot be used by the parenthesized syntax. The macros <code class="computeroutput"><a class="link" href="../BOOST_IDENTITY_TYPE.html" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code> can also
+ be used to overcome these issue:
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Variadic Macro Syntax (C99 and later compilers)
+ 
+ </th>
+<th>
+ 
+ Sequencing Macro Syntax (all C++ compilers)
+ 
+ </th>
+</tr></thead>
+<tbody><tr>
+<td>
+ 
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a class="link" href="../BOOST_LOCAL_FUNCTION_PARAMS.html" title="Macro BOOST_LOCAL_FUNCTION_PARAMS">BOOST_LOCAL_FUNCTION_PARAMS</a></code>(
+ ...
+ <code class="computeroutput"><a class="link" href="../BOOST_IDENTITY_TYPE.html" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code>((::sign_t)) sign, // OK.
+ ...
+)
+</pre>
+
+ 
+ </td>
+<td>
+ 
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a class="link" href="../BOOST_LOCAL_FUNCTION_PARAMS.html" title="Macro BOOST_LOCAL_FUNCTION_PARAMS">BOOST_LOCAL_FUNCTION_PARAMS</a></code>(
+ ...
+ (<code class="computeroutput"><a class="link" href="../BOOST_IDENTITY_TYPE.html" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code>((::sign_t)) sign) // OK.
+ ...
+)
+</pre>
+
+ 
+ </td>
+</tr></tbody>
+</table></div>
+
+ Often, there might be better ways to overcome this limitation that lead to
+ code which is more readable than the one using these macros. For example,
+ in this case the symbol "<code class="computeroutput">::</code>"
+ could be simply dropped to obtain the following and more readable code:
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Variadic Macro Syntax (C99 and later compilers)
+ 
+ </th>
+<th>
+ 
+ Sequencing Macro Syntax (all C++ compilers)
+ 
+ </th>
+</tr></thead>
+<tbody><tr>
+<td>
+ 
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a class="link" href="../BOOST_LOCAL_FUNCTION_PARAMS.html" title="Macro BOOST_LOCAL_FUNCTION_PARAMS">BOOST_LOCAL_FUNCTION_PARAMS</a></code>(
+ ...
+ sign_t sign, // OK.
+ ...
+)
+</pre>
+
+ 
+ </td>
+<td>
+ 
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a class="link" href="../BOOST_LOCAL_FUNCTION_PARAMS.html" title="Macro BOOST_LOCAL_FUNCTION_PARAMS">BOOST_LOCAL_FUNCTION_PARAMS</a></code>(
+ ...
+ (sign_t sign) // OK.
+ ...
+)
+</pre>
+
+ 
+ </td>
+</tr></tbody>
+</table></div>
+
+ (3) The default parameter value <code class="computeroutput">key_size<std::string, size_t>::value</code>
 contains a comma "<code class="computeroutput">,</code>"
 after the first template parameter <code class="computeroutput">std::string</code>.
 Again, this comma is not wrapped by any parenthesis <code class="computeroutput">()</code>
 so it will cause a preprocessor error. Because this is a value expression
- (and not a type expression), the macro <code class="computeroutput"><a class="link" href="../BOOST_IDENTITY_VALUE.html" title="Macro BOOST_IDENTITY_VALUE">BOOST_IDENTITY_VALUE</a>(</code>parenthesized-value<code class="computeroutput">)</code> is used to overcome this issue:
+ (and not a type expression), it can simply be wrapped within an extra set
+ of round parenthesis <code class="computeroutput">()</code>:
 
-<pre class="programlisting">(void) (print)(
- ...
- (const size_t&)(factor)(default)
- (<code class="computeroutput"><a class="link" href="../BOOST_IDENTITY_VALUE.html" title="Macro BOOST_IDENTITY_VALUE">BOOST_IDENTITY_VALUE</a></code>((key_size<std::string, size_t>::value))) // OK.
- ...
- )
-</pre>
-
- This macro expands to an expression that evaluates (at run-time) exactly
- to the specified value. Note again that a total of three set of parenthesis
- <code class="computeroutput">()</code> are needed similarly to
- <code class="computeroutput"><a class="link" href="../BOOST_IDENTITY_TYPE.html" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code>.
- 
-
- (3) The parenthesized signature element
- <code class="computeroutput">cat(':', '
- ')</code> is instead fine because
- it contains a comma "<code class="computeroutput">,</code>"
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Variadic Macro Syntax (C99 and later compilers)
+ 
+ </th>
+<th>
+ 
+ Sequencing Macro Syntax (all C++ compilers)
+ 
+ </th>
+</tr></thead>
+<tbody><tr>
+<td>
+ 
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a class="link" href="../BOOST_LOCAL_FUNCTION_PARAMS.html" title="Macro BOOST_LOCAL_FUNCTION_PARAMS">BOOST_LOCAL_FUNCTION_PARAMS</a></code>(
+ ...
+ const size_t& factor, default
+ (key_size<std::string, size_t>::value), // OK.
+ ...
+)
+</pre>
+
+ 
+ </td>
+<td>
+ 
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a class="link" href="../BOOST_LOCAL_FUNCTION_PARAMS.html" title="Macro BOOST_LOCAL_FUNCTION_PARAMS">BOOST_LOCAL_FUNCTION_PARAMS</a></code>(
+ ...
+ (const size_t& factor)(default
+ (key_size<std::string, size_t>::value)) // OK.
+ ...
+)
+</pre>
+
+ 
+ </td>
+</tr></tbody>
+</table></div>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top">
+ Alternatively, the macro <code class="computeroutput"><a class="link" href="../BOOST_IDENTITY_VALUE.html" title="Macro BOOST_IDENTITY_VALUE">BOOST_IDENTITY_VALUE</a>(</code>parenthesized-value<code class="computeroutput">)</code> could have been equivalently used. This
+ macro expands to an expression that evaluates (at run-time) exactly to
+ the specified value (but it adds overhead compared with simply using the
+ extra parenthesis <code class="computeroutput">()</code>). Note
+ that, similarly to <code class="computeroutput"><a class="link" href="../BOOST_IDENTITY_TYPE.html" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code>,
+ the <code class="computeroutput"><a class="link" href="../BOOST_IDENTITY_VALUE.html" title="Macro BOOST_IDENTITY_VALUE">BOOST_IDENTITY_VALUE</a></code>
+ macro also requires two sets of extra parenthesis one set for invoking
+ the macro and another set to wrap the value.
+ </td></tr>
+</table></div>
+
+ (4) The default parameter value <code class="computeroutput">cat(':', ' ')</code>
+ is instead fine because it contains a comma "<code class="computeroutput">,</code>"
 which is already wrapped by the parenthesis <code class="computeroutput">()</code>
 of the function call <code class="computeroutput">cat(...)</code>.
 

- (4) The parenthesized signature elements
- <code class="computeroutput">::sign_t</code>
- and <code class="computeroutput">-1</code>
- (the type and default value of the <code class="computeroutput">sign</code>
- parameter) start with the non-alphanumeric symbols "<code class="computeroutput">::</code>"
- and "<code class="computeroutput">-</code>" respectively
- thus they cannot be used by the parenthesized syntax. The macros <code class="computeroutput"><a class="link" href="../BOOST_IDENTITY_TYPE.html" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code> and <code class="computeroutput"><a class="link" href="../BOOST_IDENTITY_VALUE.html" title="Macro BOOST_IDENTITY_VALUE">BOOST_IDENTITY_VALUE</a></code> can also
- be used to overcome these issues:
- 
-<pre class="programlisting">(void) (print)(
- ...
- (<code class="computeroutput"><a class="link" href="../BOOST_IDENTITY_TYPE.html" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code>((::sign_t)))(sign)(default)
- (<code class="computeroutput"><a class="link" href="../BOOST_IDENTITY_VALUE.html" title="Macro BOOST_IDENTITY_VALUE">BOOST_IDENTITY_VALUE</a></code>((-1))) // OK.
- )
-</pre>
-
- This way the parenthesized signature elements became <code class="computeroutput">(<a class="link" href="../BOOST_IDENTITY_TYPE.html" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a>((::sign_t)))</code>
- and <code class="computeroutput">(<a class="link" href="../BOOST_IDENTITY_VALUE.html" title="Macro BOOST_IDENTITY_VALUE">BOOST_IDENTITY_VALUE</a>((-1)))</code>
- which start with the alphanumeric symbols of the macro names and they can
- be used by the parenthesized syntax.
+ Consider the following complete example: [<a name="id883052" href="#ftn.id883052" class="footnote">17</a>]
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Variadic Macro Syntax (C99 and later compilers)
+ 
+ </th>
+<th>
+ 
+ Sequencing Macro Syntax (all C++ compilers)
+ 
+ </th>
+</tr></thead>
+<tbody><tr>
+<td>
+ 
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">#include <boost/local/function.hpp>
+#include <boost/utility/identity.hpp>
+#include <map>
+#include <string>
+#include <iostream>
+
+template<typename K, typename T> struct key_size { static const size_t value; };
+template<typename K, typename T> const size_t key_size<K, T>::value = sizeof(K);
+
+std::string cat(const std::string& a, const std::string& b) { return a + b; }
+
+typedef int const& sign_t;
+
+int main() {
+ void BOOST_LOCAL_FUNCTION_PARAMS(
+ // Identity macros handle commas.
+ BOOST_IDENTITY_TYPE((const std::map<std::string, size_t>))& m,
+ // Also, identity macros handle leading symbols.
+ BOOST_IDENTITY_TYPE((::sign_t)) sign, default -1,
+ const size_t& factor, default // Or use `BOOST_IDENTITY_VALE`.
+ (key_size<std::string, size_t>::value),
+ const std::string& separator, default cat(":", " ")) {
+ for (std::map<std::string, size_t>::const_iterator i = m.begin();
+ i != m.end(); ++i) {
+ std::cout << i->first << separator <<
+ sign * int(i->second) * int(factor) << std::endl;
+ }
+ } BOOST_LOCAL_FUNCTION_NAME(print)
+
+ std::map<std::string, size_t> sizes;
+ sizes["a"] = 1; sizes["ab"] = 2; sizes["abc"] = 3;
+ print(sizes);
+
+ return 0;
+}
+</pre>
+
+ 
+ </td>
+<td>
+ 
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">#include <boost/local/function.hpp>
+#include <boost/utility/identity.hpp>
+#include <map>
+#include <string>
+#include <iostream>
+
+template<typename K, typename T> struct key_size { static const size_t value; };
+template<typename K, typename T> const size_t key_size<K, T>::value = sizeof(K);
+
+std::string cat(const std::string& a, const std::string& b) { return a + b; }
+
+typedef int const& sign_t;
+
+int main() {
+ void BOOST_LOCAL_FUNCTION_PARAMS(
+ // Identity macros handle commas.
+ (BOOST_IDENTITY_TYPE((const std::map<std::string, size_t>))& m)
+ // Also, identity macros handle leading symbols.
+ (BOOST_IDENTITY_TYPE((::sign_t)) sign)(default -1)
+ (const size_t& factor)(default // Or use `BOOST_IDENTITY_VALUE`.
+ (key_size<std::string, size_t>::value))
+ (const std::string& separator)(default cat(":", " ")) ) {
+ for (std::map<std::string, size_t>::const_iterator i = m.begin();
+ i != m.end(); ++i) {
+ std::cout << i->first << separator <<
+ sign * int(i->second) * int(factor) << std::endl;
+ }
+ } BOOST_LOCAL_FUNCTION_NAME(print)
+
+ std::map<std::string, size_t> sizes;
+ sizes["a"] = 1; sizes["ab"] = 2; sizes["abc"] = 3;
+ print(sizes);
+
+ return 0;
+}
+</pre>
+
+ 
+ </td>
+</tr></tbody>
+</table></div>
+
+ The <code class="computeroutput"><a class="link" href="../BOOST_IDENTITY_TYPE.html" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code>
+ macro must be prefixed by the <code class="computeroutput">typename</code>
+ keyword when used within templates.
+ 
+</div>
+<div class="section"><div class="titlepage"><div><div><h3 class="title">
+<a name="boost_local.Advanced.deducing_bound_types"></a><a class="link" href="Advanced.html#boost_local.Advanced.deducing_bound_types" title="Deducing Bound Types">Deducing Bound
+ Types</a>
+</h3></div></div></div></div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_local.Advanced.passing_local_functions"></a><a class="link" href="Advanced.html#boost_local.Advanced.passing_local_functions" title="Passing Local Functions">Passing
+ Local Functions</a>
+</h3></div></div></div>
+
+ It is possible to obtain a reference to a local function so to assign it
+ to a variable, to pass it as a function parameter, etc.
 
+<div class="important"><table border="0" summary="Important">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../doc/src/images/important.png"></td>
+<th align="left">Important</th>
+</tr>
+<tr><td align="left" valign="top">
+ Local functions are never copied by value. You can only obtain a reference
+ to a local function therefore you need to make sure that the local function survives the scope of its reference
+ otherwise the reference will be invalid and its use will generate a run-time
+ error (as usual with C++ references). [<a name="id886296" href="#ftn.id886296" class="footnote">18</a>]
+ </td></tr>
+</table></div>

- Often, there might be better ways to overcome this limitation that lead to
- code which is more readable than the one using these macros. For example,
- in this case the symbol "<code class="computeroutput">::</code>"
- could be dropped and <code class="computeroutput">-1</code>
- could be wrapped within <code class="computeroutput">int(...)</code> to obtain the following, more readable,
- and still valid parenthesized signature code:
+ For this purpose, it is possible to assign a <code class="computeroutput">boost::function</code>
+ functor to a local function (see also Boost.Function).
+ However, it is in general preferable to use the <code class="computeroutput">boost::local::<a class="link" href="../boost/local/function.html" title="Struct template function">function</a></code>
+ functor instead because its API also supports default parameters.
 
-<pre class="programlisting">(void) (print)(
- ...
- (sign_t)(sign)(default)(int(-1)) // OK.
- )
+
+ The <code class="computeroutput">boost::local::<a class="link" href="../boost/local/function.html" title="Struct template function">function</a></code> template takes two
+ parameters (see the Reference section):
+ 
+<pre class="programlisting">template< typename F, size_t defaults = 0 > class <code class="computeroutput"><a class="link" href="../boost/local/function.html" title="Struct template function">function</a></code>;
</pre>
+<div class="variablelist">
+
+<dl>
+<dt>F</dt>
+<dd>
+
+ The template parameter <code class="computeroutput">F</code>
+ specifies the function signature using the same syntax as Boost.Function's
+ preferred syntax. For example:
+
+<pre class="programlisting"><code class="computeroutput"><a class="link" href="../boost/local/function.html" title="Struct template function">function</a></code>< int() > // Returns `int` and takes no parameter.
+<code class="computeroutput"><a class="link" href="../boost/local/function.html" title="Struct template function">function</a></code>< int(double, char) > // Returns `int`and takes two parameters: a `double` followed by a `char`.
+</pre>
+
+ 
+</dd>
+<dt>defaults</dt>
+<dd>
+
+ The template parameter <code class="computeroutput">defaults</code>
+ specifies the number of defaults parameters counting from the last
+ parameter: <code class="computeroutput">0</code> if no parameter
+ is optional, <code class="computeroutput">1</code> if the last
+ parameter is optional, <code class="computeroutput">2</code>
+ if the last two parameters are optional, etc. This template parameter
+ must be between <code class="computeroutput">0</code> and the
+ total number of parameters as specified by <code class="computeroutput">F</code>.
+ This template parameter is optional and it is <code class="computeroutput">0</code>
+ by default. For example:
+
+<pre class="programlisting"><code class="computeroutput"><a class="link" href="../boost/local/function.html" title="Struct template function">function</a></code>< int(double, char) > // No default: All parameters must be specified.
+<code class="computeroutput"><a class="link" href="../boost/local/function.html" title="Struct template function">function</a></code>< int(double, char), 1 > // 1 default: The last `char` parameter is optional.
+<code class="computeroutput"><a class="link" href="../boost/local/function.html" title="Struct template function">function</a></code>< int(double, char), 2 > // 2 defaults: All parameters are optional.
+</pre>
+
+ 
+</dd>
+</dl>
+</div>

- Consider the following complete example: [<a name="id876264" href="#ftn.id876264" class="footnote">15</a>]
+ For example:
 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Variadic Macro Syntax (C99 and later compilers)
+ 
+ </th>
+<th>
+ 
+ Sequencing Macro Syntax (all C++ compilers)
+ 
+ </th>
+</tr></thead>
+<tbody><tr>
+<td>
+ 
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">#include <boost/local/function.hpp>
+#include <boost/function.hpp>
+#include <iostream>
+
+// Using `function` allows to use the same functor for all calls (regardless of
+// which set of default parameters is specified).
+void doit(boost::local::function< int (int, int), 2 > l) {
+ std::cout << l(1, 2) << std::endl;
+ std::cout << l(1) << std::endl;
+ std::cout << l() << std::endl;
+}
+
+// Using `function` requires different functors for calls with different set of
+// default parameters.
+void doit2(boost::function< int (int, int) > l)
+ { std::cout << l(1, 2) << std::endl; }
+void doit1(boost::function< int (int) > l) { std::cout << l(1) << std::endl; }
+void doit0(boost::function< int () > l) { std::cout << l() << std::endl; }
+
+int main() {
+ boost::function<int (int, int)> l2;
+
+ {
+ int i = 2;
+
+ int BOOST_LOCAL_FUNCTION_PARAMS(int x, default 1, int y, default 2,
+ bind i) {
+ return x + i * y;
+ } BOOST_LOCAL_FUNCTION_NAME(linear)
+
+ // Assign local functions variables.
+ boost::local::function< int (int, int), 2 > l = linear;
+ l(1, 2); l(1); l(); // All calls because of default parameters.
+ l2 = linear;
+ l2(1, 2); // Only one call operation (without default parameters).
+
+ // Similarly, pass local functions as a function parameter.
+ doit(linear);
+ std::cout << std::endl;
+ doit2(linear);
+ doit1(linear);
+ doit0(linear);
+ }
+
+ if (false) {
+ l2(1, 2); // This wouuld raise run-time error because invalid reference.
+ }
+
+ return 0;
+}
+</pre>

-
+ 
+ </td>
+<td>
+ 
+

-<pre class="programlisting">#include <boost/local/function.hpp>
-#include <boost/utility/identity.hpp>
-#include <map>
-#include <string>
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">#include <boost/local/function.hpp>
+#include <boost/function.hpp>
#include <iostream>

-template<typename K, typename T> struct key_size { static const size_t value; };
-template<typename K, typename T> const size_t key_size<K, T>::value = sizeof(K);
-
-std::string cat(const std::string& a, const std::string& b) { return a + b; }
+// Using `function` allows to use the same functor for all calls (regardless of
+// which set of default parameters is specified).
+void doit(boost::local::function< int (int, int), 2 > l) {
+ std::cout << l(1, 2) << std::endl;
+ std::cout << l(1) << std::endl;
+ std::cout << l() << std::endl;
+}

-typedef int const& sign_t;
+// Using `function` requires different functors for calls with different set of
+// default parameters.
+void doit2(boost::function< int (int, int) > l)
+ { std::cout << l(1, 2) << std::endl; }
+void doit1(boost::function< int (int) > l) { std::cout << l(1) << std::endl; }
+void doit0(boost::function< int () > l) { std::cout << l() << std::endl; }

int main() {
- void BOOST_LOCAL_FUNCTION_PARAMS(
- // Identity macors handle commas.
- (BOOST_IDENTITY_TYPE((const std::map<std::string, size_t>))& m)
- (const size_t& factor)(default // Or just use `(default (...))`.
- BOOST_IDENTITY_VALUE((key_size<std::string, size_t>::value)))
- (const std::string& separator)(default cat(":", " "))
- // Also, identity macors handle leading symbols.
- (BOOST_IDENTITY_TYPE((::sign_t)) sign)(default -1) ) {
- for (std::map<std::string, size_t>::const_iterator i = m.begin();
- i != m.end(); ++i) {
- std::cout << i->first << separator <<
- sign * int(i->second) * int(factor) << std::endl;
- }
- } BOOST_LOCAL_FUNCTION_NAME(print)
+ boost::function<int (int, int)> l2;

- std::map<std::string, size_t> sizes;
- sizes["a"] = 1; sizes["ab"] = 2; sizes["abc"] = 3;
- print(sizes);
+ {
+ int i = 2;
+
+ int BOOST_LOCAL_FUNCTION_PARAMS( (int x)(default 1) (int y)(default 2)
+ (bind i) ) {
+ return x + i * y;
+ } BOOST_LOCAL_FUNCTION_NAME(linear)
+
+ // Assign local functions variables.
+ boost::local::function< int (int, int), 2 > l = linear;
+ l(1, 2); l(1); l(); // All calls because of default parameters.
+ l2 = linear;
+ l2(1, 2); // Only one call operation (without default parameters).
+
+ // Similarly, pass local functions as a function parameter.
+ doit(linear);
+ std::cout << std::endl;
+ doit2(linear);
+ doit1(linear);
+ doit0(linear);
+ }
+
+ if (false) {
+ l2(1, 2); // This wouuld raise run-time error because invalid reference.
+ }

 return 0;
}
</pre>

- 
-</div>
-<div class="section">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="boost_local.Advanced.recursive_local_functions"></a><a class="link" href="Advanced.html#boost_local.Advanced.recursive_local_functions" title="Recursive Local Functions">Recursive
- Local Functions</a>
-</h3></div></div></div>
-
- A local function can recursively call itself as usual with C++ functions.
- 
+ 
+ </td>
+</tr></tbody>
+</table></div>

- For example, the following local function is used to recursively calculate
- and print the factorial of the specified numbers:
+ In addition, a local function can be bind and call another local function.
+ For example, the following local function <code class="computeroutput">inc_sum</code>
+ binds the local function <code class="computeroutput">inc</code>
+ so the <code class="computeroutput">inc_sum</code> can call
+ <code class="computeroutput">inc</code>:
 
-
-
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Variadic Macro Syntax (C99 and later compilers)
+ 
+ </th>
+<th>
+ 
+ Sequencing Macro Syntax (all C++ compilers)
+ 
+ </th>
+</tr></thead>
+<tbody><tr>
+<td>
+ 
+

-<pre class="programlisting">#include <boost/local/function.hpp>
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">#include <boost/local/function.hpp>
#include <iostream>
-#include <sstream>
#include <algorithm>
#include <vector>

int main () {
- std::ostringstream output;
-
- int BOOST_LOCAL_FUNCTION_PARAMS( (int n) (bool recursion)(default false)
- (bind& output) ) {
- int result = 0;
-
- if (n < 2 ) result = 1;
- else result = n * factorial(n - 1, true); // Recursive call.
-
- if (!recursion) output << result << " ";
- return result;
- } BOOST_LOCAL_FUNCTION_NAME(factorial)
-
- std::vector<int> v(3);
- v[0] = 1; v[1] = 4; v[2] = 7;
- std::for_each(v.begin(), v.end(), factorial);
-
- std::cout << output.str() << std::endl;
+ int offset = 5;
+ std::vector<int> v;
+ std::vector<int> w;
+
+ // v = 10 20 30 40 50
+ for (int i = 1; i < 6; i++) v.push_back(i * 10);
+ w.resize(v.size());
+
+ // w = ++v + 5 = 16 26 36 46 56
+ int BOOST_LOCAL_FUNCTION_PARAMS(int i, const bind& offset) {
+ // Compiler error if const `offset` modified here by mistake.
+ return ++i + offset;
+ } BOOST_LOCAL_FUNCTION_NAME(inc)
+ std::transform(v.begin(), v.end(), w.begin(), inc);
+
+ offset = 0;
+
+ // v = ++(v + w) + 0 = 27 47 67 87 107
+ int BOOST_LOCAL_FUNCTION_PARAMS(int i, int j,
+ bind inc) { // Bind another local function.
+ return inc(i + j); // Call the bound local function.
+ } BOOST_LOCAL_FUNCTION_NAME(inc_sum)
+ std::transform(v.begin(), v.end(), w.begin(), v.begin(), inc_sum);
+
+ for (std::vector<int>::iterator i = v.begin(); i != v.end(); ++i)
+ { std::cout << " " << *i; }
+ std::cout << std::endl;
+
 return 0;
}
</pre>

- 
+ 
+ </td>
+<td>
+ 
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">#include <boost/local/function.hpp>
+#include <iostream>
+#include <algorithm>
+#include <vector>
+
+int main () {
+ int offset = 5;
+ std::vector<int> v;
+ std::vector<int> w;
+
+ // v = 10 20 30 40 50
+ for (int i = 1; i < 6; i++) v.push_back(i * 10);
+ w.resize(v.size());
+
+ // w = ++v + 5 = 16 26 36 46 56
+ int BOOST_LOCAL_FUNCTION_PARAMS( (int i) (const bind& offset) ) {
+ // Compiler error if const `offset` modified here by mistake.
+ return ++i + offset;
+ } BOOST_LOCAL_FUNCTION_NAME(inc)
+ std::transform(v.begin(), v.end(), w.begin(), inc);
+
+ offset = 0;
+
+ // v = ++(v + w) + 0 = 27 47 67 87 107
+ int BOOST_LOCAL_FUNCTION_PARAMS( (int i) (int j)
+ (bind inc) ) { // Bind another local function.
+ return inc(i + j); // Call the bound local function.
+ } BOOST_LOCAL_FUNCTION_NAME(inc_sum)
+ std::transform(v.begin(), v.end(), w.begin(), v.begin(), inc_sum);
+
+ for (std::vector<int>::iterator i = v.begin(); i != v.end(); ++i)
+ { std::cout << " " << *i; }
+ std::cout << std::endl;
+
+ return 0;
+}
+</pre>

- The original local function name as specified in the parenthesized signature
- passed to <code class="computeroutput">BOOST_LOCAL_FUNCTION</code>
- must always be used for recursive calls even when the function is renamed
- using <code class="computeroutput">BOOST_LOCAL_FUNCTION_END_RENAME</code>
- (see renamed local functions later in this section).
- 
+ 
+ </td>
+</tr></tbody>
+</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
@@ -346,12 +893,11 @@
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
-<a name="boost_local.Advanced.optimizers___inline____auto___and__register_"></a><a class="link" href="Advanced.html#boost_local.Advanced.optimizers___inline____auto___and__register_" title="Optimizers: inline, auto, and register">Optimizers:
- <code class="computeroutput">inline</code>, <code class="computeroutput">auto</code>,
- and <code class="computeroutput">register</code></a>
+<a name="boost_local.Advanced.storage_classifiers__auto__and__register_"></a><a class="link" href="Advanced.html#boost_local.Advanced.storage_classifiers__auto__and__register_" title="Storage Classifiers auto and register">Storage
+ Classifiers <code class="computeroutput">auto</code> and <code class="computeroutput">register</code></a>
</h3></div></div></div>

- As specified in the <a class="link" href="Grammar.html" title="Appendix: Grammar">Grammar</a> section,
+ As specified in the <a class="link" href="../">Grammar</a> section,
 the parenthesized signature also supports <code class="computeroutput">inline</code>d
 local functions, and the <code class="computeroutput">auto</code>
 and <code class="computeroutput">register</code> classifiers for
@@ -393,264 +939,134 @@
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
-<a name="boost_local.Advanced.references_to_local_functions"></a><a class="link" href="Advanced.html#boost_local.Advanced.references_to_local_functions" title="References to Local Functions">References
- to Local Functions</a>
+<a name="boost_local.Advanced.recursive_local_functions"></a><a class="link" href="Advanced.html#boost_local.Advanced.recursive_local_functions" title="Recursive Local Functions">Recursive
+ Local Functions</a>
</h3></div></div></div>

- It is possible to obtain a reference to a local function so to assign it
- to a variable, to pass it as a function parameter, etc.
- 
-<div class="important"><table border="0" summary="Important">
-<tr>
-<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../doc/src/images/important.png"></td>
-<th align="left">Important</th>
-</tr>
-<tr><td align="left" valign="top">
- Local functions are never copied by value. You can only obtain a reference
- to a local function therefore you need to make sure that the local function survives the scope of its reference
- otherwise the reference will be invalid and its use will generate a run-time
- error (as usual with C++ references). [<a name="id880541" href="#ftn.id880541" class="footnote">16</a>]
- </td></tr>
-</table></div>
-
- For this purpose, it is possible to assign a <code class="computeroutput">boost::function</code>
- functor to a local function (see also Boost.Function).
- However, it is in general preferable to use the <code class="computeroutput">boost::local::function_ref</code>
- functor instead because its API also supports default parameters.
+ A local function can recursively call itself as usual with C++ functions.
 

- The <code class="computeroutput">boost::local::function_ref</code> template
- takes two parameters (see the Reference
- section):
- 
-<pre class="programlisting">template<typename F, size_t defaults = 0>
-class <code class="computeroutput">function_ref</code> { ... };
-</pre>
-
- Where:
- 
-<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
- The template parameter <code class="computeroutput">F</code>
- specifies the function signature using the same syntax as Boost.Function's
- preferred syntax. For example:
- </li></ul></div>
-<pre class="programlisting"><code class="computeroutput">function_ref</code>< int() > // Returns `int` and takes no parameter.
-<code class="computeroutput">function_ref</code>< int(double, char) > // Returns `int`and takes two parameters: a `double` followed by a `char`.
-</pre>
-<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
- The template parameter <code class="computeroutput">defaults</code>
- specifies the number of defaults parameters counting from the last parameter:
- <code class="computeroutput">0</code> if no parameter is optional,
- <code class="computeroutput">1</code> if the last parameter is
- optional, <code class="computeroutput">2</code> if the last two
- parameters are optional, etc. This template parameter must be between
- <code class="computeroutput">0</code> and the total number of
- parameters as specified by <code class="computeroutput">F</code>.
- This template parameter is optional and it is <code class="computeroutput">0</code>
- by default. For example:
- </li></ul></div>
-<pre class="programlisting"><code class="computeroutput">function_ref</code>< int(double, char) > // No default: All parameters must be specified.
-<code class="computeroutput">function_ref</code>< int(double, char), 1 > // 1 default: The last `char` parameter is optional.
-<code class="computeroutput">function_ref</code>< int(double, char), 2 > // 2 defaults: All parameters are optional.
-</pre>
-
- For example:
+ For example, the following local function is used to recursively calculate
+ and print the factorial of the specified numbers:
 



<pre class="programlisting">#include <boost/local/function.hpp>
-#include <boost/function.hpp>
#include <iostream>
+#include <sstream>
+#include <algorithm>
+#include <vector>

-// Using `function` allows to use the same functor for all calls (regardless of
-// which set of default parameters is specified).
-void doit(boost::local::function< int (int, int), 2 > l) {
- std::cout << l(1, 2) << std::endl;
- std::cout << l(1) << std::endl;
- std::cout << l() << std::endl;
-}
-
-// Using `function` requires different functors for calls with different set of
-// default parameters.
-void doit2(boost::function< int (int, int) > l)
- { std::cout << l(1, 2) << std::endl; }
-void doit1(boost::function< int (int) > l) { std::cout << l(1) << std::endl; }
-void doit0(boost::function< int () > l) { std::cout << l() << std::endl; }
-
-int main() {
- boost::function<int (int, int)> l2;
+int main () {
+ std::ostringstream output;

- {
- int i = 2;
-
- int BOOST_LOCAL_FUNCTION_PARAMS( (int x)(default 1) (int y)(default 2)
- (bind i) ) {
- return x + i * y;
- } BOOST_LOCAL_FUNCTION_NAME(linear)
+ int BOOST_LOCAL_FUNCTION_PARAMS( (int n) (bool recursion)(default false)
+ (bind& output) ) {
+ int result = 0;

- // Assign local functions variables.
- boost::local::function< int (int, int), 2 > l = linear;
- l(1, 2); l(1); l(); // All calls because of default parameters.
- l2 = linear;
- l2(1, 2); // Only one call operation (without default parameters).
+ if (n < 2 ) result = 1;
+ else result = n * factorial(n - 1, true); // Recursive call.

- // Similarly, pass local functions as a function parameter.
- doit(linear);
- std::cout << std::endl;
- doit2(linear);
- doit1(linear);
- doit0(linear);
- }
-
- if (false) {
- l2(1, 2); // This wouuld raise run-time error because invalid reference.
- }
+ if (!recursion) output << result << " ";
+ return result;
+ } BOOST_LOCAL_FUNCTION_NAME(factorial)
+
+ std::vector<int> v(3);
+ v[0] = 1; v[1] = 4; v[2] = 7;
+ std::for_each(v.begin(), v.end(), factorial);

+ std::cout << output.str() << std::endl;
 return 0;
}
</pre>

 
-</div>
-<div class="section">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="boost_local.Advanced.renaming_local_functions"></a><a class="link" href="Advanced.html#boost_local.Advanced.renaming_local_functions" title="Renaming Local Functions">Renaming
- Local Functions</a>
-</h3></div></div></div>
-
- Local functions can be renamed using the <code class="computeroutput">BOOST_LOCAL_FUNCTION_END_RENAME</code>
- macro instead of <code class="computeroutput">BOOST_LOCAL_FUNCTION_END</code>:
- 
-<pre class="programlisting"><code class="computeroutput">BOOST_LOCAL_FUNCTION_END_RENAME</code>(new-local-function-name)
-</pre>
-
- Where the new-local-function-name no longer has to match
- the local function name as originally specified in the parenthesized signature
- passed to <code class="computeroutput">BOOST_LOCAL_FUNCTION</code>.
- For example: [<a name="id883056" href="#ftn.id883056" class="footnote">17</a>]
- 
-<pre class="programlisting">{
- <code class="computeroutput">BOOST_LOCAL_FUNCTION</code>(
- (void) (l)( (int)(x) )
- ) {
- ... // Body uses original name `l`.
- } <code class="computeroutput">BOOST_LOCAL_FUNCTION_END_RENAME</code>(m) // Renamed to `m`.
-
- ... // Enclosing scope uses new name `m`.
-}
-</pre>
-
- Note that the local function is renamed only after the call to <code class="computeroutput">BOOST_LOCAL_FUNCTION_END_RENAME</code>.
- Therefore, within the local function body the original local function name
- as specified by <code class="computeroutput">BOOST_LOCAL_FUNCTION</code>
- must be used (e.g., to recursively call the local function). However, within
- the enclosing scope only the new local function name as specified by <code class="computeroutput">BOOST_LOCAL_FUNCTION_END_RENAME</code>
- is available.
- 
-
- A limitation is that renamed local functions cannot be directly passed as
- template parameters (e.g., they cannot be passed to STL algorithms like
- <code class="computeroutput">std::for_each</code>). However, it is possible to workaround
- this limitation by obtaining a reference of the renamed local function and
- then passing the reference as template parameter. For example:
- 
-
- [renamed_print_cpp]
- 
-<a name="boost_local.Advanced.renaming_local_functions.motivation"></a><h6>
-<a name="id883353"></a>
- <a class="link" href="Advanced.html#boost_local.Advanced.renaming_local_functions.motivation">Motivation</a>
- </h6>
-
- The motivation for renaming a local function might not be obvious at first.
- In fact, in most cases programmers will not need to rename local functions.
- 
-
- Renaming local functions might be useful at least to program macros that
- expand using local functions and that do not want to pass the local function
- body as a macro parameter (so to retain the usual meaning of compiler error
- line numbers for the body code). Consider the following example that implements
- a simple version of the local exit macros using a renamed local function:
- 

- [renamed_exit_cpp]
+ The original local function name as specified in the parenthesized signature
+ passed to <code class="computeroutput">__BOOST_LOCAL_FUNCTION__</code>
+ must always be used for recursive calls even when the function is renamed
+ using <code class="computeroutput">__BOOST_LOCAL_FUNCTION_END_RENAME__</code>
+ (see renamed local functions later in this section).
 
</div>
+<div class="section"><div class="titlepage"><div><div><h3 class="title">
+<a name="boost_local.Advanced.nested_declarations"></a><a class="link" href="Advanced.html#boost_local.Advanced.nested_declarations" title="Nested Declarations">Nested Declarations</a>
+</h3></div></div></div></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
-<a name="boost_local.Advanced.limitations__overloading__nesting__operators__etc"></a><a class="link" href="Advanced.html#boost_local.Advanced.limitations__overloading__nesting__operators__etc" title="Limitations: Overloading, Nesting, Operators, Etc">Limitations:
- Overloading, Nesting, Operators, Etc</a>
+<a name="boost_local.Advanced.limitations__overloading_and_operators"></a><a class="link" href="Advanced.html#boost_local.Advanced.limitations__overloading_and_operators" title="Limitations: Overloading and Operators">Limitations:
+ Overloading and Operators</a>
</h3></div></div></div>

 This is a list of limitations of this library's local functions compared
 to usual features of C++ functions.
 
-<a name="boost_local.Advanced.limitations__overloading__nesting__operators__etc.overloading"></a><h6>
-<a name="id883437"></a>
- <a class="link" href="Advanced.html#boost_local.Advanced.limitations__overloading__nesting__operators__etc.overloading">Overloading</a>
+<a name="boost_local.Advanced.limitations__overloading_and_operators.overloading"></a><h6>
+<a name="id895860"></a>
+ <a class="link" href="Advanced.html#boost_local.Advanced.limitations__overloading_and_operators.overloading">Overloading</a>
 </h6>

 It is not possible to overload local functions. Declaring multiple local
 functions with the same name within the same enclosing scope generates a
 compile-time error (even if the different declarations specify different
- parameters). [<a name="id883457" href="#ftn.id883457" class="footnote">18</a>]
+ parameters). [<a name="id895879" href="#ftn.id895879" class="footnote">19</a>]
 

 For example, the following code will not
 compile:
 
<pre class="programlisting">void f() {
- <code class="computeroutput">BOOST_LOCAL_FUNCTION</code>(
+ __BOOST_LOCAL_FUNCTION__(
 (void) (l)( (const int&)(i) )
 ) {
 std::cout << i << std::endl;
- } <code class="computeroutput">BOOST_LOCAL_FUNCTION_END</code>(l)
+ } __BOOST_LOCAL_FUNCTION_END__(l)

- <code class="computeroutput">BOOST_LOCAL_FUNCTION</code>(
+ __BOOST_LOCAL_FUNCTION__(
 (void) (l)( (const double&)(d) )
 ) {
 std::cout << d << std::endl;
- } <code class="computeroutput">BOOST_LOCAL_FUNCTION_END</code>(l) // Error: Cannot overload.
+ } __BOOST_LOCAL_FUNCTION_END__(l) // Error: Cannot overload.

 ...
}
</pre>
-<a name="boost_local.Advanced.limitations__overloading__nesting__operators__etc.nesting"></a><h6>
-<a name="id883899"></a>
- <a class="link" href="Advanced.html#boost_local.Advanced.limitations__overloading__nesting__operators__etc.nesting">Nesting</a>
+<a name="boost_local.Advanced.limitations__overloading_and_operators.nesting"></a><h6>
+<a name="id896320"></a>
+ <a class="link" href="Advanced.html#boost_local.Advanced.limitations__overloading_and_operators.nesting">Nesting</a>
 </h6>

 It is not possible to nest local functions, local blocks, or local exits
- within each other. Nesting will generate a compile-time error. [<a name="id883921" href="#ftn.id883921" class="footnote">19</a>]
+ within each other. Nesting will generate a compile-time error. [<a name="id896342" href="#ftn.id896342" class="footnote">20</a>]
 

 For example, the following code will not
 compile:
 
<pre class="programlisting">void f() {
- <code class="computeroutput">BOOST_LOCAL_FUNCTION</code>(
+ __BOOST_LOCAL_FUNCTION__(
 (int) (l)( (int)(i) )
 ) {
- <code class="computeroutput">BOOST_LOCAL_FUNCTION</code>( // Error: Cannot nest.
+ __BOOST_LOCAL_FUNCTION__( // Error: Cannot nest.
 (int) (m)( (int)(j) )
 ) {
 return j * 10;
- } <code class="computeroutput">BOOST_LOCAL_FUNCTION_END</code>(m)
+ } __BOOST_LOCAL_FUNCTION_END__(m)

 return m(i) * 10;
- } <code class="computeroutput">BOOST_LOCAL_FUNCTION_END</code>(l)
+ } __BOOST_LOCAL_FUNCTION_END__(l)

 ...
}
</pre>
-<a name="boost_local.Advanced.limitations__overloading__nesting__operators__etc.operators"></a><h6>
-<a name="id884322"></a>
- <a class="link" href="Advanced.html#boost_local.Advanced.limitations__overloading__nesting__operators__etc.operators">Operators</a>
+<a name="boost_local.Advanced.limitations__overloading_and_operators.operators"></a><h6>
+<a name="id896744"></a>
+ <a class="link" href="Advanced.html#boost_local.Advanced.limitations__overloading_and_operators.operators">Operators</a>
 </h6>

 Local functions cannot be operators. Naming a local function <code class="computeroutput">operator...</code>
- will generate a compile-time error. [<a name="id884359" href="#ftn.id884359" class="footnote">20</a>]
+ will generate a compile-time error. [<a name="id896780" href="#ftn.id896780" class="footnote">21</a>]
 

 For example, the following code will not
@@ -662,23 +1078,23 @@
 double y;
 };

- <code class="computeroutput">BOOST_LOCAL_FUNCTION</code>( // Error: Cannot be `operator==`.
+ __BOOST_LOCAL_FUNCTION__( // Error: Cannot be `operator==`.
 (bool) (operator==)( (const point&)(p) (const point&)(q) )
 ) {
 return p.x == q.x && p.y == q.y;
- ) <code class="computeroutput">BOOST_LOCAL_FUNCTION_END</code>(operator==)
+ ) __BOOST_LOCAL_FUNCTION_END__(operator==)

 ...
}
</pre>
-<a name="boost_local.Advanced.limitations__overloading__nesting__operators__etc.etc"></a><h6>
-<a name="id884753"></a>
- <a class="link" href="Advanced.html#boost_local.Advanced.limitations__overloading__nesting__operators__etc.etc">Etc</a>
+<a name="boost_local.Advanced.limitations__overloading_and_operators.etc"></a><h6>
+<a name="id897173"></a>
+ <a class="link" href="Advanced.html#boost_local.Advanced.limitations__overloading_and_operators.etc">Etc</a>
 </h6>

 Some usual C++ function features like <code class="computeroutput">inline</code>
 and default parameters are supported for local functions while other features
- are not supported. The parenthesized syntax itself (see the <a class="link" href="Grammar.html" title="Appendix: Grammar">Grammar</a>
+ are not supported. The parenthesized syntax itself (see the <a class="link" href="../">Grammar</a>
 section) could be extended to support all C++ function
 features even with the addition of concepts and named parameters (see Contract++):
 
@@ -977,39 +1393,47 @@
</div>
<div class="footnotes">
 <hr width="100" align="left">
-<div class="footnote">[<a id="ftn.id876264" href="#id876264" class="para">15</a>] 
- We recognize that the use of the identity macros adds
- extra parenthesis to the already significant number of parenthesis required
- by the parenthesized syntax. However, parenthesized signatures usually
+<div class="footnote">[<a id="ftn.id880579" href="#id880579" class="para">15</a>] 
+ Rationale. This limitation cames from
+ the implementation of the library parsing macros that use preprocessor
+ token concatenation to inspect the parameter type token to see if the token
+ is a parameter or a bound variable. The C++ preprocessor does not allow
+ to concatenate non-alphanumeric tokens.
+ </div>
+<div class="footnote">[<a id="ftn.id881869" href="#id881869" class="para">16</a>] 
+ Rationale. Using variadic macros,
+ this extra set of parenthesis could be eliminated requiring only the
+ parenthesis to invoke the <code class="computeroutput"><a class="link" href="../BOOST_IDENTITY_TYPE.html" title="Macro BOOST_IDENTITY_TYPE">BOOST_IDENTITY_TYPE</a></code>
+ macro. This feature is currently not implemented and the double parenthesis
+ are always needed when invoking this macro.
+ </div>
+<div class="footnote">[<a id="ftn.id883052" href="#id883052" class="para">17</a>] 
+ The authors recognize that the use of the identity macros
+ adds extra parenthesis to the already significant number of parenthesis
+ required by the parenthesized syntax. However, macro parameters usually
 do not contain unwrapped commas "<code class="computeroutput">,</code>"
 (unless template metaprogramming is being used).
 </div>
-<div class="footnote">[<a id="ftn.id880541" href="#id880541" class="para">16</a>] 
- The suffix <code class="computeroutput">ref</code> of <code class="computeroutput">boost::local::function_ref</code> is meant
- to help programmers remember that they are dealing with references to
- (and not copies of) local functions.
+<div class="footnote">[<a id="ftn.id886296" href="#id886296" class="para">18</a>] 
+ The suffix <code class="computeroutput">ref</code> of <code class="computeroutput">boost::local::<a class="link" href="../boost/local/function.html" title="Struct template function">function</a></code> is meant to
+ help programmers remember that they are dealing with references to (and
+ not copies of) local functions.
 </div>
-<div class="footnote">[<a id="ftn.id883056" href="#id883056" class="para">17</a>] 
- Rationale. Local functions are often named
- <code class="computeroutput">l</code> in the casual examples
- of this documentation because the name of the author starts with the letter
- "<code class="computeroutput">l</code>". <img src="../../images/smiley.png" alt="smiley">
- </div>
-<div class="footnote">[<a id="ftn.id883457" href="#id883457" class="para">18</a>] 
+<div class="footnote">[<a id="ftn.id895879" href="#id895879" class="para">19</a>] 
 Rationale. This is because a local function
 is a functor object declared as a local variable within the enclosing scope.
 Therefore, declaring two local functions with the same name within the
 same enclosing scope declares two local variables with the same name within
 the same scope and that is not allowed in C++.
 </div>
-<div class="footnote">[<a id="ftn.id883921" href="#id883921" class="para">19</a>] 
+<div class="footnote">[<a id="ftn.id896342" href="#id896342" class="para">20</a>] 
 Rationale. This is because within a nested
 code block only global or static variables can be accessed while Boost.ScopeExit
 variable <a href="http://lists.boost.org/Archives/boost/2006/11/113658.php" target="_top">binding
 mechanism</a> requires to access local variables that hold the bound
 variables.
 </div>
-<div class="footnote">[<a id="ftn.id884359" href="#id884359" class="para">20</a>] 
+<div class="footnote">[<a id="ftn.id896780" href="#id896780" class="para">21</a>] 
 Rationale. This is the because a local
 function name must be a valid local variable name (the local variable to
 hold the local functor object) and operators cannot be used as local variable

Modified: sandbox/local/libs/local/doc/html/boost_local/Alternatives.html
==============================================================================
--- sandbox/local/libs/local/doc/html/boost_local/Alternatives.html (original)
+++ sandbox/local/libs/local/doc/html/boost_local/Alternatives.html 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -6,8 +6,8 @@
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<link rel="home" href="../index.html" title="Boost.Local 0.1.1">
<link rel="up" href="../index.html" title="Boost.Local 0.1.1">
-<link rel="prev" href="Grammar.html" title="Appendix: Grammar">
-<link rel="next" href="Examples.html" title="Appendix: Examples">
+<link rel="prev" href="Examples.html" title="Appendix: Examples">
+<link rel="next" href="Implementation.html" title="Appendix: Implementation">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
@@ -20,7 +20,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="Grammar.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="Examples.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
+<a accesskey="p" href="Examples.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="Implementation.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
@@ -255,7 +255,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="Grammar.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="Examples.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
+<a accesskey="p" href="Examples.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="Implementation.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

Modified: sandbox/local/libs/local/doc/html/boost_local/Examples.html
==============================================================================
--- sandbox/local/libs/local/doc/html/boost_local/Examples.html (original)
+++ sandbox/local/libs/local/doc/html/boost_local/Examples.html 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -6,8 +6,8 @@
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<link rel="home" href="../index.html" title="Boost.Local 0.1.1">
<link rel="up" href="../index.html" title="Boost.Local 0.1.1">
-<link rel="prev" href="Alternatives.html" title="Appendix: Alternatives">
-<link rel="next" href="Rationale.html" title="Appendix: Rationale">
+<link rel="prev" href="../BOOST_IDENTITY_VALUE.html" title="Macro BOOST_IDENTITY_VALUE">
+<link rel="next" href="Alternatives.html" title="Appendix: Alternatives">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
@@ -20,7 +20,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="Alternatives.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="Rationale.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
+<a accesskey="p" href="../BOOST_IDENTITY_VALUE.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="Alternatives.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
@@ -233,7 +233,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="Alternatives.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="Rationale.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
+<a accesskey="p" href="../BOOST_IDENTITY_VALUE.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="Alternatives.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

Modified: sandbox/local/libs/local/doc/html/boost_local/Grammar.html
==============================================================================
--- sandbox/local/libs/local/doc/html/boost_local/Grammar.html (original)
+++ sandbox/local/libs/local/doc/html/boost_local/Grammar.html 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -132,7 +132,7 @@
 (default)(parameter-default) // Default value for this optional parameter.
</pre>

- Binding variables in scope: [<a name="id889233" href="#ftn.id889233" class="footnote">21</a>] [<a name="id889538" href="#ftn.id889538" class="footnote">22</a>]
+ Binding variables in scope: [<a name="id889912" href="#ftn.id889912" class="footnote">21</a>] [<a name="id890216" href="#ftn.id890216" class="footnote">22</a>]
 
<pre class="programlisting">bindings:
 const-bindings // Only constant binding.
@@ -151,7 +151,7 @@
</pre>
<div class="footnotes">
 <hr width="100" align="left">
-<div class="footnote">[<a id="ftn.id889233" href="#id889233" class="para">21</a>] 
+<div class="footnote">[<a id="ftn.id889912" href="#id889912" class="para">21</a>] 
 Rationale. The alternative syntax <code class="computeroutput">(bind)((const& x)...)</code>
 would have been preferred because <code class="computeroutput">const</code>
 appears before the reference as usual in C++ and because a single <code class="computeroutput">bind</code> sequence is used for both plain and
@@ -172,7 +172,7 @@
 symbol <code class="computeroutput">&</code> never appears in
 the back).
 </div>
-<div class="footnote">[<a id="ftn.id889538" href="#id889538" class="para">22</a>] 
+<div class="footnote">[<a id="ftn.id890216" href="#id890216" class="para">22</a>] 
 Rationale. Binding is used within the function
 parameter list because this syntax seemed natural given that the bound variables
 are used by the function body as if they were function parameters (only their

Modified: sandbox/local/libs/local/doc/html/boost_local/Rationale.html
==============================================================================
--- sandbox/local/libs/local/doc/html/boost_local/Rationale.html (original)
+++ sandbox/local/libs/local/doc/html/boost_local/Rationale.html 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -1018,7 +1018,7 @@
 Default parameter values are not part of the type so it is not possible
 to program a metafunction that counts the number of default parameter
 values at compile-time but such information is also needed by the local
- functions in order to properly support default parameters. [<a name="id897512" href="#ftn.id897512" class="footnote">23</a>]
+ functions in order to properly support default parameters. [<a name="id898183" href="#ftn.id898183" class="footnote">23</a>]
 </li>
</ol></div>

@@ -1037,7 +1037,7 @@
 Note that the <code class="computeroutput">=</code> symbol needs
 to be replaced with the alphanumeric keyword <code class="computeroutput">default</code>
 because parenthesized syntax elements cannot start with a non alphanumeric
- symbol like <code class="computeroutput">=</code>. [<a name="id897911" href="#ftn.id897911" class="footnote">24</a>]
+ symbol like <code class="computeroutput">=</code>. [<a name="id898582" href="#ftn.id898582" class="footnote">24</a>]
 

 For C99, some or all the parenthesis can be replaced by commas.
@@ -1215,7 +1215,7 @@
</div>
<div class="footnotes">
 <hr width="100" align="left">
-<div class="footnote">[<a id="ftn.id897512" href="#id897512" class="para">23</a>] 
+<div class="footnote">[<a id="ftn.id898183" href="#id898183" class="para">23</a>] 
 Specifically, the number of default parameter value is needed at
 compile-time to instantiate the proper <code class="computeroutput">function_ref<typename
 F,
@@ -1224,7 +1224,7 @@
 functor is needed to implement the trick that allows local functions
 to be passed as template parameters (see http://lists.boost.org/Archives/boost/2010/09/170888.php).
 </div>
-<div class="footnote">[<a id="ftn.id897911" href="#id897911" class="para">24</a>] 
+<div class="footnote">[<a id="ftn.id898582" href="#id898582" class="para">24</a>] 
 This is because the parenthesized syntax needs to check if its token
 matches a keyword like <code class="computeroutput">void</code>,
 <code class="computeroutput">inline</code>, etc. This checking

Modified: sandbox/local/libs/local/doc/html/boost_local/Releases.html
==============================================================================
--- sandbox/local/libs/local/doc/html/boost_local/Releases.html (original)
+++ sandbox/local/libs/local/doc/html/boost_local/Releases.html 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -6,7 +6,7 @@
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<link rel="home" href="../index.html" title="Boost.Local 0.1.1">
<link rel="up" href="../index.html" title="Boost.Local 0.1.1">
-<link rel="prev" href="Rationale.html" title="Appendix: Rationale">
+<link rel="prev" href="Implementation.html" title="Appendix: Implementation">
<link rel="next" href="Bibliography.html" title="Bibliography">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
@@ -20,7 +20,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="Rationale.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="Bibliography.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
+<a accesskey="p" href="Implementation.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="Bibliography.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
@@ -89,7 +89,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="Rationale.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="Bibliography.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
+<a accesskey="p" href="Implementation.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="Bibliography.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

Modified: sandbox/local/libs/local/doc/html/boost_local/Starting.html
==============================================================================
--- sandbox/local/libs/local/doc/html/boost_local/Starting.html (original)
+++ sandbox/local/libs/local/doc/html/boost_local/Starting.html 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -76,18 +76,13 @@
 manual of the library public API.
 </li>
<li class="listitem">
- The <a class="link" href="Grammar.html" title="Appendix: Grammar">Grammar</a> section formally
- describes the parenthesized syntax used by this library to specify the
- local function signatures.
+ The <a class="link" href="Examples.html" title="Appendix: Examples">Examples</a> section lists
+ the source code of a few additional examples that use this library.
 </li>
<li class="listitem">
 The <a class="link" href="Alternatives.html" title="Appendix: Alternatives">Alternatives</a> section
 describes alternatives to this library to implement local functions.
 </li>
-<li class="listitem">
- The <a class="link" href="Examples.html" title="Appendix: Examples">Examples</a> section lists
- the source code of a few additional examples that use this library.
- </li>
</ul></div>

 The following sections are for reference only:
@@ -177,7 +172,9 @@
<pre class="programlisting"><code class="computeroutput"><a class="link" href="../reference.html#header.boost.local.function_hpp" title="Header <boost/local/function.hpp>">boost/local/function.hpp</a></code> local functions
<code class="computeroutput"><a class="link" href="../reference.html#header.boost.local.block_hpp" title="Header <boost/local/block.hpp>">boost/local/block.hpp</a></code> local blocks
<code class="computeroutput"><a class="link" href="../reference.html#header.boost.local.exit_hpp" title="Header <boost/local/exit.hpp>">boost/local/exit.hpp</a></code> local exits
-<code class="computeroutput">boost/local/function_ref.hpp</code> references to local functions
+<code class="computeroutput">boost/local/typeof.hpp</code> bound variable type deduction
+<code class="computeroutput"><a class="link" href="../reference.html#header.boost.local.function_hpp" title="Header <boost/local/function.hpp>">boost/local/function.hpp</a></code> local functors
+<code class="computeroutput"><a class="link" href="../reference.html#header.boost.local.config_hpp" title="Header <boost/local/config.hpp>">boost/local/config.hpp</a></code> configuration macros
</pre>
</div>
<div class="section">
@@ -186,7 +183,7 @@
</h3></div></div></div>

 The following symbols are part of the library private API, they are not documented,
- and they should not be directly used by programmers: [<a name="id865081" href="#ftn.id865081" class="footnote">1</a>]
+ and they should not be directly used by programmers: [<a name="id865347" href="#ftn.id865347" class="footnote">2</a>]
 
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
@@ -220,13 +217,13 @@

 All configuration macros have names prefixed by <code class="computeroutput">BOOST_LOCAL_CONFIG</code>
 (see Reference section). It is strongly
- recommended not to change this library configuration macros unless strictly
- necessary.
+ recommended not to change the library configuration macro definitions unless
+ strictly necessary.
 
</div>
<div class="footnotes">
 <hr width="100" align="left">
-<div class="footnote">[<a id="ftn.id865081" href="#id865081" class="para">1</a>] 
+<div class="footnote">[<a id="ftn.id865347" href="#id865347" class="para">2</a>] 
 Rationale. This library concatenates symbols
 specified by the programmers (e.g., the local function name) with other
 symbols (e.g., special prefixes or preprocessor line numbers) to make internal
@@ -235,9 +232,10 @@
 when they are concatenated so they can be read more easily while debugging
 the library. The underscore character "<code class="computeroutput">_</code>"
 could not be used instead of the letter "<code class="computeroutput">X</code>"
- because if the original symbols already contain a leading or trailing underscore
- the concatenation would result in a symbol with double underscores "<code class="computeroutput">__</code>" which is reserved by the C++
- standard.
+ because if the original symbols already contained a leading or trailing
+ underscore, the concatenation would result in a symbol with double underscores
+ "<code class="computeroutput">__</code>" which is
+ reserved by the C++ standard.
 </div>
</div>
</div>

Modified: sandbox/local/libs/local/doc/html/boost_local/Tutorial.html
==============================================================================
--- sandbox/local/libs/local/doc/html/boost_local/Tutorial.html (original)
+++ sandbox/local/libs/local/doc/html/boost_local/Tutorial.html 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -27,274 +27,446 @@
<a name="boost_local.Tutorial"></a><a class="link" href="Tutorial.html" title="Tutorial">Tutorial</a>
</h2></div></div></div>
<div class="toc"><dl>
-<dt><a href="Tutorial.html#boost_local.Tutorial.parenthesized_syntax">Parenthesized
- Syntax</a></dt>
<dt>Local Functions</dt>
-<dt>Binding</dt>
+<dt>Empty Parameters</dt>
+<dt>Default Parameters</dt>
+<dt>Binding</dt>
<dt>Local Blocks</dt>
<dt>Local Exits</dt>
<dt>Templates</dt>
</dl></div>

- This section illustrates basic usages of local functions, local blocks, and
+ This section illustrates basic usage of local functions, local blocks, and
 local exits.
 
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
-<a name="boost_local.Tutorial.parenthesized_syntax"></a><a class="link" href="Tutorial.html#boost_local.Tutorial.parenthesized_syntax" title="Parenthesized Syntax">Parenthesized
- Syntax</a>
+<a name="boost_local.Tutorial.local_functions"></a><a class="link" href="Tutorial.html#boost_local.Tutorial.local_functions" title="Local Functions">Local Functions</a>
</h3></div></div></div>

- The parenthesized syntax is used to pass the syntactic
- elements of a function signature as macro parameters in a way that resembles
- the usual C++ syntax. All the function signature elements are wrapped within
- round parenthesis <code class="computeroutput">()</code> to form
- a Boost.Preprocessor
- sequence called parenthesized signature. This allows
- to program preprocessor macros that can parse the parenthesized syntax expanding
- differently based on the different elements that are specified in the signature
- (if the function has parameters or not, if the result type token matches
- the <code class="computeroutput">void</code> keyword or not, etc).
+ Local functions are defined using the following macros (see the Reference
+ section) from within a declarative context (this is a limitation with respect
+ to <a href="http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions" target="_top">C++0x
+ lambda</a> functions which can instead be declared within expressions):
 
-<div class="important"><table border="0" summary="Important">
-<tr>
-<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../doc/src/images/important.png"></td>
-<th align="left">Important</th>
-</tr>
-<tr><td align="left" valign="top">
-
- The general rules to program the parenthesized signature
- are:
- 
-
- 1. Wrap all the signature syntactic elements within parenthesis <code class="computeroutput">()</code>. [<a name="id865404" href="#ftn.id865404" class="footnote">2</a>]
- 
-
- 2. If a token does not start with an alphanumeric symbol (i.e., <code class="computeroutput">a-z</code>,
- <code class="computeroutput">A-Z</code>, or <code class="computeroutput">0-9</code>), replace
- the token with its alphanumeric equivalent (as indicated in the <a class="link" href="Grammar.html" title="Appendix: Grammar">Grammar</a>
- section). [<a name="id865531" href="#ftn.id865531" class="footnote">3</a>]
- 
-
- 3. Empty parenthesis <code class="computeroutput">()</code> are
- not allowed. [<a name="id865568" href="#ftn.id865568" class="footnote">4</a>]
- 
+<pre class="programlisting">{ // Some declarative context.
+ ...
+
+ result-type <code class="computeroutput"><a class="link" href="../BOOST_LOCAL_FUNCTION_PARAMS.html" title="Macro BOOST_LOCAL_FUNCTION_PARAMS">BOOST_LOCAL_FUNCTION_PARAMS</a></code>(parameters) {
+ body-code
+ } <code class="computeroutput"><a class="link" href="../BOOST_LOCAL_FUNCTION_NAME.html" title="Macro BOOST_LOCAL_FUNCTION_NAME">BOOST_LOCAL_FUNCTION_NAME</a></code>(name)
+
+ ...
+}
+</pre>

- 4. Spaces and newlines do not matter and they can be used anywhere.
- 
-</td></tr>
+ The expansion of this macros declares a functor object with the local function
+ name that can be called from the enclosing scope. The usual C++ scope visibility
+ rules apply to local functions for which a local function is visible and
+ can be called only within the enclosing scope in which it is declared.
+ 
+
+ The local function parameters are passed to the <code class="computeroutput"><a class="link" href="../BOOST_LOCAL_FUNCTION_PARAMS.html" title="Macro BOOST_LOCAL_FUNCTION_PARAMS">BOOST_LOCAL_FUNCTION_PARAMS</a></code>
+ macro either using the sequencing macro syntax (which
+ separates the parameters by wrapping them within round parenthesis <code class="computeroutput">()</code> and it is supported on all C++ compilers)
+ or using the variadic macro syntax (which separates
+ the parameters using a comma <code class="computeroutput">,</code>
+ but it is supported only on C99 and later compilers):
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Variadic Macro Syntax (C99 and later compilers)
+ 
+ </th>
+<th>
+ 
+ Sequencing Macro Syntax (all C++ compilers)
+ 
+ </th>
+</tr></thead>
+<tbody><tr>
+<td>
+ 
+ <code class="computeroutput"><a class="link" href="../BOOST_LOCAL_FUNCTION_PARAMS.html" title="Macro BOOST_LOCAL_FUNCTION_PARAMS">BOOST_LOCAL_FUNCTION_PARAMS</a>(</code><code class="literal">parameter-type1
+ parameter-name1</code><code class="computeroutput">,</code>
+ <code class="literal">parameter-type2 parameter-name2 ...</code><code class="computeroutput">)</code>
+ 
+ </td>
+<td>
+ 
+ <code class="computeroutput"><a class="link" href="../BOOST_LOCAL_FUNCTION_PARAMS.html" title="Macro BOOST_LOCAL_FUNCTION_PARAMS">BOOST_LOCAL_FUNCTION_PARAMS</a>( (</code><code class="literal">parameter-type1
+ parameter-name1</code><code class="computeroutput">)
+ (</code><code class="literal">parameter-type2
+ parameter-name2</code><code class="computeroutput">)</code>
+ <code class="literal">...</code><code class="computeroutput">)</code>
+ 
+ </td>
+</tr></tbody>
</table></div>

- For example, let's rewrite the following C++ function signature using the
- parenthesized syntax:
- 
-<pre class="programlisting">int l(double& y, const double& x = 0.0)
+ The local function body is specified in a code block <code class="computeroutput">{
+ ... }</code>
+ using the usual C++ syntax. The body is specified outside any of the macros
+ so eventual compiler error messages and line numbers retain their usual meaning.
+ [<a name="id865988" href="#ftn.id865988" class="footnote">3</a>]
+ 
+
+ The macro <code class="computeroutput"><a class="link" href="../BOOST_LOCAL_FUNCTION_NAME.html" title="Macro BOOST_LOCAL_FUNCTION_NAME">BOOST_LOCAL_FUNCTION_NAME</a></code>
+ is used to end the local function definition and to specify the local function
+ name. [<a name="id866018" href="#ftn.id866018" class="footnote">4</a>]
+ 
+
+ For example, let's program a local function named <code class="computeroutput">add</code>
+ that takes two integer numbers <code class="computeroutput">x</code>
+ and <code class="computeroutput">y</code>, and adds them together
+ -- for simplicity, we will not bind any of the variables in scope just yet
+ (binding is explained later in this section):
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Variadic Macro Syntax (C99 and later compilers)
+ 
+ </th>
+<th>
+ 
+ Sequencing Macro Syntax (all C++ compilers)
+ 
+ </th>
+</tr></thead>
+<tbody><tr>
+<td>
+ 
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">#include <boost/local/function.hpp>
+#include <iostream>
+
+int main() {
+ int BOOST_LOCAL_FUNCTION_PARAMS(int x, int y) {
+ return x + y;
+ } BOOST_LOCAL_FUNCTION_NAME(add)
+
+ add(1, 2);
+ return 0;
+}
</pre>

- Step 1. We start by wrapping all the syntactic
- elements within round parenthesis <code class="computeroutput">()</code>:
- 
-<pre class="programlisting">(int) (l)( (double&)(y) (,) (const double&)(x)(=)(0.0) ) <code class="literal">/* wrap all elements within parenthesis `()` */</code>
+ 
+ </td>
+<td>
+ 
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">#include <boost/local/function.hpp>
+#include <iostream>
+
+int main() {
+ int BOOST_LOCAL_FUNCTION_PARAMS( (int x) (int y) ) {
+ return x + y;
+ } BOOST_LOCAL_FUNCTION_NAME(add)
+
+ add(1, 2);
+ return 0;
+}
</pre>

- Note how parameter types are wrapped within parenthesis separately from parameter
- names. However, all the tokens of a parameter type are wrapped together within
- a single set of parenthesis because the parameter type is one single syntactic
- element of the function signature. For example, <code class="computeroutput">x</code>'s
- type is specified by <code class="computeroutput">(const
- double&)</code>
- and not by <code class="computeroutput">(const)(double)(&)</code>.
- 
+ 
+ </td>
+</tr></tbody>
+</table></div>

- Step 2. We note that the element <code class="computeroutput">(,)</code> wraps the non-alphanumeric symbol "<code class="computeroutput">,</code>" so it needs to be replaced. The parenthesized
- syntax requires no special delimiter to separate function parameters (see
- the <a class="link" href="Grammar.html" title="Appendix: Grammar">Grammar</a> section) so <code class="computeroutput">(,)</code> can simply be removed (if you like, you
- can use a space or a newline to separate the function parameters):
+ Note that not all compilers that support variadic macros also support empty
+ macro parameters.
 
-<pre class="programlisting">(int) (l)( (double&)(y) <code class="literal">/* use spaces or newlines instead of commas to separate parameters */</code> (const double&)(x)(=)(0.0) )
-</pre>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_local.Tutorial.Empty_Parameters"></a><a class="link" href="Tutorial.html#boost_local.Tutorial.Empty_Parameters" title="Empty Parameters">Empty Parameters</a>
+</h3></div></div></div>

- Step 3. We note also that the element <code class="computeroutput">(=)</code> wraps the non-alphanumeric symbol "<code class="computeroutput">=</code>" so it also needs to be replaced. The
- parenthesized syntax uses the keyword <code class="computeroutput">default</code>
- to specify a parameter default value (see the <a class="link" href="Grammar.html" title="Appendix: Grammar">Grammar</a>
- section) so <code class="computeroutput">(=)</code> is replaced
- by <code class="computeroutput">(default)</code>:
+ C++ allows to specify a function with no parameters using the empty parenthesis
+ <code class="computeroutput">()</code>. For example, let's program
+ a function <code class="computeroutput">ten</code> which takes
+ no parameter and returns the integer number <code class="computeroutput">10</code>:
 
-<pre class="programlisting">(int) (l)( (double&)(y) (const double&)(x)(default)(0.0) )
+<pre class="programlisting">int ten() {
+ return 10;
+}
</pre>

- We are done. The following is the valid parenthesized signature:
+ The ISO C++ standard does not allow pass empty parameters to a macro so the
+ macro <code class="computeroutput"><a class="link" href="../BOOST_LOCAL_FUNCTION_PARAMS.html" title="Macro BOOST_LOCAL_FUNCTION_PARAMS">BOOST_LOCAL_FUNCTION_PARAMS</a></code>
+ cannot be invoked with an empty set of parenthesis <code class="computeroutput">()</code>
+ unless programmers use compiler extensions that support empty macro parameters
+ (e.g., C99 and later compilers). However, C++ also allows to specify an empty
+ parameter list using the keyword <code class="computeroutput">void</code>:
 
-<pre class="programlisting">(int) (l)( (double&)(y) (const double&)(x)(default)(0.0) )
+<pre class="programlisting">int ten(void) {
+ return 10;
+}
</pre>

- for a function:
- 
-<div class="itemizedlist"><ul class="itemizedlist" type="disc">
-<li class="listitem">
- With <code class="computeroutput">int</code> result type.
- </li>
-<li class="listitem">
- Named <code class="computeroutput">l</code>.
- </li>
-<li class="listitem">
- With one required parameter of type <code class="computeroutput">double&</code> and named <code class="computeroutput">y</code>.
- </li>
-<li class="listitem">
- With an optional parameter of type <code class="computeroutput">const
- double&</code>,
- named <code class="computeroutput">x</code>, and with default
- value <code class="computeroutput">0.0</code>.
- </li>
-</ul></div>
-<div class="warning"><table border="0" summary="Warning">
-<tr>
-<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../doc/src/images/warning.png"></td>
-<th align="left">Warning</th>
-</tr>
-<tr><td align="left" valign="top">
- Unfortunately, there are intrinsic limitations to the amount of syntactic
- error checking that can be done by the parsing macros implemented using
- the preprocessor. As a consequence, an error in using the parenthesized
- syntax might result in cryptic preprocessor errors.
- The best way to identify and correct these errors is usually to visually
- inspect the signature comparing it with the parenthesized syntax grammar
- (see the <a class="link" href="Grammar.html" title="Appendix: Grammar">Grammar</a> section). When
- syntactic errors can be detected by the parsing macros, they are raised
- at compile-time using error messages of the form <code class="computeroutput">ERROR_</code>description_text.
- [<a name="id866513" href="#ftn.id866513" class="footnote">5</a>]
- </td></tr>
+ Therefore, on all C++ compilers the macro <code class="computeroutput"><a class="link" href="../BOOST_LOCAL_FUNCTION_PARAMS.html" title="Macro BOOST_LOCAL_FUNCTION_PARAMS">BOOST_LOCAL_FUNCTION_PARAMS</a></code>
+ can be invoked passing one parameter <code class="computeroutput">(void)</code> to specify
+ an empty parameter list. In addition, on compilers that support variadic
+ macros, the macro <code class="computeroutput"><a class="link" href="../BOOST_LOCAL_FUNCTION_PARAMS.html" title="Macro BOOST_LOCAL_FUNCTION_PARAMS">BOOST_LOCAL_FUNCTION_PARAMS</a></code>
+ can be invoked passing one parameter <code class="computeroutput">void</code>
+ (without the extra parenthesis). In summary, depending on your compiler support
+ for empty macro parameters and variadic macros, this library accepts any
+ of the following syntaxes to specify an empty parameter list:
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Empty Macro Syntax (C99 and later compilers)
+ 
+ </th>
+<th>
+ 
+ Variadic Macro Syntax (C99 and later compilers)
+ 
+ </th>
+<th>
+ 
+ Sequencing Macro Syntax (all C++ compilers)
+ 
+ </th>
+</tr></thead>
+<tbody><tr>
+<td>
+ 
+ <code class="computeroutput"><a class="link" href="../BOOST_LOCAL_FUNCTION_PARAMS.html" title="Macro BOOST_LOCAL_FUNCTION_PARAMS">BOOST_LOCAL_FUNCTION_PARAMS</a>()</code>
+ 
+ </td>
+<td>
+ 
+ <code class="computeroutput"><a class="link" href="../BOOST_LOCAL_FUNCTION_PARAMS.html" title="Macro BOOST_LOCAL_FUNCTION_PARAMS">BOOST_LOCAL_FUNCTION_PARAMS</a>(void)</code>
+ 
+ </td>
+<td>
+ 
+ <code class="computeroutput"><a class="link" href="../BOOST_LOCAL_FUNCTION_PARAMS.html" title="Macro BOOST_LOCAL_FUNCTION_PARAMS">BOOST_LOCAL_FUNCTION_PARAMS</a>( (void)
+ )</code>
+ 
+ </td>
+</tr></tbody>
</table></div>
-<a name="boost_local.Tutorial.parenthesized_syntax.functions_with_no_parameters"></a><h6>
-<a name="id866553"></a>
- <a class="link" href="Tutorial.html#boost_local.Tutorial.parenthesized_syntax.functions_with_no_parameters">Functions
- With No Parameters</a>
- </h6>

- Let's rewrite the following C++ signature for a function with no parameters
- using the parenthesized syntax:
+ For example, let's program the function <code class="computeroutput">ten</code>
+ as a local function:
 
-<pre class="programlisting">int l()
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Empty Macro Syntax (C99 and later compilers)
+ 
+ </th>
+<th>
+ 
+ Variadic Macro Syntax (C99 and later compilers)
+ 
+ </th>
+<th>
+ 
+ Sequencing Macro Syntax (all C++ compilers)
+ 
+ </th>
+</tr></thead>
+<tbody><tr>
+<td>
+ 
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">#include <boost/local/function.hpp>
+#include <iostream>
+
+int main() {
+ int BOOST_LOCAL_FUNCTION_PARAMS() {
+ return 10;
+ } BOOST_LOCAL_FUNCTION_NAME(ten)
+
+ std::cout << ten() << std::endl;
+ return 0;
+}
</pre>

- If we wrap all the elements within parenthesis we have:
- 
-<pre class="programlisting">(int) (l)() // Error: Empty parenthesis `()` cannot be used.
-</pre>
-
- However, this is not a valid parenthesized signature because it contains
- the empty parenthesis <code class="computeroutput">()</code>.
- 
-<div class="note"><table border="0" summary="Note">
-<tr>
-<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td>
-<th align="left">Note</th>
-</tr>
-<tr><td align="left" valign="top">
- This limitation applies to the ISO C++ standard preprocessor but it does
- not apply to the C99 and other more recent preprocessors. This library
- allows the use of empty parenthesis <code class="computeroutput">()</code> if the preprocessor used supports empty
- macro parameters. However, programmers should be well aware that if they
- use empty parenthesis in the parenthesized syntax, the code is not C++
- ISO standard compliant and it will be less portable (that is why the use
- of empty parenthesis is excluded by the <a class="link" href="Grammar.html" title="Appendix: Grammar">Grammar</a>
- section).
- </td></tr>
-</table></div>
-
- C++ also allows to use the keyword <code class="computeroutput">void</code>
- to specify empty parameter lists. Therefore, the original C++ function signature
- can be equivalently rewritten as:
- 
-<pre class="programlisting">int l(void)
+ 
+ </td>
+<td>
+ 
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">#include <boost/local/function.hpp>
+#include <iostream>
+
+int main() {
+ int BOOST_LOCAL_FUNCTION_PARAMS(void) {
+ return 10;
+ } BOOST_LOCAL_FUNCTION_NAME(ten)
+
+ std::cout << ten() << std::endl;
+ return 0;
+}
</pre>

- If we now wrap all the elements within parenthesis we obtain the valid parenthesized
- signature:
- 
-<pre class="programlisting">(int) (l)( (void) ) // OK: Use `(void)` for empty parameter lists.
-</pre>
+ 
+ </td>
+<td>
+ 
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">#include <boost/local/function.hpp>
+#include <iostream>
+
+int main() {
+ int BOOST_LOCAL_FUNCTION_PARAMS( (void) ) {
+ return 10;
+ } BOOST_LOCAL_FUNCTION_NAME(ten)
+
+ std::cout << ten() << std::endl;
+ return 0;
+}
+</pre>

- In conclusion, the parenthesized syntax requires to use <code class="computeroutput">(void)</code> to indicate
- an empty parameter list (see the <a class="link" href="Grammar.html" title="Appendix: Grammar">Grammar</a>
- section).
- 
+ 
+ </td>
+</tr></tbody>
+</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
-<a name="boost_local.Tutorial.local_functions"></a><a class="link" href="Tutorial.html#boost_local.Tutorial.local_functions" title="Local Functions">Local Functions</a>
+<a name="boost_local.Tutorial.default_parameters"></a><a class="link" href="Tutorial.html#boost_local.Tutorial.default_parameters" title="Default Parameters">Default Parameters</a>
</h3></div></div></div>

- Local functions are defined using the following macros (see the Reference
- section) from within a declarative context (this is a limitation with respect
- to <a href="http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions" target="_top">C++0x
- lambda</a> functions which can instead appear within expressions):
- 
-<pre class="programlisting">{ // Some declarative context.
- ...
+ This library also allows to specify default values for the local function
+ parameters. However, the usual C++ syntax for default parameters that uses
+ the assignment symbol <code class="computeroutput">=</code> cannot
+ be used. [<a name="id867944" href="#ftn.id867944" class="footnote">5</a>] The keyword <code class="computeroutput">default</code>
+ is used instead:
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Variadic Macro Syntax (C99 and later compilers)
+ 
+ </th>
+<th>
+ 
+ Sequencing Macro Syntax (all C++ compilers)
+ 
+ </th>
+</tr></thead>
+<tbody><tr>
+<td>
+ 
+ <code class="literal">parameter-type parameter-name</code><code class="computeroutput">, default</code>
+ <code class="literal">parameter-default-value</code><code class="computeroutput">,</code> <code class="literal">...</code>
+ 
+ </td>
+<td>
+ 
+ <code class="computeroutput">(</code><code class="literal">parameter-type
+ parameter-name</code><code class="computeroutput">)(default</code> <code class="literal">parameter-default-value</code><code class="computeroutput">)</code> <code class="literal">...</code>
+ 
+ </td>
+</tr></tbody>
+</table></div>
+
+ For example, let's assume that the we want to program a local function <code class="computeroutput">add(x, y)</code>
+ similar to the one programmed above but where the second parameter <code class="computeroutput">y</code> is optional and has a default value of
+ <code class="computeroutput">2</code>:
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Variadic Macro Syntax (C99 and later compilers)
+ 
+ </th>
+<th>
+ 
+ Sequencing Macro Syntax (all C++ compilers)
+ 
+ </th>
+</tr></thead>
+<tbody><tr>
+<td>
+ 
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">#include <boost/local/function.hpp>
+#include <iostream>

- <code class="computeroutput">BOOST_LOCAL_FUNCTION</code>(
- parenthesized-signature
- ) {
- local-function-body
- } <code class="computeroutput">BOOST_LOCAL_FUNCTION_END</code>(local-function-name)
+int main() {
+ int BOOST_LOCAL_FUNCTION_PARAMS(int x, int y, default 2) {
+ return x + y;
+ } BOOST_LOCAL_FUNCTION_NAME(add)

- ...
+ add(1);
+ return 0;
}
</pre>

- This creates a functor object with the local function name that can be called
- from the enclosing scope. Note that:
- 
-<div class="itemizedlist"><ul class="itemizedlist" type="disc">
-<li class="listitem">
- The usual C++ scope visibility rules apply to local functions for which
- a local function is visible and can be called only within the enclosing
- scope in which it is defined.
- </li>
-<li class="listitem">
- The local function signature is expressed using the parenthesized syntax
- and passed to the <code class="computeroutput">BOOST_LOCAL_FUNCTION</code>
- macro.
- </li>
-<li class="listitem">
- The local function body is defined in a code block <code class="computeroutput">{
- ... }</code>
- using the usual C++ syntax. The body is specified outside any of the
- macros so eventual compiler error messages and line numbers retain their
- usual meaning. [<a name="id867034" href="#ftn.id867034" class="footnote">6</a>]
- </li>
-<li class="listitem">
- The macro <code class="computeroutput">BOOST_LOCAL_FUNCTION_END</code>
- is used to end the local function definition and it must repeat the local
- function name. [<a name="id867063" href="#ftn.id867063" class="footnote">7</a>] The compiler will generate an error if the name specified
- by this macro does not match the one from the local function signature
- (see <code class="computeroutput">BOOST_LOCAL_FUNCTION_END_RENAME</code>
- to remove this constraint).
- </li>
-</ul></div>
-
- For example, let's program a local function <code class="computeroutput">add</code>
- similar to the one in the example from the <a class="link" href="../index.html#boost_local.Introduction" title="Introduction">Introduction</a>
- section. We start by rewriting its signature:
- 
-<pre class="programlisting">void add(double num)
-</pre>
-
- using the parenthesized syntax:
- 
-<pre class="programlisting">(void) (add)( (double)(num) )
+ 
+ </td>
+<td>
+ 
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">#include <boost/local/function.hpp>
+#include <iostream>
+
+int main() {
+ int BOOST_LOCAL_FUNCTION_PARAMS( (int x) (int y)(default 2) ) {
+ return x + y;
+ } BOOST_LOCAL_FUNCTION_NAME(add)
+
+ add(1);
+ return 0;
+}
</pre>

- For simplicity, we will not bind any of the variables in scope just yet (binding
- is explained later in this section).
- 
+ 
+ </td>
+</tr></tbody>
+</table></div>

- Then we pass the parenthesized signature to the <code class="computeroutput">BOOST_LOCAL_FUNCTION</code>
- macro, we implement a simple body that prints the number, and we pass the
- local function name <code class="computeroutput">add</code> to
- the <code class="computeroutput">BOOST_LOCAL_FUNCTION_END</code>
- macro:
+ If this variadic macro syntax seems strange, programmers could define a
+ <code class="computeroutput">WITH_DEFAULT</code> macro similar
+ to the following if they think it improves readability:
 


@@ -302,35 +474,30 @@
<pre class="programlisting">#include <boost/local/function.hpp>
#include <iostream>

+#define WITH_DEFAULT , default
+
int main() {
- void BOOST_LOCAL_FUNCTION_PARAMS( (double num) ) {
- std::clog << num << std::endl;
+ int BOOST_LOCAL_FUNCTION_PARAMS(int x, int y WITH_DEFAULT 2) {
+ return x + y;
 } BOOST_LOCAL_FUNCTION_NAME(add)

- add(100.0);
+ add(1);
 return 0;
}
</pre>

 
-
- This creates a local function <code class="computeroutput">add</code>
- that can be called from within the enclosing scope as for example by the
- <code class="computeroutput">add(100.0);</code> instruction.
- 
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
-<a name="boost_local.Tutorial.binding"></a><a class="link" href="Tutorial.html#boost_local.Tutorial.binding" title="Binding">Binding</a>
+<a name="boost_local.Tutorial.Binding"></a><a class="link" href="Tutorial.html#boost_local.Tutorial.Binding" title="Binding">Binding</a>
</h3></div></div></div>

 Variables in scope (local variables, enclosing function parameters, member
 variables, the object <code class="computeroutput">this</code>,
- etc) can be bound to a local function declaration. Variables in scope can
- be bound by reference, by constant reference, by value, or by constant value.
- The types of bound variables are automatically deduced by this library using
- Boost.Typeof.
- [<a name="id867627" href="#ftn.id867627" class="footnote">8</a>]
+ etc) can be bound to a local function declaration. The types of bound variables
+ are automatically deduced by this library using Boost.Typeof.
+ [<a name="id869130" href="#ftn.id869130" class="footnote">6</a>]
 
<div class="important"><table border="0" summary="Important">
<tr>
@@ -346,27 +513,29 @@
 </td></tr>
</table></div>

- The parenthesized syntax introduces the additional "keyword" <code class="computeroutput">bind</code> which is used to list all the bound
- variable names wrapped within parenthesis at the end of the local function
- parameter list (see the <a class="link" href="Grammar.html" title="Appendix: Grammar">Grammar</a>
- section):
+ This library introduces the new "keyword" <code class="computeroutput">bind</code>
+ [<a name="id869215" href="#ftn.id869215" class="footnote">7</a>] which is used in place of the parameter type to specify the name
+ of a variable in scope to bind. The variable can be bound by value:
 
-<pre class="programlisting">(result-type) (function-name)( parameters (bind)((var1)(var2)...(varN)) )
-</pre>
+<pre class="programlisting">bind variable-name // Bind by value.
+</pre>

- Where var is the name of the variable in scope to bind
- and it is prefixed by <code class="computeroutput">&</code>
- if the variable is bound by reference, otherwise is it bound by value.
+ Or by reference if the variable name is prefixed by <code class="computeroutput">&</code>:
 
+<pre class="programlisting">bind& variable-name // Bind by reference.
+</pre>

- For example, let's assume we want to bind two variables in scope <code class="computeroutput">a</code> and <code class="computeroutput">b</code>
- to the local function <code class="computeroutput">l</code> shown
- before. Let's also assume we want to bind <code class="computeroutput">a</code>
- by value and <code class="computeroutput">b</code> by reference.
- Then we use the following parenthesized signature for the local function:
+ Furthermore, the "keyword" <code class="computeroutput">bind</code>
+ can be prefixed by <code class="computeroutput">const</code> to
+ bind the variable by constant value:
 
-<pre class="programlisting">(int) (l)( (double&)(y) (const double&)(x)(default)(0.0) (bind)((a)(&b)) )
-</pre>
+<pre class="programlisting">const bind variable-name // Bind by constant value.
+</pre>
+
+ Or by constant reference:
+ 
+<pre class="programlisting">const bind& variable-name // Bind by constant value.
+</pre>

 If a variable is bound by value, then a copy of the variable value is taken
 at the point of the local function declaration. If a variable is bound by
@@ -375,50 +544,61 @@
 to ensure that variables bound by reference survive the scope of declaration
 of the local function otherwise the bound references will be invalid causing
 run-time errors (in other words, the usual care in using C++ references must
- be used for variables in scope bound by reference). It is also possible to
- bind a local function to another local function as shown in the STL Transform
- example from the <a class="link" href="Examples.html" title="Appendix: Examples">Examples</a> section
- (note that local functions cannot be copied so they are always bound by reference
- even if <code class="computeroutput">&</code> is not specified).
+ be used for variables bound by reference).
 

 The type of bound variables is automatically deduced and it is the exact
- same type used to declare such variables in the enclosing scope. Therefore:
- 
-<div class="itemizedlist"><ul class="itemizedlist" type="disc">
-<li class="listitem">
- If a bound variable was declared constant using the <code class="computeroutput">const</code>
- qualifier then it will be bound by constant value or reference.
- </li>
-<li class="listitem">
- If a bound variable was not declared constant then it will not be bound
- as constant. This library allows to force constant biding even for variables
- that are not originally declared constant using <code class="computeroutput">(const bind)(...)</code> as explained below.
- </li>
-<li class="listitem">
- You might want to bind variables of complex types by (constant) reference
- instead than by value to avoid expensive copy operations when these variables
- are automatically passed to the local function (as usual with C++ function
- parameter passing).
- </li>
-</ul></div>
-
- For example, let's continue to program a local function <code class="computeroutput">add</code>
- similar to the one from the example in <a class="link" href="../index.html#boost_local.Introduction" title="Introduction">Introduction</a>
- section. We bind the local variable <code class="computeroutput">sum</code>
- by (non-constant) reference and update the body to perform the summation:
+ same type used to declare such variables in the enclosing scope. Therefore,
+ if a bound variable was declared constant using the <code class="computeroutput">const</code>
+ qualifier then it will be bound by constant value or reference and if a bound
+ variable was not declared constant then it will not be bound as constant
+ unless constant binding is forced using <code class="computeroutput">const
+ bind ...</code>
+ (note that binding by constant reference is not supported by <a href="http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions" target="_top">C++0x
+ lambda</a> functions). [<a name="id869470" href="#ftn.id869470" class="footnote">8</a>] Programmers might want to bind variables of complex types by
+ (constant) reference instead than by value to avoid expensive copy operations
+ when these variables are automatically passed to the local function (as usual
+ with C++ function parameter passing).
 

-
+ For example, let's program a local function <code class="computeroutput">add</code>
+ similar to the one in the example from the <a class="link" href="../index.html#boost_local.Introduction" title="Introduction">Introduction</a>
+ section. We bind the local variable <code class="computeroutput">factor</code>
+ by constant value, the local variable <code class="computeroutput">sum</code>
+ by (non-constant) reference, and program the body to perform the summation:
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Variadic Macro Syntax (C99 and later compilers)
+ 
+ </th>
+<th>
+ 
+ Sequencing Macro Syntax (all C++ compilers)
+ 
+ </th>
+</tr></thead>
+<tbody><tr>
+<td>
+ 
+

-<pre class="programlisting">#include <boost/local/function.hpp>
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">#include <boost/local/function.hpp>
#include <iostream>

int main() {
 double sum = 0.0;
+ int factor = 10;

- void BOOST_LOCAL_FUNCTION_PARAMS( (double num) (bind& sum) ) {
- sum += num;
+ void BOOST_LOCAL_FUNCTION_PARAMS(double num, const bind factor,
+ bind& sum) {
+ sum += factor * num;
 std::clog << "Summed: " << sum << std::endl;
 } BOOST_LOCAL_FUNCTION_NAME(add)

@@ -427,68 +607,13 @@
}
</pre>

- 
-<a name="boost_local.Tutorial.binding.constant_binding"></a><h6>
-<a name="id868531"></a>
- <a class="link" href="Tutorial.html#boost_local.Tutorial.binding.constant_binding">Constant Binding</a>
- </h6>
-
- Constant binding allows to bind variables in scope by constant reference
- or constant value (constant binding is not supported by <a href="http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions" target="_top">C++0x
- lambda</a> functions). [<a name="id868556" href="#ftn.id868556" class="footnote">9</a>]
- 
-
- The parenthesized syntax uses the "keywords" <code class="computeroutput">const
- bind</code> to list constant bound variables
- wrapped within parenthesis at the end of the function parameter list (see
- the <a class="link" href="Grammar.html" title="Appendix: Grammar">Grammar</a> section):
- 
-<pre class="programlisting">(result-type) (function-name)( parameters (const bind)((cvar1)(cvar2)...(cvarM)) )
-</pre>
-
- Where cvar is the name of the variable in scope to bind
- by constant and it is prefixed by <code class="computeroutput">&</code>
- if the variable is bound by constant reference, otherwise it is bound by
- constant value. If both constant and plain bindings are used, constant bindings
- must be specified before plain bindings (see the <a class="link" href="Grammar.html" title="Appendix: Grammar">Grammar</a>
- section):
- 
-<pre class="programlisting">(result-type) (function-name)( parameters (const bind)((cvar1)(cvar2)...(cvarM)) (bind)((var1)(var2)...(varN)) ) /* `(const bind)(...)` before `(bind)(...)` */
-</pre>
-
- For example, let's assume we want to bind two variables in scope <code class="computeroutput">c</code> and <code class="computeroutput">d</code>
- to the local function <code class="computeroutput">l</code> shown
- before. Let's also assume we want to bind <code class="computeroutput">c</code>
- by constant value and <code class="computeroutput">b</code> by
- costant reference. Then we use the following parenthesized signature for
- the local function:
- 
-<pre class="programlisting">(int) (l)( (double&)(y) (const double&)(x)(default)(0.0) (const bind)((c)(&d)) )
-</pre>
-
- If the variables in scope <code class="computeroutput">a</code>
- and <code class="computeroutput">b</code> are also bound but
- by (plain) value and reference respectively then the parenthesized signature
- becomes:
- 
-<pre class="programlisting">(int) (l)( (double&)(y) (const double&)(x)(default)(0.0) (const bind)((c)(&d)) (bind)((a)(&b)) )
-</pre>
-
- Note how <code class="computeroutput">(const
- bind)(...)</code>
- must always be used before <code class="computeroutput">(bind)(...)</code>
- when they are both present.
- 
-
- For example, let's continue to program a local function <code class="computeroutput">add</code>
- similar to the one in the example from the <a class="link" href="../index.html#boost_local.Introduction" title="Introduction">Introduction</a>
- section. We bind the local variable <code class="computeroutput">factor</code>
- by constant value and update the body to perform the factor scaling:
- 
-
-
+ 
+ </td>
+<td>
+ 
+

-<pre class="programlisting">#include <boost/local/function.hpp>
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">#include <boost/local/function.hpp>
#include <iostream>

int main() {
@@ -506,62 +631,74 @@
}
</pre>

- 
-<a name="boost_local.Tutorial.binding.binding_the_object__code__phrase_role__keyword__this__phrase___code_"></a><h6>
-<a name="id869824"></a>
- <a class="link" href="Tutorial.html#boost_local.Tutorial.binding.binding_the_object__code__phrase_role__keyword__this__phrase___code_">Binding
+ 
+ </td>
+</tr></tbody>
+</table></div>
+<a name="boost_local.Tutorial.Binding.binding_the_object__code__phrase_role__keyword__this__phrase___code_"></a><h6>
+<a name="id870457"></a>
+ <a class="link" href="Tutorial.html#boost_local.Tutorial.Binding.binding_the_object__code__phrase_role__keyword__this__phrase___code_">Binding
 the Object <code class="computeroutput">this</code></a>
 </h6>

 It is also possible to bind the object <code class="computeroutput">this</code>
- when it is in scope (from enclosing member functions, etc). This is done
+ when it is in scope (e.g., from an enclosing member function). This is done
 by using <code class="computeroutput">this</code> as the name of
 the variable to bind and by using the special symbol <code class="computeroutput">this_</code>
 (instead of <code class="computeroutput">this</code>) to access
- the object within the local function body. Note that:
+ the object within the local function body.
 
-<div class="itemizedlist"><ul class="itemizedlist" type="disc">
-<li class="listitem">
- The object <code class="computeroutput">this</code> can be bound
- by value using <code class="computeroutput">(bind)((this)...)</code>. In this case the local function
- will be able to modify the object when the enclosing scope is a non-constant
- member, or it will not be able to modify the object when the enclosing
- scope is a constant member.
- </li>
-<li class="listitem">
- The object <code class="computeroutput">this</code> can be bound
- by constant value <code class="computeroutput">(const
- bind)((this)...)</code>.
- In this case the local function will never be able to modify the object
- (regardless of whether the enclosing scope is a constant member or not).
- </li>
-<li class="listitem">
- Finally, the object <code class="computeroutput">this</code>
- can never be bound by reference because C++ does not allow to get a reference
- to <code class="computeroutput">this</code>. You will get a
- compile-time error if you try to use <code class="computeroutput">(bind)((&this)...)</code>
- or <code class="computeroutput">(const
- bind)((&this)...)</code>.
- However, <code class="computeroutput">this</code> is a pointer
- so the object is not copied even if it is bound by value. (Note that
- it is not possible to bind <code class="computeroutput">*this</code> because it starts with <code class="computeroutput">*</code> and it is not a variable name.)
- </li>
-</ul></div>
-<div class="important"><table border="0" summary="Important">
+
+ The object <code class="computeroutput">this</code> can be bound
+ by value:
+ 
+<pre class="programlisting">bind this // Bind the object `this` by value.
+</pre>
+
+ In this case the local function will be able to modify the object when the
+ enclosing scope is not a constant member, or it will not be able to modify
+ the object when the enclosing scope is a constant member. Otherwise, the
+ object <code class="computeroutput">this</code> can be bound by
+ constant value:
+ 
+<pre class="programlisting">const bind this // Bind the object `this` by constant value.
+</pre>
+
+ In this case the local function will never be able to modify the object (regardless
+ of whether the enclosing scope is a constant member or not).
+ 
+
+ Note that the object <code class="computeroutput">this</code> can
+ never be bound by reference because C++ does not allow to obtain a reference
+ to <code class="computeroutput">this</code> (the library will generate
+ a compile-time error if programmers try to use <code class="computeroutput">bind& this</code>
+ or <code class="computeroutput">const bind& this</code>).
+ Note that <code class="computeroutput">this</code> is a pointer
+ so the object is not copied even if it is bound by value (it is not possible
+ to bind <code class="computeroutput">*this</code>
+ because <code class="computeroutput">*this</code>
+ is an expression and not a valid name of a variable in scope).
+ 
+<div class="warning"><table border="0" summary="Warning">
<tr>
-<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../doc/src/images/important.png"></td>
-<th align="left">Important</th>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../doc/src/images/warning.png"></td>
+<th align="left">Warning</th>
</tr>
-<tr><td align="left" valign="top">
+<tr><td align="left" valign="top">
+
 When the object <code class="computeroutput">this</code> is bound
 to a local function, the local function body must
 use the special symbol <code class="computeroutput">this_</code>
 (instead of <code class="computeroutput">this</code>) to access
- the bound object. [<a name="id870178" href="#ftn.id870178" class="footnote">10</a>] Using <code class="computeroutput">this</code> within
- the local function body will generate a compile-time error so programmers
- cannot mistakenly confuse the use of <code class="computeroutput">this_</code>
- with <code class="computeroutput">this</code>. [<a name="id870281" href="#ftn.id870281" class="footnote">11</a>]
- </td></tr>
+ the bound object. [<a name="id870776" href="#ftn.id870776" class="footnote">9</a>]
+ 
+
+ Unfortunately, mistakenly using <code class="computeroutput">this</code>
+ within the local function body instead of <code class="computeroutput">this_</code>
+ will not necessarily generate a compile-time error. [<a name="id870870" href="#ftn.id870870" class="footnote">10</a>] Programmers are responsible to make sure that <code class="computeroutput">this</code> is never used within a local function
+ body which should only use the special symbol <code class="computeroutput">this_</code>.
+ 
+</td></tr>
</table></div>

 For example, let's rewrite a local function <code class="computeroutput">add</code>
@@ -569,10 +706,72 @@
 section but using a member function to illustrate how to bind the object
 <code class="computeroutput">this</code>:
 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Variadic Macro Syntax (C99 and later compilers)
+ 
+ </th>
+<th>
+ 
+ Sequencing Macro Syntax (all C++ compilers)
+ 
+ </th>
+</tr></thead>
+<tbody><tr>
+<td>
+ 
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">#include <boost/local/function.hpp>
+#include <vector>
+#include <algorithm>
+#include <iostream>
+#include <cassert>
+
+class adder {
+public:
+ adder(): sum_(0.0) {}
+
+ double sum(const std::vector<double>& nums, const int& factor = 10) {
+ void BOOST_LOCAL_FUNCTION_PARAMS(double num, const bind factor,
+ bind this) {
+ this_->sum_ += factor * num; // Use `this_` instead of `this`.
+ std::clog << "Summed: " << this_->sum_ << std::endl;
+ } BOOST_LOCAL_FUNCTION_NAME(add)
+
+ std::for_each(nums.begin(), nums.end(), add);
+ return sum_;
+ }
+
+private:
+ double sum_;
+};
+
+int main() {
+ std::vector<double> v(3);
+ v[0] = 100.0; v[1] = 90.5; v[2] = 7.0;
+
+ adder a;
+ // sum = 10 * 100.0 + 10 * 90.5 + 10 * 7.0 = 1975.0
+ assert(a.sum(v) == 1975.0);
+
+ return 0;
+}
+</pre>

-
+ 
+ </td>
+<td>
+ 
+

-<pre class="programlisting">#include <boost/local/function.hpp>
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">#include <boost/local/function.hpp>
#include <vector>
#include <algorithm>
#include <iostream>
@@ -609,7 +808,10 @@
}
</pre>

- 
+ 
+ </td>
+</tr></tbody>
+</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
@@ -622,45 +824,27 @@
<pre class="programlisting">{ // Some declarative context.
 ...

- <code class="computeroutput"><a class="link" href="../BOOST_LOCAL_BLOCK.html" title="Macro BOOST_LOCAL_BLOCK">BOOST_LOCAL_BLOCK</a></code>( parenthesized-binding ) {
- block-body
+ <code class="computeroutput"><a class="link" href="../BOOST_LOCAL_BLOCK.html" title="Macro BOOST_LOCAL_BLOCK">BOOST_LOCAL_BLOCK</a></code>(bindings) {
+ body-code
 } <code class="computeroutput"><a class="link" href="../BOOST_LOCAL_BLOCK_END.html" title="Macro BOOST_LOCAL_BLOCK_END">BOOST_LOCAL_BLOCK_END</a></code>

 ...
}
</pre>

- This expands to code that executes the body instructions in place where the
- block is defined. However, only bound variables specified by the parenthesized-binding
- are accessible from within the local block body.
- 
-
- Adopting a parenthesized syntax similar to the one used for local functions
- (see the <a class="link" href="Grammar.html" title="Appendix: Grammar">Grammar</a> section), the
- parenthesized-binding can specify to bind no variable:
- 
-<pre class="programlisting">(void)
-</pre>
-
- Or, to bind variables by constant type only:
- 
-<pre class="programlisting">(const bind)((cvar1)(cvar2)...(cvarM))
-</pre>
-
- Or, to bind variables by plain type only:
+ These macros expand to code that executes the body instructions "in
+ place" where the block is defined.
 
-<pre class="programlisting">(bind)((var1)(var2)...(varN))
-</pre>
-
- Or, to bind variables by both constant and plain types:
- 
-<pre class="programlisting">(const bind)((cvar1)(cvar2)...(cvarM)) (bind)((var1)(var2)...(varN))
-</pre>

- Where cvar and var are the names
- of the variables in scope to bind. They can be prefixed by <code class="computeroutput">&</code> to bind by reference instead of by value,
- and one of them can be <code class="computeroutput">this</code>
- to bind the object when it is in scope.
+ Only bound variables specified bu <code class="literal">bindings</code>
+ are accessible from within the local block body. Following the same syntax
+ used for local functions, <code class="literal">bindings</code>
+ can either be empty (using <code class="computeroutput">(void)</code>, <code class="computeroutput">void</code>, or an empty macro parameter depending
+ on your compiler extensions, see <a class="link" href="Tutorial.html#boost_local.Tutorial.Empty_Parameters" title="Empty Parameters">Empty
+ Parameters</a>), or they can list the variables to bind using the "keyword"
+ <code class="computeroutput">bind</code> in place of the parameter
+ type, using <code class="computeroutput">const bind</code>
+ for constant binding, prefixing the bound variable name with <code class="computeroutput">&</code> to bind by reference, and using <code class="computeroutput">this</code> to bind the object in scope (see <a class="link" href="Tutorial.html#boost_local.Tutorial.Binding" title="Binding">Binding</a>).
 
<div class="important"><table border="0" summary="Important">
<tr>
@@ -670,18 +854,62 @@
<tr><td align="left" valign="top">
 A <code class="computeroutput">return;</code>
 instruction from within a local block jumps to the end of the local block
- body and it does not return the enclosing scope.
- [<a name="id871733" href="#ftn.id871733" class="footnote">12</a>]
+ body and it does not return the enclosing function.
+ [<a name="id873248" href="#ftn.id873248" class="footnote">11</a>]
 </td></tr>
</table></div>

 For example, let's program a local block similar to the one in the example
 from the <a class="link" href="../index.html#boost_local.Introduction" title="Introduction">Introduction</a> section:
 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Variadic Macro Syntax (C99 and later compilers)
+ 
+ </th>
+<th>
+ 
+ Sequencing Macro Syntax (all C++ compilers)
+ 
+ </th>
+</tr></thead>
+<tbody><tr>
+<td>
+ 
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">#include <boost/local/block.hpp>
+#include <iostream>
+#include <cassert>
+
+int main() {
+ double sum = 1975.0;
+
+ BOOST_LOCAL_BLOCK(const bind& sum) {
+ assert(sum == 1975.0); // OK: Complier error if `==` confused with `=`.
+ std::clog << "Asserted summation: " << sum << std::endl;
+
+ return; // Return this local block (and not the enclosing scope).
+ assert(false); // OK: Never executed.
+ } BOOST_LOCAL_BLOCK_END
+
+ return 0;
+}
+</pre>

-
+ 
+ </td>
+<td>
+ 
+

-<pre class="programlisting">#include <boost/local/block.hpp>
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">#include <boost/local/block.hpp>
#include <iostream>
#include <cassert>

@@ -700,7 +928,10 @@
}
</pre>

- 
+ 
+ </td>
+</tr></tbody>
+</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
@@ -713,7 +944,7 @@
<pre class="programlisting">{ // Some declarative context.
 ...

- <code class="computeroutput"><a class="link" href="../BOOST_LOCAL_EXIT.html" title="Macro BOOST_LOCAL_EXIT">BOOST_LOCAL_EXIT</a></code>( parenthesized-binding ) {
+ <code class="computeroutput"><a class="link" href="../BOOST_LOCAL_EXIT.html" title="Macro BOOST_LOCAL_EXIT">BOOST_LOCAL_EXIT</a></code>(bindings) {
 exit-body
 } <code class="computeroutput"><a class="link" href="../BOOST_LOCAL_EXIT_END.html" title="Macro BOOST_LOCAL_EXIT_END">BOOST_LOCAL_EXIT_END</a></code>

@@ -721,34 +952,88 @@
}
</pre>

- This expands to code that executes the body instructions when the enclosing
- scope is exited (i.e., at the very end of the enclosing scope). If multiple
- local exits are defined within the same scope, their bodies will be executed
- in the reverse order in which they have been defined. Only bound variables
- specified by parenthesized-binding are accessible from
- within the local exit body. The parenthesized-biding
- is specified following the exact same syntax as for the one used by local
- blocks.
+ These macros expand to code that executes the body instructions when the
+ enclosing scope is exited (i.e., at the very end of the enclosing scope).
+ If multiple local exits are declared within the same scope, their bodies
+ will be executed in the reverse order in which they have been declared. The
+ execution of the local exit code can be guaranteed only if the program does
+ not terminate because of an uncaught exception. [<a name="id874394" href="#ftn.id874394" class="footnote">12</a>]
+ 
+
+ Only bound variables specified by <code class="literal">bindings</code>
+ are accessible from within the local exit body. Following the same syntax
+ used for local functions, <code class="literal">bindings</code>
+ can either be empty (using <code class="computeroutput">(void)</code>, <code class="computeroutput">void</code>, or an empty macro parameter depending
+ on your compiler extensions, see <a class="link" href="Tutorial.html#boost_local.Tutorial.Empty_Parameters" title="Empty Parameters">Empty
+ Parameters</a>), or they can list the variables to bind using the "keyword"
+ <code class="computeroutput">bind</code> in place of the parameter
+ type, using <code class="computeroutput">const bind</code>
+ for constant binding, prefixing the bound variable name with <code class="computeroutput">&</code> to bind by reference, and using <code class="computeroutput">this</code> to bind the object in scope (see <a class="link" href="Tutorial.html#boost_local.Tutorial.Binding" title="Binding">Binding</a>).
 
-<div class="note"><table border="0" summary="Note">
+<div class="important"><table border="0" summary="Important">
<tr>
-<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td>
-<th align="left">Note</th>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../doc/src/images/important.png"></td>
+<th align="left">Important</th>
</tr>
<tr><td align="left" valign="top">
 A <code class="computeroutput">return;</code>
 instruction from within a local exit jumps to the end of the local exit
- body and it does not return the enclosing scope.
+ body and it does not return the enclosing function.
 </td></tr>
</table></div>

 For example, let's program a local exit similar to the one in the example
 from the <a class="link" href="../index.html#boost_local.Introduction" title="Introduction">Introduction</a> section:
 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Variadic Macro Syntax (C99 and later compilers)
+ 
+ </th>
+<th>
+ 
+ Sequencing Macro Syntax (all C++ compilers)
+ 
+ </th>
+</tr></thead>
+<tbody><tr>
+<td>
+ 
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">#include <boost/local/exit.hpp>
+#include <iostream>
+#include <cassert>
+
+int main() {
+ size_t size = 2;
+ double* nums = new double[size];
+
+ BOOST_LOCAL_EXIT(const bind& size, bind nums) {
+ if (size && nums) delete[] nums;
+ std::clog << "Freed array: " << nums << std::endl;
+
+ return; // Return this local exit (and not the enclosing scope).
+ assert(false); // OK: Never executed.
+ } BOOST_LOCAL_EXIT_END
+
+ return 0;
+}
+</pre>

-
+ 
+ </td>
+<td>
+ 
+

-<pre class="programlisting">#include <boost/local/exit.hpp>
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">#include <boost/local/exit.hpp>
#include <iostream>
#include <cassert>

@@ -768,11 +1053,99 @@
}
</pre>

+ 
+ </td>
+</tr></tbody>
+</table></div>
+
+ Local exits are very similar to the scope exits provided
+ by Boost.ScopeExit
+ with the addition that they also support constant binding and binding of
+ the object <code class="computeroutput">this</code>. [<a name="id875646" href="#ftn.id875646" class="footnote">13</a>]
+ 
+<a name="boost_local.Tutorial.local_exits.d_s_scope_guards"></a><h6>
+<a name="id875873"></a>
+ <a class="link" href="Tutorial.html#boost_local.Tutorial.local_exits.d_s_scope_guards">D's Scope
+ Guards</a>
+ </h6>
+
+ Local exits are very similar to the <a href="http://www.digitalmars.com/d/2.0/statement.html" target="_top">scope
+ exit</a> statements provided by the D programming language. Local exits
+ can be used also to emulate D's <a href="http://www.digitalmars.com/d/2.0/statement.html" target="_top">scope
+ success</a> and <a href="http://www.digitalmars.com/d/2.0/statement.html" target="_top">scope
+ failure</a> statements using a local variable that is set when an error
+ occurs. For example, using error codes:
+ 
+
+
+
+<pre class="programlisting">#include <boost/local/exit.hpp>
+#include <iostream>
+
+int f() {
+ int error = 0; // No error to start with.
+
+ BOOST_LOCAL_EXIT( (void) ) { // Same as D's `scope(exit)`.
+ std::cout << "exit" << std::endl;
+ } BOOST_LOCAL_EXIT_END
+
+ BOOST_LOCAL_EXIT( (const bind& error) ) { // Sane as D's `scope(success)`.
+ if (!error) std::cout << "success" << std::endl;
+ } BOOST_LOCAL_EXIT_END
+
+ BOOST_LOCAL_EXIT( (const bind& error) ) { // Same as D's `scope(failure)`.
+ if (error) std::cout << "failure" << std::endl;
+ } BOOST_LOCAL_EXIT_END
+
+ return error = -1; // Must set error.
+}
+
+int main() {
+ return f();
+}
+</pre>
+
 

- Local exits are very similar to the functionality already provided by Boost.ScopeExit
- with the addition that they also support constant binding and the binding
- of the object <code class="computeroutput">this</code>. [<a name="id873021" href="#ftn.id873021" class="footnote">13</a>]
+ Or similarly but using exceptions:
+ 
+
+
+
+<pre class="programlisting">#include <boost/local/exit.hpp>
+#include <iostream>
+#include <stdexcept>
+
+void f() {
+ bool error = false; // No error to start with.
+
+ BOOST_LOCAL_EXIT( (void) ) { // Same as D's `scope(exit)`.
+ std::cout << "exit" << std::endl;
+ } BOOST_LOCAL_EXIT_END
+
+ BOOST_LOCAL_EXIT( (const bind& error) ) { // Same as D's `scope(success)`.
+ if (!error) std::cout << "success" << std::endl;
+ } BOOST_LOCAL_EXIT_END
+
+ BOOST_LOCAL_EXIT( (const bind& error) ) { // Same as D's `scope(failure)`.
+ if (error) std::cout << "failure" << std::endl;
+ } BOOST_LOCAL_EXIT_END
+
+ error = true; throw std::runtime_error("some error"); // Must set error.
+}
+
+int main() {
+ // Program cannot terminate with uncaught exception (otherwise local exit
+ // code is not guaranteed to be executed).
+ try {
+ f();
+ return 0;
+ } catch(...) {
+ return -1;
+ }
+}
+</pre>
+
 
</div>
<div class="section">
@@ -783,25 +1156,92 @@
 When local functions, local blocks, and local exits are programmed within
 templates, they need to be declared using the following special macros ending
 with the <code class="computeroutput">TPL</code> postfix (see
- the Reference section): [<a name="id873362" href="#ftn.id873362" class="footnote">14</a>]
+ the Reference section): [<a name="id877428" href="#ftn.id877428" class="footnote">14</a>]
 
-<pre class="programlisting"><code class="computeroutput">BOOST_LOCAL_FUNCTION_TPL</code>( parenthesized-signature )
-<code class="computeroutput"><a class="link" href="../BOOST_LOCAL_BLOCK_TPL.html" title="Macro BOOST_LOCAL_BLOCK_TPL">BOOST_LOCAL_BLOCK_TPL</a></code>( parenthesized-binding )
-<code class="computeroutput"><a class="link" href="../BOOST_LOCAL_EXIT_TPL.html" title="Macro BOOST_LOCAL_EXIT_TPL">BOOST_LOCAL_EXIT_TPL</a></code>( parenthesized-binding )
+<pre class="programlisting"><code class="computeroutput"><a class="link" href="../BOOST_LOCAL_FUNCTION_PARAMS_TPL.html" title="Macro BOOST_LOCAL_FUNCTION_PARAMS_TPL">BOOST_LOCAL_FUNCTION_PARAMS_TPL</a></code>(parameters)
+<code class="computeroutput"><a class="link" href="../BOOST_LOCAL_BLOCK_TPL.html" title="Macro BOOST_LOCAL_BLOCK_TPL">BOOST_LOCAL_BLOCK_TPL</a></code>(bindings)
+<code class="computeroutput"><a class="link" href="../BOOST_LOCAL_EXIT_TPL.html" title="Macro BOOST_LOCAL_EXIT_TPL">BOOST_LOCAL_EXIT_TPL</a></code>(bindings)
</pre>

- These macros have the exact same API as their equivalents without the <code class="computeroutput">TPL</code> postfix that we have seen so far. The
- local function, local block, and local exit ending macros (with the <code class="computeroutput">END</code> postfix) can be used unchanged within
- templates.
+ These macros have the exact same API as their equivalent macros without the
+ <code class="computeroutput">TPL</code> postfix that we have
+ seen so far.
 

- For example, let's rewrite an example similar to the one from the <a class="link" href="../index.html#boost_local.Introduction" title="Introduction">Introduction</a>
+ For example, let's rewrite a local function, a local exit, and a local block
+ similar to the ones from the <a class="link" href="../index.html#boost_local.Introduction" title="Introduction">Introduction</a>
 section but wrapped within a template:
 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Variadic Macro Syntax (C99 and later compilers)
+ 
+ </th>
+<th>
+ 
+ Sequencing Macro Syntax (all C++ compilers)
+ 
+ </th>
+</tr></thead>
+<tbody><tr>
+<td>
+ 
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">#include <boost/local/function.hpp>
+#include <boost/local/block.hpp>
+#include <boost/local/exit.hpp>
+#include <algorithm>
+#include <cassert>
+
+template<typename T>
+T total(const T& x, const T& y, const T& z) {
+ T sum = T();
+ int factor = 10;
+
+ // Use `..._TPL()` macros within templates.
+ void BOOST_LOCAL_FUNCTION_PARAMS_TPL(T num, const bind factor,
+ bind& sum) {
+ sum += factor * num;
+ } BOOST_LOCAL_FUNCTION_NAME(add)
+ add(x);
+
+ size_t size = 2;
+ T* nums = new T[size];
+ BOOST_LOCAL_EXIT_TPL(const bind& size, bind nums) {
+ if (size && nums) delete[] nums;
+ } BOOST_LOCAL_EXIT_END
+
+ nums[0] = y; nums[1] = z;
+ std::for_each(nums, nums + size, add);
+
+ BOOST_LOCAL_BLOCK_TPL(const bind &sum, const bind& factor,
+ const bind& x, const bind& y, const bind& z) {
+ assert(sum == factor * (x + y + z));
+ } BOOST_LOCAL_BLOCK_END
+
+ return sum;
+}
+
+int main() {
+ total(100.0, 90.5, 7.0);
+ return 0;
+}
+</pre>

-
+ 
+ </td>
+<td>
+ 
+

-<pre class="programlisting">#include <boost/local/function.hpp>
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">#include <boost/local/function.hpp>
#include <boost/local/block.hpp>
#include <boost/local/exit.hpp>
#include <algorithm>
@@ -819,20 +1259,20 @@
 } BOOST_LOCAL_FUNCTION_NAME(add)
 add(x);

-// size_t size = 2;
-// T* nums = new T[size];
-// BOOST_LOCAL_EXIT_TPL( (const bind& size) (bind nums) ) {
-// if (size && nums) delete[] nums;
-// } BOOST_LOCAL_EXIT_END
-
-// nums[0] = y; nums[1] = z;
-// std::for_each(nums, nums + size, add);
-
-// BOOST_LOCAL_BLOCK_TPL( (const bind &sum) (const bind& factor)
-// (const bind& x) (const bind& y) (const bind& z) ) {
-// assert(sum == factor * (x + y + z));
-// } BOOST_LOCAL_BLOCK_END
-
+ size_t size = 2;
+ T* nums = new T[size];
+ BOOST_LOCAL_EXIT_TPL( (const bind& size) (bind nums) ) {
+ if (size && nums) delete[] nums;
+ } BOOST_LOCAL_EXIT_END
+
+ nums[0] = y; nums[1] = z;
+ std::for_each(nums, nums + size, add);
+
+ BOOST_LOCAL_BLOCK_TPL( (const bind &sum) (const bind& factor)
+ (const bind& x) (const bind& y) (const bind& z) ) {
+ assert(sum == factor * (x + y + z));
+ } BOOST_LOCAL_BLOCK_END
+
 return sum;
}

@@ -842,62 +1282,37 @@
}
</pre>

- 
+ 
+ </td>
+</tr></tbody>
+</table></div>
</div>
<div class="footnotes">
 <hr width="100" align="left">
-<div class="footnote">[<a id="ftn.id865404" href="#id865404" class="para">2</a>] 
- The parenthesized syntax owes its name to the indeed large number of
- parenthesis <code class="computeroutput">()</code> that are
- required to wrap its elements. Programmers might notice some similarities
- between the parenthesized syntax and the syntax of the LISP
- programming language. However, these similarities are not intentional
- in that they were not a design choice but rather a consequence of the
- fact that both LISP
- sequences and Boost.Preprocessor
- sequences are formed by wrapping tokens within round parenthesis <code class="computeroutput">()</code>.
- </div>
-<div class="footnote">[<a id="ftn.id865531" href="#id865531" class="para">3</a>] 
- Rationale. This constraint comes form
- the fact that the C++ preprocessor can only concatenate <code class="literal">##</code>
- alphanumeric symbols.
- </div>
-<div class="footnote">[<a id="ftn.id865568" href="#id865568" class="para">4</a>] 
- Rationale. This constraint comes from
- the fact that the ISO C++ standard preprocessor forbids empty macro parameters
- (this is different for C99 and other more recent preprocessors).
- </div>
-<div class="footnote">[<a id="ftn.id866513" href="#id866513" class="para">5</a>] 
- While there are fundamental limitations to the amount of parenthesized
- syntax error checking that can be done using the preprocessor (e.g.,
- there is no way to gracefully detect and report a missing parenthesis
- "<code class="computeroutput">)</code>"), the current
- implementation of the parsing macros does not perform all the error checking
- that could be done. Improving the parenthesized syntax error checking
- is a work in progress. Programmers are encouraged to report cryptic error
- messages they experience because of parenthesized syntax errors so to
- help this development effort.
- </div>
-<div class="footnote">[<a id="ftn.id867034" href="#id867034" class="para">6</a>] 
- Rationale. If the local function body
- were instead passed as a macro parameter, it would be expanded on a
- single line of code (because macros always expand as a single line
- of code). Therefore, eventual compiler error line numbers would all
- have the same value and would no longer be useful to pinpoint the error.
- </div>
-<div class="footnote">[<a id="ftn.id867063" href="#id867063" class="para">7</a>] 
- Rationale. The local function name
- must be passed to the ending macro <code class="computeroutput">BOOST_LOCAL_FUNCTION_END</code>
- so this macro can declare a local variable with the local function
- name to hold the local functor object. At the same time, the local
- function name must also be passed to the declaration macro <code class="computeroutput">BOOST_LOCAL_FUNCTION</code>
- to allow the local function to recursively call itself. The local function
- declaration and ending macros are kept as two separate macros so that
- the local function body does not have to be passed as a macro parameter
- (otherwise, the compiler error line numbers will all appear on the
- same line and they will no longer be useful to pinpoint the errors).
- </div>
-<div class="footnote">[<a id="ftn.id867627" href="#id867627" class="para">8</a>] 
+<div class="footnote">[<a id="ftn.id865988" href="#id865988" class="para">3</a>] 
+ Rationale. If the local function body
+ were instead passed as a macro parameter, it would be expanded on a single
+ line of code (because macros always expand as a single line of code). Therefore,
+ eventual compiler error line numbers would all have the same value and
+ would no longer be useful to pinpoint the error.
+ </div>
+<div class="footnote">[<a id="ftn.id866018" href="#id866018" class="para">4</a>] 
+ Rationale. The local function name must
+ be passed to the macro <code class="computeroutput"><a class="link" href="../BOOST_LOCAL_FUNCTION_NAME.html" title="Macro BOOST_LOCAL_FUNCTION_NAME">BOOST_LOCAL_FUNCTION_NAME</a></code>
+ ending the function definition so this macro can declare a local variable
+ with the local function name to hold the local functor object.
+ </div>
+<div class="footnote">[<a id="ftn.id867944" href="#id867944" class="para">5</a>] 
+ Rationale. The assignment symbol <code class="computeroutput">=</code> cannot be used to specify default parameter
+ values because default values are not part of the parameter type so they
+ cannot be handled using template metaprogamming. Default parameter values
+ need to be separated from the rest of the parameter declaration using the
+ preprocessor. Specifically, this library needs to use preprocessor mataprogramming
+ to remove default values when constructing the local function type and
+ it counts the number of default values to provide the correct set of call
+ operators for the local functor object.
+ </div>
+<div class="footnote">[<a id="ftn.id869130" href="#id869130" class="para">6</a>] 
 Rationale. By binding a variable in scope,
 the local function declaration is specifying that such a variable should
 be accessible within the local function body regardless of its type. Semantically,
@@ -910,7 +1325,16 @@
 This is especially useful for maintenance so if a bound variable type is
 changed, the local function declaration does not have to change.
 </div>
-<div class="footnote">[<a id="ftn.id868556" href="#id868556" class="para">9</a>] 
+<div class="footnote">[<a id="ftn.id869215" href="#id869215" class="para">7</a>] 
+ The token <code class="computeroutput">bind</code> is not a
+ real keyword of the C++ language. This library parses <code class="computeroutput">bind</code>
+ during macro expansion using preprocessor metaprogramming. Therefore,
+ <code class="computeroutput">bind</code> can be considered
+ a new "keyword" only at the preprocessor metaprogramming level
+ within the syntax defined by the macros of this library -- thus it is referred
+ to as a "keyword" only within quotes.
+ </div>
+<div class="footnote">[<a id="ftn.id869470" href="#id869470" class="para">8</a>] 
 An historical note: Constant binding of variables in scope was the main
 use case that originally motivated the authors in developing this library.
 The authors needed to locally create a chuck of code to assert some correctness
@@ -925,7 +1349,7 @@
 generates an error because the bound variable is of <code class="computeroutput">const</code>
 type within the local function body.
 </div>
-<div class="footnote">[<a id="ftn.id870178" href="#id870178" class="para">10</a>] 
+<div class="footnote">[<a id="ftn.id870776" href="#id870776" class="para">9</a>] 
 Rationale. This limitation comes from
 the fact that <code class="computeroutput">this</code> is a
 reserved C++ keyword so it cannot be used as the name of the internal
@@ -939,29 +1363,47 @@
 behaviour of <code class="computeroutput">static_cast</code></a>
 (which might not work on all platforms at the cost of portability).
 </div>
-<div class="footnote">[<a id="ftn.id870281" href="#id870281" class="para">11</a>] 
- Rationale. This is because the body
- function is implemented as static function of the local functor class.
+<div class="footnote">[<a id="ftn.id870870" href="#id870870" class="para">10</a>] 
+ Rationale. The local function body cannot
+ be a static member function of the local functor object in order to support
+ recursion (because the local function name is specified by the <code class="computeroutput"><a class="link" href="../BOOST_LOCAL_FUNCTION_NAME.html" title="Macro BOOST_LOCAL_FUNCTION_NAME">BOOST_LOCAL_FUNCTION_NAME</a></code>
+ macro only after the body so it must be make available via a functor
+ member variable named after the local function and local classes cannot
+ have static member variables in C++) and nesting (because the argument
+ binding variable must be declared as a member function so it is visible
+ in a local function nested within another local function body). Therefore,
+ from within the local function body the variable <code class="computeroutput">this</code>
+ is visible but it refers to the local functor object and not to the bound
+ object.
 </div>
-<div class="footnote">[<a id="ftn.id871733" href="#id871733" class="para">12</a>] 
+<div class="footnote">[<a id="ftn.id873248" href="#id873248" class="para">11</a>] 
 Rationale. Programmers might expect
 <code class="computeroutput">return;</code>
 to exit the enclosing function instead of the local block (or local exit),
 especially if the enclosing function has a <code class="computeroutput">void</code>
 result type. However, using <code class="computeroutput">return;</code> to exit local blocks (and local exits)
- seemed to follow a more natural syntax and also it is the same syntax
- already provided by Boost.ScopeExit
+ seemed to follow a natural syntax and also it is the same syntax already
+ provided by Boost.ScopeExit
 (in fact, <code class="computeroutput">return;</code>
 is used by Boost.ScopeExit
- to exit the local scope and not to exit the enclosing scope). However,
- if programmers were to find this use of <code class="computeroutput">return;</code> confusing, this library API could be
+ to exit the local scope and not to exit the enclosing scope). If programmers
+ were to find this use of <code class="computeroutput">return;</code> confusing, this library API could be
 changed to forbid the use of <code class="computeroutput">return</code>
 from within local blocks (and local exits) generating a compile-time
 error, and to use a different instruction (e.g., <code class="computeroutput">break;</code> or a special macro instruction like
 <code class="computeroutput">BOOST_LOCAL_RETURN;</code>)
 to exit local blocks (and local exits).
 </div>
-<div class="footnote">[<a id="ftn.id873021" href="#id873021" class="para">13</a>] 
+<div class="footnote">[<a id="ftn.id874394" href="#id874394" class="para">12</a>] 
+ Rationale. This library (as well as Boost.ScopeExit)
+ uses the destructor of a local variable to automatically execute the local
+ exit code upon exit of the enclosing scope. However, in C++ it is no possible
+ to (portably) ensure the execution of the destructor of all objects if
+ the main program terminates because of an uncaught exception. (This is
+ different from the D programming language which executes the scope exit
+ code even if the main program terminates because of an uncaught exception.)
+ </div>
+<div class="footnote">[<a id="ftn.id875646" href="#id875646" class="para">13</a>] 
 Rationale. This library could be merged
 together with Boost.ScopeExit
 into a new library named Boost.Scope (from the meaning of the word "scope"
@@ -969,26 +1411,26 @@
 the functionality already provided by <code class="computeroutput">BOOST_SCOPE_EXIT</code>.
 The headers will be <code class="computeroutput">"boost/scope/function.hpp"</code>,
 <code class="computeroutput">"boost/scope/block.hpp"</code>,
- and <code class="computeroutput">"boost/scope/exit.hpp"</code>.
- For backward compatibility with Boost.ScopeExit,
+ and <code class="computeroutput">"boost/scope/exit.hpp"</code>
+ (for backward compatibility with Boost.ScopeExit,
 the header <code class="computeroutput">"boost/scope_exit.hpp"</code>
- could also be kept and it would be equivalent to including <code class="computeroutput">"boost/scope/exit.hpp"</code>. In addition
- and again for backward compatibility, the <code class="computeroutput">BOOST_SCOPE_EXIT</code>
- macro could be extended to accept either the original Boost.ScopeExit
- sequence of <code class="computeroutput">(var1)...(varN)</code> without the <code class="computeroutput">bind</code>
- "keyword" (which would be equivalent to plain binding) or the
- parenthesized binding sequence with the <code class="computeroutput">(bind)(...)</code>
- and <code class="computeroutput">(const
- bind)(...)</code>
- "keywords" plus the binding of the object <code class="computeroutput">this</code>.
- Local blocks would be named "scope blocks" and they would be
- provided by the <code class="computeroutput">BOOST_SCOPE_BLOCK...</code> macros. However, local functions would
- have to be named "scope functions" and they would be provided
- by the <code class="computeroutput">BOOST_SCOPE_FUNCTION...</code> macros. This might not be ideal because
- local functions are not known under the name of "scope functions"
- (they are indeed known by the name of "local functions" or "nested functions").
+ could also be kept and it would be equivalent to including <code class="computeroutput">"boost/scope/exit.hpp"</code>). However,
+ the new <code class="computeroutput">BOOST_SCOPE_EXIT</code>
+ macro will not be backward compatible with the current Boost.ScopeExit
+ macro because it will require to prefix the bound variable with <code class="computeroutput">bind</code> or <code class="computeroutput">const
+ bind</code> (in order to differentiate
+ from constant and non-constant binding). Local blocks would be named "scope
+ blocks" and they would be provided by the <code class="computeroutput">BOOST_SCOPE_BLOCK...</code> macros (the "scope block"
+ names seem reasonably expressive). However, local functions would have
+ to be named "scope functions" and they would be provided by the
+ <code class="computeroutput">BOOST_SCOPE_FUNCTION...</code>
+ macros. These names might not expressive enough because local functions
+ are not known under the name of "scope functions" -- they are
+ indeed known by either the name of "local functions" or by the
+ name of "<a href="http://gcc.gnu.org/onlinedocs/gcc/Nested-Functions.html" target="_top">nested
+ functions</a>".
 </div>
-<div class="footnote">[<a id="ftn.id873362" href="#id873362" class="para">14</a>] 
+<div class="footnote">[<a id="ftn.id877428" href="#id877428" class="para">14</a>] 
 Rationale. Within templates, this library
 needs to use <code class="computeroutput">typename</code> to explicitly
 indicate that some expressions evaluate to a type. Because C++ does not

Modified: sandbox/local/libs/local/doc/html/index.html
==============================================================================
--- sandbox/local/libs/local/doc/html/index.html (original)
+++ sandbox/local/libs/local/doc/html/index.html 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -27,7 +27,7 @@
</h3></div></div></div>
<div>Copyright © 2009 -2011 Lorenzo Caminiti</div>
<div><div class="legalnotice">
-<a name="id807671"></a>
+<a name="id809313"></a>
 Use, modification, and distribution is subject to 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).
 
@@ -41,10 +41,9 @@
<dt>Tutorial</dt>
<dt>Advanced</dt>
<dt>Reference</dt>
-<dt>Appendix: Grammar</dt>
-<dt>Appendix: Alternatives</dt>
<dt>Appendix: Examples</dt>
-<dt>Appendix: Rationale</dt>
+<dt>Appendix: Alternatives</dt>
+<dt>Appendix: Implementation</dt>
<dt>Releases</dt>
<dt>Bibliography</dt>
<dt>Acknowledgments</dt>
@@ -67,15 +66,10 @@
 of many programming languages, notably Pascal
 and Ada,
 yet lacking from C++ (see also [N2511]).
- 
-
 This library supports the following features for local functions (see the
 <a class="link" href="boost_local/Alternatives.html" title="Appendix: Alternatives">Alternatives</a> section for a
- comparison between this library and features offered by C++ local class members,
- <a href="http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions" target="_top">C++0x
- lambda</a> functions, Boost.Lambda,
- Boost.Phoenix,
- and Boost.ScopeExit):
+ comparison between this library and the features offered by other C++ libraries
+ and constructs):
 
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
@@ -84,7 +78,9 @@
 defined within a member function can bind the enclosing object <code class="computeroutput">this</code>.
 </li>
<li class="listitem">
- The local function body is programmed using the usual C++ syntax.
+ The local function body is programmed using the usual C++ syntax (as a
+ consequence, compiler error messages and line numbers retain their usual
+ meaning).
 </li>
<li class="listitem">
 Local functions can be passed as template parameters (so they can be conveniently
@@ -112,31 +108,52 @@
 and binding of the object <code class="computeroutput">this</code>).
 </li>
</ul></div>
-<a name="boost_local.Introduction.an_example"></a><h6>
-<a name="id808985"></a>
- <a class="link" href="index.html#boost_local.Introduction.an_example">An Example</a>
+<a name="boost_local.Introduction.two_syntaxes"></a><h6>
+<a name="id809120"></a>
+ <a class="link" href="index.html#boost_local.Introduction.two_syntaxes">Two Syntaxes</a>
 </h6>

- The following example illustrates a simple use of this library and it starts
- introducing the library API (see the <a class="link" href="boost_local/Tutorial.html" title="Tutorial">Tutorial</a>
- section for more details on how to use this library):
+ This library uses macros to declare the local functions, local blocks, and
+ local exits. The library macros support two different syntaxes:
 
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
- A local function is passed to the STL <code class="computeroutput">std::for_each</code>
- algorithm to add together the values of an array. Variables in scope are
- bound to the local function by both constant value and non-constant reference.
- </li>
-<li class="listitem">
- A local exit is used to automatically release the array's memory at scope
- exit.
+ The sequencing macro syntax is fully compliant with
+ the ISO C++ standard and supported on all C++ compilers. This syntax requires
+ to wrap the local function parameters and bound variables between round
+ parenthesis <code class="computeroutput">()</code>.
 </li>
<li class="listitem">
- A local block is used to assert the correct final value of the summation
- in a constant-correct context (therefore preventing the assertion from
- mistakenly changing any of the variables in scope).
+ The variadic macro synstax is available only on C++
+ compilers that support <a href="http://en.wikipedia.org/wiki/Variadic_macro" target="_top">variadic
+ macros</a>. [<a name="id851524" href="#ftn.id851524" class="footnote">1</a>] This syntax allow to use commas <code class="computeroutput">,</code>
+ to separate macro parameters therefore resembling the usual C++ syntax
+ for function parameter declaration.
 </li>
</ul></div>
+
+ The same library macros accept both syntaxes on compilers that support variadic
+ macros and only the sequencing macro syntax on compilers that do not support
+ variadic macros. The use of the variadic macro syntax might lead to more readable
+ code however it should only be used when programmers know that their code will
+ be compiled with variadic macros support to avoid portability issues. Most
+ of the examples presented in this documentation provide a side-by-side comparison
+ of both syntaxes.
+ 
+<a name="boost_local.Introduction.an_example"></a><h6>
+<a name="id851586"></a>
+ <a class="link" href="index.html#boost_local.Introduction.an_example">An Example</a>
+ </h6>
+
+ In the following example, a local function is passed to the STL <code class="computeroutput">std::for_each</code>
+ algorithm to add together the values of an array (variables in scope are bound
+ to the local function by both constant value and non-constant reference). A
+ local exit is used to automatically release the array's memory when the enclosing
+ function exits. A local block is used to assert the correct final value of
+ the summation in a constant-correct context (therefore preventing the assertion
+ from mistakenly changing any of the variables in scope). See the <a class="link" href="boost_local/Tutorial.html" title="Tutorial">Tutorial</a>
+ section for more details.
+ 
<div class="informaltable"><table class="table">
<colgroup>
<col>
@@ -296,7 +313,7 @@
</tr></tbody>
</table></div>

- Where the notes refer to the following comments:
+ Notes:
 
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
@@ -308,33 +325,36 @@
 a Boost.Preprocessor
 sequence of tokens listing each parameter type and name wrapped within
 round parenthesis <code class="literal">(parameter-type parameter-name)...</code>
- (default parameter values can also specified using a special syntax, see
- the <a class="link" href="boost_local/Tutorial.html" title="Tutorial">Tutorial</a> section). On C99
- and later preprocessors which support variadic macros, the same parameter
- macro also allows to specify the parameters separated by commas instead
- that wrapped within parenthesis <code class="literal">parameter-type parameter-name,...</code>
- so to provide a syntax more similar to the normal C++ syntax for function
- parameter lists. The local function result type is specified just before
- the parameter macro.
+ (default parameter values can also be specified using a special syntax,
+ see the <a class="link" href="boost_local/Tutorial.html" title="Tutorial">Tutorial</a> section).
+ On C99 and later preprocessors which support variadic macros, the same
+ parameter macro also allows to specify the parameters separated by commas
+ instead that wrapped within parenthesis <code class="literal">parameter-type
+ parameter-name,...</code> so to support
+ a syntax similar to the usual C++ syntax for function parameter lists.
+ The local function result type is specified just before the parameter macro.
 </li>
<li class="listitem">
 This library macros introduce the special "keyword" <code class="computeroutput">bind</code> which can be used instead of the
 parameter type to bind variables in scope. Variables can be bound by value,
- reference, constant value, and constant reference plus the object <code class="computeroutput">this</code> can be bound from within a non-static
- member function scope (see the <a class="link" href="boost_local/Tutorial.html" title="Tutorial">Tutorial</a>
- section). For example, the variable <code class="computeroutput">factor</code>
+ by reference, by constant value, and by constant reference. In addition,
+ the object <code class="computeroutput">this</code> can be bound
+ (but never by reference) from within a non-static member function (see
+ the <a class="link" href="boost_local/Tutorial.html" title="Tutorial">Tutorial</a> section). For
+ example, the variable <code class="computeroutput">factor</code>
 is bound by constant value so it cannot be mistakenly modified by the local
 function body. The variable <code class="computeroutput">sum</code>
 is instead bound by non-constant reference because the local function needs
 to change its value to report the summation result to the enclosing scope.
 </li>
<li class="listitem">
- The local function body is programmed outside the macros and using normal
+ The local function body is programmed outside the macros with the usual
 C++ syntax. Eventual compiler error messages and line numbers retain their
 usual meaning. Exceptions specifications can be programmed outside the
 macro and just before the body code block <code class="computeroutput">{...}</code>
- as usual (see the <a class="link" href="boost_local/Tutorial.html" title="Tutorial">Tutorial</a>
- section).
+ as usual. Finally, within the local function body the type of a bound variable
+ can be accessed using <code class="literal"><code class="computeroutput">BOOST_LOCAL_TYPEOF</code>(variable-name)</code>.
+ (See the <a class="link" href="boost_local/Tutorial.html" title="Tutorial">Tutorial</a> section.)
 </li>
<li class="listitem">
 The macro ending the local function definition specifies the local function
@@ -387,9 +407,19 @@
 </li>
</ol></div>
</div>
+<div class="footnotes">
+ <hr width="100" align="left">
+<div class="footnote">[<a id="ftn.id851524" href="#id851524" class="para">1</a>] 
+ Variadic macros were first introduced by the C99 preprocessor (via the
+ use of the special macro symbols ellipses <code class="computeroutput">...</code>
+ and <code class="computeroutput">__VA_ARGS__</code>). They
+ are now supported on essentially all modern C++ compilers (GCC, MVSC,
+ etc).
+ </div>
+</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left">Last revised: February 25, 2011 at 17:02:25 GMT</td>
+<td align="left">Last revised: March 10, 2011 at 14:09:29 GMT</td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>

Modified: sandbox/local/libs/local/doc/html/standalone_HTML.manifest
==============================================================================
--- sandbox/local/libs/local/doc/html/standalone_HTML.manifest (original)
+++ sandbox/local/libs/local/doc/html/standalone_HTML.manifest 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -17,10 +17,9 @@
BOOST_LOCAL_FUNCTION_NAME.html
BOOST_IDENTITY_TYPE.html
BOOST_IDENTITY_VALUE.html
-boost_local/Grammar.html
-boost_local/Alternatives.html
boost_local/Examples.html
-boost_local/Rationale.html
+boost_local/Alternatives.html
+boost_local/Implementation.html
boost_local/Releases.html
boost_local/Bibliography.html
boost_local/Acknowledgments.html

Modified: sandbox/local/libs/local/doc/qbk/advanced.qbk
==============================================================================
--- sandbox/local/libs/local/doc/qbk/advanced.qbk (original)
+++ sandbox/local/libs/local/doc/qbk/advanced.qbk 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -6,131 +6,173 @@

[section:Advanced Advanced]

-This section illustrates advanced usages of this library.
-At the end of this section there is also a list of limitations of this library.
+This section illustrates advanced usage of this library.
+At the end of this section there is also a list of knwon limitations of this library.

-[section Commas in Macro Parameters]
+[section Commas and Symbols in Macro Parameters]

The C++ preprocessor does not allow commas "`,`" within macro parameters unless they are wrapped by the round parenthesis `()`.
-The elements of the parenthesized signature are internally used as macro parameters while they are being processed by the parsing macros.
-Therefore, commas within parenthesized signature elements will generate (cryptic) preprocessor errors unless they are wrapped within extra round parenthesis `()` as explained here.
+Therefore, using commas the local function parameters and bindings passed to this library macros ill generate (cryptic) preprocessor errors unless they are wrapped within extra round parenthesis `()` as explained here.

[note
*Macro parameters with commas* which are already wrapped by round parenthesis `()` are fine (function calls, etc).
However, macro parameters with commas that are not wrapped by round parenthesis need to be wrapped by an extra set of round parenthesis `()` as described here.
-Therefore, also macro parameters with commas wrapped by angular parenthesis `<>` (templates, etc) or square parenthesis `[]` (multidimensional array access, etc) need to be wrapped by the extra round parenthesis `()` as explained here (this is because the preprocessor only recognizes the round parenthesis and it does not recognize angular, square, or any other type of parenthesis).
+Also macro parameters with commas wrapped by angular parenthesis `<>` (templates, etc) or square parenthesis `[]` (multidimensional array access, etc) need to be wrapped by the extra round parenthesis `()` as explained here (this is because the preprocessor only recognizes the round parenthesis and it does not recognize angular, square, or any other type of parenthesis).
]

-For example, let's consider the following parenthesized signature (see the complete example code later in this section):
+In addition, local function parameter types cannot start with non-alphanumeric symbols (alphanumeric symbols are `A-Z`, `a-z`, and `0-9`).
+[footnote
+*Rationale.*
+This limitation cames from the implementation of the library parsing macros that use preprocessor token concatenation to inspect the parameter type token to see if the token is a parameter or a bound variable.
+The C++ preprocessor does not allow to concatenate non-alphanumeric tokens.
+]
+The library will generate (cryptic) preprocessor errors if a parameter type starts with a non-alphanumeric symbol.
+
+Let's consider the following example:

- (void) (print)(
- (const std::map<std::string, size_t>&)(m) // (1) Error.
- (const size_t&)(factor)(default)
- (key_size<std::string, size_t>::value) // (2) Error.
- (const std::string&)(separator)(default)(cat(":", " ")) // (3) OK.
- (::sign_t)(sign)(default)(-1) // (4) Error.
- )
+[table
+[ [Variadic Macro Syntax (C99 and later compilers)] [Sequencing Macro Syntax (all C++ compilers)] ]
+[ [``
+ __BOOST_LOCAL_FUNCTION_PARAMS__(
+ const std::map<std::string, size_t>& m, // (1) Error.
+ ::sign_t sign, // (2) Error.
+ const size_t& factor, default
+ key_size<std::string, size_t>::value, // (3) Error.
+ const std::string& separator, default cat(":", " "), // (4) OK.
+ )
+``] [``
+ __BOOST_LOCAL_FUNCTION_PARAMS__(
+ (const std::map<std::string, size_t>& m) // (1) Error.
+ (::sign_t sign) // (2) Error.
+ (const size_t& factor)(default
+ key_size<std::string, size_t>::value) // (3) Error.
+ (const std::string& separator)(default cat(":", " ")) // (4) OK.
+ )
+``] ]
+]

-[*(1)] The parenthesized signature element `const std::map<std::string, size_t>&` contains a comma "`,`" after the first template parameter `std::string`.
-This comma is not wrapped by any round parenthesis `()` (the outer parenthesis `()` that make this a parenthesized signature element do not count) thus it will cause a preprocessor error.
+[*(1)] The parameter type `const std::map<std::string, size_t>&` contains a comma "`,`" after the first template parameter `std::string`.
+This comma is not wrapped by any round parenthesis `()` (the outer parenthesis `()` that make the sequencing macro syntax do not count) thus it will cause a preprocessor error.
The macro `__BOOST_IDENTITY_TYPE__(`/parenthesized-type/`)` can be used to wrap a type within extra parenthesis `()` so to overcome this issue:

- (void) (print)(
- ``*(*``__BOOST_IDENTITY_TYPE__``*((*``const std::map<std::string, size_t>&``*)))*``(m) // OK.
- ...
- )
+[table
+[ [Variadic Macro Syntax (C99 and later compilers)] [Sequencing Macro Syntax (all C++ compilers)] ]
+[ [``
+ __BOOST_LOCAL_FUNCTION_PARAMS__(
+ __BOOST_IDENTITY_TYPE__((const std::map<std::string, size_t>&)) m, // OK.
+ ...
+ )
+``] [``
+ __BOOST_LOCAL_FUNCTION_PARAMS__(
+ (__BOOST_IDENTITY_TYPE__((const std::map<std::string, size_t>&)) m) // OK.
+ ...
+ )
+``] ]
+]

This macro expands to an expression that evaluates (at compile-time) exactly to the specified type.
-Note that a total of three set of parenthesis `()` are needed:
+Note that a total of two set of parenthesis `()` are added:

-# Parenthesis to wrap the parenthesized signature element.
-# Parenthesis to call the `__BOOST_IDENTITY_TYPE__` macro.
+# Parenthesis to invoke the `__BOOST_IDENTITY_TYPE__` macro.
# Parenthesis to wrap the type expression (and therefore any commas "`,`" that it contains) passed as parameter to the `__BOOST_IDENTITY_TYPE__` macro.
-
-[*(2)] The parenthesized signature element `key_size<std::string, size_t>::value` contains a comma "`,`" after the first template parameter `std::string`.
-Again, this comma is not wrapped by any parenthesis `()` so it will cause a preprocessor error.
-Because this is a value expression (and not a type expression), the macro `__BOOST_IDENTITY_VALUE__(`/parenthesized-value/`)` is used to overcome this issue:
-
- (void) (print)(
- ...
- (const size_t&)(factor)(default)
- ``*(*``__BOOST_IDENTITY_VALUE__``*((*``key_size<std::string, size_t>::value``*)))*`` // OK.
- ...
- )
-
-This macro expands to an expression that evaluates (at run-time) exactly to the specified value.
-Note again that a total of three set of parenthesis `()` are needed similarly to `__BOOST_IDENTITY_TYPE__`.
-
-[*(3)] The parenthesized signature element `cat(':', ' ')` is instead fine because it contains a comma "`,`" which is already wrapped by the parenthesis `()` of the function call `cat(...)`.
-
-[*(4)] The parenthesized signature elements `::sign_t` and `-1` (the type and default value of the `sign` parameter) start with the non-alphanumeric symbols "`::`" and "`-`" respectively thus they cannot be used by the parenthesized syntax.
-The macros `__BOOST_IDENTITY_TYPE__` and `__BOOST_IDENTITY_VALUE__` can also be used to overcome these issues:
-
- (void) (print)(
- ...
- (__BOOST_IDENTITY_TYPE__((::sign_t)))(sign)(default)
- (__BOOST_IDENTITY_VALUE__((-1))) // OK.
- )
-
-This way the parenthesized signature elements became `(__BOOST_IDENTITY_TYPE__((::sign_t)))` and `(__BOOST_IDENTITY_VALUE__((-1)))` which start with the alphanumeric symbols of the macro names and they can be used by the parenthesized syntax.
-
-Often, there might be better ways to overcome this limitation that lead to code which is more readable than the one using these macros.
-For example, in this case the symbol "`::`" could be dropped and `-1` could be wrapped within `int(...)` to obtain the following, more readable, and still valid parenthesized signature code:
-
- (void) (print)(
- ...
- (sign_t)(sign)(default)(int(-1)) // OK.
- )
-
-Consider the following complete example:
[footnote
-We recognize that the use of the /identity macros/ adds extra parenthesis to the already significant number of parenthesis required by the parenthesized syntax.
-However, parenthesized signatures usually do not contain unwrapped commas "`,`" (unless template metaprogramming is being used).
+*Rationale.*
+Using variadic macros, this extra set of parenthesis could be eliminated requiring only the parenthesis to invoke the `__BOOST_IDENTITY_TYPE__` macro.
+This feature is currently not implemented and the double parenthesis are always needed when invoking this macro.
]

-[print_map_cpp]
+[*(2)] The parameter type `::sign_t` start with the non-alphanumeric symbols "`::`" thus it cannot be used by the parenthesized syntax.
+The macros `__BOOST_IDENTITY_TYPE__` can also be used to overcome these issue:

-[endsect]
+[table
+[ [Variadic Macro Syntax (C99 and later compilers)] [Sequencing Macro Syntax (all C++ compilers)] ]
+[ [``
+ __BOOST_LOCAL_FUNCTION_PARAMS__(
+ ...
+ __BOOST_IDENTITY_TYPE__((::sign_t)) sign, // OK.
+ ...
+ )
+``] [``
+ __BOOST_LOCAL_FUNCTION_PARAMS__(
+ ...
+ (__BOOST_IDENTITY_TYPE__((::sign_t)) sign) // OK.
+ ...
+ )
+``] ]
+]

-[section Recursive Local Functions]
+Often, there might be better ways to overcome this limitation that lead to code which is more readable than the one using these macros.
+For example, in this case the symbol "`::`" could be simply dropped to obtain the following and more readable code:

-A local function can recursively call itself as usual with C++ functions.
+[table
+[ [Variadic Macro Syntax (C99 and later compilers)] [Sequencing Macro Syntax (all C++ compilers)] ]
+[ [``
+ __BOOST_LOCAL_FUNCTION_PARAMS__(
+ ...
+ sign_t sign, // OK.
+ ...
+ )
+``] [``
+ __BOOST_LOCAL_FUNCTION_PARAMS__(
+ ...
+ (sign_t sign) // OK.
+ ...
+ )
+``] ]
+]

-For example, the following local function is used to recursively calculate and print the factorial of the specified numbers:
+[*(3)] The default parameter value `key_size<std::string, size_t>::value` contains a comma "`,`" after the first template parameter `std::string`.
+Again, this comma is not wrapped by any parenthesis `()` so it will cause a preprocessor error.
+Because this is a value expression (and not a type expression), it can simply be wrapped within an extra set of round parenthesis `()`:

-[factorial_cpp]
+[table
+[ [Variadic Macro Syntax (C99 and later compilers)] [Sequencing Macro Syntax (all C++ compilers)] ]
+[ [``
+ __BOOST_LOCAL_FUNCTION_PARAMS__(
+ ...
+ const size_t& factor, default
+ (key_size<std::string, size_t>::value), // OK.
+ ...
+ )
+``] [``
+ __BOOST_LOCAL_FUNCTION_PARAMS__(
+ ...
+ (const size_t& factor)(default
+ (key_size<std::string, size_t>::value)) // OK.
+ ...
+ )
+``] ]
+]

-The original local function name as specified in the parenthesized signature passed to `__BOOST_LOCAL_FUNCTION__` must always be used for recursive calls even when the function is renamed using `__BOOST_LOCAL_FUNCTION_END_RENAME__` (see renamed local functions later in this section).

-[endsect]
+[note
+Alternatively, the macro `__BOOST_IDENTITY_VALUE__(`/parenthesized-value/`)` could have been equivalently used.
+This macro expands to an expression that evaluates (at run-time) exactly to the specified value (but it adds overhead compared with simply using the extra parenthesis `()`).
+Note that, similarly to `__BOOST_IDENTITY_TYPE__`, the `__BOOST_IDENTITY_VALUE__` macro also requires two sets of extra parenthesis one set for invoking the macro and another set to wrap the value.
+]

-[section Exception Specifications]
+[*(4)] The default parameter value `cat(':', ' ')` is instead fine because it contains a comma "`,`" which is already wrapped by the parenthesis `()` of the function call `cat(...)`.

-It is possible to program exception specifications for local functions, local blocks, and local exits.
+Consider the following complete example:
+[footnote
+The authors recognize that the use of the /identity macros/ adds extra parenthesis to the already significant number of parenthesis required by the parenthesized syntax.
+However, macro parameters usually do not contain unwrapped commas "`,`" (unless template metaprogramming is being used).
+]

-Exception specifications are programmed just before the body (and outside the macros).
-For example:
+[table
+[ [Variadic Macro Syntax (C99 and later compilers)] [Sequencing Macro Syntax (all C++ compilers)] ]
+[ [ [print_map_va_cpp] ] [ [print_map_cpp] ] ]
+]

-[add_except_cpp]
+The `__BOOST_IDENTITY_TYPE__` macro must be prefixed by the `typename` keyword when used within templates.

[endsect]

-[section Optimizers: `inline`, `auto`, and `register`]
-
-As specified in the __Grammar__ section, the parenthesized signature also supports `inline`d local functions, and the `auto` and `register` classifiers for local function parameters.
-
-[note
-However, note that local functions will always add some overhead because of the functor object used to internally implement them.
-Compilers might not be able to optimize away the local function overhead even when `inline`, `auto`, and `register` are used.
-]
-
-For example:
-
-[add_optimizers_cpp]
+[section Deducing Bound Types]

[endsect]

-[section References to Local Functions]
+[section Passing Local Functions]

It is possible to obtain a reference to a local function so to assign it to a variable, to pass it as a function parameter, etc.

@@ -138,88 +180,96 @@
Local functions are never copied by value.
You can only obtain a reference to a local function therefore you need to make sure that the *local function survives the scope of its reference* otherwise the reference will be invalid and its use will generate a run-time error (as usual with C++ references).
[footnote
-The suffix `ref` of `boost::local::__function_ref__` is meant to help programmers remember that they are dealing with references to (and not copies of) local functions.
+The suffix `ref` of `boost::local::__function__` is meant to help programmers remember that they are dealing with references to (and not copies of) local functions.
]
]

For this purpose, it is possible to assign a `boost::function` functor to a local function (see also __Boost_Function__).
-However, it is in general preferable to use the `boost::local::__function_ref__` functor instead because its API also supports default parameters.
-
-The `boost::local::__function_ref__` template takes two parameters (see the __Reference__ section):
+However, it is in general preferable to use the `boost::local::__function__` functor instead because its API also supports default parameters.

- template<typename F, size_t defaults = 0>
- class __function_ref__ { ... };
+The `boost::local::__function__` template takes two parameters (see the __Reference__ section):

-Where:
+ template< typename F, size_t defaults = 0 > class __function__;

-* The template parameter `F` specifies the function signature using the same
+[variablelist
+[ [F] [
+The template parameter `F` specifies the function signature using the same
syntax as __Boost_Function__'s preferred syntax.
-For example:
-
- __function_ref__< int() > // Returns `int` and takes no parameter.
- __function_ref__< int(double, char) > // Returns `int`and takes two parameters: a `double` followed by a `char`.
-
-* The template parameter `defaults` specifies the number of defaults parameters counting from the last parameter: `0` if no parameter is optional, `1` if the last parameter is optional, `2` if the last two parameters are optional, etc.
+For example:``
+ __function__< int() > // Returns `int` and takes no parameter.
+ __function__< int(double, char) > // Returns `int`and takes two parameters: a `double` followed by a `char`.
+``] ]
+[ [defaults] [
+The template parameter `defaults` specifies the number of defaults parameters counting from the last parameter: `0` if no parameter is optional, `1` if the last parameter is optional, `2` if the last two parameters are optional, etc.
This template parameter must be between `0` and the total number of parameters as specified by `F`.
This template parameter is optional and it is `0` by default.
-For example:
-
- __function_ref__< int(double, char) > // No default: All parameters must be specified.
- __function_ref__< int(double, char), 1 > // 1 default: The last `char` parameter is optional.
- __function_ref__< int(double, char), 2 > // 2 defaults: All parameters are optional.
+For example:``
+ __function__< int(double, char) > // No default: All parameters must be specified.
+ __function__< int(double, char), 1 > // 1 default: The last `char` parameter is optional.
+ __function__< int(double, char), 2 > // 2 defaults: All parameters are optional.
+``] ]
+]

For example:

-[doit_cpp]
+[table
+[ [Variadic Macro Syntax (C99 and later compilers)] [Sequencing Macro Syntax (all C++ compilers)] ]
+[ [ [doit_va_cpp] ] [ [doit_cpp] ] ]
+]
+
+In addition, a local function can bind and call another local function.
+For example, the following local function `inc_sum` binds the local function `inc` so `inc_sum` can call `inc`:
+
+[table
+[ [Variadic Macro Syntax (C99 and later compilers)] [Sequencing Macro Syntax (all C++ compilers)] ]
+[ [ [transform_va_cpp] ] [ [transform_cpp] ] ]
+]

[endsect]

-[section Renaming Local Functions]
+[section Exception Specifications]
+
+It is possible to program exception specifications for local functions, local blocks, and local exits.
+
+Exception specifications are programmed just before the body (and outside the macros).
+For example:

-Local functions can be renamed using the `__BOOST_LOCAL_FUNCTION_END_RENAME__` macro instead of `__BOOST_LOCAL_FUNCTION_END__`:
+[add_except_cpp]

- __BOOST_LOCAL_FUNCTION_END_RENAME__(``/new-local-function-name/``)
+[endsect]

-Where the /new-local-function-name/ no longer has to match the local function name as originally specified in the parenthesized signature passed to `__BOOST_LOCAL_FUNCTION__`.
-For example:
-[footnote
-*Rationale.*
-Local functions are often named `l` in the casual examples of this documentation because the name of the author starts with the letter "`l`". [$../images/smiley.png]
-]
+[section Storage Classifiers `auto` and `register`]

- {
- __BOOST_LOCAL_FUNCTION__(
- (void) (l)( (int)(x) )
- ) {
- ... // Body uses original name `l`.
- } __BOOST_LOCAL_FUNCTION_END_RENAME__(m) // Renamed to `m`.
-
- ... // Enclosing scope uses new name `m`.
- }
+As specified in the __Grammar__ section, the parenthesized signature also supports `inline`d local functions, and the `auto` and `register` classifiers for local function parameters.

-Note that the local function is renamed only after the call to `__BOOST_LOCAL_FUNCTION_END_RENAME__`.
-Therefore, within the local function body the original local function name as specified by `__BOOST_LOCAL_FUNCTION__` must be used (e.g., to recursively call the local function).
-However, within the enclosing scope only the new local function name as specified by `__BOOST_LOCAL_FUNCTION_END_RENAME__` is available.
+[note
+However, note that local functions will always add some overhead because of the functor object used to internally implement them.
+Compilers might not be able to optimize away the local function overhead even when `inline`, `auto`, and `register` are used.
+]

-A limitation is that renamed local functions cannot be directly passed as template parameters (e.g., they cannot be passed to STL algorithms like `std::for_each`).
-However, it is possible to workaround this limitation by obtaining a reference of the renamed local function and then passing the reference as template parameter.
For example:

-[renamed_print_cpp]
+[add_optimizers_cpp]
+
+[endsect]
+
+[section Recursive Local Functions]
+
+A local function can recursively call itself as usual with C++ functions.

-[h5 Motivation]
+For example, the following local function is used to recursively calculate and print the factorial of the specified numbers:

-The motivation for renaming a local function might not be obvious at first.
-In fact, in most cases programmers will not need to rename local functions.
+[factorial_cpp]

-Renaming local functions might be useful at least to program macros that expand using local functions and that do not want to pass the local function body as a macro parameter (so to retain the usual meaning of compiler error line numbers for the body code).
-Consider the following example that implements a simple version of the local exit macros using a renamed local function:
+The original local function name as specified in the parenthesized signature passed to `__BOOST_LOCAL_FUNCTION__` must always be used for recursive calls even when the function is renamed using `__BOOST_LOCAL_FUNCTION_END_RENAME__` (see renamed local functions later in this section).
+
+[endsect]

-[renamed_exit_cpp]
+[section Nested Declarations]

[endsect]

-[section Limitations: Overloading, Nesting, Operators, Etc]
+[section Limitations: Overloading and Operators]

This is a list of limitations of this library's local functions compared to usual features of C++ functions.

Deleted: sandbox/local/libs/local/doc/qbk/grammar.qbk
==============================================================================
--- sandbox/local/libs/local/doc/qbk/grammar.qbk 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
+++ (empty file)
@@ -1,111 +0,0 @@
-
-[/ Copyright (C) 2009-2011 Lorenzo Caminiti ]
-[/ Use, modification, and distribution is subject to 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). ]
-
-[section:Grammar Appendix: Grammar]
-
-This section describes the complete grammar of the /parenthesized syntax/ used by this library to specify the local function signature with binding of variables in scope.
-
-This should be considered a reference section.
-See the __Tutorial__ and the __Advanced__ sections for explanations and examples on how to use the parenthesized syntax.
-
-[note
-The parsers of the parenthesized syntax are implemented using macros and the __Boost_Preprocessor__ library so *the parenthesized syntax is parsed by the preprocessor*.
-
-Using preprocessor metaprogramming allows the parsers to introduce new "keywords" at the same syntactic level as the usual C++ keywords but that are used to support new features specific to this library (for example the new "keyword" `bind` which is used to bind variables in scope).
-However, the use of the preprocessor also requires using a significant number of extra parenthesis `()` with respect to usual C++ syntax (from which the parenthesized syntax's name).
-
-In addition, there is only a limited amount of syntactic error checking that can be done using macros thus sometimes a parenthesized syntax error generates cryptic preprocessor errors.
-When the macros can catch syntactic errors, these errors are reported as compile-time errors (using static assertions) with names of the form `ERROR_`/description_text/.
-]
-
-Macros using the parenthesized syntax (see the __Reference__ section):
-
- __BOOST_LOCAL_FUNCTION__( ``/parenthesized-signature/`` )
- __BOOST_LOCAL_BLOCK__( ``/parenthesized-binding/`` )
- __BOOST_LOCAL_EXIT__( ``/parenthesized-binding/`` )
-
-Additional "keywords":
-
- bind ``used to bind variables in scope``
- default ``used to specify default parameters``
-
-Terminals:
-
- ``*result-type*`` ``a function return type (can be ``void``)``
- ``*function-name*`` ``a function name (cannot be an operator)``
-
- ``*parameter-type*`` ``a parameter type``
- ``*parameter-name*`` ``a parameter name``
- ``*parameter-default*`` ``a valid default value for the specified parameter``
-
- ``*variable-name*`` ``the name of a variable in scope (can be ``this``)``
-
-Lexical conventions:
-
- ``/a | b/`` ``symbol /a/ or symbol /b/``
- ``/[a]/`` ``the symbol /a/ is optional and it can be omitted``
- ``/a+/`` ``symbol /a/ repeated one or more times``
-
-Parenthesized syntax:
-
- ``/parenthesized-signature:/``
- ``/[/``(inline)``/]/`` (``*result-type*``) (``*function-name*``)( ``/parameter-list/`` )
-
- ``/parenthesized-binding:/``
- (void) // No bindings.
- ``/| bindings/`` // Bindings (constant and/or not).
-
- ``/parameter-list:/``
- (void) // No parameters and no bindings.
- ``/| parameters/`` // Only parameters.
- ``/| bindings/`` // Only bindings.
- ``/| parameters bindings/`` // Both parameters and bindings (must appear in this order).
-
-Function parameters:
-
- ``/parameters:/``
- ``/parameter+/`` // Only required parameters.
- ``/| optional-parameter+/`` // Only optional parameters.
- ``/| parameter+ optional-parameter+/`` // Both required and optional parameters (must appear in this order).
-
- ``/parameter:/``
- ``/[/``(auto) ``/|/`` (register)``/]/`` // Optional parameter classifier `auto` or `register`.
- (``*parameter-type*``)(``*parameter-name*``)
-
- ``/optional-parameter:/``
- ``/parameter/``
- (default)(``*parameter-default*``) // Default value for this optional parameter.
-
-Binding variables in scope:
-[footnote
-*Rationale.*
-The alternative syntax `(bind)((const& x)...)` would have been preferred because `const` appears before the reference as usual in C++ and because a single `bind` sequence is used for both plain and constant binding (e.g., the single sequence `(bind)((a)(&b)(const a)(const& b))` would bind by value, by constant value, by reference, and by constant reference respectively).
-However, the parenthesized syntax parsers cannot process both `const& x` and `&x` because if they inspect the beginning of the token `&x` to search for the leading `const` they will find the non-alphanumeric symbol `&` which cannot be used for token concatenation thus generating preprocessor errors.
-The tokens `&x` and `x` can instead be processed by the parsing macros because they do not need to be inspected from the front (they are instead inspected from the back to check if a token matches `this` and that is fine because the non-alphanumeric symbol `&` never appears in the back).
-]
-[footnote
-*Rationale.*
-Binding is used within the function parameter list because this syntax seemed natural given that the bound variables are used by the function body as if they were function parameters (only their type is not explicitly specified by the function signature and the caller does not explicitly pass their values).
-However, the parenthesized syntax could be modified to accept `(const bind)(...)` and `(bind)(...)` outside the parameter list (e.g., at the very end or beginning of the function signature) if an alternative syntax was to be identified as more intuitive.
-]
-
- ``/bindings:/``
- ``/const-bindings/`` // Only constant binding.
- ``/| plain-bindings/`` // Only plain binding.
- ``/| const-bindings plain-bindings/`` // Both constant and plain bindings (must appear in this order).
-
- ``/const-bindings:/``
- (const bind)(``/bound-variable+/``) // Force constant type for bound variable.
-
- ``/plain-bindings/``:
- (bind)(``/bound-variable+/``) // Use bound variable's plain type (constant or not).
-
- ``/bound-variable/``:
- (``*variable-name*``) // Bind by value.
- | (&``*variable-name*``) // Bind by reference.
-
-[endsect]
-

Modified: sandbox/local/libs/local/doc/qbk/introduction.qbk
==============================================================================
--- sandbox/local/libs/local/doc/qbk/introduction.qbk (original)
+++ sandbox/local/libs/local/doc/qbk/introduction.qbk 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -9,12 +9,11 @@
/Local functions/ are a form of /information hiding/ and are useful for dividing procedural tasks into subtasks which are only meaningful locally, avoiding cluttering other parts of the program with functions, variables, etc unrelated to those parts.
Local functions therefore complement other structuring possibilities such as namespaces and classes.
Local functions are a feature of many programming languages, notably [@http://en.wikipedia.org/wiki/Nested_function#An_example Pascal] and [@http://en.wikipedia.org/wiki/Nesting_(computing)#In_programming Ada], yet lacking from C++ (see also __N2511__).
-
-This library supports the following features for local functions (see the __Alternatives__ section for a comparison between this library and features offered by C++ local class members, __CPP0x_lambda__ functions, __Boost_Lambda__, __Boost_Phoenix__, and __Boost_ScopeExit__):
+This library supports the following features for local functions (see the __Alternatives__ section for a comparison between this library and the features offered by other C++ libraries and constructs):

* Local functions can access, or better [@http://en.wikipedia.org/wiki/Name_binding /bind/], any of the variables from the enclosing scope.
Furthermore, local functions defined within a member function can bind the enclosing object `this`.
-* The local function body is programmed using the usual C++ syntax.
+* The local function body is programmed using the usual C++ syntax (as a consequence, compiler error messages and line numbers retain their usual meaning).
* Local functions can be passed as template parameters (so they can be conveniently passed to STL algorithms, etc).
* However, local functions must be defined within a declarative context (e.g., at a point in the code where local variables can be declared) thus they cannot be defined within an expression.

@@ -24,35 +23,55 @@
Local blocks allow programmers to bind variables as constants (/constant binding/) so to prevent local chunks of code from modifying selected variables.
* /Local exits/ which define blocks of code that are executed when the enclosing scope is exited (again with support for constant binding and binding of the object `this`).

-[h5 An Example]
+[h5 Two Syntaxes]
+
+This library uses macros to declare the local functions, local blocks, and local exits.
+The library macros support two different syntaxes:
+
+* The /sequencing macro syntax/ is fully compliant with the ISO C++ standard and supported on all C++ compilers.
+This syntax requires to wrap the local function parameters and bound variables between round parenthesis `()`.
+* The /variadic macro synstax/ is available only on C++ compilers that support [@http://en.wikipedia.org/wiki/Variadic_macro variadic macros].
+[footnote
+Variadic macros were first introduced by the C99 preprocessor (via the use of the special macro symbols ellipses `...` and `__VA_ARGS__`).
+They are now supported on essentially all modern C++ compilers (GCC, MVSC, etc).
+]
+This syntax allow to use commas `,` to separate macro parameters therefore resembling the usual C++ syntax for function parameter declaration.
+
+The same library macros accept both syntaxes on compilers that support variadic macros and only the sequencing macro syntax on compilers that do not support variadic macros.
+The use of the variadic macro syntax might lead to more readable code however it should only be used when programmers know that their code will be compiled with variadic macros support to avoid portability issues.
+Most of the examples presented in this documentation provide a side-by-side comparison of both syntaxes.

-The following example illustrates a simple use of this library and it starts introducing the library API (see the __Tutorial__ section for more details on how to use this library):
+[h5 An Example]

-* A local function is passed to the STL `std::for_each` algorithm to add together the values of an array.
-Variables in scope are bound to the local function by both constant value and non-constant reference.
-* A local exit is used to automatically release the array's memory at scope exit.
-* A local block is used to assert the correct final value of the summation in a constant-correct context (therefore preventing the assertion from mistakenly changing any of the variables in scope).
+In the following example, a local function is passed to the STL `std::for_each` algorithm to add together the values of an array (variables in scope are bound to the local function by both constant value and non-constant reference).
+A local exit is used to automatically release the array's memory when the enclosing function exits.
+A local block is used to assert the correct final value of the summation in a constant-correct context (therefore preventing the assertion from mistakenly changing any of the variables in scope).
+See the __Tutorial__ section for more details.

[table
[ [Notes] [Variadic Macro Syntax (C99 and later compilers)] [Sequencing Macro Syntax (all C++ compilers)] ]
[ [ [add_callouts_cpp] ] [ [add_va_cpp] ] [ [add_cpp] ] ]
]

-Where the notes refer to the following comments:
+Notes:

# Include the header files for this library local functions, local blocks, and local exits.
-# The *local function* parameter macro takes a __Boost_Preprocessor__ sequence of tokens listing each parameter type and name wrapped within round parenthesis [^(['parameter-type parameter-name])['...]] (default parameter values can also specified using a special syntax, see the __Tutorial__ section).
-On C99 and later preprocessors which support variadic macros, the same parameter macro also allows to specify the parameters separated by commas instead that wrapped within parenthesis [^['parameter-type parameter-name],['...]] so to provide a syntax more similar to the normal C++ syntax for function parameter lists.
+# The *local function* parameter macro takes a __Boost_Preprocessor__ sequence of tokens listing each parameter type and name wrapped within round parenthesis [^(['parameter-type parameter-name])['...]] (default parameter values can also be specified using a special syntax, see the __Tutorial__ section).
+On C99 and later preprocessors which support variadic macros, the same parameter macro also allows to specify the parameters separated by commas instead that wrapped within parenthesis [^['parameter-type parameter-name],['...]] so to support a syntax similar to the usual C++ syntax for function parameter lists.
The local function result type is specified just before the parameter macro.
# This library macros introduce the special "keyword" `bind` which can be used instead of the parameter type to bind variables in scope.
-Variables can be bound by value, reference, constant value, and constant reference plus the object `this` can be bound from within a non-static member function scope (see the __Tutorial__ section).
+Variables can be bound by value, by reference, by constant value, and by constant reference.
+In addition, the object `this` can be bound (but never by reference) from within a non-static member function (see the __Tutorial__ section).
For example, the variable `factor` is bound by constant value so it cannot be mistakenly modified by the local function body.
The variable `sum` is instead bound by non-constant reference because the local function needs to change its value to report the summation result to the enclosing scope.
-# The local function body is programmed outside the macros and using normal C++ syntax.
+# The local function body is programmed outside the macros with the usual C++ syntax.
Eventual compiler error messages and line numbers retain their usual meaning.
-Exceptions specifications can be programmed outside the macro and just before the body code block `{...}` as usual (see the __Tutorial__ section).
+Exceptions specifications can be programmed outside the macro and just before the body code block `{...}` as usual.
+Finally, within the local function body the type of a bound variable can be accessed using [^__BOOST_LOCAL_TYPEOF__(['variable-name])].
+(See the __Tutorial__ section.)
# The macro ending the local function definition specifies the local function name.
-# The local function macros declare a functor object local to the enclosing scope named `add`. The functor `add` has `void` result type, it can be called by specifying one parameter of type `double`, and it has access to the variables in scope `factor` (by constant value) and `sum` (by reference).
+# The local function macros declare a functor object local to the enclosing scope named `add`.
+The functor `add` has `void` result type, it can be called by specifying one parameter of type `double`, and it has access to the variables in scope `factor` (by constant value) and `sum` (by reference).
# The *local exit* declaration macro only specifies the variables in scope to bind (by reference or value and eventually as constants).
Exceptions specifications can be programmed outside the macro and just before the body code block `{...}` as usual (see the __Tutorial__ section).
# The local exit code will be automatically executed when the enclosing scope is exited.

Modified: sandbox/local/libs/local/doc/qbk/local.qbk
==============================================================================
--- sandbox/local/libs/local/doc/qbk/local.qbk (original)
+++ sandbox/local/libs/local/doc/qbk/local.qbk 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -42,6 +42,8 @@
[def __Introduction__ [link boost_local.Introduction Introduction]]
[def __Starting__ [link boost_local.Starting Starting]]
[def __Tutorial__ [link boost_local.Tutorial Tutorial]]
+[def __Tutorial_Empty_Parameters__ [link boost_local.Tutorial.Empty_Parameters Empty Parameters]]
+[def __Tutorial_Binding__ [link boost_local.Tutorial.Binding Binding]]
[def __Advanced__ [link boost_local.Advanced Advanced]]
[def __Reference__ [@reference.html Reference]]
[def __Grammar__ [link boost_local.Grammar Grammar]]
@@ -51,33 +53,52 @@
[def __Bibliography__ [link boost_local.Bibliography Bibliography]]
[def __Acknowledgments__ [link boost_local.Acknowledgments Acknowledgments]]

-[def __BOOST_LOCAL_FUNCTION__ [macroref BOOST_LOCAL_FUNCTION]]
-[def __BOOST_LOCAL_FUNCTION_TPL__ [macroref BOOST_LOCAL_FUNCTION_TPL]]
-[def __BOOST_LOCAL_FUNCTION_END__ [macroref BOOST_LOCAL_FUNCTION_END]]
-[def __BOOST_LOCAL_FUNCTION_END_RENAME__ [macroref BOOST_LOCAL_FUNCTION_END_RENAME]]
+[def __BOOST_LOCAL_FUNCTION_PARAMS__ [macroref BOOST_LOCAL_FUNCTION_PARAMS]]
+[def __BOOST_LOCAL_FUNCTION_PARAMS_TPL__ [macroref BOOST_LOCAL_FUNCTION_PARAMS_TPL]]
+[def __BOOST_LOCAL_FUNCTION_NAME__ [macroref BOOST_LOCAL_FUNCTION_NAME]]
[def __BOOST_LOCAL_BLOCK__ [macroref BOOST_LOCAL_BLOCK]]
[def __BOOST_LOCAL_BLOCK_TPL__ [macroref BOOST_LOCAL_BLOCK_TPL]]
[def __BOOST_LOCAL_BLOCK_END__ [macroref BOOST_LOCAL_BLOCK_END]]
[def __BOOST_LOCAL_EXIT__ [macroref BOOST_LOCAL_EXIT]]
[def __BOOST_LOCAL_EXIT_TPL__ [macroref BOOST_LOCAL_EXIT_TPL]]
[def __BOOST_LOCAL_EXIT_END__ [macroref BOOST_LOCAL_EXIT_END]]
+[def __BOOST_LOCAL_TYPEOF__ [macroref BOOST_LOCAL_TYPEOF]]
[def __BOOST_IDENTITY_TYPE__ [macroref BOOST_IDENTITY_TYPE]]
[def __BOOST_IDENTITY_VALUE__ [macroref BOOST_IDENTITY_VALUE]]
-[def __function_ref__ [classref boost::local::function_ref function_ref]]
+[def __function__ [classref boost::local::function function]]

[import ../../example/add_callouts.cpp]
[import ../../example/add.cpp]
[import ../../example/add_va.cpp]
-[import ../../example/add_num.cpp]
-[import ../../example/add_num_sum.cpp]
+[import ../../example/add_x_y.cpp]
+[import ../../example/add_x_y_va.cpp]
+[import ../../example/ten.cpp]
+[import ../../example/ten_va.cpp]
+[import ../../example/ten_ep.cpp]
+[import ../../example/add_x_y_default.cpp]
+[import ../../example/add_x_y_default_va.cpp]
+[import ../../example/add_x_y_default_with_va.cpp]
[import ../../example/add_num_factor_sum.cpp]
+[import ../../example/add_num_factor_sum_va.cpp]
[import ../../example/add_this.cpp]
+[import ../../example/add_this_va.cpp]
[import ../../example/add_block.cpp]
+[import ../../example/add_block_va.cpp]
[import ../../example/add_exit.cpp]
+[import ../../example/add_exit_va.cpp]
+[import ../../example/scope_guards_errno.cpp]
+[import ../../example/scope_guards_except.cpp]
[import ../../example/add_template.cpp]
+[import ../../example/add_template_va.cpp]
[import ../../example/print_map.cpp]
-[import ../../example/factorial.cpp]
+[import ../../example/print_map_va.cpp]
[import ../../example/doit.cpp]
+[import ../../example/doit_va.cpp]
+[import ../../example/transform.cpp]
+[import ../../example/transform_va.cpp]
+
+[import ../../example/add_num_sum.cpp]
+[import ../../example/factorial.cpp]
[import ../../example/add_except.cpp]
[import ../../example/add_optimizers.cpp]

@@ -88,10 +109,9 @@
[include tutorial.qbk]
[include advanced.qbk]
[xinclude ../reference.xml]
-[include grammar.qbk]
-[include alternatives.qbk]
[include examples.qbk]
-[include rationale.qbk]
+[include alternatives.qbk]
+[include implementation.qbk]
[include releases.qbk]
[include bibliography.qbk]
[include acknowledgements.qbk]

Deleted: sandbox/local/libs/local/doc/qbk/rationale.00.qbk
==============================================================================
--- sandbox/local/libs/local/doc/qbk/rationale.00.qbk 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
+++ (empty file)
@@ -1,172 +0,0 @@
-
-[/ Copyright (C) 2009-2011 Lorenzo Caminiti ]
-[/ Use, modification, and distribution is subject to 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). ]
-
-[section:Rationale Appendix: Rationale]
-
-This section discusses rationale behind library design decisions in addition to the rationale already provided throughout the rationale footnotes in the rest of this documentation.
-
-[section Parenthesized Syntax Rationale]
-
-This section discusses the rationale behind parenthesized syntax design decisions.
-
-[section C99 Preprocessor]
-
-The C99 preprocessor (and therefore the C++0x preprocessor) allows for additional features like specifying empty macro parameters and variadic macro parameters which are not supported by the ISO C++ standard preprocessor.
-The additional features of the C99 preprocessor can be used to simplify the parenthesized syntax mainly by removing extra parenthesis and making it look more like normal C++ syntax.
-
-Most (and maybe all) modern compilers support the C99 preprocessor at this time and all new C++0x compilers will support the C99 preprocessor in the future.
-Therefore, the library macros have been programmed to automatically detect the presence of the C99 preprocessor and accept the simplified parenthesized syntax in these cases.
-The same macro will only accept the parenthesized syntax on non C99 preprocessor but will accept both the parenthesized syntax and the simplified parenthesized syntax on C99 preprocessors.
-This way, programmers that can afford to write C99 specific code can benefit from the simplifications of the parenthesized syntax.
-
-[endsect]
-
-[section Parameter Type and Name Separation]
-
-C++ allows to specify parameter names within function types:
-
- void (int x, double& y)
-
-Therefore, the parenthesized syntax for local functions does not have to separate the function parameter type and name tokens:
-
-[table Parameter Types and Names
-[ [Normal C++ Syntax] [C++ Parenthesized Syntax] [C99-Only Parenthesized Syntax] ]
-[ [
-`void f(int x, double&y)`
-] [
-`(void) (f)( (int x) (double& y) ) // Is this better than its general version below selected by the authors? Local functions don't need the generality...`
-] [
-`(void) (f)(int x, double& y) // Authors' choice.`
-] ]
-]
-
-Note that a more general form of the parenthesized syntax would have been instead:
-[table Separated Parameter Types and Names
-[ [Normal C++ Syntax] [C++ Parenthesized Syntax] [C99-Only Parenthesized Syntax] ]
-[ [
-`void f(int x, double& y)`
-] [
-`(void) (f)( (int)(x) (double&)(y) ) // Authors' choice.`
-] [
-`(void) (f)(int, x, double&, y)` /-or-/
-
-`(void) (f)( (int, x) , (double&, y) )` /-or-/
-
-`(void) (f)( (int)(x) , (double&)(y) )`
-] ]
-]
-
-This more general form makes available the parameter types and names as separate tokens for preprocessor metaprogramming.
-In fact, there is no way for the preprocessor to split `(int x)` into the parameter type `int` and name `x` while it can split `(int)(x)`.
-The parameter types can be split at compile-time (for example to force some parameters to be constant, references, etc):
-
- typedef arg_type<void (int x, double& y), 0>::type arg_type0; // int
- typedef arg_type<void (int x, double& y), 1>::type arg_type1; // double&
-
-But the parameter name `x` remains inaccessible as a token separately from its type.
-However, local function do not need to access parameter types separately from their types so this lack of generality is not an issue for local function and the less general syntax (e.g., `(int x)`) is preferred over the more general one (e.g., `(int)(x)`) because it is simpler as it uses a smaller number of parenthesis and resembles more closely the normal C++ syntax for function parameters.
-
-[note *Overloaded functions.*
-An example where parameter names need to be accessed separately from their types is to support overloading.
-For example, if the macro need to expand to support code for an overloaded function, they might need to generate unique identifiers for symbols within the support code.
-Assume also `__LINE__` cannot be used in this context because the unique identifiers need to be referred by another macro expanding on a different line (so the unique identifier need to be generated upon the function syntactic elements -- function name, parameter names, etc).
-Such identifiers cannot simply use the function name because the same function name is used multiple times when the function is overloaded and therefore the identifiers will not be unique.
-The parameter names can be concatenated by the preprocessor together with the function name to generate such unique identifiers (with the limitation that overloaded function need to used different parameter names and not just different parameter types).
-]
-
-[endsect]
-
-[section Empty Function Parameters]
-
-The C++ preprocessor does not allow to specify an empty macro parameter as a consequence preprocessor sequences cannot contain empty elements `()`.
-Therefore the following parenthesized syntax for a function with no parameter `void f()` is not valid for the C++ preprocessor:
-
- (void) (f)() // Error, cannot use empty `()`.
-
-This syntax is instead valid for the C99 preprocessor because it can instead accept empty macro parameter.
-
-C++ also allow to specify an empty parameter list using `void`:
-
- void f(void)
-
-This leads to the valid parenthesized syntax:
-
- (void) (f)( (void) )
-
-In summary:
-
-[table Empty Function Parameters
-[ [Normal C++ Syntax] [C++ Parenthesized Syntax] [C99-Only Parenthesized Syntax] ]
-[ [
-`void f()`
-] [
-`(void) (f)( (void) ) // Authors' choice.`
-] [
-`(void) (f)() // Authors' choice.`
-] ]
-]
-
-[endsect]
-
-[section Default Parameter Values]
-
-C++ does not allow to specify default parameter values within function types thus the following is not valid:
-
- void (int x = -1, double y = -1.23) // Error, can't specify default parameters within function types.
-
-Therefore, the following parenthesized syntax cannot be used:
-
- (void) (f)( (int x = -1) (double y = -1.23) )
-
-Because:
-
-# It does not allow to strip the default parameter values from the parameter type and name in order to construct and manipulate the local function type.
-# Default parameter values are not part of the type so it is not possible to program a metafunction that counts the number of default parameter values at compile-time but such information is also needed by the local functions in order to properly support default parameters.
-[footnote
-Specifically, the number of default parameter value is needed at compile-time to instantiate the proper `function_ref<typename F, size_t default_parameter_count` template to hold the local function.
-The `function_ref` functor is needed to implement the trick that allows local functions to be passed as template parameters (see [@http://lists.boost.org/Archives/boost/2010/09/170888.php]).
-]
-
-Default parameters can be separated by the rest of the parameter expression using:
-
- (void) (f)( (int x)(default -1) (double y)(default -1.23) )
-
-Note that the `=` symbol needs to be replaced with the alphanumeric keyword `default` because parenthesized syntax elements cannot start with a non alphanumeric symbol like `=`.
-[footnote
-This is because the parenthesized syntax needs to check if its token matches a keyword like `void`, `inline`, etc.
-This checking is done by concatenating from the front the token with a special library-defined symbol that generates a new macro that will ultimately expand to `1` if and only if the element matches the searched keyword.
-The preprocessor does not allow to concatenate non-alphanumeric tokens so the parenthesized syntax tokens cannot start with a non-alphanumeric token otherwise the concatenation will generate a preprocessor error (see [@http://lists.boost.org/Archives/boost/2010/08/169859.php]).
-]
-
-For C99, some or all the parenthesis can be replaced by commas.
-
-[table Default Parameter Values
-[ [Normal C++ Syntax] [C++ Parenthesized Syntax] [C99-Only Parenthesized Syntax] ]
-[ [
-`void f(inx x = -1, double y = -1.23)`
-] [
-`(void) (f)( (int x)(default -1) (double y)(default -1.23) )`
-] [
-`(void) (f)(int x, default -1, double y, default -1.23)` /-or-/ `// Authors' choice.`
-
-`(void) (f)( (int x, default -1) , (double y, default -1.23) )` /-or-/
-
-`(void) (f)( (int x)(default -1) , (double y)(default -1.23) )`
-] ]
-]
-
-[section Function Name, Result, Inline, Etc]
-[endsect]
-
-[section Variable Binding]
-[endsect]
-
-[endsect]
-
-[endsect]
-
-[endsect]
-

Deleted: sandbox/local/libs/local/doc/qbk/rationale.qbk
==============================================================================
--- sandbox/local/libs/local/doc/qbk/rationale.qbk 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
+++ (empty file)
@@ -1,550 +0,0 @@
-
-[/ Copyright (C) 2009-2011 Lorenzo Caminiti ]
-[/ Use, modification, and distribution is subject to 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). ]
-
-[section:Rationale Appendix: Rationale]
-
-This section discusses rationale behind library design decisions in addition to the rationale already provided throughout the rationale footnotes in the rest of this documentation.
-
-[section Parenthesized Syntax Rationale]
-
-This section discusses the rationale behind parenthesized syntax design decisions.
-
-[section C99 Preprocessor]
-
-The C99 preprocessor (and therefore the C++0x preprocessor) allows for additional features like specifying empty macro parameters and variadic macro parameters which are not supported by the ISO C++ standard preprocessor.
-The additional features of the C99 preprocessor can be used to simplify the parenthesized syntax mainly by removing extra parenthesis and making it look more like normal C++ syntax.
-
-Most (and maybe all) modern compilers support the C99 preprocessor at this time and all new C++0x compilers will support the C99 preprocessor in the future.
-Therefore, the library macros have been programmed to automatically detect the presence of the C99 preprocessor and accept the simplified parenthesized syntax in these cases.
-The same macro will only accept the parenthesized syntax on non C99 preprocessor but will accept both the parenthesized syntax and the simplified parenthesized syntax on C99 preprocessors.
-This way, programmers that can afford to write C99 specific code can benefit from the simplifications of the parenthesized syntax.
-
-[table
-[ [
-Function Feature
-] [
-Normal C++ Syntax
-] [
-Simplified Parenthesized Syntax (C99 only)
-] [
-Parenthesized Syntax (both C++ and C99)
-] ]
-
-[ [
-/Empty Parameter List/
-] [
-``
- void f() {
- ...
- }
-``
-Or:
-``
- void f(void) {
- ...
- }
-``
-] [
-Using empty macro parameter:
-``
- BOOST_LOCAL_FUNCTION(
- (void) (f)()
- ) {
- ...
- } BOOST_LOCAL_FUNCTION_END(f)
-``
-But also when no recursion and Boost.Typeof for result type:
-``
- // No extra parenthesis at all!
- void BOOST_LOCAL_FUNCTION_PARAMS() {
- ...
- } BOOST_LOCAL_FUNCTION_NAME_END(f)
-``
-] [
-Using `void` parameter list:
-``
- BOOST_LOCAL_FUNCTION(
- (void) (f)( (void) )
- ) {
- ...
- } BOOST_LOCAL_FUNCTION_END(f)
-``
-But also when no recursion and Boost.Typeof for result type:
-``
- void BOOST_LOCAL_FUNCTION_PARAMS( (void) ) {
- ...
- } BOOST_LOCAL_FUNCTION_NAME_END(f)
-``
-] ]
-
-[ [
-/Parameter Types and Names/
-] [
-``
- void f(int x, double& y) {
- ...
- }
-``
-Local functions do not need to access the parameter names separately from their types so they are merged into a single token (even if that reduces the generality of the syntax).
-] [
-Merging parameter type with its name and using variable length tuples:
-``
- BOOST_LOCAL_FUNCTION(
- // Parameter list syntax same as normal.
- (void) (f)(int x, double& y)
- ) {
- ...
- } BOOST_LOCAL_FUNCTION_END(f)
-``
-But also when no recursion and Boost.Typeof for result type:
-``
- // No extra parenthesis at all!
- void BOOST_LOCAL_FUNCTION_PARAMS(int x, double& y) {
- ...
- } BOOST_LOCAL_FUNCTION_NAME(f)
-``
-] [
-Merging parameter type with its name and using sequences:
-``
- BOOST_LOCAL_FUNCTION(
- (void) (f)( (int x) (double& y)
- ) {
- ...
- } BOOST_LOCAL_FUNCTION_END(f)
-``
-But also when no recursion and Boost.Typeof for result type:
-``
- void BOOST_LOCAL_FUNCTION_PARAMS( (int x) (double& y) ) {
- ...
- } BOOST_LOCAL_FUNCTION_NAME(f)
-``
-] ]
-
-[ [
-/Parameter Defaults/
-] [
-``
- void f(int x = -1,
- double y = -1.23) {
- ...
- }
-``
-Parameter defaults need to be separated from their types and names because they cannot be part of function type expressions.
-The symbol `=` cannot be used because it is not alphanumeric so `default` is used instead.
-] [
-Using `default` instead of `=` and variable length tuples:
-``
- BOOST_LOCAL_FUNCTION(
- (void) (f)(int x, default -1,
- double y, default -1.23)
- ) {
- ...
- } BOOST_LOCAL_FUNCTION_END(f)
-``
-But also when no recursion and Boost.Typeof for result type:
-``
- // No extra parenthesis needed.
- void BOOST_LOCAL_FUNCTION_PARAMS(int x, default -1,
- double y, default -1.23) {
- ...
- } BOOST_LOCAL_FUNCTION_NAME(f)
-``
-] [
-Using `default` instead of `=` and sequences:
-``
- BOOST_LOCAL_FUNCTION(
- (void) (f)( (int x)(default -1)
- (double y)(default -1.23) )
- ) {
- ...
- } BOOST_LOCAL_FUNCTION_END(f)
-``
-But also when no recursion and Boost.Typeof for result type:
-``
- void BOOST_LOCAL_FUNCTION_PARAMS( (int x)(default -1)
- (double y)(default -1.23) ) {
- ...
- } BOOST_LOCAL_FUNCTION_NAME(f)
-``
-] ]
-
-[ [
-/Variable Binding/
-] [
-Not supported by C++ (supported by C++0x via lambda functions).
-``
-int a = 0, b = 1, c = 2, d = 3;
-void f(int x) /* bind a, b, c, d somehow... */ {
- ...
-}
-``
-] [
-Using `bind` and `const bind` instead of the parameter type and variable length typles:
-``
- BOOST_LOCAL_FUNCTION(
- (void) (f)(int x, bind a, const bind b, bind& c, const bind& d)
- ) {
- ...
- ) BOOST_LOCAL_FUNCTION_END(f)
-``
-But also when no recursion and Boost.Typeof for result type:
-``
- // No extra parenthesis needed.
- void BOOST_LOCAL_FUNCTION_PARAMS(int x, bind a, const bind b,
- bind& c, const bind& d) {
- ...
- ) BOOST_LOCAL_FUNCTION_NAME(f)
-``
-] [
-Using `bind` and `const bind` instead of the parameter type:
-``
- BOOST_LOCAL_FUNCTION(
- (void) (f)(int x, bind a, const bind b, bind& c, const bind& d)
- ) {
- ...
- ) BOOST_LOCAL_FUNCTION_END(f)
-``
-But also when no recursion and Boost.Typeof for result type:
-``
- // No extra parenthesis needed.
- void BOOST_LOCAL_FUNCTION_PARAMS(int x, bind a, const bind b,
- bind& c, const bind& d) {
- ...
- ) BOOST_LOCAL_FUNCTION_NAME(f)
-``
-] ]
-
-]
-
-[table
- [
- [ Feature ]
- [ Normal C++ Syntax ]
- [ C99 Split Syntax ]
- [ C99 Parenthesized Syntax ]
- [ C++ Split Syntax ]
- [ C++ Parenthesized Syntax ]
- ]
- [
- [ Use variadics macro parameters (limitation -- C99 preprocessor only). ]
- [ ]
- [ Yes. ]
- [ Yes. ]
- [ No. ]
- [ No. ]
- ]
- [
- [ Use empty macro parameter (limitation -- C99 preprocessor only). ]
- [ ]
- [ Yes. ]
- [ Yes. ]
- [ No. ]
- [ No. ]
- ]
- [
- [ Support recursive local function calls. ]
- [ ]
- [ No. ]
- [ Yes. ]
- [ No. ]
- [ Yes. ]
- ]
- [
- [ Always require Boost.Type of for result type (limitation). ]
- [ ]
- [ Yes. ]
- [ No. ]
- [ Yes. ]
- [ No. ]
- ]
- [
- [ Support `inline` local functions. ]
- [ ]
- [ No. ]
- [ Yes. ]
- [ No. ]
- [ Yes. ]
- ]
- [
- [ /Empty parameter list./ ]
- [``
- void f() {
- ...
- }
- ``
- Or:
- ``
- void f(void) {
- ...
- }
- ``]
- [``
- void BOOST_LOCAL_FUNCTION_PARAMS() {
- ...
- } BOOST_LOCAL_FUNCTION_NAME(f)
- ``]
- [``
- BOOST_LOCAL_FUNCTION(
- (void) (f)()
- ) {
- ...
- } BOOST_LOCAL_FUNCTION_END(f)
- ``]
- [``
- void BOOST_LOCAL_FUNCTION_PARAMS( (void) ) {
- ...
- } BOOST_LOCAL_FUNCTION_NAME(f)
- ``]
- [``
- BOOST_LOCAL_FUNCTION(
- (void) (f)( (void) )
- ) {
- ...
- } BOOST_LOCAL_FUNCTION_END(f)
- ``]
- ]
- [
- [ /Parameter types and names./ ]
- [``
- void f(int x, double y) {
- ...
- }
- ``]
- [``
- void BOOST_LOCAL_FUNCTION_PARAMS(
- int x, double y) {
- ...
- } BOOST_LOCAL_FUNCTION_NAME(f)
- ``]
- [``
- BOOST_LOCAL_FUNCTION(
- (void) (f)(int x, double y)
- ) {
- ...
- } BOOST_LOCAL_FUNCTION_END(f)
- ``]
- [``
- void BOOST_LOCAL_FUNCTION_PARAMS(
- (int x) (double y) ) {
- ...
- } BOOST_LOCAL_FUNCTION_NAME(f)
- ``]
- [``
- BOOST_LOCAL_FUNCTION(
- (void) (f)( (int x) (double y) )
- ) {
- ...
- } BOOST_LOCAL_FUNCTION_END(f)
- ``]
- ]
-]
-
-[endsect]
-
-[section Parameter Type and Name Separation]
-
-C++ allows to specify parameter names within function types:
-
- void (int x, double& y)
-
-Therefore, the parenthesized syntax for local functions does not have to separate the function parameter type and name tokens:
-
-[table Parameter Types and Names
-[ [Normal C++ Syntax] [C++ Parenthesized Syntax] [C99-Only Parenthesized Syntax] ]
-[ [
-`void f(int x, double&y)`
-] [
-`(void) (f)( (int x) (double& y) ) // Is this better than its general version below selected by the authors? Local functions don't need the generality...`
-] [
-`(void) (f)(int x, double& y) // Authors' choice.`
-] ]
-]
-
-Note that a more general form of the parenthesized syntax would have been instead:
-[table Separated Parameter Types and Names
-[ [Normal C++ Syntax] [C++ Parenthesized Syntax] [C99-Only Parenthesized Syntax] ]
-[ [
-`void f(int x, double& y)`
-] [
-`(void) (f)( (int)(x) (double&)(y) ) // Authors' choice.`
-] [
-`(void) (f)(int, x, double&, y)` /-or-/
-
-`(void) (f)( (int, x) , (double&, y) )` /-or-/
-
-`(void) (f)( (int)(x) , (double&)(y) )`
-] ]
-]
-
-This more general form makes available the parameter types and names as separate tokens for preprocessor metaprogramming.
-In fact, there is no way for the preprocessor to split `(int x)` into the parameter type `int` and name `x` while it can split `(int)(x)`.
-The parameter types can be split at compile-time (for example to force some parameters to be constant, references, etc):
-
- typedef arg_type<void (int x, double& y), 0>::type arg_type0; // int
- typedef arg_type<void (int x, double& y), 1>::type arg_type1; // double&
-
-But the parameter name `x` remains inaccessible as a token separately from its type.
-However, local function do not need to access parameter types separately from their types so this lack of generality is not an issue for local function and the less general syntax (e.g., `(int x)`) is preferred over the more general one (e.g., `(int)(x)`) because it is simpler as it uses a smaller number of parenthesis and resembles more closely the normal C++ syntax for function parameters.
-
-[note *Overloaded functions.*
-An example where parameter names need to be accessed separately from their types is to support overloading.
-For example, if the macro need to expand to support code for an overloaded function, they might need to generate unique identifiers for symbols within the support code.
-Assume also `__LINE__` cannot be used in this context because the unique identifiers need to be referred by another macro expanding on a different line (so the unique identifier need to be generated upon the function syntactic elements -- function name, parameter names, etc).
-Such identifiers cannot simply use the function name because the same function name is used multiple times when the function is overloaded and therefore the identifiers will not be unique.
-The parameter names can be concatenated by the preprocessor together with the function name to generate such unique identifiers (with the limitation that overloaded function need to used different parameter names and not just different parameter types).
-]
-
-[endsect]
-
-[section Empty Function Parameters]
-
-The C++ preprocessor does not allow to specify an empty macro parameter as a consequence preprocessor sequences cannot contain empty elements `()`.
-Therefore the following parenthesized syntax for a function with no parameter `void f()` is not valid for the C++ preprocessor:
-
- (void) (f)() // Error, cannot use empty `()`.
-
-This syntax is instead valid for the C99 preprocessor because it can instead accept empty macro parameter.
-
-C++ also allow to specify an empty parameter list using `void`:
-
- void f(void)
-
-This leads to the valid parenthesized syntax:
-
- (void) (f)( (void) )
-
-In summary:
-
-[table Empty Function Parameters
-[ [Normal C++ Syntax] [C++ Parenthesized Syntax] [C99-Only Parenthesized Syntax] ]
-[ [
-`void f()`
-] [
-`(void) (f)( (void) ) // Authors' choice.`
-] [
-`(void) (f)() // Authors' choice.`
-] ]
-]
-
-[endsect]
-
-[section Default Parameter Values]
-
-C++ does not allow to specify default parameter values within function types thus the following is not valid:
-
- void (int x = -1, double y = -1.23) // Error, can't specify default parameters within function types.
-
-Therefore, the following parenthesized syntax cannot be used:
-
- (void) (f)( (int x = -1) (double y = -1.23) )
-
-Because:
-
-# It does not allow to strip the default parameter values from the parameter type and name in order to construct and manipulate the local function type.
-# Default parameter values are not part of the type so it is not possible to program a metafunction that counts the number of default parameter values at compile-time but such information is also needed by the local functions in order to properly support default parameters.
-[footnote
-Specifically, the number of default parameter value is needed at compile-time to instantiate the proper `function_ref<typename F, size_t default_parameter_count` template to hold the local function.
-The `function_ref` functor is needed to implement the trick that allows local functions to be passed as template parameters (see [@http://lists.boost.org/Archives/boost/2010/09/170888.php]).
-]
-
-Default parameters can be separated by the rest of the parameter expression using:
-
- (void) (f)( (int x)(default -1) (double y)(default -1.23) )
-
-Or using the more general parameter type/name form (even if not strictly needed by local functions):
-
- (void) (f)( (int)(x)(default -1) (double)(y)(default -1.23) )
-
-Note that the `=` symbol needs to be replaced with the alphanumeric keyword `default` because parenthesized syntax elements cannot start with a non alphanumeric symbol like `=`.
-[footnote
-This is because the parenthesized syntax needs to check if its token matches a keyword like `void`, `inline`, etc.
-This checking is done by concatenating from the front the token with a special library-defined symbol that generates a new macro that will ultimately expand to `1` if and only if the element matches the searched keyword.
-The preprocessor does not allow to concatenate non-alphanumeric tokens so the parenthesized syntax tokens cannot start with a non-alphanumeric token otherwise the concatenation will generate a preprocessor error (see [@http://lists.boost.org/Archives/boost/2010/08/169859.php]).
-]
-
-For C99, some or all the parenthesis can be replaced by commas.
-
-[table Default Parameter Values
-[ [Normal C++ Syntax] [C++ Parenthesized Syntax] [C99-Only Parenthesized Syntax] ]
-[ [
-`void f(inx x = -1, double y = -1.23)`
-] [
-`(void) (f)( (int x)(default -1) (double y)(default -1.23) )` /-or-/
-
-`(void) (f)( (int)(x)(default -1) (double)(y)(default -1.23) ) // Authors' choice.`
-] [
-`(void) (f)(int x, default -1, double y, default -1.23)` /-or-/ `// Authors' choice.`
-
-`(void) (f)( (int x, default -1) , (double y, default -1.23) )` /-or-/
-
-`(void) (f)( (int x)(default -1) , (double y)(default -1.23) )`
-] ]
-]
-
-Default parameter values are probably most useful to overload a public API.
-Therefore, it is not clear how beneficial they are for local functions which will never be publicly available to caller because they are always hidden within the enclosing scope by definition.
-Nevertheless, it seems appropriate for local functions to support default parameter values given that it is technically possible and let programmers decide when and if to leverage such a feature.
-
-[section Function Name, Result, Inline, Etc]
-
-Motivated by the C99-only simplified syntax, we note that if the local function name and result type could be omitted from the local function declaration, the macro invocation will be greatly simplified (using no extra parenthesis at all):
-
- void BOOST_LOCAL_FUNCTION(int x, double y) { // No extra parenthesis at all!
- ...
- } BOOST_LOCAL_FUNCTION_END(f)
- f(1, 1.23);
-
-And for non-C99 preprocessors:
-
- void BOOST_LOCAL_FUNCTION( (int)(x) (double)(y) ) {
- ...
- }
- f(1, 1.23);
-
-However, the above syntax introduces the following limitations:
-
-* Recursive local functions are not possible if the function name is not specified within the function declaration (because the declaration macro expansion cannot define a factor with the local function name before the body is specified given that the function name is only specified by the end macro after the body).
-* The library will require the use of Boost.Typeof to deduce the result type (because it is now specified outside the declaration macro) even when no variable is bound to the local function.
-
-The Boost.Typeof requirements might not be a big limitation however now allowing recursive function calls would be a major limitation -- for example, the following will not be possible:
-
- BOOST_LOCAL_FUNCTION(
- (int) (factorial)(int n)
- ) {
- if (n < 2) return 1;
- else return n * factorial(n - 1); // Recursive call.
- } BOOST_LOCAL_FUNCTION_END(factorial)
- std::cout << factorial(10) << std::endl;
-
-The library could provide a different macros `BOOST_LOCAL_FUNCTION_PARAMS` and `BOOST_LOCAL_FUNCTION_NAME` to still support this syntax simplification at the cost of not allowing recursion and requiring Boost.Typeof to deduce the result type.
-On C99 preprocessors:
-
- void BOOST_LOCAL_FUNCTION_PARAMS(int x, double y) {
- ...
- } BOOST_LOCAL_FUNCTION_NAME(f)
- f(1, 1.23);
-
-And for non-C99 preprocessors:
-
- void BOOST_LOCAL_FUNCTION_PARAMS( (int)(x) (double)(y) ) {
- ...
- } BOOST_LOCAL_FUNCTION_NAME(f)
- f(1, 1.23);
-
-In summary:
-
-
-[endsect]
-
-[section Variable Binding]
-[endsect]
-
-[endsect]
-
-[endsect]
-
-[endsect]
-

Modified: sandbox/local/libs/local/doc/qbk/starting.qbk
==============================================================================
--- sandbox/local/libs/local/doc/qbk/starting.qbk (original)
+++ sandbox/local/libs/local/doc/qbk/starting.qbk 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -20,9 +20,8 @@

* The __Advanced__ section explains advanced usages of the library.
* The __Reference__ section is the reference manual of the library public API.
-* The __Grammar__ section formally describes the parenthesized syntax used by this library to specify the local function signatures.
-* The __Alternatives__ section describes alternatives to this library to implement local functions.
* The __Examples__ section lists the source code of a few additional examples that use this library.
+* The __Alternatives__ section describes alternatives to this library to implement local functions.

The following sections are for reference only:

@@ -66,7 +65,9 @@
     ``[headerref boost/local/function.hpp] /local functions/``
     ``[headerref boost/local/block.hpp] /local blocks/``
     ``[headerref boost/local/exit.hpp] /local exits/``
- ``[headerref boost/local/function_ref.hpp] /references to local functions/``
+ ``[headerref boost/local/typeof.hpp] /bound variable type deduction/``
+ ``[headerref boost/local/function.hpp] /local functors/``
+ ``[headerref boost/local/config.hpp] /configuration macros/``

[endsect]

@@ -77,7 +78,7 @@
*Rationale.*
This library concatenates symbols specified by the programmers (e.g., the local function name) with other symbols (e.g., special prefixes or preprocessor line numbers) to make internal symbols with unique names to avoid name clashes.
These symbols are separated by the letter "`X`" when they are concatenated so they can be read more easily while debugging the library.
-The underscore character "`_`" could not be used instead of the letter "`X`" because if the original symbols already contain a leading or trailing underscore the concatenation would result in a symbol with double underscores "`__`" which is reserved by the C++ standard.
+The underscore character "`_`" could not be used instead of the letter "`X`" because if the original symbols already contained a leading or trailing underscore, the concatenation would result in a symbol with double underscores "`__`" which is reserved by the C++ standard.
]

* Any symbol defined by files within the `"boost/local/aux_/"` directory (these header files should not be directly included by programmers).
@@ -93,7 +94,7 @@
If a configuration macro is left undefined, the library will use an appropriate default value for it.

All configuration macros have names prefixed by `BOOST_LOCAL_CONFIG` (see __Reference__ section).
-It is strongly recommended not to change this library configuration macros unless strictly necessary.
+It is strongly recommended not to change the library configuration macro definitions unless strictly necessary.

[endsect]

Modified: sandbox/local/libs/local/doc/qbk/tutorial.qbk
==============================================================================
--- sandbox/local/libs/local/doc/qbk/tutorial.qbk (original)
+++ sandbox/local/libs/local/doc/qbk/tutorial.qbk 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -1,184 +1,143 @@

[/ Copyright (C) 2009-2011 Lorenzo Caminiti ]
-[/ Use, modification, and distribution is subject to 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). ]
+[/ Use, modification, and distribution is subject to 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). ]

[section:Tutorial Tutorial]

-This section illustrates basic usages of local functions, local blocks, and local exits.
+This section illustrates basic usage of local functions, local blocks, and local exits.

-[section Parenthesized Syntax]
+[section Local Functions]

-The /parenthesized syntax/ is used to pass the syntactic elements of a function signature as macro parameters in a way that resembles the usual C++ syntax.
-All the function signature elements are wrapped within round parenthesis `()` to form a __Boost_Preprocessor__ sequence called /parenthesized signature/.
-This allows to program preprocessor macros that can parse the parenthesized syntax expanding differently based on the different elements that are specified in the signature (if the function has parameters or not, if the result type token matches the `void` keyword or not, etc).
+Local functions are defined using the following macros (see the __Reference__ section) from within a declarative context (this is a limitation with respect to __CPP0x_lambda__ functions which can instead be declared within expressions):

-[important
-The *general rules to program the parenthesized signature* are:
+ { // Some declarative context.
+ ...

-1. Wrap all the signature syntactic elements within parenthesis `()`.
-[footnote
-The parenthesized syntax owes its name to the indeed large number of parenthesis `()` that are required to wrap its elements.
-Programmers might notice some similarities between the parenthesized syntax and the syntax of the __LISP__ programming language.
-However, these similarities are not intentional in that they were not a design choice but rather a consequence of the fact that both __LISP__ sequences and __Boost_Preprocessor__ sequences are formed by wrapping tokens within round parenthesis `()`.
-]
+ ``/result-type/`` __BOOST_LOCAL_FUNCTION_PARAMS__(``/parameters/``) {
+ ``/body-code/``
+ } __BOOST_LOCAL_FUNCTION_NAME__(``/name/``)

-2. If a token does not start with an alphanumeric symbol (i.e., `a-z`, `A-Z`, or `0-9`), replace the token with its alphanumeric equivalent (as indicated in the __Grammar__ section).
-[footnote
-*Rationale.*
-This constraint comes form the fact that the C++ preprocessor can only concatenate =##= alphanumeric symbols.
+ ...
+ }
+
+The expansion of this macros declares a functor object with the local function name that can be called from the enclosing scope.
+The usual C++ scope visibility rules apply to local functions for which a local function is visible and can be called only within the enclosing scope in which it is declared.
+
+The local function parameters are passed to the `__BOOST_LOCAL_FUNCTION_PARAMS__` macro either using the /sequencing macro syntax/ (which separates the parameters by wrapping them within round parenthesis `()` and it is supported on all C++ compilers) or using the /variadic macro syntax/ (which separates the parameters using a comma `,` but it is supported only on C99 and later compilers):
+
+[table
+[ [Variadic Macro Syntax (C99 and later compilers)] [Sequencing Macro Syntax (all C++ compilers)] ]
+[ [
+`__BOOST_LOCAL_FUNCTION_PARAMS__(`[^/parameter-type1 parameter-name1/]`,` [^/parameter-type2 parameter-name2 .../]`)`
+] [
+`__BOOST_LOCAL_FUNCTION_PARAMS__( (`[^/parameter-type1 parameter-name1/]`) (`[^/parameter-type2 parameter-name2/]`)` [^/.../]`)`
+] ]
]

-3. Empty parenthesis `()` are not allowed.
+The local function body is specified in a code block `{ ... }` using the usual C++ syntax.
+The body is specified outside any of the macros so eventual compiler error messages and line numbers retain their usual meaning.
[footnote
*Rationale.*
-This constraint comes from the fact that the ISO C++ standard preprocessor forbids empty macro parameters (this is different for C99 and other more recent preprocessors).
-]
-
-4. Spaces and newlines do not matter and they can be used anywhere.
+If the local function body were instead passed as a macro parameter, it would be expanded on a single line of code (because macros always expand as a single line of code).
+Therefore, eventual compiler error line numbers would all have the same value and would no longer be useful to pinpoint the error.
]

-For example, let's rewrite the following C++ function signature using the parenthesized syntax:
-
- int l(double& y, const double& x = 0.0)
-
-[*Step 1.]
-We start by wrapping all the syntactic elements within round parenthesis `()`:
-
- (int) (l)( (double&)(y) (,) (const double&)(x)(=)(0.0) ) ``[*=/* wrap all elements within parenthesis `()` */=]``
-
-Note how parameter types are wrapped within parenthesis separately from parameter names.
-However, all the tokens of a parameter type are wrapped together within a single set of parenthesis because the parameter type is one single syntactic element of the function signature.
-For example, `x`'s type is specified by `(const double&)` and not by `(const)(double)(&)`.
-
-[*Step 2.]
-We note that the element `(,)` wraps the non-alphanumeric symbol "`,`" so it needs to be replaced.
-The parenthesized syntax requires no special delimiter to separate function parameters (see the __Grammar__ section) so `(,)` can simply be removed (if you like, you can use a space or a newline to separate the function parameters):
-
- (int) (l)( (double&)(y) ``[*=/* use spaces or newlines instead of commas to separate parameters */=]`` (const double&)(x)(=)(0.0) )
-
-[*Step 3.]
-We note also that the element `(=)` wraps the non-alphanumeric symbol "`=`" so it also needs to be replaced.
-The parenthesized syntax uses the keyword `default` to specify a parameter default value (see the __Grammar__ section) so `(=)` is replaced by `(default)`:
-
- (int) (l)( (double&)(y) (const double&)(x)``*(default)*``(0.0) )
-
-We are done.
-The following is the valid parenthesized signature:
-
- (int) (l)( (double&)(y) (const double&)(x)(default)(0.0) )
-
-for a function:
-
-* With `int` result type.
-* Named `l`.
-* With one required parameter of type `double&` and named `y`.
-* With an optional parameter of type `const double&`, named `x`, and with default value `0.0`.
-
-[warning
-Unfortunately, there are intrinsic limitations to the amount of syntactic error checking that can be done by the parsing macros implemented using the preprocessor.
-As a consequence, an error in using the parenthesized syntax might result in *cryptic preprocessor errors*.
-The best way to identify and correct these errors is usually to visually inspect the signature comparing it with the parenthesized syntax grammar (see the __Grammar__ section).
-When syntactic errors can be detected by the parsing macros, they are raised at compile-time using error messages of the form `ERROR_`/description_text/.
+The macro `__BOOST_LOCAL_FUNCTION_NAME__` is used to end the local function definition and to specify the local function name.
[footnote
-While there are fundamental limitations to the amount of parenthesized syntax error checking that can be done using the preprocessor (e.g., there is no way to gracefully detect and report a missing parenthesis "`)`"), the current implementation of the parsing macros does not perform all the error checking that could be done.
-Improving the parenthesized syntax error checking is a work in progress.
-Programmers are encouraged to report cryptic error messages they experience because of parenthesized syntax errors so to help this development effort.
-]
+*Rationale.*
+The local function name must be passed to the macro `__BOOST_LOCAL_FUNCTION_NAME__` ending the function definition so this macro can declare a local variable with the local function name to hold the local functor object.
]

-[h5 Functions With No Parameters]
-
-Let's rewrite the following C++ signature for a function with no parameters using the parenthesized syntax:
-
- int l()
-
-If we wrap all the elements within parenthesis we have:
+For example, let's program a local function named `add` that takes two integer numbers `x` and `y`, and adds them together -- for simplicity, we will not bind any of the variables in scope just yet (binding is explained later in this section):

- (int) (l)``*()*`` // Error: Empty parenthesis `()` cannot be used.
-
-However, this is not a valid parenthesized signature because it contains the empty parenthesis `()`.
-
-[note
-This limitation applies to the ISO C++ standard preprocessor but it does not apply to the C99 and other more recent preprocessors.
-This library allows the *use of empty parenthesis* `()` if the preprocessor used supports empty macro parameters.
-However, programmers should be well aware that if they use empty parenthesis in the parenthesized syntax, the code is not C++ ISO standard compliant and it will be less portable (that is why the use of empty parenthesis is excluded by the __Grammar__ section).
+[table
+[ [Variadic Macro Syntax (C99 and later compilers)] [Sequencing Macro Syntax (all C++ compilers)] ]
+[ [ [add_x_y_va_cpp] ] [ [add_x_y_cpp] ] ]
]

-C++ also allows to use the keyword `void` to specify empty parameter lists.
-Therefore, the original C++ function signature can be equivalently rewritten as:
-
- int l(void)
-
-If we now wrap all the elements within parenthesis we obtain the valid parenthesized signature:
-
- (int) (l)( (void) ) // OK: Use `(void)` for empty parameter lists.
-
-In conclusion, the parenthesized syntax requires to use `(void)` to indicate an empty parameter list (see the __Grammar__ section).
+Note that not all compilers that support variadic macros also support empty macro parameters.

[endsect]

-[section Local Functions]
+[section:Empty_Parameters Empty Parameters]

-Local functions are defined using the following macros (see the __Reference__ section) from within a declarative context (this is a limitation with respect to __CPP0x_lambda__ functions which can instead appear within expressions):
+C++ allows to specify a function with no parameters using the empty parenthesis `()`.
+For example, let's program a function `ten` which takes no parameter and returns the integer number `10`:

- { // Some declarative context.
- ...
+ int ten() {
+ return 10;
+ }

- __BOOST_LOCAL_FUNCTION__(
- ``/parenthesized-signature/``
- ) {
- ``/local-function-body/``
- } __BOOST_LOCAL_FUNCTION_END__(``/local-function-name/``)
+The ISO C++ standard does not allow pass empty parameters to a macro so the macro `__BOOST_LOCAL_FUNCTION_PARAMS__` cannot be invoked with an empty set of parenthesis `()` unless programmers use compiler extensions that support empty macro parameters (e.g., C99 and later compilers).
+However, C++ also allows to specify an empty parameter list using the keyword `void`:

- ...
+ int ten(void) {
+ return 10;
     }

-This creates a functor object with the local function name that can be called from the enclosing scope.
-Note that:
-
-* The usual C++ scope visibility rules apply to local functions for which a local function is visible and can be called only within the enclosing scope in which it is defined.
-* The local function signature is expressed using the parenthesized syntax and passed to the `__BOOST_LOCAL_FUNCTION__` macro.
-* The local function body is defined in a code block `{ ... }` using the usual C++ syntax.
-The body is specified outside any of the macros so eventual compiler error messages and line numbers retain their usual meaning.
-[footnote
-*Rationale.*
-If the local function body were instead passed as a macro parameter, it would be expanded on a single line of code (because macros always expand as a single line of code).
-Therefore, eventual compiler error line numbers would all have the same value and would no longer be useful to pinpoint the error.
+Therefore, on all C++ compilers the macro `__BOOST_LOCAL_FUNCTION_PARAMS__` can be invoked passing one parameter `(void)` to specify an empty parameter list.
+In addition, on compilers that support variadic macros, the macro `__BOOST_LOCAL_FUNCTION_PARAMS__` can be invoked passing one parameter `void` (without the extra parenthesis).
+In summary, depending on your compiler support for empty macro parameters and variadic macros, this library accepts any of the following syntaxes to specify an empty parameter list:
+
+[table
+[ [Empty Macro Syntax (C99 and later compilers)] [Variadic Macro Syntax (C99 and later compilers)] [Sequencing Macro Syntax (all C++ compilers)] ]
+[ [
+`__BOOST_LOCAL_FUNCTION_PARAMS__()`
+] [
+`__BOOST_LOCAL_FUNCTION_PARAMS__(void)`
+] [
+`__BOOST_LOCAL_FUNCTION_PARAMS__( (void) )`
+] ]
+]
+
+For example, let's program the function `ten` as a local function:
+
+[table
+[ [Empty Macro Syntax (C99 and later compilers)] [Variadic Macro Syntax (C99 and later compilers)] [Sequencing Macro Syntax (all C++ compilers)] ]
+[ [ [ten_ep_cpp] ] [ [ten_va_cpp] ] [ [ten_cpp] ] ]
]
-* The macro `__BOOST_LOCAL_FUNCTION_END__` is used to end the local function definition and it must repeat the local function name.
-[footnote
-*Rationale.*
-The local function name must be passed to the ending macro `__BOOST_LOCAL_FUNCTION_END__` so this macro can declare a local variable with the local function name to hold the local functor object.
-At the same time, the local function name must also be passed to the declaration macro `__BOOST_LOCAL_FUNCTION__` to allow the local function to recursively call itself.
-The local function declaration and ending macros are kept as two separate macros so that the local function body does not have to be passed as a macro parameter (otherwise, the compiler error line numbers will all appear on the same line and they will no longer be useful to pinpoint the errors).
-]
-The compiler will generate an error if the name specified by this macro does not match the one from the local function signature (see `__BOOST_LOCAL_FUNCTION_END_RENAME__` to remove this constraint).

-For example, let's program a local function `add` similar to the one in the example from the __Introduction__ section.
-We start by rewriting its signature:
+[endsect]

- void add(double num)
+[section Default Parameters]

-using the parenthesized syntax:
+This library also allows to specify default values for the local function parameters.
+However, the usual C++ syntax for default parameters that uses the assignment symbol `=` cannot be used.
+[footnote
+[*Rationale.] The assignment symbol `=` cannot be used to specify default parameter values because default values are not part of the parameter type so they cannot be handled using template metaprogamming.
+Default parameter values need to be separated from the rest of the parameter declaration using the preprocessor.
+Specifically, this library needs to use preprocessor mataprogramming to remove default values when constructing the local function type and it counts the number of default values to provide the correct set of call operators for the local functor object.
+]
+The keyword `default` is used instead:

- (void) (add)( (double)(num) )
+[table
+[ [Variadic Macro Syntax (C99 and later compilers)] [Sequencing Macro Syntax (all C++ compilers)] ]
+[ [
+[^/parameter-type parameter-name/]`, default` [^/parameter-default-value/]`,` [^/.../]
+] [
+`(`[^/parameter-type parameter-name/]`)(default` [^/parameter-default-value/]`)` [^/.../]
+] ]
+]

-For simplicity, we will not bind any of the variables in scope just yet (binding is explained later in this section).
+For example, let's assume that the we want to program a local function `add(x, y)` similar to the one programmed above but where the second parameter `y` is optional and has a default value of `2`:

-Then we pass the parenthesized signature to the `__BOOST_LOCAL_FUNCTION__` macro, we implement a simple body that prints the number, and we pass the local function name `add` to the `__BOOST_LOCAL_FUNCTION_END__` macro:
+[table
+[ [Variadic Macro Syntax (C99 and later compilers)] [Sequencing Macro Syntax (all C++ compilers)] ]
+[ [ [add_x_y_default_va_cpp] ] [ [add_x_y_default_cpp] ] ]
+]

-[add_num_cpp]
+If this variadic macro syntax seems strange, programmers could define a `WITH_DEFAULT` macro similar to the following if they think it improves readability:

-This creates a local function `add` that can be called from within the enclosing scope as for example by the `add(100.0);` instruction.
+[add_x_y_default_with_va_cpp]

[endsect]

-[section Binding]
+[section:Binding Binding]

Variables in scope (local variables, enclosing function parameters, member variables, the object `this`, etc) can be bound to a local function declaration.
-Variables in scope can be bound by reference, by constant reference, by value, or by constant value.
The types of bound variables are automatically deduced by this library using __Boost_Typeof__.
[footnote
*Rationale.*
@@ -192,104 +151,93 @@
User defined *types need to be manually registered* as usual when using __Boost_Typeof__ (see __Boost_Typeof__ documentation and the Local Exit example from the __Examples__ section).
]

-The parenthesized syntax introduces the additional "keyword" `bind` which is used to list all the bound variable names wrapped within parenthesis at the end of the local function parameter list (see the __Grammar__ section):
-
- (``/result-type/``) (``function-name``)( ``/parameters/`` ``*(bind)(*``(``/var1/``)(``/var2/``)``/.../``(``/varN/``)``*)*`` )
-
-Where /var/ is the name of the variable in scope to bind and it is prefixed by `&` if the variable is bound by reference, otherwise is it bound by value.
-
-For example, let's assume we want to bind two variables in scope `a` and `b` to the local function `l` shown before.
-Let's also assume we want to bind `a` by value and `b` by reference.
-Then we use the following parenthesized signature for the local function:
+This library introduces the new "keyword" `bind`
+[footnote
+The token `bind` is not a real keyword of the C++ language.
+This library parses `bind` during macro expansion using preprocessor metaprogramming.
+Therefore, `bind` can be considered a new "keyword" only at the preprocessor metaprogramming level within the syntax defined by the macros of this library -- thus it is referred to as a "keyword" only within quotes.
+]
+which is used in place of the parameter type to specify the name of a variable in scope to bind.
+The variable can be bound by value:
+
+ bind ``/variable-name/`` // Bind by value.
+
+Or by reference if the variable name is prefixed by `&`:

- (int) (l)( (double&)(y) (const double&)(x)(default)(0.0) (bind)((a)(&b)) )
+ bind& ``/variable-name/`` // Bind by reference.
+
+Furthermore, the "keyword" `bind` can be prefixed by `const` to bind the variable by constant value:
+
+ const bind ``/variable-name/`` // Bind by constant value.

+Or by constant reference:
+
+ const bind& ``/variable-name/`` // Bind by constant value.
+
If a variable is bound by value, then a copy of the variable value is taken at the point of the local function declaration.
If a variable is bound by reference instead, the variable will refer to the value it has at the point of the local function call.
-Furthermore, it is the programmers' responsibility to ensure that variables bound by reference survive the scope of declaration of the local function otherwise the bound references will be invalid causing run-time errors (in other words, the usual care in using C++ references must be used for variables in scope bound by reference).
-It is also possible to bind a local function to another local function as shown in the STL Transform example from the __Examples__ section (note that local functions cannot be copied so they are always bound by reference even if `&` is not specified).
+Furthermore, it is the programmers' responsibility to ensure that variables bound by reference survive the scope of declaration of the local function otherwise the bound references will be invalid causing run-time errors (in other words, the usual care in using C++ references must be used for variables bound by reference).

The type of bound variables is automatically deduced and it is the exact same type used to declare such variables in the enclosing scope.
-Therefore:
-
-* If a bound variable was declared constant using the `const` qualifier then it will be bound by constant value or reference.
-* If a bound variable was not declared constant then it will not be bound as constant.
-This library allows to force constant biding even for variables that are not originally declared constant using `(const bind)(...)` as explained below.
-* You might want to bind variables of complex types by (constant) reference instead than by value to avoid expensive copy operations when these variables are automatically passed to the local function (as usual with C++ function parameter passing).
-
-For example, let's continue to program a local function `add` similar to the one from the example in __Introduction__ section.
-We bind the local variable `sum` by (non-constant) reference and update the body to perform the summation:
-
-[add_num_sum_cpp]
-
-[h5 Constant Binding]
-
-Constant binding allows to bind variables in scope by constant reference or constant value (constant binding is not supported by __CPP0x_lambda__ functions).
+Therefore, if a bound variable was declared constant using the `const` qualifier then it will be bound by constant value or reference and if a bound variable was not declared constant then it will not be bound as constant unless constant binding is forced using `const bind ...` (note that binding by constant reference is not supported by __CPP0x_lambda__ functions).
[footnote
An historical note: Constant binding of variables in scope was the main use case that originally motivated the authors in developing this library.
The authors needed to locally create a chuck of code to assert some correctness conditions while these assertions were not supposed to modify any of the variables they were using (see the __Contractpp__ library).
This was achieved by binding by constant reference the variables needed by the assertions and then by programming the local function body to check the assertions (or more conveniently by using `__BOOST_LOCAL_BLOCK__`).
This way if any of the assertions mistakenly changes a bound variable (for example confusing the operator `==` with `=`), the compiler correctly generates an error because the bound variable is of `const` type within the local function body.
]
+Programmers might want to bind variables of complex types by (constant) reference instead than by value to avoid expensive copy operations when these variables are automatically passed to the local function (as usual with C++ function parameter passing).

-The parenthesized syntax uses the "keywords" `const bind` to list constant bound variables wrapped within parenthesis at the end of the function parameter list (see the __Grammar__ section):
-
- (``/result-type/``) (``function-name``)( ``/parameters/`` ``*(const bind)(*``(``/cvar1/``)(``/cvar2/``)``/.../``(``/cvarM/``)``*)*`` )
-
-Where /cvar/ is the name of the variable in scope to bind by constant and it is prefixed by `&` if the variable is bound by constant reference, otherwise it is bound by constant value.
-If both constant and plain bindings are used, constant bindings must be specified before plain bindings (see the __Grammar__ section):
-
- (``/result-type/``) (``function-name``)( ``/parameters/`` (const bind)((``/cvar1/``)(``/cvar2/``)``/.../``(``/cvarM/``)) (bind)((``/var1/``)(``/var2/``)``/.../``(``/varN/``)) ) /* `(const bind)(...)` before `(bind)(...)` */
+For example, let's program a local function `add` similar to the one in the example from the __Introduction__ section.
+We bind the local variable `factor` by constant value, the local variable `sum` by (non-constant) reference, and program the body to perform the summation:

-For example, let's assume we want to bind two variables in scope `c` and `d` to the local function `l` shown before.
-Let's also assume we want to bind `c` by constant value and `b` by costant reference.
-Then we use the following parenthesized signature for the local function:
+[table
+[ [Variadic Macro Syntax (C99 and later compilers)] [Sequencing Macro Syntax (all C++ compilers)] ]
+[ [ [add_num_factor_sum_va_cpp] ] [ [add_num_factor_sum_cpp] ] ]
+]

- (int) (l)( (double&)(y) (const double&)(x)(default)(0.0) (const bind)((c)(&d)) )
-
-If the variables in scope `a` and `b` are also bound but by (plain) value and reference respectively then the parenthesized signature becomes:
-
- (int) (l)( (double&)(y) (const double&)(x)(default)(0.0) (const bind)((c)(&d)) (bind)((a)(&b)) )
+[h5 Binding the Object `this`]

-Note how `(const bind)(...)` must always be used before `(bind)(...)` when they are both present.
+It is also possible to bind the object `this` when it is in scope (e.g., from an enclosing member function).
+This is done by using `this` as the name of the variable to bind and by using the special symbol `this_` (instead of `this`) to access the object within the local function body.

-For example, let's continue to program a local function `add` similar to the one in the example from the __Introduction__ section.
-We bind the local variable `factor` by constant value and update the body to perform the factor scaling:
+The object `this` can be bound by value:

-[add_num_factor_sum_cpp]
+ bind this // Bind the object `this` by value.

-[h5 Binding the Object `this`]
+In this case the local function will be able to modify the object when the enclosing scope is not a constant member, or it will not be able to modify the object when the enclosing scope is a constant member.
+Otherwise, the object `this` can be bound by constant value:

-It is also possible to bind the object `this` when it is in scope (from enclosing member functions, etc).
-This is done by using `this` as the name of the variable to bind and by using the special symbol `this_` (instead of `this`) to access the object within the local function body.
-Note that:
+ const bind this // Bind the object `this` by constant value.

-* The object `this` can be bound by value using `(bind)((this)...)`.
-In this case the local function will be able to modify the object when the enclosing scope is a non-constant member, or it will not be able to modify the object when the enclosing scope is a constant member.
-* The object `this` can be bound by constant value `(const bind)((this)...)`.
In this case the local function will never be able to modify the object (regardless of whether the enclosing scope is a constant member or not).
-* Finally, the object `this` can never be bound by reference because C++ does not allow to get a reference to `this`.
-You will get a compile-time error if you try to use `(bind)((&this)...)` or `(const bind)((&this)...)`.
-However, `this` is a pointer so the object is not copied even if it is bound by value.
-(Note that it is not possible to bind `*this` because it starts with `*` and it is not a variable name.)

-[important
+Note that the object `this` can never be bound by reference because C++ does not allow to obtain a reference to `this` (the library will generate a compile-time error if programmers try to use `bind& this` or `const bind& this`).
+Note that `this` is a pointer so the object is not copied even if it is bound by value (it is not possible to bind `*this` because `*this` is an expression and not a valid name of a variable in scope).
+
+[warning
When the object `this` is bound to a local function, the local function *body must use the special symbol* `this_` (instead of `this`) to access the bound object.
[footnote
*Rationale.*
This limitation comes from the fact that `this` is a reserved C++ keyword so it cannot be used as the name of the internal parameter passing the bound object to the local function body.
It would be possible to use `this` (instead of `this_`) within the local function body either at the expenses of copying the bound object (which would introduce run-time overhead and also the stringent requirement that the bound object must have a deep copy constructor) or by relying on an [@http://groups.google.com/group/comp.lang.c++.moderated/browse_thread/thread/d3a86f27277f713b undefined behaviour of `static_cast`] (which might not work on all platforms at the cost of portability).
]
-Using `this` within the local function body will generate a compile-time error so programmers cannot mistakenly confuse the use of `this_` with `this`.
+
+Unfortunately, mistakenly using `this` within the local function body instead of `this_` will not necessarily generate a compile-time error.
[footnote
*Rationale.*
-This is because the body function is implemented as static function of the local functor class.
+The local function body cannot be a static member function of the local functor object in order to support recursion (because the local function name is specified by the `__BOOST_LOCAL_FUNCTION_NAME__` macro only after the body so it must be make available via a functor member variable named after the local function and local classes cannot have static member variables in C++) and nesting (because the argument binding variable must be declared as a member function so it is visible in a local function nested within another local function body).
+Therefore, from within the local function body the variable `this` is visible but it refers to the local functor object and not to the bound object.
]
+Programmers are responsible to make sure that `this` is never used within a local function body which should only use the special symbol `this_`.
]

For example, let's rewrite a local function `add` similar to the one in the example from the __Introduction__ section but using a member function to illustrate how to bind the object `this`:

-[add_this_cpp]
+[table
+[ [Variadic Macro Syntax (C99 and later compilers)] [Sequencing Macro Syntax (all C++ compilers)] ]
+[ [ [add_this_va_cpp] ] [ [add_this_cpp] ] ]
+]

[endsect]

@@ -300,48 +248,34 @@
     { // Some declarative context.
         ...

- __BOOST_LOCAL_BLOCK__( ``/parenthesized-binding/`` ) {
- ``/block-body/``
+ __BOOST_LOCAL_BLOCK__(``/bindings/``) {
+ ``/body-code/``
         } __BOOST_LOCAL_BLOCK_END__

         ...
     }

-This expands to code that executes the body instructions in place where the block is defined.
-However, only bound variables specified by the /parenthesized-binding/ are accessible from within the local block body.
-
-Adopting a parenthesized syntax similar to the one used for local functions (see the __Grammar__ section), the /parenthesized-binding/ can specify to bind no variable:
-
- (void)
-
-Or, to bind variables by constant type only:
-
- (const bind)((``/cvar1/``)(``/cvar2/``)``/.../``(``/cvarM/``))
-
-Or, to bind variables by plain type only:
-
- (bind)((``/var1/``)(``/var2/``)``/.../``(``/varN/``))
-
-Or, to bind variables by both constant and plain types:
+These macros expand to code that executes the body instructions "in place" where the block is defined.

- (const bind)((``/cvar1/``)(``/cvar2/``)``/.../``(``/cvarM/``)) (bind)((``/var1/``)(``/var2/``)``/.../``(``/varN/``))
-
-Where /cvar/ and /var/ are the names of the variables in scope to bind.
-They can be prefixed by `&` to bind by reference instead of by value, and one of them can be `this` to bind the object when it is in scope.
+Only bound variables specified bu [^/bindings/] are accessible from within the local block body.
+Following the same syntax used for local functions, [^['bindings]] can either be empty (using `(void)`, `void`, or an empty macro parameter depending on your compiler extensions, see __Tutorial_Empty_Parameters__), or they can list the variables to bind using the "keyword" `bind` in place of the parameter type, using `const bind` for constant binding, prefixing the bound variable name with `&` to bind by reference, and using `this` to bind the object in scope (see __Tutorial_Binding__).

[important
-A `return;` instruction from within a local block jumps to the end of the local block body and *it does not return the enclosing scope*.
+A `return;` instruction from within a local block jumps to the end of the local block body and *it does not return the enclosing function*.
[footnote
*Rationale.*
Programmers might expect `return;` to exit the enclosing function instead of the local block (or local exit), especially if the enclosing function has a `void` result type.
-However, using `return;` to exit local blocks (and local exits) seemed to follow a more natural syntax and also it is the same syntax already provided by __Boost_ScopeExit__ (in fact, `return;` is used by __Boost_ScopeExit__ to exit the local scope and not to exit the enclosing scope).
-However, if programmers were to find this use of `return;` confusing, this library API could be changed to forbid the use of `return` from within local blocks (and local exits) generating a compile-time error, and to use a different instruction (e.g., `break;` or a special macro instruction like `BOOST_LOCAL_RETURN;`) to exit local blocks (and local exits).
+However, using `return;` to exit local blocks (and local exits) seemed to follow a natural syntax and also it is the same syntax already provided by __Boost_ScopeExit__ (in fact, `return;` is used by __Boost_ScopeExit__ to exit the local scope and not to exit the enclosing scope).
+If programmers were to find this use of `return;` confusing, this library API could be changed to forbid the use of `return` from within local blocks (and local exits) generating a compile-time error, and to use a different instruction (e.g., `break;` or a special macro instruction like `BOOST_LOCAL_RETURN;`) to exit local blocks (and local exits).
]
]

For example, let's program a local block similar to the one in the example from the __Introduction__ section:

-[add_block_cpp]
+[table
+[ [Variadic Macro Syntax (C99 and later compilers)] [Sequencing Macro Syntax (all C++ compilers)] ]
+[ [ [add_block_va_cpp] ] [ [add_block_cpp] ] ]
+]

[endsect]

@@ -352,39 +286,61 @@
     { // Some declarative context.
         ...

- __BOOST_LOCAL_EXIT__( ``/parenthesized-binding/`` ) {
+ __BOOST_LOCAL_EXIT__(``/bindings/``) {
             ``/exit-body/``
         } __BOOST_LOCAL_EXIT_END__

         ...
     }

-This expands to code that executes the body instructions when the enclosing scope is exited (i.e., at the very end of the enclosing scope).
-If multiple local exits are defined within the same scope, their bodies will be executed in the reverse order in which they have been defined.
-Only bound variables specified by /parenthesized-binding/ are accessible from within the local exit body.
-The /parenthesized-biding/ is specified following the exact same syntax as for the one used by local blocks.
+These macros expand to code that executes the body instructions when the enclosing scope is exited (i.e., at the very end of the enclosing scope).
+If multiple local exits are declared within the same scope, their bodies will be executed in the reverse order in which they have been declared.
+The execution of the local exit code can be guaranteed only if the program does not terminate because of an uncaught exception.
+[footnote
+*Rationale.*
+This library (as well as __Boost_ScopeExit__) uses the destructor of a local variable to automatically execute the local exit code upon exit of the enclosing scope.
+However, in C++ it is no possible to (portably) ensure the execution of the destructor of all objects if the main program terminates because of an uncaught exception.
+(This is different from the D programming language which executes the scope exit code even if the main program terminates because of an uncaught exception.)
+]
+
+Only bound variables specified by [^['bindings]] are accessible from within the local exit body.
+Following the same syntax used for local functions, [^['bindings]] can either be empty (using `(void)`, `void`, or an empty macro parameter depending on your compiler extensions, see __Tutorial_Empty_Parameters__), or they can list the variables to bind using the "keyword" `bind` in place of the parameter type, using `const bind` for constant binding, prefixing the bound variable name with `&` to bind by reference, and using `this` to bind the object in scope (see __Tutorial_Binding__).

-[note
-A `return;` instruction from within a local exit jumps to the end of the local exit body and *it does not return the enclosing scope*.
+[important
+A `return;` instruction from within a local exit jumps to the end of the local exit body and *it does not return the enclosing function*.
]

For example, let's program a local exit similar to the one in the example from the __Introduction__ section:

-[add_exit_cpp]
+[table
+[ [Variadic Macro Syntax (C99 and later compilers)] [Sequencing Macro Syntax (all C++ compilers)] ]
+[ [ [add_exit_va_cpp] ] [ [add_exit_cpp] ] ]
+]

-Local exits are very similar to the functionality already provided by __Boost_ScopeExit__ with the addition that they also support constant binding and the binding of the object `this`.
+Local exits are very similar to the /scope exits/ provided by __Boost_ScopeExit__ with the addition that they also support constant binding and binding of the object `this`.
[footnote
*Rationale.*
This library could be merged together with __Boost_ScopeExit__ into a new library named Boost.Scope (from the meaning of the word "[@http://en.wikipedia.org/wiki/Scope_(programming) scope]" in computer programming).
This would be justified by the fact that `__BOOST_LOCAL_EXIT__` simply extends the functionality already provided by `BOOST_SCOPE_EXIT`.
-The headers will be `"boost/scope/function.hpp"`, `"boost/scope/block.hpp"`, and `"boost/scope/exit.hpp"`.
-For backward compatibility with __Boost_ScopeExit__, the header `"boost/scope_exit.hpp"` could also be kept and it would be equivalent to including `"boost/scope/exit.hpp"`.
-In addition and again for backward compatibility, the `BOOST_SCOPE_EXIT` macro could be extended to accept either the original __Boost_ScopeExit__ sequence of `(var1)...(varN)` without the `bind` "keyword" (which would be equivalent to plain binding) or the parenthesized binding sequence with the `(bind)(...)` and `(const bind)(...)` "keywords" plus the binding of the object `this`.
-Local blocks would be named "scope blocks" and they would be provided by the `BOOST_SCOPE_BLOCK...` macros.
+The headers will be `"boost/scope/function.hpp"`, `"boost/scope/block.hpp"`, and `"boost/scope/exit.hpp"` (for backward compatibility with __Boost_ScopeExit__, the header `"boost/scope_exit.hpp"` could also be kept and it would be equivalent to including `"boost/scope/exit.hpp"`).
+However, the new `BOOST_SCOPE_EXIT` macro will not be backward compatible with the current __Boost_ScopeExit__ macro because it will require to prefix the bound variable with `bind` or `const bind` (in order to differentiate from constant and non-constant binding).
+Local blocks would be named "scope blocks" and they would be provided by the `BOOST_SCOPE_BLOCK...` macros (the "scope block" names seem reasonably expressive).
However, local functions would have to be named "scope functions" and they would be provided by the `BOOST_SCOPE_FUNCTION...` macros.
-This might not be ideal because local functions are not known under the name of "scope functions" (they are indeed known by the name of "local functions" or "[@http://gcc.gnu.org/onlinedocs/gcc/Nested-Functions.html nested functions]").
+These names might not expressive enough because local functions are not known under the name of "scope functions" -- they are indeed known by either the name of "local functions" or by the name of "[@http://gcc.gnu.org/onlinedocs/gcc/Nested-Functions.html nested functions]".
]

+[h5 D's Scope Guards]
+
+Local exits are very similar to the [@http://www.digitalmars.com/d/2.0/statement.html scope exit] statements provided by the D programming language.
+Local exits can be used also to emulate D's [@http://www.digitalmars.com/d/2.0/statement.html scope success] and [@http://www.digitalmars.com/d/2.0/statement.html scope failure] statements using a local variable that is set when an error occurs.
+For example, using error codes:
+
+[scope_guards_errno_cpp]
+
+Or similarly but using exceptions:
+
+[scope_guards_except_cpp]
+
[endsect]

[section Templates]
@@ -396,16 +352,18 @@
Because C++ does not allow this use of `typename` outside templates, the special `TPL` macros are used to indicate that the enclosing scope is a template so this library can safety use `typename` to resolve expression type ambiguities.
]

- __BOOST_LOCAL_FUNCTION_TPL__( ``/parenthesized-signature/`` )
- __BOOST_LOCAL_BLOCK_TPL__( ``/parenthesized-binding/`` )
- __BOOST_LOCAL_EXIT_TPL__( ``/parenthesized-binding/`` )
+ __BOOST_LOCAL_FUNCTION_PARAMS_TPL__(``/parameters/``)
+ __BOOST_LOCAL_BLOCK_TPL__(``/bindings/``)
+ __BOOST_LOCAL_EXIT_TPL__(``/bindings/``)

-These macros have the exact same API as their equivalents without the `TPL` postfix that we have seen so far.
-The local function, local block, and local exit ending macros (with the `END` postfix) can be used unchanged within templates.
+These macros have the exact same API as their equivalent macros without the `TPL` postfix that we have seen so far.

-For example, let's rewrite an example similar to the one from the __Introduction__ section but wrapped within a template:
+For example, let's rewrite a local function, a local exit, and a local block similar to the ones from the __Introduction__ section but wrapped within a template:

-[add_template_cpp]
+[table
+[ [Variadic Macro Syntax (C99 and later compilers)] [Sequencing Macro Syntax (all C++ compilers)] ]
+[ [ [add_template_va_cpp] ] [ [add_template_cpp] ] ]
+]

[endsect]

Modified: sandbox/local/libs/local/example/add_block_va.cpp
==============================================================================
--- sandbox/local/libs/local/example/add_block_va.cpp (original)
+++ sandbox/local/libs/local/example/add_block_va.cpp 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -4,7 +4,7 @@
// License, Version 1.0 (see accompanying file LICENSE_1_0.txt or a
// copy at http://www.boost.org/LICENSE_1_0.txt).

-//[ add_block_cpp
+//[ add_block_va_cpp
#include <boost/local/block.hpp>
#include <iostream>
#include <cassert>

Deleted: sandbox/local/libs/local/example/add_num.cpp
==============================================================================
--- sandbox/local/libs/local/example/add_num.cpp 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
+++ (empty file)
@@ -1,20 +0,0 @@
-
-// Copyright (C) 2009-2011 Lorenzo Caminiti
-// Use, modification, and distribution is subject to 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).
-
-//[ add_num_cpp
-#include <boost/local/function.hpp>
-#include <iostream>
-
-int main() {
- void BOOST_LOCAL_FUNCTION_PARAMS( (double num) ) {
- std::clog << num << std::endl;
- } BOOST_LOCAL_FUNCTION_NAME(add)
-
- add(100.0);
- return 0;
-}
-//]
-

Deleted: sandbox/local/libs/local/example/add_num_va.cpp
==============================================================================
--- sandbox/local/libs/local/example/add_num_va.cpp 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
+++ (empty file)
@@ -1,20 +0,0 @@
-
-// Copyright (C) 2009-2011 Lorenzo Caminiti
-// Use, modification, and distribution is subject to 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).
-
-//[ add_num_va_cpp
-#include <boost/local/function.hpp>
-#include <iostream>
-
-int main() {
- void BOOST_LOCAL_FUNCTION_PARAMS(double num) {
- std::clog << num << std::endl;
- } BOOST_LOCAL_FUNCTION_NAME(add)
-
- add(100.0);
- return 0;
-}
-//]
-

Modified: sandbox/local/libs/local/example/add_template_va.cpp
==============================================================================
--- sandbox/local/libs/local/example/add_template_va.cpp (original)
+++ sandbox/local/libs/local/example/add_template_va.cpp 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -4,7 +4,7 @@
// License, Version 1.0 (see accompanying file LICENSE_1_0.txt or a
// copy at http://www.boost.org/LICENSE_1_0.txt).

-//[add_template_cpp
+//[add_template_va_cpp
#include <boost/local/function.hpp>
#include <boost/local/block.hpp>
#include <boost/local/exit.hpp>

Copied: sandbox/local/libs/local/example/add_x_y.cpp (from r69597, /sandbox/local/libs/local/example/add_num.cpp)
==============================================================================
--- /sandbox/local/libs/local/example/add_num.cpp (original)
+++ sandbox/local/libs/local/example/add_x_y.cpp 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -4,16 +4,16 @@
// License, Version 1.0 (see accompanying file LICENSE_1_0.txt or a
// copy at http://www.boost.org/LICENSE_1_0.txt).

-//[ add_num_cpp
+//[ add_x_y_cpp
#include <boost/local/function.hpp>
#include <iostream>

int main() {
- void BOOST_LOCAL_FUNCTION_PARAMS( (double num) ) {
- std::clog << num << std::endl;
+ int BOOST_LOCAL_FUNCTION_PARAMS( (int x) (int y) ) {
+ return x + y;
} BOOST_LOCAL_FUNCTION_NAME(add)

- add(100.0);
+ add(1, 2);
return 0;
}
//]

Copied: sandbox/local/libs/local/example/add_x_y_va.cpp (from r69597, /sandbox/local/libs/local/example/add_num_va.cpp)
==============================================================================
--- /sandbox/local/libs/local/example/add_num_va.cpp (original)
+++ sandbox/local/libs/local/example/add_x_y_va.cpp 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -4,16 +4,16 @@
// License, Version 1.0 (see accompanying file LICENSE_1_0.txt or a
// copy at http://www.boost.org/LICENSE_1_0.txt).

-//[ add_num_va_cpp
+//[ add_x_y_va_cpp
#include <boost/local/function.hpp>
#include <iostream>

int main() {
- void BOOST_LOCAL_FUNCTION_PARAMS(double num) {
- std::clog << num << std::endl;
+ int BOOST_LOCAL_FUNCTION_PARAMS(int x, int y) {
+ return x + y;
} BOOST_LOCAL_FUNCTION_NAME(add)

- add(100.0);
+ add(1, 2);
return 0;
}
//]

Modified: sandbox/local/libs/local/example/print_map.cpp
==============================================================================
--- sandbox/local/libs/local/example/print_map.cpp (original)
+++ sandbox/local/libs/local/example/print_map.cpp 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -20,13 +20,13 @@

int main() {
 void BOOST_LOCAL_FUNCTION_PARAMS(
- // Identity macors handle commas.
+ // Identity macros handle commas.
 (BOOST_IDENTITY_TYPE((const std::map<std::string, size_t>))& m)
- (const size_t& factor)(default // Or just use `(default (...))`.
- BOOST_IDENTITY_VALUE((key_size<std::string, size_t>::value)))
- (const std::string& separator)(default cat(":", " "))
- // Also, identity macors handle leading symbols.
- (BOOST_IDENTITY_TYPE((::sign_t)) sign)(default -1) ) {
+ // Also, identity macros handle leading symbols.
+ (BOOST_IDENTITY_TYPE((::sign_t)) sign)(default -1)
+ (const size_t& factor)(default // Or use `BOOST_IDENTITY_VALUE`.
+ (key_size<std::string, size_t>::value))
+ (const std::string& separator)(default cat(":", " ")) ) {
 for (std::map<std::string, size_t>::const_iterator i = m.begin();
 i != m.end(); ++i) {
 std::cout << i->first << separator <<

Modified: sandbox/local/libs/local/example/print_map_va.cpp
==============================================================================
--- sandbox/local/libs/local/example/print_map_va.cpp (original)
+++ sandbox/local/libs/local/example/print_map_va.cpp 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -4,7 +4,7 @@
// License, Version 1.0 (see accompanying file LICENSE_1_0.txt or a
// copy at http://www.boost.org/LICENSE_1_0.txt).

-//[ print_map_cpp
+//[ print_map_va_cpp
#include <boost/local/function.hpp>
#include <boost/utility/identity.hpp>
#include <map>
@@ -20,13 +20,13 @@

int main() {
 void BOOST_LOCAL_FUNCTION_PARAMS(
- // Identity macors handle commas.
+ // Identity macros handle commas.
 BOOST_IDENTITY_TYPE((const std::map<std::string, size_t>))& m,
- const size_t& factor, default // Or just use `(default (...))`.
- BOOST_IDENTITY_VALUE((key_size<std::string, size_t>::value)),
- const std::string& separator, default cat(":", " "),
- // Also, identity macors handle leading symbols.
- BOOST_IDENTITY_TYPE((::sign_t)) sign, default -1) {
+ // Also, identity macros handle leading symbols.
+ BOOST_IDENTITY_TYPE((::sign_t)) sign, default -1,
+ const size_t& factor, default // Or use `BOOST_IDENTITY_VALE`.
+ (key_size<std::string, size_t>::value),
+ const std::string& separator, default cat(":", " ")) {
 for (std::map<std::string, size_t>::const_iterator i = m.begin();
 i != m.end(); ++i) {
 std::cout << i->first << separator <<

Modified: sandbox/local/libs/local/example/scope_guards_errno.cpp
==============================================================================
--- sandbox/local/libs/local/example/scope_guards_errno.cpp (original)
+++ sandbox/local/libs/local/example/scope_guards_errno.cpp 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -1,4 +1,5 @@

+//[scope_guards_errno_cpp
#include <boost/local/exit.hpp>
#include <iostream>

@@ -17,14 +18,11 @@
 if (error) std::cout << "failure" << std::endl;
 } BOOST_LOCAL_EXIT_END

- // Cannot use `return <NUMBER>` otherwise scope exits do not know the
- // error number. Set error and exit using `return error` instead.
- error = -2; return error;
- error = -1; return error;
+ return error = -1; // Must set error.
}

int main() {
- std::cout << "error number: " << f() << std::endl;
- return 0;
+ return f();
}
+//]

Modified: sandbox/local/libs/local/example/scope_guards_except.cpp
==============================================================================
--- sandbox/local/libs/local/example/scope_guards_except.cpp (original)
+++ sandbox/local/libs/local/example/scope_guards_except.cpp 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -1,55 +1,13 @@

+//[scope_guards_except_cpp
#include <boost/local/exit.hpp>
#include <iostream>
#include <stdexcept>

-struct exception_error_interface {
- virtual operator bool() const = 0;
- virtual void throw_if() const = 0;
-};
-
-template<typename E>
-struct exception_error: exception_error_interface {
- template<typename A0>
- explicit exception_error(A0 arg0): ex_(E(arg0)) {}
- template<typename A0, typename A1>
- exception_error(A0 arg0, A1 arg1): ex_(E(arg0, arg1)) {}
- // Add more constructors for more parameters if needed...
-
- operator bool() const { return true; }
- void throw_if() const { throw ex_; }
-
-private:
- E ex_; // I need the exception type `E` here so I can throw it later.
-};
-
-template<>
-struct exception_error<void> { // Use `void` for no error (cannot throw void).
- exception_error(): err_() {} // No error by default.
-
- template<typename E> // Construct with some error.
- /* implicit */ exception_error(exception_error<E> const& err): err_(&err) {}
- template<typename E> // Set some error.
- exception_error& operator=(exception_error<E> const& err)
- { err_ = &err; return *this; }
-
- operator bool() const { return err_ && bool(*err_); }
- // Select proper type to throw via polymorphism.
- void throw_if() const { if (err_) err_->throw_if(); }
-
-private:
- exception_error_interface const* err_;
-};
-
void f() {
- exception_error<void> error; // No error (i.e., `void`) to start with.
- // This scope exit is special -- it's used to throw on exit if error.
- BOOST_LOCAL_EXIT( (const bind& error) ) {
- std::cout << "throwing if error" << std::endl;
- error.throw_if(); // Throws if error set not to `exception_error<void>`.
- } BOOST_LOCAL_EXIT_END
+ bool error = false; // No error to start with.

- BOOST_LOCAL_EXIT( (void) ) { // Smae as D's `scope(exit)`.
+ BOOST_LOCAL_EXIT( (void) ) { // Same as D's `scope(exit)`.
 std::cout << "exit" << std::endl;
 } BOOST_LOCAL_EXIT_END

@@ -61,14 +19,18 @@
 if (error) std::cout << "failure" << std::endl;
 } BOOST_LOCAL_EXIT_END

- // Cannot use `throw` otherwise scope exits are not executed. Set error
- // and exit using `return` instead (the 1st scope exit will throw).
- error = exception_error<std::runtime_error>("some error"); return;
- error = exception_error<int>(-1); return;
+ error = true; throw std::runtime_error("some error"); // Must set error.
}

int main() {
- f();
- return 0;
+ // Program cannot terminate with uncaught exception (otherwise local exit
+ // code is not guaranteed to be executed).
+ try {
+ f();
+ return 0;
+ } catch(...) {
+ return -1;
+ }
}
+//]

Deleted: sandbox/local/libs/local/example/scope_guards_se.cpp
==============================================================================
--- sandbox/local/libs/local/example/scope_guards_se.cpp 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
+++ (empty file)
@@ -1,20 +0,0 @@
-
-#include <boost/scope_exit.hpp>
-#include <iostream>
-#include <stdexcept>
-
-void f() {
- bool error = false;
-
- BOOST_SCOPE_EXIT( (&error) ) {
- std::cout << "returning" << std::endl; // Not executed on throw.
- } BOOST_SCOPE_EXIT_END
-
- throw std::runtime_error("some error");
-}
-
-int main() {
- f();
- return 0;
-}
-

Modified: sandbox/local/libs/local/example/transform.cpp
==============================================================================
--- sandbox/local/libs/local/example/transform.cpp (original)
+++ sandbox/local/libs/local/example/transform.cpp 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -4,6 +4,7 @@
// License, Version 1.0 (see accompanying file LICENSE_1_0.txt or a
// copy at http://www.boost.org/LICENSE_1_0.txt).

+//[transform_cpp
#include <boost/local/function.hpp>
#include <iostream>
#include <algorithm>
@@ -29,7 +30,7 @@

 // v = ++(v + w) + 0 = 27 47 67 87 107
 int BOOST_LOCAL_FUNCTION_PARAMS( (int i) (int j)
- (bind inc) ) { // Bind another local function.
+ (const bind& inc) ) { // Bind another local function.
 return inc(i + j); // Call the bound local function.
 } BOOST_LOCAL_FUNCTION_NAME(inc_sum)
 std::transform(v.begin(), v.end(), w.begin(), v.begin(), inc_sum);
@@ -40,4 +41,5 @@

 return 0;
}
+//]

Modified: sandbox/local/libs/local/example/transform_va.cpp
==============================================================================
--- sandbox/local/libs/local/example/transform_va.cpp (original)
+++ sandbox/local/libs/local/example/transform_va.cpp 2011-03-10 09:22:09 EST (Thu, 10 Mar 2011)
@@ -4,6 +4,7 @@
// License, Version 1.0 (see accompanying file LICENSE_1_0.txt or a
// copy at http://www.boost.org/LICENSE_1_0.txt).

+//[transform_va_cpp
#include <boost/local/function.hpp>
#include <iostream>
#include <algorithm>
@@ -29,7 +30,7 @@

 // v = ++(v + w) + 0 = 27 47 67 87 107
 int BOOST_LOCAL_FUNCTION_PARAMS(int i, int j,
- bind inc) { // Bind another local function.
+ const bind& inc) { // Bind another local function.
 return inc(i + j); // Call the bound local function.
 } BOOST_LOCAL_FUNCTION_NAME(inc_sum)
 std::transform(v.begin(), v.end(), w.begin(), v.begin(), inc_sum);
@@ -40,4 +41,5 @@

 return 0;
}
+//]

Next message: lorcaminiti_at_[hidden]: "[Boost-commit] svn:boost r69819 - in sandbox/local/libs/local: doc/html/boost_local doc/qbk example"
Previous message: john_at_[hidden]: "[Boost-commit] svn:boost r69817 - trunk/boost/config/platform"

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