Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r76623 - in sandbox/closure/libs/local_function/doc/html: . boost_localfunction
From: lorcaminiti_at_[hidden]
Date: 2012-01-21 13:28:38

Next message: lorcaminiti_at_[hidden]: "[Boost-commit] svn:boost r76624 - sandbox/closure/libs/local_function/doc/html"
Previous message: lorcaminiti_at_[hidden]: "[Boost-commit] svn:boost r76622 - sandbox/closure/libs/local_function/doc"

Author: lcaminiti
Date: 2012-01-21 13:28:36 EST (Sat, 21 Jan 2012)
New Revision: 76623
URL: http://svn.boost.org/trac/boost/changeset/76623

Log:
Examples, tests, and docs.
Added:
   sandbox/closure/libs/local_function/doc/html/
   sandbox/closure/libs/local_function/doc/html/boost_localfunction/
   sandbox/closure/libs/local_function/doc/html/boost_localfunction/Acknowledgments.html (contents, props changed)
   sandbox/closure/libs/local_function/doc/html/boost_localfunction/Advanced_Topics.html (contents, props changed)
   sandbox/closure/libs/local_function/doc/html/boost_localfunction/Alternatives.html (contents, props changed)
   sandbox/closure/libs/local_function/doc/html/boost_localfunction/Bibliography.html (contents, props changed)
   sandbox/closure/libs/local_function/doc/html/boost_localfunction/Examples.html (contents, props changed)
   sandbox/closure/libs/local_function/doc/html/boost_localfunction/Getting_Started.html (contents, props changed)
   sandbox/closure/libs/local_function/doc/html/boost_localfunction/Implementation.html (contents, props changed)
   sandbox/closure/libs/local_function/doc/html/boost_localfunction/No_Variadic_Macros.html (contents, props changed)
   sandbox/closure/libs/local_function/doc/html/boost_localfunction/Release_Notes.html (contents, props changed)
   sandbox/closure/libs/local_function/doc/html/boost_localfunction/Tutorial.html (contents, props changed)
   sandbox/closure/libs/local_function/doc/html/index.html (contents, props changed)

Added: sandbox/closure/libs/local_function/doc/html/boost_localfunction/Acknowledgments.html
==============================================================================
--- (empty file)
+++ sandbox/closure/libs/local_function/doc/html/boost_localfunction/Acknowledgments.html 2012-01-21 13:28:36 EST (Sat, 21 Jan 2012)
@@ -0,0 +1,96 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Acknowledgments</title>
+<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
+<link rel="home" href="../index.html" title="Chapter 1. Boost.LocalFunction 1.0.0">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.LocalFunction 1.0.0">
+<link rel="prev" href="Bibliography.html" title="Bibliography">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="Bibliography.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>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="boost_localfunction.Acknowledgments"></a><a class="link" href="Acknowledgments.html" title="Acknowledgments">Acknowledgments</a>
+</h2></div></div></div>
+
+ This section attempts to recognize the contributions of all
+ the different people that participated directly or indirectly to the design
+ and development of this library.
+ 
+
+ Many thanks to Steven Watanabe and Vicente Botet for suggesting to me to use
+ Boost.ScopeExit
+ binding to <a href="http://boost.2283326.n4.nabble.com/contract-diff-n1962-tt2671482.html#none" target="_top">emulate
+ local functions</a>. Many thanks to Alexander Nasonov for clarifying how
+ Boost.ScopeExit
+ binding could be used to implement local functions and for some <a href="http://thread.gmane.org/gmane.comp.lib.boost.devel/168612" target="_top">early
+ work</a> in this direction.
+ 
+
+ Many thanks to Gregory Crosswhite for using an early version of this library
+ in one of his projects.
+ 
+
+ Thanks to David Abrahams, Vicente Botet, et al. for suggesting to provide the
+ <a href="http://lists.boost.org/Archives/boost/2011/02/176712.php" target="_top">variadic
+ macro syntax</a> on compilers that support variadic macros.
+ 
+
+ Thanks to Pierre Morcello for suggesting to use <code class="computeroutput">return;</code> to exit local blocks (in the context of a
+ discussion about a possible Boost.Breakable
+ library). Thanks to Pierre also for sharing some code that experimented with
+ implementing local functions using Boost.ScopeExit
+ binding (even if this library was not developed using such a code).
+ 
+
+ Thanks to John Bytheway for checking the authors' virtual functor technique
+ that originally allowed this library to pass local functions as template parameters.
+ 
+
+ Thanks to Jeffrey Lee Hellrung for suggesting the use of the "keyword"
+ <code class="computeroutput">bind</code> to bind variables in scope
+ and for suggesting to use <code class="literal">bind(type)</code>
+ to optionally specify the bound variable type. Thanks to Vicente Botet for
+ suggesting to provide a macro to expose the bound variable type to the public
+ API.
+ 
+
+ Thanks to Steven Watanabe, Vicente Botet, Michael Caisse, Yechezkel Mett, Joel
+ de Guzman, Thomas Heller, et al. for helping with the <a class="link" href="../">Alternatives</a>
+ section and with the profiling of the different alternatives.
+ 
+
+ Finally, many thanks to the entire Boost
+ community and mailing list for
+ providing valuable comments about this library and great insights on the C++
+ programming language.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2009-2012 Lorenzo
+ Caminiti
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="Bibliography.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>
+</div>
+</body>
+</html>

Added: sandbox/closure/libs/local_function/doc/html/boost_localfunction/Advanced_Topics.html
==============================================================================
--- (empty file)
+++ sandbox/closure/libs/local_function/doc/html/boost_localfunction/Advanced_Topics.html 2012-01-21 13:28:36 EST (Sat, 21 Jan 2012)
@@ -0,0 +1,1241 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Advanced Topics</title>
+<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
+<link rel="home" href="../index.html" title="Chapter 1. Boost.LocalFunction 1.0.0">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.LocalFunction 1.0.0">
+<link rel="prev" href="Tutorial.html" title="Tutorial">
+<link rel="next" href="Examples.html" title="Appendix: Examples">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="Tutorial.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>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="boost_localfunction.Advanced_Topics"></a><a class="link" href="Advanced_Topics.html" title="Advanced Topics">Advanced Topics</a>
+</h2></div></div></div>
+<div class="toc"><dl>
+<dt><a href="Advanced_Topics.html#boost_localfunction.Advanced_Topics.default_parameters">Default
+ Parameters</a></dt>
+<dt><a href="Advanced_Topics.html#boost_localfunction.Advanced_Topics.commas_and_symbols_in_macros">Commas
+ and Symbols in Macros</a></dt>
+<dt><a href="Advanced_Topics.html#boost_localfunction.Advanced_Topics.assigning_and_returning">Assigning
+ and Returning</a></dt>
+<dt>Nesting</dt>
+<dt><a href="Advanced_Topics.html#boost_localfunction.Advanced_Topics.deducing_bound_types__concepts__etc_">Deducing
+ Bound Types (concepts, etc)</a></dt>
+<dt><a href="Advanced_Topics.html#boost_localfunction.Advanced_Topics.specifying_types">Specifying
+ Types</a></dt>
+<dt>Inlining</dt>
+<dt>Recursion</dt>
+<dt>Overloading</dt>
+<dt><a href="Advanced_Topics.html#boost_localfunction.Advanced_Topics.exception_specifications">Exception
+ Specifications</a></dt>
+<dt><a href="Advanced_Topics.html#boost_localfunction.Advanced_Topics.storage_classifiers___auto__and__register__">Storage
+ Classifiers (<code class="computeroutput">auto</code> and <code class="computeroutput">register</code>)</a></dt>
+<dt><a href="Advanced_Topics.html#boost_localfunction.Advanced_Topics.limitations__operators__etc_">Limitations
+ (operators, etc)</a></dt>
+</dl></div>
+
+ This section illustrates advanced usages 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_localfunction.Advanced_Topics.default_parameters"></a><a class="link" href="Advanced_Topics.html#boost_localfunction.Advanced_Topics.default_parameters" title="Default Parameters">Default
+ Parameters</a>
+</h3></div></div></div>
+
+ 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="boost_localfunction.Advanced_Topics.default_parameters.f0" href="#ftn.boost_localfunction.Advanced_Topics.default_parameters.f0" class="footnote">15</a>] The keyword <code class="computeroutput">default</code>
+ is used instead:
+ 
+<pre class="programlisting"><code class="literal">parameter-type parameter-name</code>, default <code class="literal">parameter-default-value</code>, ...
+</pre>
+
+ For example, let's program a local function <code class="computeroutput">add(x,
+ y)</code>
+ where the second parameter <code class="computeroutput">y</code>
+ is optional and has a default value of <code class="computeroutput">2</code>
+ (see also "add_default.cpp"):
+ 
+
+
+<pre class="programlisting">int BOOST_LOCAL_FUNCTION(int x, int y, default 2) { // Default.
+ return x + y;
+} BOOST_LOCAL_FUNCTION_NAME(add)
+
+BOOST_CHECK( add(1) == 3 );
+</pre>
+
+ 
+
+ Programmers can define a <code class="computeroutput">WITH_DEFAULT</code>
+ macro similar to the following if they think it improves readability over
+ the syntax above (see also "add_with_default.cpp"):
+ [<a name="boost_localfunction.Advanced_Topics.default_parameters.f1" href="#ftn.boost_localfunction.Advanced_Topics.default_parameters.f1" class="footnote">16</a>]
+ 
+
+
+<pre class="programlisting">#define WITH_DEFAULT , default
+</pre>
+
+ 
+
+
+<pre class="programlisting">int BOOST_LOCAL_FUNCTION(int x, int y WITH_DEFAULT 2) { // Default.
+ return x + y;
+} BOOST_LOCAL_FUNCTION_NAME(add)
+
+BOOST_CHECK( add(1) == 3 );
+</pre>
+
+ 
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Advanced_Topics.commas_and_symbols_in_macros"></a><a class="link" href="Advanced_Topics.html#boost_localfunction.Advanced_Topics.commas_and_symbols_in_macros" title="Commas and Symbols in Macros">Commas
+ and Symbols in Macros</a>
+</h3></div></div></div>
+
+ The C++ preprocessor does not allow commas <code class="computeroutput">,</code>
+ within macro parameters unless they are wrapped by round parenthesis <code class="computeroutput">()</code>. Therefore, using commas within the local
+ function parameters and bindings will generate (cryptic) preprocessor errors
+ unless they are wrapped with an extra set of round parenthesis <code class="computeroutput">()</code> as explained here.
+ 
+<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">
+ Macro parameters with commas which are already wrapped by round parenthesis
+ <code class="computeroutput">()</code> 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. 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>
+
+ 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="boost_localfunction.Advanced_Topics.commas_and_symbols_in_macros.f0" href="#ftn.boost_localfunction.Advanced_Topics.commas_and_symbols_in_macros.f0" class="footnote">17</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 BOOST_LOCAL_FUNCTION(
+ 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_NAME(f)
+</pre>
+
+ (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>
+ thus it will cause a preprocessor error. The Boost.Utility
+ macro <code class="computeroutput">BOOST_IDENTITY_TYPE(</code>parenthesized-type<code class="computeroutput">)</code> from the header <code class="computeroutput">"boost/utility/identity_type.hpp"</code>
+ can be used to wrap a type within extra parenthesis <code class="computeroutput">()</code>
+ so to overcome this issue:
+ 
+<pre class="programlisting">#include <boost/utility/identity_type.hpp>
+
+void BOOST_LOCAL_FUNCTION(
+ BOOST_IDENTITY_TYPE((const std::map<std::string, size_t>&)) m, // OK.
+ ...
+) {
+ ...
+} BOOST_LOCAL_FUNCTION_NAME(f)
+</pre>
+
+ This macro expands to an expression that evaluates (at compile-time) exactly
+ to the specified type. Note that a total of two set of parenthesis <code class="computeroutput">()</code> are needed: The parenthesis to invoke the
+ <code class="computeroutput">BOOST_IDENTITY_TYPE(..)</code>
+ macro plus the parenthesis to wrap the type expression (and therefore any
+ comma <code class="computeroutput">,</code> that it contains) passed
+ as parameter to the <code class="computeroutput">BOOST_IDENTITY_TYPE((...)</code> macro. [<a name="boost_localfunction.Advanced_Topics.commas_and_symbols_in_macros.f1" href="#ftn.boost_localfunction.Advanced_Topics.commas_and_symbols_in_macros.f1" class="footnote">18</a>] Finally, the <code class="computeroutput">BOOST_IDENTITY_TYPE</code>
+ macro must be prefixed by the <code class="computeroutput">typename</code>
+ keyword as in <code class="computeroutput">typename BOOST_IDENTITY_TYPE(</code>parenthesized-type<code class="computeroutput">)</code> when used within <code class="computeroutput">BOOST_LOCAL_FUNCTION_TPL</code>
+ for templates.
+ 
+<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">
+ Often, there might be better ways to overcome this limitation that lead
+ to code which is more readable than the one using the <code class="computeroutput">BOOST_IDENTITY_TYPE</code>
+ macro. For example, in this case a <code class="computeroutput">typedef</code>
+ could have been used in the enclosing scope to obtain the following valid
+ and perhaps more readable code:
+ </td></tr>
+</table></div>
+<pre class="programlisting">typedef std::map<std::string, size_t> map_type;
+void BOOST_LOCAL_FUNCTION(
+ const map_type& m, // OK.
+ ...
+) BOOST_LOCAL_FUNCTION_NAME(f)
+</pre>
+
+ (2) The parameter type <code class="computeroutput">::sign_t</code> starts with the non-alphanumeric
+ symbols <code class="computeroutput">::</code> thus it will generate
+ preprocessor errors if used as a local function parameter type. The macros
+ <code class="computeroutput">BOOST_IDENTITY_TYPE</code> can also
+ be used to overcome this issue:
+ 
+<pre class="programlisting">void BOOST_LOCAL_FUNCTION(
+ ...
+ BOOST_IDENTITY_TYPE((::sign_t)) sign, // OK.
+ ...
+) {
+ ...
+} BOOST_LOCAL_FUNCTION_NAME(f)
+</pre>
+<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">
+ Often, there might be better ways to overcome this limitation that lead
+ to code which is more readable than the one using the <code class="computeroutput">BOOST_IDENTITY_TYPE</code>
+ macro. For example, in this case the symbols <code class="computeroutput">::</code>
+ could have been simply dropped to obtain the following valid and perhaps
+ more readable code:
+ </td></tr>
+</table></div>
+<pre class="programlisting">void BOOST_LOCAL_FUNCTION(
+ ...
+ sign_t sign, // OK.
+ ...
+) {
+ ...
+} BOOST_LOCAL_FUNCTION_NAME(f)
+</pre>
+
+ (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), it can be simply wrapped within an extra set
+ of round parenthesis <code class="computeroutput">()</code>:
+ 
+<pre class="programlisting">void BOOST_LOCAL_FUNCTION(
+ ...
+ const size_t& factor, default
+ (key_size<std::string, size_t>::value), // OK.
+ ...
+) {
+ ...
+} BOOST_LOCAL_FUNCTION_NAME(f)
+</pre>
+
+ (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>.
+ 
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Advanced_Topics.assigning_and_returning"></a><a class="link" href="Advanced_Topics.html#boost_localfunction.Advanced_Topics.assigning_and_returning" title="Assigning and Returning">Assigning
+ and Returning</a>
+</h3></div></div></div>
+
+ Local functions are function objects so it is possible to assign them to
+ other functors like Boost.Function
+ <code class="computeroutput">boost::function</code> in order to store the local function
+ into a variable, pass it as a parameter to another function, or return it
+ from the enclosing function.
+ 
+
+ For example (see also "return_assign.cpp"):
+ 
+
+
+<pre class="programlisting">void call1(boost::function<int (int)> f) { BOOST_CHECK( f(1) == 5 ); }
+
+void call0(boost::function<int (void)> f) { BOOST_CHECK( f() == 5 ); }
+
+boost::function<int (int, int)> linear(int slope) {
+ boost::function< int (int, int) > l2;
+
+ int BOOST_LOCAL_FUNCTION(bind slope, int x, default 1, int y, default 2) {
+ return x + slope * y;
+ } BOOST_LOCAL_FUNCTION_NAME(lin)
+
+ boost::function<int (int, int)> f = lin; // Assign to local variable.
+ BOOST_CHECK( f(1, 2) == 5 );
+
+ call1(lin); // Pass to other functions.
+ call0(lin);
+
+ return lin; // Return.
+}
+
+void call(void) {
+ boost::function<int (int, int)> f = linear(2);
+ BOOST_CHECK( f(1, 2) == 5 );
+}
+</pre>
+
+ 
+
+ Note that:
+ 
+<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">
+ As with <a href="http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions" target="_top">C++11
+ lambda</a> functions, programmers are responsible to ensure that bound
+ references are valid in any scope where the local function object is called.
+ </td></tr>
+</table></div>
+
+ This might be tricky to verify in a program so in general it is better to
+ never bind by reference when a local function is returned by the enclosing
+ scope to a different scope (see a few examples on this topic in the <a class="link" href="../">Examples</a> section).
+ 
+
+ In addition, a local function can bind and call another local function. Local
+ functions should always be bound by constant reference <code class="computeroutput">const
+ bind&</code>
+ to avoid unnecessary copies. For example, the following local function <code class="computeroutput">inc_sum</code> binds the local function <code class="computeroutput">inc</code> so <code class="computeroutput">inc_sum</code>
+ can call <code class="computeroutput">inc</code> (see aslo "transform.cpp"):
+ 
+
+
+<pre class="programlisting">int offset = 5;
+std::vector<int> v;
+std::vector<int> w;
+
+for(int i = 1; i <= 2; ++i) v.push_back(i * 10);
+BOOST_CHECK( v[0] == 10 ); BOOST_CHECK( v[1] == 20 );
+w.resize(v.size());
+
+int BOOST_LOCAL_FUNCTION(const bind& offset, int i) {
+ return ++i + offset;
+} BOOST_LOCAL_FUNCTION_NAME(inc)
+
+std::transform(v.begin(), v.end(), w.begin(), inc);
+BOOST_CHECK( w[0] == 16 ); BOOST_CHECK( w[1] == 26 );
+
+int BOOST_LOCAL_FUNCTION(const bind& inc, int i, int j) {
+ return inc(i + j); // Call the other bound local function.
+} BOOST_LOCAL_FUNCTION_NAME(inc_sum)
+
+offset = 0;
+std::transform(v.begin(), v.end(), w.begin(), v.begin(), inc_sum);
+BOOST_CHECK( v[0] == 27 ); BOOST_CHECK( v[1] == 47 );
+</pre>
+
+ 
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Advanced_Topics.nesting"></a><a class="link" href="Advanced_Topics.html#boost_localfunction.Advanced_Topics.nesting" title="Nesting">Nesting</a>
+</h3></div></div></div>
+
+ It is possible to nest local functions into one another. For example (see
+ also "nesting.cpp"):
+ 
+
+
+<pre class="programlisting">int x = 0;
+
+void BOOST_LOCAL_FUNCTION(bind& x) {
+ void BOOST_LOCAL_FUNCTION_PARAMS(bind& x) { // Nested.
+ x++;
+ } BOOST_LOCAL_FUNCTION_NAME(g)
+
+ x--;
+ g(); // Nested local function call.
+} BOOST_LOCAL_FUNCTION_NAME(f)
+
+f();
+</pre>
+
+ 
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Advanced_Topics.deducing_bound_types__concepts__etc_"></a><a class="link" href="Advanced_Topics.html#boost_localfunction.Advanced_Topics.deducing_bound_types__concepts__etc_" title="Deducing Bound Types (concepts, etc)">Deducing
+ Bound Types (concepts, etc)</a>
+</h3></div></div></div>
+
+ This library never requires to explicitly specify the type of the bound variables.
+ From within local functions, programmers can access the type of a bound variable
+ using the following macro:
+ 
+<pre class="programlisting">BOOST_LOCAL_FUNCTION_TYPEOF(bound-variable-name)
+</pre>
+
+ The <code class="computeroutput">BOOST_LOCAL_FUNCTION_TYPEOF</code>
+ macro expands to a type expression that evaluates (at compile-time) to the
+ fully qualified type of the bound variable with the specified name.
+ 
+<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 type expression is fully qualified in the sense that it will be constant
+ if the variable is bound by constant <code class="computeroutput">const
+ bind[&]</code>
+ and it will also be a reference is the variable is bound by reference
+ <code class="computeroutput">[const] bind&</code> (if needed, programmers can strip
+ away the <code class="computeroutput">const</code> and <code class="computeroutput">&</code> qualifiers using <code class="computeroutput">boost::remove_const</code>
+ and <code class="computeroutput">boost::remove_reference</code>, see Boost.TypeTraits).
+ </td></tr>
+</table></div>
+
+ The deduced bound type can be used within the body to declare a local variable,
+ to check concepts, etc. For example (see also "typeof.cpp" and "addable.hpp"):
+ 
+
+
+<pre class="programlisting">int sum = 0, factor = 10;
+
+void BOOST_LOCAL_FUNCTION(const bind factor, bind& sum, int num) {
+ // Typeof for concept checking.
+ BOOST_CONCEPT_ASSERT((Addable<boost::remove_reference<
+ BOOST_LOCAL_FUNCTION_TYPEOF(sum)>::type>));
+ // Typeof for declarations.
+ boost::remove_reference<BOOST_LOCAL_FUNCTION_TYPEOF(
+ factor)>::type mult = factor * num;
+ sum += mult;
+} BOOST_LOCAL_FUNCTION_NAME(add)
+
+add(6);
+</pre>
+
+ 
+
+ Within templates, <code class="computeroutput">BOOST_LOCAL_FUNCTION_TYPEOF</code>
+ does not require to be prefixed by the <code class="computeroutput">typename</code>
+ keyword but eventual type manipulations need the <code class="computeroutput">typename</code>
+ prefix as usual (see also "typeof_template.cpp" and
+ "addable.hpp"):
+ 
+
+
+<pre class="programlisting">template<typename T>
+T calculate(const T& factor) {
+ T sum = 0;
+
+ void BOOST_LOCAL_FUNCTION_TPL(const bind factor, bind& sum, T num) {
+ // Typeof for concept checking.
+ BOOST_CONCEPT_ASSERT((Addable<typename boost::remove_reference<
+ BOOST_LOCAL_FUNCTION_TYPEOF(sum)>::type>));
+ // Typeof for declarations.
+ boost::remove_reference<BOOST_LOCAL_FUNCTION_TYPEOF(
+ factor)>::type mult = factor * num;
+ sum += mult;
+ } BOOST_LOCAL_FUNCTION_NAME(add)
+
+ add(6);
+ return sum;
+}
+</pre>
+
+ 
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Advanced_Topics.specifying_types"></a><a class="link" href="Advanced_Topics.html#boost_localfunction.Advanced_Topics.specifying_types" title="Specifying Types">Specifying
+ Types</a>
+</h3></div></div></div>
+
+ While not required, it is possible to explicitly specify the type of a bound
+ variable so the library will not internally use Boost.Typeof
+ to automatically deduce the type. When specified, the bound variable type
+ must follow the <code class="computeroutput">bind</code> "keyword"
+ and it must be wrapped within round parenthesis <code class="computeroutput">()</code>:
+ 
+<pre class="programlisting">bind(variable-type) variable-name // Bind by value with explicit type.
+bind(variable-type)& variable-name // Bind by reference with explicit type.
+const bind(variable-type) variable-name // Bind by constant value with explicit type.
+const bind(variable-type)& variable-name // Bind by constant reference with explicit type.
+bind(class-type*) this_ // Bind object `this` with type.
+const bind(class-type*) this_ // Bind object `this` by constant with type.
+</pre>
+
+ Note that within the local function body it is always possible to abstract
+ the access to the type of a bound variable using <code class="computeroutput">BOOST_LOCAL_FUNCTION_TYPEOF</code>
+ (even when the bound variable type is explicitly specified).
+ 
+
+ The library also needs to use Boost.Typeof
+ to determine the local function result type because this type specified outside
+ the <code class="computeroutput">BOOST_LOCAL_FUNCTION</code>
+ macro. Thus it is also possible to specify the local function result type
+ as one of the <code class="computeroutput">BOOST_LOCAL_FUNCTION</code>
+ macro parameters prefixed by <code class="computeroutput">return</code>
+ so the library will not use Boost.Typeof
+ to deduce it:
+ 
+<pre class="programlisting">BOOST_LOCAL_FUNCTION_TYPE(return <code class="literal">result-type</code>, ...)
+</pre>
+
+ The following example specifies the type of all bound variables and of the
+ local function result (see also "add_typed.cpp"): [<a name="boost_localfunction.Advanced_Topics.specifying_types.f0" href="#ftn.boost_localfunction.Advanced_Topics.specifying_types.f0" class="footnote">19</a>]
+ 
+
+
+<pre class="programlisting">struct adder {
+ adder(): sum_(0) {}
+
+ int sum(const std::vector<int>& nums, const int& factor = 10) {
+ // Explicitly specify bound variable and result types.
+ BOOST_LOCAL_FUNCTION(const bind(const int&) factor,
+ bind(adder*) this_, int num, return int) {
+ return this_->sum_ += factor * num;
+ } BOOST_LOCAL_FUNCTION_NAME(add)
+
+ std::for_each(nums.begin(), nums.end(), add);
+ return sum_;
+ }
+private:
+ int sum_;
+};
+</pre>
+
+ 
+
+ Unless necessary, it is recommended to not specify the bound variable and
+ result types. Let the library deduce these types so the local function syntax
+ is more concise and the local function declaration will not have to change
+ if a bound variable type changes (facilitating maintenance).
+ 
+<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">
+ Even when the result type and all bound variable types are explicitly specified,
+ the library implementation still internally uses Boost.Typeof
+ to deduce the local function object type (see the <a class="link" href="../">Implementation</a>
+ section). However, this type is automatically registered with Boost.Typeof
+ by this library so programmers will never be required to perform explicit
+ Boost.Typeof
+ registrations when they specify all result and bound variable types.
+ </td></tr>
+</table></div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Advanced_Topics.inlining"></a><a class="link" href="Advanced_Topics.html#boost_localfunction.Advanced_Topics.inlining" title="Inlining">Inlining</a>
+</h3></div></div></div>
+
+ Local functions can be declared inline to increase the chances that the compiler
+ will be able to reduce the run-time of the local function call by inlining
+ the generated assembly code. A local function is declared inline by prefixing
+ the local function name passed to the <code class="computeroutput">BOOST_LOCAL_FUNCTION_NAME</code>
+ macro with the "keyword" <code class="computeroutput">inline</code>:
+ 
+<pre class="programlisting">result-type BOOST_LOCAL_FUNCTION(parameters) {
+ ... // Body.
+} BOOST_LOCAL_FUNCTION_NAME(inline name) // Inlining.
+</pre>
+
+ When inlining a local function, note the following:
+ 
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem">
+ On C++03
+ compliant compilers, inlined local functions always have a run-time comparable
+ to their equivalent implementation that uses local functors (see the
+ <a class="link" href="../">Alternatives</a> section).
+ However, inlined local functions have the important limitation that they
+ cannot be assigned to other functors (like <code class="computeroutput">boost::function</code>)
+ and they cannot be passed as template parameters. [<a name="boost_localfunction.Advanced_Topics.inlining.f0" href="#ftn.boost_localfunction.Advanced_Topics.inlining.f0" class="footnote">20</a>]
+ </li>
+<li class="listitem">
+ On C++11
+ compilers, <code class="computeroutput">inline</code> has no
+ effect because this library will automatically generate code that uses
+ C++11 specific
+ features to inline the local function calls whenever possible even if
+ the local function is not declared inline. Furthermore, non C++11
+ local functions can always be passes as template parameters even when
+ they are declared inline.
+ </li>
+</ul></div>
+<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">
+ It is recommended to not declare a local function inlined unless it is
+ strictly necessary for optimizing pure C++03
+ compliant code (because in all other cases this library will automatically
+ take advantage of C++11
+ features to optimize the local function calls while always allowing to
+ pass the local function as a template parameter).
+ </td></tr>
+</table></div>
+
+ For example, the following local function is declared inlined (thus a for-loop
+ needs to be used for portability instead of passing the local function as
+ a template parameter to the <code class="computeroutput">std::for_each</code>
+ algorithm, see also "add_inline.cpp"):
+ 
+
+
+<pre class="programlisting">int sum = 0, factor = 10;
+
+void BOOST_LOCAL_FUNCTION(const bind factor, bind& sum, int num) {
+ sum += factor * num;
+} BOOST_LOCAL_FUNCTION_NAME(inline add) // Inlined.
+
+std::vector<int> v(100);
+std::fill(v.begin(), v.end(), 1);
+
+for(size_t i = 0; i < v.size(); ++i) add(v[i]); // Cannot use for_each.
+</pre>
+
+ 
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Advanced_Topics.recursion"></a><a class="link" href="Advanced_Topics.html#boost_localfunction.Advanced_Topics.recursion" title="Recursion">Recursion</a>
+</h3></div></div></div>
+
+ Local functions can be declared recursive
+ so a local function can recursively call itself from its body (as usual with
+ C++ functions). A local function is declared recursive by prefixing the local
+ function name passed to <code class="computeroutput">BOOST_LOCAL_FUNCTION_NAME</code>
+ macro with the "keyword" <code class="computeroutput">recursive</code>:
+ 
+<pre class="programlisting">result-type BOOST_LOCAL_FUNCTION(parameters) {
+ ... // Body.
+} BOOST_LOCAL_FUNCTION_NAME(recursive name) // Recursive.
+</pre>
+
+ For example, the following local function is used to recursively calculate
+ the factorials of all the numbers in the specified vector (see also "factorial.cpp"):
+ 
+
+
+<pre class="programlisting">struct calculator {
+ std::vector<int> results;
+
+ void factorials(const std::vector<int>& nums) {
+ int BOOST_LOCAL_FUNCTION(bind this_, int num,
+ bool recursion, default false) {
+ int result = 0;
+
+ if (n < 2 ) result = 1;
+ else result = n * factorial(n - 1, true); // Recursive call.
+
+ if (!recursion) this_->results.push_back(result);
+ return result;
+ } BOOST_LOCAL_FUNCTION_NAME(recursive factorial) // Recursive.
+
+ std::for_each(nums.begin(), nums.end(), factorial);
+ }
+};
+</pre>
+
+ 
+
+ Compilers have not been observed to be able to inline recursive local function
+ calls (not even when the recursive local function is also declared inline).
+ 
+<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">
+ Recursive local functions should never be assigned to another functor object
+ or called outside their declaration scope. Therefore, if a local function
+ is assigned to <code class="computeroutput">boost::function</code>, returned from the enclosing
+ function, and called in a different scope, the result in undefined behaviour
+ (which will likely generate a run-time error). [<a name="boost_localfunction.Advanced_Topics.recursion.f0" href="#ftn.boost_localfunction.Advanced_Topics.recursion.f0" class="footnote">21</a>] This is not a limitation with respect to <a href="http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions" target="_top">C++11
+ lambda</a> functions because lambdas can never call themselves recursively
+ (in other words, there is no recursive lambda function that can successfully
+ be called outside its declaration scope because there is no recursive lambda
+ function period).
+ </td></tr>
+</table></div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Advanced_Topics.overloading"></a><a class="link" href="Advanced_Topics.html#boost_localfunction.Advanced_Topics.overloading" title="Overloading">Overloading</a>
+</h3></div></div></div>
+
+ It is possible to overload local functions using __Boost_FunctionalOverloadedFunction__
+ <code class="computeroutput">boost::overloaded_function</code> from the header <code class="computeroutput">"boost/functional/overloaded_function.hpp"</code>
+ (see the __Boost_FunctionalOverloadedFunction__ documentation for more detail).
+ 
+
+ In the following example, the overloaded function object <code class="computeroutput">add</code>
+ can be called with signatures from either the local function <code class="computeroutput">add_s</code>, or the local function <code class="computeroutput">add_d</code>, or the local function <code class="computeroutput">add_d</code> with its extra default parameter,
+ or the function pointer <code class="computeroutput">add_i</code>
+ (see also "overload.cpp"):
+ 
+
+
+<pre class="programlisting">int add_i(int x, int y) { return x + y; }
+
+BOOST_AUTO_TEST_CASE( test_overload ) {
+ std::string s = "abc";
+ std::string BOOST_LOCAL_FUNCTION(
+ const bind& s, const std::string& x) {
+ return s + x;
+ } BOOST_LOCAL_FUNCTION_NAME(add_s)
+
+ double d = 1.23;
+ double BOOST_LOCAL_FUNCTION(const bind d, double x, double y, default 0) {
+ return d + x + y;
+ } BOOST_LOCAL_FUNCTION_NAME(add_d)
+
+ boost::overloaded_function<
+ std::string (const std::string&)
+ , double (double)
+ , double (double, double) // Overload giving default param.
+ , int (int, int)
+ > add(add_s, add_d, add_d, add_i); // Overloaded function object.
+
+ BOOST_CHECK( add("xyz") == "abcxyz" ); // Call `add_s`.
+ BOOST_CHECK( fabs(add(3.21) - 4.44) < 0.001 ); // Call `add_d` (no default).
+ BOOST_CHECK( fabs(add(3.21, 40.0) - 44.44) < 0.001); // Call `add_d`.
+ BOOST_CHECK( add(1, 2) == 3 ); // Call `add_i`.
+}
+</pre>
+
+ 
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Advanced_Topics.exception_specifications"></a><a class="link" href="Advanced_Topics.html#boost_localfunction.Advanced_Topics.exception_specifications" title="Exception Specifications">Exception
+ Specifications</a>
+</h3></div></div></div>
+
+ It is possible to program exception specifications for local functions by
+ specifying them after the <code class="computeroutput">BOOST_LOCAL_FUNCTION</code>
+ macro and before the body code block <code class="computeroutput">{
+ ... }</code>.
+ 
+<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">
+ Note that the exception specifications only apply to the body code specified
+ by programmers and they do not apply to the rest of the code automatically
+ generated by the macro expansions to implement local functions. For example,
+ even if the body code is specified to throw no exception using <code class="computeroutput">throw () { ... }</code>,
+ the execution of the library code automatically generated by the macros
+ could still throw (if there is no memory, etc).
+ </td></tr>
+</table></div>
+
+ For example (see also "add_except.cpp"):
+ 
+
+
+<pre class="programlisting">double sum = 0.0;
+int factor = 10;
+
+void BOOST_LOCAL_FUNCTION(const bind factor, bind& sum,
+ double num) throw() { // Throw nothing.
+ sum += factor * num;
+} BOOST_LOCAL_FUNCTION_NAME(add)
+
+add(100);
+</pre>
+
+ 
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Advanced_Topics.storage_classifiers___auto__and__register__"></a><a class="link" href="Advanced_Topics.html#boost_localfunction.Advanced_Topics.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>
+
+ Local function parameters support the storage classifiers as usual in C++03.
+ The <code class="computeroutput">auto</code> storage classifier
+ is specified as: [<a name="boost_localfunction.Advanced_Topics.storage_classifiers___auto__and__register__.f0" href="#ftn.boost_localfunction.Advanced_Topics.storage_classifiers___auto__and__register__.f0" class="footnote">22</a>]
+ 
+<pre class="programlisting">auto parameter-type parameter-name
+</pre>
+
+ The <code class="computeroutput">register</code> storage classifier
+ is specified as:
+ 
+<pre class="programlisting">register parameter-type parameter-name
+</pre>
+
+ For example (see also "add_classifiers.cpp"):
+ 
+
+
+<pre class="programlisting">int BOOST_LOCAL_FUNCTION(auto int x, register int y) { // Classifers.
+ return x + y;
+} BOOST_LOCAL_FUNCTION_NAME(add)
+</pre>
+
+ 
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Advanced_Topics.limitations__operators__etc_"></a><a class="link" href="Advanced_Topics.html#boost_localfunction.Advanced_Topics.limitations__operators__etc_" title="Limitations (operators, etc)">Limitations
+ (operators, etc)</a>
+</h3></div></div></div>
+
+ The following table summarizes all C++ function features indicating those
+ features that are not supported by this library for local functions.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ C++ Function Feature
+ 
+ </th>
+<th>
+ 
+ Local Function Support
+ 
+ </th>
+<th>
+ 
+ Reason
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ <code class="computeroutput">export</code>
+ 
+ </td>
+<td>
+ 
+ No
+ 
+ </td>
+<td>
+ 
+ This is not supported because local functions cannot be templates
+ (plus most C++ compilers do not implement <code class="computeroutput">export</code>).
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">template<</code>template-parameter-list<code class="computeroutput">></code>
+ 
+ </td>
+<td>
+ 
+ No
+ 
+ </td>
+<td>
+ 
+ This is not supported because local functions are implemented using
+ local classes and C++03
+ local classes cannot be templates.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">explicit</code>
+ 
+ </td>
+<td>
+ 
+ No
+ 
+ </td>
+<td>
+ 
+ This is not supported because local functions are not constructors.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">inline</code>
+ 
+ </td>
+<td>
+ 
+ Yes
+ 
+ </td>
+<td>
+ 
+ Local functions can be specified <code class="computeroutput">inline</code>
+ to improve the chances that C++03
+ standard compilers can optimize the local function call run-time
+ (but <code class="computeroutput">inline</code> local
+ functions cannot be passes as template parameters on C++03
+ standard compilers).
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">extern</code>
+ 
+ </td>
+<td>
+ 
+ No
+ 
+ </td>
+<td>
+ 
+ This is not supported because local functions are always defined
+ locally within the enclosing scope and together with their declarations.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">static</code>
+ 
+ </td>
+<td>
+ 
+ No
+ 
+ </td>
+<td>
+ 
+ This is not supported because local functions are not member functions.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">virtual</code>
+ 
+ </td>
+<td>
+ 
+ No
+ 
+ </td>
+<td>
+ 
+ This is not supported because local functions are not member functions.
+ [<a name="boost_localfunction.Advanced_Topics.limitations__operators__etc_.f0" href="#ftn.boost_localfunction.Advanced_Topics.limitations__operators__etc_.f0" class="footnote">a</a>]
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="literal">result-type</code>
+ 
+ </td>
+<td>
+ 
+ Yes
+ 
+ </td>
+<td>
+ 
+ This is supported (see the <a class="link" href="../">Tutorial</a>
+ section).
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="literal">function-name</code>
+ 
+ </td>
+<td>
+ 
+ Yes
+ 
+ </td>
+<td>
+ 
+ Local functions are named and they can call themselves recursively
+ but they cannot be overloaded and they cannot be operators (see
+ the <a class="link" href="../">Tutorial</a> and <a class="link" href="../">Advanced Topics</a> sections).
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="literal">parameter-list</code>
+ 
+ </td>
+<td>
+ 
+ Yes
+ 
+ </td>
+<td>
+ 
+ This is supported and it also supports the <code class="computeroutput">auto</code>
+ and <code class="computeroutput">register</code> storage
+ classifiers, default parameters, and binding of variables in scope
+ (see the <a class="link" href="../">Tutorial</a> and
+ <a class="link" href="../">Advanced Topics</a>
+ sections).
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Trailing <code class="computeroutput">const</code> qualifier
+ 
+ </td>
+<td>
+ 
+ No
+ 
+ </td>
+<td>
+ 
+ This is not supported because local functions are not member functions.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Trailing <code class="computeroutput">volatile</code>
+ qualifier
+ 
+ </td>
+<td>
+ 
+ No
+ 
+ </td>
+<td>
+ 
+ This is not supported because local functions are not member functions.
+ 
+ </td>
+</tr>
+</tbody>
+<tbody class="footnotes"><tr><td colspan="3"><div class="footnote">[<a id="ftn.boost_localfunction.Advanced_Topics.limitations__operators__etc_.f0" href="#boost_localfunction.Advanced_Topics.limitations__operators__etc_.f0" class="para">a</a>] 
+ Rationale. It would be possible
+ to make a local function class inherit from another local function
+ class. However, this "inheritance" feature is not implemented
+ because it seemed of <a href="http://lists.boost.org/Archives/boost/2010/09/170895.php" target="_top">no
+ use</a> given that local functions can be bound to one another
+ thus they can simply call each other directly without recurring
+ to dynamic binding or base function call.
+ </div></td></tr></tbody>
+</table></div>
+<h6>
+<a name="boost_localfunction.Advanced_Topics.limitations__operators__etc_.h0"></a>
+ <a name="boost_localfunction.Advanced_Topics.limitations__operators__etc_.operators"></a><a class="link" href="Advanced_Topics.html#boost_localfunction.Advanced_Topics.limitations__operators__etc_.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="boost_localfunction.Advanced_Topics.limitations__operators__etc_.f1" href="#ftn.boost_localfunction.Advanced_Topics.limitations__operators__etc_.f1" class="footnote">23</a>]
+ 
+
+ For example, the following code will not
+ compile:
+ 
+<pre class="programlisting">void f() {
+ struct point {
+ double x;
+ double y;
+ };
+
+ bool BOOST_LOCAL_FUNCTION(const point& p, const point& q) {
+ return p.x == q.x && p.y == q.y;
+ ) BOOST_LOCAL_FUNCTION_NAME(operator==) // Error: Cannot use `operator==`.
+
+ ...
+}
+</pre>
+<h6>
+<a name="boost_localfunction.Advanced_Topics.limitations__operators__etc_.h1"></a>
+ <a name="boost_localfunction.Advanced_Topics.limitations__operators__etc_.goto"></a><a class="link" href="Advanced_Topics.html#boost_localfunction.Advanced_Topics.limitations__operators__etc_.goto">Goto</a>
+ </h6>
+
+ It is not possible to jump with a <code class="computeroutput">goto</code>
+ from within a local function, local block, or local exit to a label defined
+ in the enclosing scope.
+ 
+
+ For example, the following will not compile:
+ 
+<pre class="programlisting">int f() {
+ void BOOST_LOCAL_FUNCTION(bool error) {
+ if (error) goto failure; // Error: Cannot jump to enclosing label `failure`.
+ else goto success; // Ok: Can jump within enclosing scope.
+
+ success:
+ ...
+ } BOOST_LOCAL_FUNCTION_NAME(f)
+
+ f(true);
+
+ return 0;
+failure:
+ return -1;
+}
+</pre>
+</div>
+<div class="footnotes">
+ <hr width="100" align="left">
+<div class="footnote">[<a id="ftn.boost_localfunction.Advanced_Topics.default_parameters.f0" href="#boost_localfunction.Advanced_Topics.default_parameters.f0" class="para">15</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
+ then to count the number of default values to provide the correct set of
+ call operators for the local functor. Therefore, the symbol <code class="computeroutput">=</code> cannot be used because it cannot be handled
+ by preprocessor metaprogramming (specifically, such a non-alphanumeric
+ symbol cannot be detected by preprocessor metaprogramming because it cannot
+ be concatenated by the preprocessor).
+ </div>
+<div class="footnote">[<a id="ftn.boost_localfunction.Advanced_Topics.default_parameters.f1" href="#boost_localfunction.Advanced_Topics.default_parameters.f1" class="para">16</a>] 
+ The authors do not personally find the use of the <code class="computeroutput">WITH_DEFAULT</code>
+ macro more readable and they prefer to use the <code class="computeroutput">default</code>
+ "keyword" directly. Furthermore, <code class="computeroutput">WITH_DEFAULT</code>
+ need to be defined differently for compilers without variadic macros <code class="computeroutput">#define WITH_DEFAULT
+ (default)</code> so it can only be defined by programmers
+ based on the syntax they decide to use.
+ </div>
+<div class="footnote">[<a id="ftn.boost_localfunction.Advanced_Topics.commas_and_symbols_in_macros.f0" href="#boost_localfunction.Advanced_Topics.commas_and_symbols_in_macros.f0" class="para">17</a>] 
+ Rationale. This limitation derives from
+ the fact that <code class="computeroutput">BOOST_LOCAL_FUNCTION</code>
+ uses preprocessor token concatenation <code class="literal">##</code> to inspect
+ the parameter type token (to see if this token is a parameter or a bound
+ variable) and the C++ preprocessor does not allow to concatenate non-alphanumeric
+ tokens.
+ </div>
+<div class="footnote">[<a id="ftn.boost_localfunction.Advanced_Topics.commas_and_symbols_in_macros.f1" href="#boost_localfunction.Advanced_Topics.commas_and_symbols_in_macros.f1" class="para">18</a>] 
+ Rationale. Using variadic macros, this
+ extra set of parenthesis could be eliminated requiring only the parenthesis
+ to invoke the <code class="computeroutput">BOOST_IDENTITY_TYPE</code>
+ macro. However, this feature is currently not implemented and the double
+ parenthesis are always needed when invoking this macro.
+ </div>
+<div class="footnote">[<a id="ftn.boost_localfunction.Advanced_Topics.specifying_types.f0" href="#boost_localfunction.Advanced_Topics.specifying_types.f0" class="para">19</a>] 
+ In the examples of this documentation, we specify bound variables, function
+ parameters, and result type in this order because that is the order used
+ by <a href="http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions" target="_top">C++11
+ lambda</a> functions. However, the library accepts bound variables,
+ function parameters, and the result type in any order.
+ </div>
+<div class="footnote">[<a id="ftn.boost_localfunction.Advanced_Topics.inlining.f0" href="#boost_localfunction.Advanced_Topics.inlining.f0" class="para">20</a>] 
+ Rationale. This library uses an indirect
+ function call via a function pointer in order to pass the local function
+ as a template parameter (see the <a class="link" href="../">Implementation</a>
+ section). No compiler has yet been observed to be able to inline function
+ calls when they use such indirect function pointer calls. Therefore,
+ inlined local functions do not use such indirect function pointer call
+ (so they are more likely to be optimized) but because of that they
+ cannot be passed as template parameters. The indirect function pointer
+ call is needed on C++03
+ but it is not needed on C++11
+ (see [N2657])
+ thus this library automatically generates local function calls that
+ can be inlined on C++11
+ compilers (even when the local function is not declared inline).
+ </div>
+<div class="footnote">[<a id="ftn.boost_localfunction.Advanced_Topics.recursion.f0" href="#boost_localfunction.Advanced_Topics.recursion.f0" class="para">21</a>] 
+ Rationale. This limitation comes from
+ the fact that a global functor used to pass the local function as a template
+ parameter (and eventually use it outside its declarations scope) does
+ not know the local function name so the local function name used for
+ recursive call cannot be set in the global functor. This limitation and
+ preventing the possibility for inlining is also the reason why local
+ function are not recursive unless programmers explicitly declare them
+ <code class="computeroutput">recursive</code>.
+ </div>
+<div class="footnote">[<a id="ftn.boost_localfunction.Advanced_Topics.storage_classifiers___auto__and__register__.f0" href="#boost_localfunction.Advanced_Topics.storage_classifiers___auto__and__register__.f0" class="para">22</a>] 
+ The <code class="computeroutput">auto</code> storage classifier
+ is part of the C++03
+ standard and therefore supported by this library. However, the meaning
+ and usage of the <code class="computeroutput">auto</code> keyword
+ changed in C++11.
+ Therefore, use the <code class="computeroutput">auto</code> storage
+ classifier with the usual care in order to avoid writing C++03
+ code that might not work on C++11.
+ </div>
+<div class="footnote">[<a id="ftn.boost_localfunction.Advanced_Topics.limitations__operators__etc_.f1" href="#boost_localfunction.Advanced_Topics.limitations__operators__etc_.f1" class="para">23</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) and operators cannot be used as local variable
+ names.
+ </div>
+</div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2009-2012 Lorenzo
+ Caminiti
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="Tutorial.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>
+</div>
+</body>
+</html>

Added: sandbox/closure/libs/local_function/doc/html/boost_localfunction/Alternatives.html
==============================================================================
--- (empty file)
+++ sandbox/closure/libs/local_function/doc/html/boost_localfunction/Alternatives.html 2012-01-21 13:28:36 EST (Sat, 21 Jan 2012)
@@ -0,0 +1,748 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Appendix: Alternatives</title>
+<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
+<link rel="home" href="../index.html" title="Chapter 1. Boost.LocalFunction 1.0.0">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.LocalFunction 1.0.0">
+<link rel="prev" href="Examples.html" title="Appendix: Examples">
+<link rel="next" href="No_Variadic_Macros.html" title="Annex: No Variadic Macros">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<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="No_Variadic_Macros.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">
+<a name="boost_localfunction.Alternatives"></a><a class="link" href="Alternatives.html" title="Appendix: Alternatives">Appendix: Alternatives</a>
+</h2></div></div></div>
+<div class="toc"><dl>
+<dt>Features</dt>
+<dt>Performances</dt>
+</dl></div>
+
+ This section compares the features offered by this library with similar features
+ offered by other libraries and by the new C++11
+ standard.
+ 
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Alternatives.features"></a><a class="link" href="Alternatives.html#boost_localfunction.Alternatives.features" title="Features">Features</a>
+</h3></div></div></div>
+
+ The following table compares local function features.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Local Function Feature
+ 
+ </th>
+<th>
+ 
+ Boost.Local (this library)
+ 
+ </th>
+<th>
+ 
+ Local Functor
+ 
+ </th>
+<th>
+ 
+ Global Functor (not local)
+ 
+ </th>
+<th>
+ 
+ __CPP0x_Lambda__ (not C++03)
+ 
+ </th>
+<th>
+ 
+ Boost.Lambda
+ 
+ </th>
+<th>
+ 
+ Boost.Phoenix
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ Can be defined locally
+ 
+ </td>
+<td>
+ 
+ Yes.
+ 
+ </td>
+<td>
+ 
+ Yes.
+ 
+ </td>
+<td>
+ 
+ No. Therefore this not really an alternative implementation of
+ local functions but it is listed here just for comparison.
+ 
+ </td>
+<td>
+ 
+ Yes.
+ 
+ </td>
+<td>
+ 
+ Yes.
+ 
+ </td>
+<td>
+ 
+ Yes.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Can be defined using C++ statement syntax
+ 
+ </td>
+<td>
+ 
+ Yes. Plus eventual compiler errors follow the usual format of C++
+ statement errors.
+ 
+ </td>
+<td>
+ 
+ Yes. Plus eventual compiler errors follow the usual format of C++
+ statement errors.
+ 
+ </td>
+<td>
+ 
+ Yes. Plus eventual compiler errors follow the usual format of C++
+ statement errors.
+ 
+ </td>
+<td>
+ 
+ Yes. Plus eventual compiler errors follow the usual format of C++
+ statement errors.
+ 
+ </td>
+<td>
+ 
+ No (it uses C++ <a href="http://en.wikibooks.org/wiki/More_C%2B%2B_Idioms/Expression-template" target="_top">expression
+ template</a> syntax).
+ 
+ </td>
+<td>
+ 
+ No (it uses C++ <a href="http://en.wikibooks.org/wiki/More_C%2B%2B_Idioms/Expression-template" target="_top">expression
+ template</a> syntax).
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Can be defined within expressions
+ 
+ </td>
+<td>
+ 
+ No. It can be defined only within declarations.
+ 
+ </td>
+<td>
+ 
+ No. It can be defined only within declarations.
+ 
+ </td>
+<td>
+ 
+ No. It can be defined only within declarations.
+ 
+ </td>
+<td>
+ 
+ Yes (plus the local function can be unnamed).
+ 
+ </td>
+<td>
+ 
+ Yes (plus the local function can be unnamed).
+ 
+ </td>
+<td>
+ 
+ Yes (plus the local function can be unnamed).
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Can be passed as template parameter (e.g., to STL algorithms)
+ 
+ </td>
+<td>
+ 
+ Yes. The C++03
+ standard does not allow to pass local types as template parameters
+ (see [N2657])
+ but this library implements a "trick" to get around this
+ limitation (see the <a class="link" href="../">Implementation</a>
+ section).
+ 
+ </td>
+<td>
+ 
+ No on C++03
+ compilers (but yes on C++11
+ compilers and some compilers like MSVC 8.0, see [N2657]).
+ 
+ </td>
+<td>
+ 
+ Yes.
+ 
+ </td>
+<td>
+ 
+ Yes.
+ 
+ </td>
+<td>
+ 
+ Yes.
+ 
+ </td>
+<td>
+ 
+ Yes.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Access variables in scope
+ 
+ </td>
+<td>
+ 
+ Yes. The variable names are repeated in the function declaration
+ so they can be bound by value, by constant value, by reference,
+ and by constant reference (the object <code class="computeroutput">this</code>
+ can also be bound).
+ 
+ </td>
+<td>
+ 
+ No. Programmers must manually manage functor member variables and
+ explicitly specify their types to access variables in scope.
+ 
+ </td>
+<td>
+ 
+ No. Programmers must manually manage functor member variables and
+ explicitly specify their types to access variables in scope.
+ 
+ </td>
+<td>
+ 
+ Yes. The variable names are repeated in the function declaration
+ (plus there is a short-hand syntax to bind all variables in scope
+ at once) so they can be bound by constant value and by reference
+ (the object <code class="computeroutput">this</code> can
+ also be bound). However, variables cannot be bound by constant
+ references and non-constant value (see below).
+ 
+ </td>
+<td>
+ 
+ Yes (variables in scope are accessible as usual within expressions).
+ 
+ </td>
+<td>
+ 
+ Yes (variables in scope are accessible as usual within expressions)
+ plus <code class="computeroutput">boost::phoenix::let</code> can be used to bind variables
+ by constant reference.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Polymorphic
+ in the unbound parameter types
+ 
+ </td>
+<td>
+ 
+ No (local functions cannot be function templates).
+ 
+ </td>
+<td>
+ 
+ No (local classes cannot have member function templates).
+ 
+ </td>
+<td>
+ 
+ Yes.
+ 
+ </td>
+<td>
+ 
+ No (C++11
+ lambdas cannot be function templates).
+ 
+ </td>
+<td>
+ 
+ Yes.
+ 
+ </td>
+<td>
+ 
+ Yes.
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+<h6>
+<a name="boost_localfunction.Alternatives.features.h0"></a>
+ <a name="boost_localfunction.Alternatives.features.comparison_with___cpp0x_lambda___functions"></a><a class="link" href="Alternatives.html#boost_localfunction.Alternatives.features.comparison_with___cpp0x_lambda___functions">Comparison
+ with __CPP0x_Lambda__ Functions</a>
+ </h6>
+
+ __CPP0x_lambda__ functions have most of the features that __Boost_Local__
+ local functions have, key pro and cons of the two approaches are:
+ 
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem">
+ __CPP0x_lambda__ functions can be defined within expressions while __Boost_Local__
+ local functions can only be defined within declarations.
+ </li>
+<li class="listitem">
+ __CPP0x_lambda__ functions are only supported by the C++11
+ standard so they are not supported by all C++ compilers. __Boost_Local__
+ local functions use only C++03
+ compliant features so they are supported on all C++ compliant compilers.
+ </li>
+<li class="listitem">
+ __CPP0x_lambda__ functions do not allow to bind variables in scope by
+ constant reference or by non-constant value. Because a variable cannot
+ be bound by constant reference, __CPP0x_lambda__ functions can bind a
+ variable by constant only if the variable is copyable and the binding
+ requires a (potentially expensive) extra copy operation. Both constant
+ reference and non-constant value binding are instead supported by __Boost_Local__.
+ </li>
+</ul></div>
+
+ For example, for non-copyable objects:
+ 
+<div class="informaltable"><table class="table">
+<colgroup><col></colgroup>
+<thead><tr>
+<th>
+ 
+ __CPP0x_Lambda__
+ 
+ </th>
+<th>
+ 
+ __Boost_Local__ __Variadic_Macro_Syntax__
+ 
+ </th>
+<th>
+ 
+ __Boost_Local__ __Sequencing_Macro_Syntax__
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr><td>
+ 
+ [noncopyable_0x_lambda_cpp
+ 
+ </td></tr>
+<tr><td>
+ 
+ noncopyable_boost_local_va_cpp
+ 
+ </td></tr>
+<tr><td>
+ 
+ noncopyable_boost_local_cpp
+ 
+ </td></tr>
+</tbody>
+</table></div>
+
+ ]
+ 
+
+ Or, for objects with expensive copy operations:
+ 
+<div class="informaltable"><table class="table">
+<colgroup><col></colgroup>
+<thead><tr>
+<th>
+ 
+ __CPP0x_Lambda__
+ 
+ </th>
+<th>
+ 
+ __Boost_Local__ __Variadic_Macro_Syntax__
+ 
+ </th>
+<th>
+ 
+ __Boost_Local__ __Sequencing_Macro_Syntax__
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr><td>
+ 
+ [expensive_copy_0x_lambda_cpp
+ 
+ </td></tr>
+<tr><td>
+ 
+ expensive_copy_boost_local_va_cpp
+ 
+ </td></tr>
+<tr><td>
+ 
+ expensive_copy_boost_local_cpp
+ 
+ </td></tr>
+</tbody>
+</table></div>
+
+ ]
+ 
+<h6>
+<a name="boost_localfunction.Alternatives.features.h1"></a>
+ <a name="boost_localfunction.Alternatives.features.examples"></a><a class="link" href="Alternatives.html#boost_localfunction.Alternatives.features.examples">Examples</a>
+ </h6>
+
+ The same example is rewritten here for all the different alternatives to
+ local functions so programmers can get a sense of the different syntaxes
+ and programming styles that the alternatives require. The following example
+ adds together all the elements of a vector using this library local functions:
+ 
+<div class="informaltable"><table class="table">
+<colgroup><col></colgroup>
+<thead><tr>
+<th>
+ 
+ __Variadic_Macro_Syntax__
+ 
+ </th>
+<th>
+ 
+ __Sequencing_Macro_Syntax__
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr><td>
+ 
+ [add_using_boost_local_va_cpp
+ 
+ </td></tr>
+<tr><td>
+ 
+ add_using_boost_local_cpp
+ 
+ </td></tr>
+</tbody>
+</table></div>
+
+ ]
+ 
+
+ Or using C++ local functors:
+ 
+
+ [add_using_local_functor_cpp]
+ 
+
+ Or using C++ global functors (but these do not allow to define the function
+ locally so they are not a real alternative implementation of local functions):
+ 
+
+ [add_using_global_functor_cpp]
+ 
+
+ Or using __CPP0x_lambda__ functions (but not part of the C++03
+ standard):
+ 
+
+ [add_using_cpp0x_lambda_cpp]
+ 
+
+ Or using Boost.Lambda
+ functions:
+ 
+
+ [add_using_boost_lambda_cpp]
+ 
+
+ Or using Boost.Phoenix:
+ 
+
+ [add_using_boost_phoenix_cpp]
+ 
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Alternatives.performances"></a><a class="link" href="Alternatives.html#boost_localfunction.Alternatives.performances" title="Performances">Performances</a>
+</h3></div></div></div>
+
+ The following tables compare run-times, compile-times, and binary sizes for
+ the different alternatives presented so far for local functions.
+ 
+
+ Overall, this library has compile-times and generates binary sizes similar
+ to the ones of the other approaches. This library run-times on C++03
+ compliant compilers (see "__Boost_Local__ Compliant" below) were
+ measured to be larger than other approaches when compiler optimization is
+ enabled (using <code class="computeroutput">bjam release
+ ...</code>). However, on compilers that allow
+ to pass local types as template parameters (e.g., MSVC 8.0 or GCC 4.5.1 with
+ C++11 features
+ enabled, see also [N2657])
+ this library automatically generates optimized code that runs as fast as
+ the fastest of the other approaches (see "__Boost_Local__" below).
+ When this library local function is specified <code class="computeroutput">inline</code>
+ (see "__Boost_Local__ Inline For-Loop" below and the <a class="link" href="../">Advanced
+ Topics</a> section) its run-times are always comparable to both the "Local
+ Functor" and "Global Functor" approaches (but in this case
+ the local function cannot be portably passed as template parameter, see
+ [N2657],
+ so <code class="computeroutput">std::for_each</code> is replaced by a for-loop). Finally,
+ this library run-times are always among the fastest when no compiler optimization
+ is enabled (using <code class="computeroutput">bjam debug
+ ...</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">
+ The run-time performances of this library local functions are explained
+ because on C++03
+ compliant compilers (e.g., GCC 4.3.4) this library needs to use a function
+ pointer in order to pass the local function class as a template parameter
+ (see [N2657]
+ and the <a class="link" href="../">Implementation</a>
+ section). For all tested compilers, this function pointer prevents the
+ compiler optimization algorithms from inlining the local function calls.
+ Instead, the functors used by other approaches like "Boost.Lambda"
+ and "Boost.Phoenix"
+ have been observed to allow all tested compilers to inline all the function
+ calls for optimization. This run-time performance cost is not present on
+ compilers that allow to pass local types as template parameters (e.g.,
+ MSVC 8.0 or GCC 4.5.1 with C++11
+ features enabled) because this library does not have to use the extra function
+ pointer to implement the local function call (it directly passes the local
+ class type as template parameter).
+ </td></tr>
+</table></div>
+
+ This run-time performance cost on C++03
+ compliant compilers might or might not be an issue depending on the performance
+ requirements of specific applications. For example, an application might
+ already be using a number of indirect function calls (function pointers,
+ virtual functions, etc) for which the overhead added by using the one extra
+ function pointer required by the local function call might not be noticeable
+ within the overall program run-time.
+ 
+
+ Finally, note that only a very simple local function body with just a single
+ instruction was used for the anaylsis presented here (see the <code class="computeroutput">profile_...</code>
+ source files linked below). The authors have not studied how this library
+ and the other approaches will perform with respect to each other when a more
+ complex set of instructions is programmed for the local function body (e.g.,
+ if a more complex set of instructions in the local function
+ body were to inhibit some compilers from inlining functor objects also other
+ approaches like Boost.Lambda
+ and Boost.Phoenix
+ could start to show higher run-times even when optimization
+ is enabled).
+ 
+<div class="informaltable"><table class="table">
+<colgroup><col></colgroup>
+<thead><tr><th>
+ 
+ Legend, Source Files, and Commands
+ 
+ </th></tr></thead>
+<tbody>
+<tr><td>
+ 
+ <img src="../../../example/profile_legend.png" width="1170" alt="profile_legend">
+ 
+ </td></tr>
+<tr><td>
+ 
+ The local function was called <code class="literal">1e8</code> times to add
+ together all the elements of a vector and the run-time was measured
+ using Boost.Chrono
+ averaging over <code class="literal">10</code> executions of the vector summation
+ (see source files profile_boost_local.cpp,
+ profile_boost_local_inline.cpp,
+ profile_local_functor.cpp,
+ profile_global_functor.cpp,
+ profile_0x_lambda.cpp,
+ profile_boost_lambda.cpp,
+ and profile_boost_phoenix.cpp).
+ 
+ </td></tr>
+<tr><td>
+ 
+ The following commands were executed from the library example directory
+ to measure compile-time, binary size, and run-time respectively:
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">> python chrono.py bjam {release|debug} <PROGRAM> # compile-time
+> size <PROGRAM> # binary size (Linux and Gygwin)
+> <PROGRAM> # run-time
+</pre>
+
+ 
+ </td></tr>
+</tbody>
+</table></div>
+<div class="informaltable"><table class="table">
+<colgroup><col></colgroup>
+<thead><tr><th>
+ 
+ GCC 4.5.1 With C++11
+ Lambdas and "Local Types as Template Parameters" (<code class="literal">bjam
+ cxxflags=-std=c++0x ...</code>) on Ubuntu Linux 10
+ 
+ </th></tr></thead>
+<tbody>
+<tr><td>
+ 
+ Compiled with <code class="literal">bjam release ...</code>
+ for maximum optimization (<code class="literal">-O3 -finline-functions</code>)
+ <img src="../../../example/profile_gcc-4.5.1-0x_release.png" width="1170" alt="profile_gcc-4.5.1-0x_release">
+ 
+ </td></tr>
+<tr><td>
+ 
+ Compiled with <code class="literal">bjam debug ...</code>
+ for no optimization (<code class="literal">-O0 -fno-inline</code>)
+ <img src="../../../example/profile_gcc-4.5.1-0x_debug.png" width="1170" alt="profile_gcc-4.5.1-0x_debug">
+ 
+ </td></tr>
+</tbody>
+</table></div>
+<div class="informaltable"><table class="table">
+<colgroup><col></colgroup>
+<thead><tr><th>
+ 
+ MSVC 8.0 With "Local Types as Template Parameters" (Without
+ C++11
+ Lambdas) on Windows XP
+ 
+ </th></tr></thead>
+<tbody>
+<tr><td>
+ 
+ Compiled with <code class="literal">bjam release ...</code>
+ for maximum optimization (<code class="literal">/O2 /Ob2</code>)
+ <img src="../../../example/profile_msvc-8.0_release.png" width="1170" alt="profile_msvc-8.0_release">
+ 
+ </td></tr>
+<tr><td>
+ 
+ Compiled with <code class="literal">bjam debug ...</code>
+ for no optimization (<code class="literal">/Od /Ob0</code>) <img src="../../../example/profile_msvc-8.0_debug.png" width="1170" alt="profile_msvc-8.0_debug">
+ 
+ </td></tr>
+</tbody>
+</table></div>
+<div class="informaltable"><table class="table">
+<colgroup><col></colgroup>
+<thead><tr><th>
+ 
+ GCC 4.3.4 With C++03
+ Only (Without C++11
+ Lambdas and Without "Local Types as Template Parameters) on
+ Cygwin
+ 
+ </th></tr></thead>
+<tbody>
+<tr><td>
+ 
+ Compiled with <code class="literal">bjam release ...</code>
+ for maximum optimization (<code class="literal">-O3 -finline-functions</code>)
+ <img src="../../../example/profile_gcc-4.3.4_release.png" width="1170" alt="profile_gcc-4.3.4_release">
+ 
+ </td></tr>
+<tr><td>
+ 
+ Compiled with <code class="literal">bjam debug ...</code>
+ for no optimization (<code class="literal">-O0 -fno-inline</code>)
+ <img src="../../../example/profile_gcc-4.3.4_debug.png" width="1170" alt="profile_gcc-4.3.4_debug">
+ 
+ </td></tr>
+</tbody>
+</table></div>
+</div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2009-2012 Lorenzo
+ Caminiti
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<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="No_Variadic_Macros.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: sandbox/closure/libs/local_function/doc/html/boost_localfunction/Bibliography.html
==============================================================================
--- (empty file)
+++ sandbox/closure/libs/local_function/doc/html/boost_localfunction/Bibliography.html 2012-01-21 13:28:36 EST (Sat, 21 Jan 2012)
@@ -0,0 +1,69 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Bibliography</title>
+<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
+<link rel="home" href="../index.html" title="Chapter 1. Boost.LocalFunction 1.0.0">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.LocalFunction 1.0.0">
+<link rel="prev" href="Release_Notes.html" title="Release Notes">
+<link rel="next" href="Acknowledgments.html" title="Acknowledgments">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="Release_Notes.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="Acknowledgments.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">
+<a name="boost_localfunction.Bibliography"></a><a class="link" href="Bibliography.html" title="Bibliography">Bibliography</a>
+</h2></div></div></div>
+
+ This section lists all the bibliographic references cited by this documentation.
+ 
+
+ [N2511]
+ Alisdair Meredith. Named Lambdas and Local Functions.
+ The C++ Standards Committee, document no. N2511=08-0021, 2008.
+ 
+
+ [N2529]
+ Jaakko Jarvi, John Freeman, Lawrence Crowl. Lambda Expressions and
+ Closures: Wording for Monomorphic Lambdas (Revision 3). The C++
+ Standards Committee, document no. N2529=08-0039, 2008.
+ 
+
+ [N2550]
+ Jaakko Jarvi, John Freeman, Lawrence Crowl. Lambda Expressions and
+ Closures: Wording for Monomorphic Lambdas (Revision 4). The C++
+ Standards Committee, document no. N2550=08-0060, 2008.
+ 
+
+ [N2657]
+ John Spicer. Local and Unamed Types as Template Arguments.
+ The C++ Standard Committee, document no. N2657=08-0167, 2008.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2009-2012 Lorenzo
+ Caminiti
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="Release_Notes.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="Acknowledgments.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: sandbox/closure/libs/local_function/doc/html/boost_localfunction/Examples.html
==============================================================================
--- (empty file)
+++ sandbox/closure/libs/local_function/doc/html/boost_localfunction/Examples.html 2012-01-21 13:28:36 EST (Sat, 21 Jan 2012)
@@ -0,0 +1,461 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Appendix: Examples</title>
+<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
+<link rel="home" href="../index.html" title="Chapter 1. Boost.LocalFunction 1.0.0">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.LocalFunction 1.0.0">
+<link rel="prev" href="Advanced_Topics.html" title="Advanced Topics">
+<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>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="Advanced_Topics.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">
+<a name="boost_localfunction.Examples"></a><a class="link" href="Examples.html" title="Appendix: Examples">Appendix: Examples</a>
+</h2></div></div></div>
+<div class="toc"><dl>
+<dt><a href="Examples.html#boost_localfunction.Examples.gcc_lambdas__without_c__11_">GCC
+ Lambdas (Without C++11)</a></dt>
+<dt><a href="Examples.html#boost_localfunction.Examples.constant_blocks">Constant
+ Blocks</a></dt>
+<dt>Scope Exits</dt>
+<dt><a href="Examples.html#boost_localfunction.Examples.gcc_nested_functions">GCC
+ Nested Functions</a></dt>
+<dt>N-Papers</dt>
+</dl></div>
+
+ This sections lists some (interesting) examples that use this library features.
+ 
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Examples.gcc_lambdas__without_c__11_"></a><a class="link" href="Examples.html#boost_localfunction.Examples.gcc_lambdas__without_c__11_" title="GCC Lambdas (Without C++11)">GCC
+ Lambdas (Without C++11)</a>
+</h3></div></div></div>
+
+ Combing local functions with the <a href="http://gcc.gnu.org/onlinedocs/gcc/Statement-Exprs.html" target="_top">statement
+ expression</a> GCC extension, it is possible to implement lambda functions
+ for GCC compilers even without C++11
+ support.
+ 
+<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">
+ This code only works on compilers that support the statement expression
+ GCC extension or that support <a href="http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions" target="_top">C++11
+ lambda</a> functions.
+ </td></tr>
+</table></div>
+
+ For example (see also "gcc_lambda.cpp" and "gcc_lambda_cpp11.cpp"):
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ With Local Functions (GCC only)
+ 
+ </th>
+<th>
+ 
+ C++11 Lambdas
+ 
+ </th>
+</tr></thead>
+<tbody><tr>
+<td>
+ 
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">int val = 2;
+int nums[] = {1, 2, 3};
+int* end = nums + 3;
+
+int* iter = std::find_if(nums, end,
+ GCC_LAMBDA(const bind val, int num, return bool) {
+ return num == val;
+ } GCC_LAMBDA_END
+);
+</pre>
+
+ 
+ </td>
+<td>
+ 
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">int val = 2;
+int nums[] = {1, 2, 3};
+int* end = nums + 3;
+
+int* iter = std::find_if(nums, end,
+ [val](int num) -> bool {
+ return num == val;
+ }
+);
+</pre>
+
+ 
+ </td>
+</tr></tbody>
+</table></div>
+
+ The macros are defined in "gcc_lambda.hpp".
+ 
+
+ This is possible because GCC statement expressions allow to put declaration
+ statements within expressions and therefore to declare a local function within
+ an expression. The macros automatically detect if the compiler supports
+ <a href="http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions" target="_top">C++11
+ lambda</a> functions in which case the implementation uses native lambdas
+ instead of local functions. However, <a href="http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions" target="_top">C++11
+ lambda</a> functions do not support constant binding so it is best to
+ only use <code class="computeroutput">const bind
+ variable</code> (same as <a href="http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions" target="_top">C++11
+ lambda</a> <code class="computeroutput">=variable</code>)
+ and <code class="computeroutput">bind&
+ variable</code> (same as <a href="http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions" target="_top">C++11
+ lambda</a> <code class="computeroutput">&variable</code>)
+ because these have the exact same semantic between the local function and
+ native lambda implementation. Unfortunately, the <a href="http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions" target="_top">C++11
+ lambda</a> short-hand binds <code class="computeroutput">&</code>
+ and <code class="computeroutput">=</code> (which automatically bind
+ all variables in scope either by reference or value) are not supported by
+ the macros because they are not supported by the local function implementation.
+ Finally, the result type <code class="computeroutput">return </code><code class="literal">result-type</code>
+ is optional and it is assumed <code class="computeroutput">void</code>
+ when it is not specified (as with <a href="http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions" target="_top">C++11
+ lambda</a> functions).
+ 
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Examples.constant_blocks"></a><a class="link" href="Examples.html#boost_localfunction.Examples.constant_blocks" title="Constant Blocks">Constant
+ Blocks</a>
+</h3></div></div></div>
+
+ It is possible to use local functions to check assertions between variables
+ that are constant within the assertion expression. This is advantageous because
+ assertions are not supposed to change the state of the program and ideally
+ the compiler will not compile assertions that modify variables.
+ 
+
+ For example, consider the following assertion where by mistake we programmed
+ <code class="computeroutput">operator=</code>
+ instead of <code class="computeroutput">operator==</code>:
+ 
+<pre class="programlisting">int x = 1, y = 2;
+assert(x = y); // Mistakenly `=` instead of `==`.
+</pre>
+
+ Ideally this code will not compile instead this example not only compiles
+ but the assertion even passes the run-time check and no error is generated
+ at all. The [N1613]
+ paper introduced the idea of a const-block which could
+ be used to wrap the assertion above and catch the mistake at compile-time.
+ Similarly to [N1613]
+ const-blocks, the following code will generate a compile-time error when
+ <code class="computeroutput">operator=</code>
+ is mistakenly used instead of <code class="computeroutput">operator==</code> because both <code class="computeroutput">x</code>
+ and <code class="computeroutput">y</code> are constants within
+ the block of code performing the assertion (see also "const_block.cpp"):
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ With Local Functions
+ 
+ </th>
+<th>
+ 
+ N1613 Constant Block
+ 
+ </th>
+</tr></thead>
+<tbody><tr>
+<td>
+ 
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">int x = 1, y = 2;
+CONST_BLOCK(x, y) { // Constant block.
+ assert(x = y); // Compiler error.
+} CONST_BLOCK_END
+</pre>
+
+ 
+ </td>
+<td>
+ 
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">int x = 1, y = 2;
+const { // Constant block.
+ assert(x = y); // Compiler error.
+}
+</pre>
+
+ 
+ </td>
+</tr></tbody>
+</table></div>
+
+ The macros are defined in "const_block.hpp".
+ 
+
+ The constant block macros are implemented using a local function which binds
+ by constant reference <code class="computeroutput">const bind&</code>
+ all the specified variables, it executes the <code class="computeroutput">assert</code>
+ instruction in local function body, and the local function is then called
+ immediately after it is defined. More in general, constant blocks can be
+ used to evaluate any instruction (not just assertions) within a block were
+ all specified variables are constant.
+ 
+
+ Unfortunately, constant blocks cannot be implemented with <a href="http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions" target="_top">C++11
+ lambda</a> functions because these do not support constant binding. Ideally,
+ <a href="http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions" target="_top">C++11
+ lambda</a> functions would allow to bind variables also using <code class="computeroutput">const& variable</code> (constant reference) and <code class="computeroutput">const&</code>
+ (all variables by constant reference). Variables bound by value using <a href="http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions" target="_top">C++11
+ lambda</a> functions (<code class="computeroutput">variable</code>,
+ <code class="computeroutput">=variable</code>,
+ and <code class="computeroutput">=</code>) are constant but they
+ are required to be <code class="computeroutput">CopyConstructible</code>
+ and they introduce potentially expensive copy operations.
+ 
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Examples.scope_exits"></a><a class="link" href="Examples.html#boost_localfunction.Examples.scope_exits" title="Scope Exits">Scope Exits</a>
+</h3></div></div></div>
+
+ Scope exits allow to execute arbitrary code at the exit of the enclosing
+ scope and they are provided by the Boost.ScopeExit
+ library.
+ 
+
+ For curiosity, here we show how to re-implement scope exits using local functions.
+ One small advantage of scope exits that use local functions is that they
+ support constant binding. Boost.ScopeExit
+ does not directly support constant binding (however, it is always possible
+ to introduce an extra <code class="computeroutput">const</code>
+ local variable, assign it to the value to bind, and then bind the <code class="computeroutput">const</code> variable so to effectively have constant
+ binding with Boost.ScopeExit
+ as well). In general, the authors recommend to use Boost.ScopeExit
+ instead of the code listed here whenever possible.
+ 
+
+ The following example binds <code class="computeroutput">p</code>
+ by constant reference so this variable cannot be modified within the scope
+ exit body but it is not copied and it will present the value it has at the
+ exit of the enclosing scope and not at the scope exit declaration (see also
+ "scope_exit.cpp"):
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ With Local Functions
+ 
+ </th>
+<th>
+ 
+ Boost.ScopeExit
+ 
+ </th>
+</tr></thead>
+<tbody><tr>
+<td>
+ 
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">person& p = persons_.back();
+person::evolution_t checkpoint = p.evolution_;
+
+SCOPE_EXIT(const bind checkpoint, const bind& p, bind this_) {
+ if (checkpoint == p.evolution_) this_->persons_.pop_back();
+} SCOPE_EXIT_END
+</pre>
+
+ 
+ </td>
+<td>
+ 
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">person& p = persons_.back();
+person::evolution_t checkpoint = p.evolution_;
+
+BOOST_SCOPE_EXIT(checkpoint, &p, this_) { // Or extra variable `const_p`.
+ if (checkpoint == p.evolution_) this_->persons_.pop_back();
+} BOOST_SCOPE_EXIT_END
+</pre>
+
+ 
+ </td>
+</tr></tbody>
+</table></div>
+
+ The macros are defined in "scope_exit.hpp".
+ 
+
+ The scope exit macros are implemented by passing a local function to the
+ constructor of the following object:
+ 
+
+
+<pre class="programlisting">struct scope_exit {
+ scope_exit(boost::function<void (void)> f): f_(f) {}
+ ~scope_exit(void) { f_(); }
+private:
+ boost::function<void (void)> f_;
+};
+</pre>
+
+ 
+
+ The object variable is declared locally within the enclosing scope so the
+ object destructor will be invoked at the exit of the enclosing scope and
+ it will in turn call the local function. The scope exit local function has
+ no parameter and <code class="computeroutput">void</code> result
+ type but it supports binding and constant binding.
+ 
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Examples.gcc_nested_functions"></a><a class="link" href="Examples.html#boost_localfunction.Examples.gcc_nested_functions" title="GCC Nested Functions">GCC
+ Nested Functions</a>
+</h3></div></div></div>
+
+ The GCC C compiler supports local functions under the name of <a href="http://gcc.gnu.org/onlinedocs/gcc/Nested-Functions.html" target="_top">nested
+ functions</a>. Nested functions are exclusively a C extension of the
+ GCC compiler (they are not supported for C++ not even by the GCC compiler,
+ and they are not part of any C or C++ standard, nor they are supported by
+ other compilers like MSVC).
+ 
+
+ The following examples are taken form the GCC nested function documentation
+ but are programmed using this library:
+ 
+<div class="informaltable"><table class="table">
+<colgroup><col></colgroup>
+<thead><tr><th>
+ 
+ Files
+ 
+ </th></tr></thead>
+<tbody>
+<tr><td>
+ 
+ "gcc_square.cpp"
+ 
+ </td></tr>
+<tr><td>
+ 
+ "gcc_access.cpp"
+ 
+ </td></tr>
+<tr><td>
+ 
+ "gcc_store.cpp"
+ 
+ </td></tr>
+</tbody>
+</table></div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Examples.n_papers"></a><a class="link" href="Examples.html#boost_localfunction.Examples.n_papers" title="N-Papers">N-Papers</a>
+</h3></div></div></div>
+
+ The following examples are taken from a number of N-papers and programmed
+ using this library.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Files
+ 
+ </th>
+<th>
+ 
+ Notes
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ "n2550_find_if.cpp"
+ 
+ </td>
+<td>
+ 
+ This example is adapted from [N2550]
+ (<a href="http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions" target="_top">C++11
+ lambda</a> functions): It passes a local function to the STL
+ algorithm <code class="computeroutput">std::find_if</code>.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ "n2529_this.cpp"
+ 
+ </td>
+<td>
+ 
+ This example is adapted from [N2529]
+ (<a href="http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions" target="_top">C++11
+ lambda</a> functions): It binds the object in scope <code class="computeroutput">this</code> to a local function.
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2009-2012 Lorenzo
+ Caminiti
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="Advanced_Topics.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>

Added: sandbox/closure/libs/local_function/doc/html/boost_localfunction/Getting_Started.html
==============================================================================
--- (empty file)
+++ sandbox/closure/libs/local_function/doc/html/boost_localfunction/Getting_Started.html 2012-01-21 13:28:36 EST (Sat, 21 Jan 2012)
@@ -0,0 +1,200 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Getting Started</title>
+<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
+<link rel="home" href="../index.html" title="Chapter 1. Boost.LocalFunction 1.0.0">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.LocalFunction 1.0.0">
+<link rel="prev" href="../index.html" title="Chapter 1. Boost.LocalFunction 1.0.0">
+<link rel="next" href="Tutorial.html" title="Tutorial">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../index.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="Tutorial.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">
+<a name="boost_localfunction.Getting_Started"></a><a class="link" href="Getting_Started.html" title="Getting Started">Getting Started</a>
+</h2></div></div></div>
+<div class="toc"><dl>
+<dt><a href="Getting_Started.html#boost_localfunction.Getting_Started.this_documentation">This
+ Documentation</a></dt>
+<dt><a href="Getting_Started.html#boost_localfunction.Getting_Started.compilers_and_platforms">Compilers
+ and Platforms</a></dt>
+<dt>Installation</dt>
+<dt><a href="Getting_Started.html#boost_localfunction.Getting_Started.compile_time_configuration">Compile-Time
+ Configuration</a></dt>
+</dl></div>
+
+ This section explains how to setup a system to use this library.
+ 
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Getting_Started.this_documentation"></a><a class="link" href="Getting_Started.html#boost_localfunction.Getting_Started.this_documentation" title="This Documentation">This
+ Documentation</a>
+</h3></div></div></div>
+
+ Programmers should have enough knowledge to use this library after reading
+ the <a class="link" href="../">Introduction</a>, <a class="link" href="../">Getting
+ Started</a>, and <a class="link" href="../">Tutorial</a>
+ sections. The <a class="link" href="../">Advanced Topics</a>
+ and Reference sections can be consulted
+ at a later point to gain a more advanced knowledge of the library. All the
+ other sections of this documentation are optional.
+ 
+
+ Some footnotes are marked by the word "Rationale".
+ They explain reasons behind decisions made during the design and implementation
+ of this library.
+ 
+
+ In some of the examples presented in this documentation, the Boost.Test
+ macro <code class="computeroutput">BOOST_CHECK</code> is used
+ equivalently to <code class="computeroutput">assert</code> and
+ Boost.Test
+ <code class="computeroutput">BOOST_AUTO_TEST_CASE</code> equivalently
+ to <code class="computeroutput">main</code>. [<a name="boost_localfunction.Getting_Started.this_documentation.f0" href="#ftn.boost_localfunction.Getting_Started.this_documentation.f0" class="footnote">1</a>]
+ 
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Getting_Started.compilers_and_platforms"></a><a class="link" href="Getting_Started.html#boost_localfunction.Getting_Started.compilers_and_platforms" title="Compilers and Platforms">Compilers
+ and Platforms</a>
+</h3></div></div></div>
+
+ The implementation of this library uses preprocessor and template metaprogramming
+ (as supported by Boost.Preprocessor
+ and Boost.MPL),
+ templates with partial specializations and function pointers (similarly to
+ Boost.Function).
+ As a consequence, this library is fairly demanding on compilers' compliance
+ with the C++03
+ standard. At present, this library has been successfully compiled and tested
+ on the following compilers and platforms:
+ 
+<div class="orderedlist"><ol class="orderedlist" type="1">
+<li class="listitem">
+ GNU Compiler Collection (GCC) 4.5.1 (with and without C++11
+ features enabled) on Ubuntu Linux 10.
+ </li>
+<li class="listitem">
+ GCC 4.3.4 on Cygwin.
+ </li>
+<li class="listitem">
+ Miscrosoft Visual Studio Compiler (MSVC) 8.0 on Windows XP and Windows
+ 7.
+ </li>
+</ol></div>
+
+ This library has not yet been tested on any other compiler or platform.
+ 
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Getting_Started.installation"></a><a class="link" href="Getting_Started.html#boost_localfunction.Getting_Started.installation" title="Installation">Installation</a>
+</h3></div></div></div>
+
+ This library is composed of header files only. Therefore there is no pre-compiled
+ object file which needs to be installed. Programmers can simply instruct
+ the C++ compiler where to find the library header files (<code class="computeroutput">-I</code> option for GCC, <code class="computeroutput">/I</code> option for MSVC, etc) and they can start
+ compiling the code that uses this library.
+ 
+
+ This library implementation uses a number of Boost
+ libraries among which: Boost.Preprocessor,
+ Boost.ScopeExit,
+ Boost.Typeof,
+ Boost.TypeTraits,
+ and Boost.MPL.
+ These Boost libraries must be
+ properly installed on your system in order for this library to work.
+ 
+
+ The followings are part of the library private API, they are not documented,
+ and they should not be directly used by programmers: [<a name="boost_localfunction.Getting_Started.installation.f0" href="#ftn.boost_localfunction.Getting_Started.installation.f0" class="footnote">2</a>]
+ 
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem">
+ Any symbol defined by files within the <code class="computeroutput">"boost/local_function/aux_/"</code>
+ or <code class="computeroutput">"boost/local_function/detail"</code>
+ directories (these header files should not be directly included by programmers).
+ </li>
+<li class="listitem">
+ Any symbol prefixed by <code class="computeroutput">BOOST_LOCAL_FUNCTION_AUX_...</code> or <code class="computeroutput">BOOST_LOCAL_FUNCTION_DETAIL_...</code> (regardless of its namespace).
+ </li>
+<li class="listitem">
+ Any symbol within the <code class="computeroutput">boost::local_function::aux</code>
+ or <code class="computeroutput">boost::local_function::detail</code> namespace.
+ </li>
+<li class="listitem">
+ Any symbol prefixed by <code class="computeroutput">boost_local_function_aux_...</code> or <code class="computeroutput">boost_local_function_detail_...</code> (regardless of its namespace).
+ </li>
+</ul></div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Getting_Started.compile_time_configuration"></a><a class="link" href="Getting_Started.html#boost_localfunction.Getting_Started.compile_time_configuration" title="Compile-Time Configuration">Compile-Time
+ Configuration</a>
+</h3></div></div></div>
+
+ Some of the library behaviour can be changed at compile-time by defining
+ special configuration macros. If a configuration macro
+ is left undefined, the library will use an appropriate default value for
+ it.
+ 
+
+ All configuration macros have names prefixed by <code class="computeroutput">BOOST_LOCAL_CONFIG_...</code> (see the Reference
+ section). It is strongly 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.boost_localfunction.Getting_Started.this_documentation.f0" href="#boost_localfunction.Getting_Started.this_documentation.f0" class="para">1</a>] 
+ Rationale. Using Boost.Test
+ allows to add the documentation examples to the library regression test
+ suite so to make sure that the listed examples always compile and run correctly.
+ </div>
+<div class="footnote">[<a id="ftn.boost_localfunction.Getting_Started.installation.f0" href="#boost_localfunction.Getting_Started.installation.f0" 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
+ symbols with unique names to avoid name clashes. These symbols are separated
+ by the letter "<code class="computeroutput">X</code>"
+ when they are concatenated so they read more easily during debugging. 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 contained a leading or trailing
+ underscore, the concatenation could result in a symbol with double underscores
+ "<code class="computeroutput">__</code>" which is
+ reserved by the C++ standard. The "aux" symbols are private to
+ this library while the "detail" symbols can be used within Boost
+ by other libraries but they are still not part of this library public API.
+ </div>
+</div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2009-2012 Lorenzo
+ Caminiti
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../index.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="Tutorial.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: sandbox/closure/libs/local_function/doc/html/boost_localfunction/Implementation.html
==============================================================================
--- (empty file)
+++ sandbox/closure/libs/local_function/doc/html/boost_localfunction/Implementation.html 2012-01-21 13:28:36 EST (Sat, 21 Jan 2012)
@@ -0,0 +1,422 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Appendix: Implementation</title>
+<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
+<link rel="home" href="../index.html" title="Chapter 1. Boost.LocalFunction 1.0.0">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.LocalFunction 1.0.0">
+<link rel="prev" href="No_Variadic_Macros.html" title="Annex: No Variadic Macros">
+<link rel="next" href="Release_Notes.html" title="Release Notes">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="No_Variadic_Macros.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="Release_Notes.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">
+<a name="boost_localfunction.Implementation"></a><a class="link" href="Implementation.html" title="Appendix: Implementation">Appendix: Implementation</a>
+</h2></div></div></div>
+<div class="toc"><dl>
+<dt><a href="Implementation.html#boost_localfunction.Implementation.local_classes_as_template_parameters">Local
+ Classes as Template Parameters</a></dt>
+<dt><a href="Implementation.html#boost_localfunction.Implementation.parsing_macros">Parsing
+ Macros</a></dt>
+<dt><a href="Implementation.html#boost_localfunction.Implementation.local_functions">Local
+ Functions</a></dt>
+</dl></div>
+
+ This section gives an overview of the key programming techniques used to implement
+ this library.
+ 
+<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">
+ The code listed here can be used by curious readers and library maintainers
+ as a reference in trying to understand this library source files. There is
+ absolutely no guarantee that the library implementation uses the exact code
+ listed here.
+ </td></tr>
+</table></div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Implementation.local_classes_as_template_parameters"></a><a class="link" href="Implementation.html#boost_localfunction.Implementation.local_classes_as_template_parameters" title="Local Classes as Template Parameters">Local
+ Classes as Template Parameters</a>
+</h3></div></div></div>
+
+ This library uses a local class to implement the local function object. However,
+ in C++03
+ local classes (and therefore the local function objects they implement) cannot
+ be passed as template parameters (e.g., to the <code class="computeroutput">std::for_each</code>
+ algorithm), this is instead possible on C++11,
+ MSVC, and some other compilers (see [N2657]).
+ To work around this limitation, this library investigated the following two
+ "tricks" (both tricks can be extended to support eventual function
+ default parameters):
+ 
+<div class="orderedlist"><ol class="orderedlist" type="1">
+<li class="listitem">
+ The casting functor trick uses a non-local functor
+ that calls a static member function of the local class via a function
+ pointer. The static member function then calls the correct local function
+ body after type casting the object from a <code class="computeroutput">void*</code> pointer (local classes can always be
+ used for type casting).
+ </li>
+<li class="listitem">
+ The virtual functor trick derives the local functor
+ class from a non-local base class. The correct overridden implementation
+ of the virtual <code class="computeroutput">operator()</code> is then called via polymorphism.
+ </li>
+</ol></div>
+
+
+<pre class="programlisting">#define BOOST_TEST_MODULE ExampleTparamTricks
+#include <boost/test/unit_test.hpp>
+#include <vector>
+#include <algorithm>
+
+// Casting functor trick.
+struct casting_func {
+ explicit casting_func(void* obj, void (*call)(void*, const int&)):
+ obj_(obj), call_(call) {}
+ // Unfortunately, function pointer call is not inlined.
+ inline void operator()(const int& num) { call_(obj_, num); }
+private:
+ void* obj_;
+ void (*call_)(void*, const int&);
+};
+
+// Virtual functor trick.
+struct virtual_func {
+ struct interface {
+ // Unfortunately, virtual function call is not inlined.
+ inline virtual void operator()(const int&) {}
+ };
+ explicit virtual_func(interface& func): func_(&func) {}
+ inline void operator()(const int& num) { (*func_)(num); }
+private:
+ interface* func_;
+};
+
+BOOST_AUTO_TEST_CASE( example_tparam_tricks ) {
+ int sum = 0, factor = 10;
+
+ // Local class for local function.
+ struct local_add: virtual_func::interface {
+ explicit local_add(int& _sum, const int& _factor):
+ sum_(_sum), factor_(_factor) {}
+ inline void operator()(const int& num) {
+ body(sum_, factor_, num);
+ }
+ inline static void call(
+ void* obj, const int& num) {
+ local_add* self = static_cast<local_add*>(obj);
+ self->body(self->sum_, self->factor_, num);
+ }
+ private:
+ int& sum_;
+ const int& factor_;
+ inline void body(int& sum, const int& factor, const int& num) {
+ sum += factor * num;
+ }
+ } add_local(sum, factor);
+ casting_func add_casting(&add_local, &local_add::call);
+ virtual_func add_virtual(add_local);
+
+ std::vector<int> v(10);
+ std::fill(v.begin(), v.end(), 1);
+
+// std::for_each(v.begin(), v.end(), add_local); // Error but OK on C++11.
+ std::for_each(v.begin(), v.end(), add_casting); // OK.
+ std::for_each(v.begin(), v.end(), add_virtual); // OK.
+
+ BOOST_CHECK( sum == 200 );
+}
+</pre>
+
+ 
+
+ The casting functor trick measured slightly better run-time performances
+ than the virtual functor trick so the current implementation of this library
+ uses the casting functor trick (probably because in addition to the indirect
+ function call, the virtual functor trick also requires accessing the <a href="http://en.wikipedia.org/wiki/Virtual_method_table" target="_top">virtual function
+ table</a>). However, neither one of tricks has been observed to allow
+ for compiler optimizations that inline the local function calls because they
+ rely on one indirect function call (via either a function pointer or a virtual
+ function respectively). Therefore, on compilers that accept local types as
+ template parameters (MSVC, C++11,
+ etc, see [N2657]),
+ this library automatically generates code that passes the local class type
+ directly as template parameter without using neither one of these two tricks
+ in order to take full advantage of compiler optimizations that inline the
+ local function calls.
+ 
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Implementation.parsing_macros"></a><a class="link" href="Implementation.html#boost_localfunction.Implementation.parsing_macros" title="Parsing Macros">Parsing
+ Macros</a>
+</h3></div></div></div>
+
+ This library macros can parse the list of specified parameters and detect
+ if any of the bound parameter name matches the token <code class="computeroutput">this_</code>
+ (to generate special code to bind the object in scope), or if the parameter
+ is bound by <code class="computeroutput">const</code> (to generate
+ special code to bind by constant), etc. The parameter tokens are inspected
+ using preprocessor metaprogramming, specifically using the macros from <code class="computeroutput">"boost/local_function/detail/preprocessor/keyword/"</code>.
+ [<a name="boost_localfunction.Implementation.parsing_macros.f0" href="#ftn.boost_localfunction.Implementation.parsing_macros.f0" class="footnote">24</a>]
+ 
+
+ For example, the following code defines a macro that allows the preprocessor
+ to detect if a set of space-separated tokens end with <code class="computeroutput">this_</code>
+ or not:
+ 
+
+
+<pre class="programlisting">#include <boost/local_function/detail/preprocessor/keyword/thisunderscore.hpp>
+#include <boost/local_function/detail/preprocessor/keyword/const.hpp>
+#include <boost/local_function/detail/preprocessor/keyword/bind.hpp>
+#define BOOST_TEST_MODULE ExampleImplPpKeyword
+#include <boost/test/unit_test.hpp>
+
+// Expand to 1 if space-separated tokens end with `this_`, 0 otherwise.
+#define HAS_THIS_(tokens) \
+ BOOST_LOCAL_FUNCTION_DETAIL_PP_KEYWORD_IS_THISUNDERSCORE_BACK( \
+ BOOST_LOCAL_FUNCTION_DETAIL_PP_KEYWORD_BIND_REMOVE_FRONT( \
+ BOOST_LOCAL_FUNCTION_DETAIL_PP_KEYWORD_CONST_REMOVE_FRONT( \
+ tokens \
+ )))
+
+BOOST_AUTO_TEST_CASE( example_impl_pp_keyword ) {
+ BOOST_CHECK( HAS_THIS_(const bind this_) == 1 );
+ BOOST_CHECK( HAS_THIS_(const bind& x) == 0 );
+}
+</pre>
+
+ 
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Implementation.local_functions"></a><a class="link" href="Implementation.html#boost_localfunction.Implementation.local_functions" title="Local Functions">Local
+ Functions</a>
+</h3></div></div></div>
+
+ The local function macros expand to code equivalent to the following:
+ 
+
+
+<pre class="programlisting">#include <boost/local/function.hpp>
+#include <iostream>
+#include <sstream>
+#include <algorithm>
+#include <vector>
+#include <string>
+
+struct calculator {
+ std::ostringstream output;
+
+ void factorials(const std::vector<int>& nums,
+ const std::string& separator = " ") {
+
+ int // The local function result type (just before the `BOOST_LOCAL_FUNCTION_PARAMS` macro).
+
+ // *BEGIN* The macro
+ // BOOST_LOCAL_FUNCTION_PARAMS( (int n) (bool recursion)(default false)
+ // (const bind& separator) (bind this) )
+ // expands (at line 21) to:
+
+ // DEDUCE RESULT TYPE
+ // Long name `ERROR_...` gives meaningful compiler-error message if programmers forget result type before the macro. 
+ (*ERROR_missing_result_type_before_the_local_function_parameter_macro_id21)();
+ // Use Boost.ScopeExit type deduction technique (tagging, wrapping, struct, etc) so to work on all compilers (specifically, some GCC version give internal errors otherwise).
+ typedef void (*boost_local_auxXdeduce_result_tag21)( int ERROR_missing_result_type_before_the_local_function_parameter_macro_id21);
+ typedef BOOST_TYPEOF(boost::scope_exit::aux::wrap( boost::scope_exit::aux::deref( ERROR_missing_result_type_before_the_local_function_parameter_macro_id21, (boost_local_auxXdeduce_result_tag21)0))) boost
_local_auxXdeduce_result_wrap21;
+ typedef boost_local_auxXdeduce_result_wrap21::type boost_local_auxXdeduce_result_capture21;
+ struct boost_local_auxXdeduce_result_params21 {
+ typedef boost_local_auxXdeduce_result_capture21 function_ptr_type;
+ };
+ typedef boost::remove_pointer< boost_local_auxXdeduce_result_params21::function_ptr_type >::type boost_local_auxXdeduce_result_function_type21;
+ typedef boost::function_traits< boost_local_auxXdeduce_result_function_type21>::result_type boost_local_auxXresult_type21;
+
+ // HANDLE BOUND PARAMETERS
+ // Deduce object `this` type (using technique from Boost.ScopeExit patch to support `this`).
+#if BOOST_WORKAROUND(BOOST_MSVC,>=1300)
+ enum { boost_se_thistype_index_21 = sizeof(*boost::scope_exit::msvc_typeof_this::encode_start(this)) };
+ typedef boost::scope_exit::msvc_typeof_this::msvc_typeid_wrapper<boost_se_thistype_index_21>::type se_this_type21;
+#else
+ typedef BOOST_TYPEOF(this) se_this_type21;
+#endif
+ // Deduce other `& separator` type (using Boost.ScopeExit techniques).
+ typedef void (*boost_se_tag_0_21)(int & separator);
+ typedef BOOST_TYPEOF(boost::scope_exit::aux::wrap( boost::scope_exit::aux::deref(& separator, (boost_se_tag_0_21)0))) boost_se_wrapped_t_0_21;
+ typedef boost_se_wrapped_t_0_21::type boost_se_capture_t_0_21;
+ // Store bound parameter values and references.
+ struct boost_se_params_t_21 {
+ se_this_type21 se_this;
+ typedef boost_se_capture_t_0_21 boost_se_param_t_0_21;
+ boost::scope_exit::aux::member< boost_se_param_t_0_21, boost_se_tag_0_21 > boost_se_param_0_21;
+ } boost_local_auxXparams21 = {
+ this ,
+#ifdef BOOST_SCOPE_EXIT_AUX_TPL_WORKAROUND
+ {
+#endif
+ boost::scope_exit::aux::deref(& separator, (boost_se_tag_0_21)0)
+#ifdef BOOST_SCOPE_EXIT_AUX_TPL_WORKAROUND
+ }
+#endif
+ };
+ // Use variable name `...args` without line number to hold bound parameter values (so the same variable name can be used by the `NAME` macro even if it expands on a different line number).
+ // The `declared<>` template makes sure that the variable `...args` is not declared multiple times in the same context (if the variable is already declared, this template expand to a no-operation).
+ boost::scope_exit::aux::declared< boost::scope_exit::aux::resolve< sizeof(boost_local_auxXargs) >::cmp1<0>::cmp2 > boost_local_auxXargs;
+ boost_local_auxXargs.value = &boost_local_auxXparams21;
+
+ // LOCAL FUNCTOR
+ class boost_local_auxXfunctor21 {
+ typedef boost_local_auxXresult_type21 (boost_local_auxXfunction_type) ( int n , bool recursion );
+ typedef ::boost::local::aux::function< boost_local_auxXfunction_type, 1 > boost_local_auxXfunctor_type;
+ typedef ::boost::add_const< boost_se_params_t_21:: boost_se_param_t_0_21 >::type & separatorXboost_local_auxXtypeof_type ;
+ typedef se_this_type21 thisXboost_local_auxXtypeof_type ;
+ public:
+ // Take a generic pointer so it can be invoked by the `NAME` macro even if it expands on a different line number. 
+ inline explicit boost_local_auxXfunctor21( void* bindings) :
+ boost_local_auxXbind_this( static_cast< boost_se_params_t_21* >( bindings)-> se_this )
+ , boost_local_auxXbind0 ( static_cast< boost_se_params_t_21* >( bindings)-> boost_se_param_0_21.value )
+ { }
+
+ // Implement `operator()` for all parameters and any combination of default parameter.
+ inline boost_local_auxXresult_type21 operator()(
+ ::boost::call_traits< ::boost::function_traits< boost_local_auxXfunction_type>::arg1_type>::param_type arg1
+ , ::boost::call_traits< ::boost::function_traits< boost_local_auxXfunction_type>::arg2_type>::param_type arg2
+ ) const {
+ return boost_local_auxXbody( boost_local_auxXbind0 , boost_local_auxXbind_this , arg1 , arg2 );
+ }
+ inline boost_local_auxXresult_type21 operator()(
+ ::boost::call_traits< ::boost::function_traits< boost_local_auxXfunction_type>::arg1_type>::param_type arg1
+ ) const {
+ return boost_local_auxXbody( boost_local_auxXbind0 , boost_local_auxXbind_this , arg1 );
+ }
+
+ // "Casting functor trick" to pass this local class as template parameter.
+ inline static boost_local_auxXresult_type21 boost_local_auxXcall0(
+ void* object
+ , ::boost::call_traits< ::boost::function_traits< boost_local_auxXfunction_type>::arg1_type>::param_type arg1
+ , ::boost::call_traits< ::boost::function_traits< boost_local_auxXfunction_type>::arg2_type>::param_type arg2
+ ) {
+ return static_cast< boost_local_auxXfunctor21* >( object)->operator()( arg1 , arg2 );
+ }
+ inline static boost_local_auxXresult_type21 boost_local_auxXcall1(
+ void* object
+ , ::boost::call_traits< ::boost::function_traits< boost_local_auxXfunction_type>::arg1_type>::param_type arg1
+ ) {
+ return static_cast< boost_local_auxXfunctor21* >( object)->operator()( arg1 );
+ }
+ inline static void boost_local_auxXinit_call( void* object, boost_local_auxXfunctor_type& functor) {
+ functor.boost_local_auxXinit_call(object, &boost_local_auxXcall0 , &boost_local_auxXcall1 );
+ }
+
+ private:
+ // Hold bound variables (by value and reference).
+ se_this_type21 & boost_local_auxXbind_this ;
+ ::boost::add_const< boost_se_params_t_21:: boost_se_param_t_0_21 >::type & boost_local_auxXbind0 ;
+ // This same declaration is first made at global scope in one of the library header files. This declaration needs to be repeated here so it is also visible from within the local function body to allow for nesting local function into one another.
+ boost::scope_exit::aux::undeclared boost_local_auxXargs;
+
+ // The local function body.
+ inline boost_local_auxXresult_type21 boost_local_auxXbody(
+ ::boost::add_const< boost_se_params_t_21:: boost_se_param_t_0_21 >::type & separator
+ , se_this_type21 const this_ // Use special name `this_` instead of `this` here.
+ // Specify default parameter values here.
+ , int n , bool recursion = false
+ ) const
+
+ // *END* The expansion of `BOOST_LOCAL_FUNCTION_PARAMS` ends here.
+
+ // *BEGIN* The local function body code `{ ... }` as specified by the programmers:
+
+ {
+
+ int result = 0;
+
+ if (n < 2 ) result = 1;
+ else result = n * factorial(n - 1, true); // Recursive call.
+
+ if (!recursion) this_->output << result << separator;
+ return result;
+ }
+
+ // *END* The local function body `{ ... }` ends here.
+
+ // *BEGIN* The macro `BOOST_LOCAL_FUNCTION_NAME(recursive factorial)` expands to:
+
+ public:
+ // Member variable named after the local function so the body can recursively call the local function (this must be defined here because the local function name was not known before). This must be public because it is also used to deduce the local function functor type later when when declaring the actual local function object.
+ boost_local_auxXfunctor_type factorial;
+ // Initializes the local functor member variable (this cannot be done directly within the constructor because the local function name is not known when the constructor code is expanded by the `PARAMS` macro).
+ inline void boost_local_auxXinit_recursion( boost_local_auxXfunctor_type& functor) {
+ factorial = functor;
+ }
+ // Declare the local class object -- which cannot be passed as template parameter (because it is a local class). It uses the variable with the generic `...args` name to pass the bound parameter values and references (so this variable name must not contain the line number because it is used by different macros expanding on different lines).
+ } boost_local_auxXfactorial(boost_local_auxXargs.value);
+ // Declare the actual local function object with the local function name -- which can be passed as template parameter (because it is a `boost::local::function` functor and not a local class).
+ BOOST_TYPEOF(boost_local_auxXfactorial. factorial) factorial;
+ // Initializes casting functor to pass local function as template parameter.
+ boost_local_auxXfactorial.boost_local_auxXinit_call( &boost_local_auxXfactorial, factorial);
+ // Initializes functor for recursion.
+ boost_local_auxXfactorial.boost_local_auxXinit_recursion( factorial);
+
+ // *END* The expansion of `BOOST_LOCAL_FUNCTION_NAME` ends here.
+
+ std::for_each(nums.begin(), nums.end(), factorial);
+ }
+};
+
+int main() {
+ std::vector<int> v(3);
+ v[0] = 1; v[1] = 4; v[2] = 7;
+
+ calculator calc;
+ calc.factorials(v);
+ std::cout << calc.output.str() << std::endl;
+
+ return 0;
+}
+</pre>
+
+ 
+</div>
+<div class="footnotes">
+ <hr width="100" align="left">
+<div class="footnote">[<a id="ftn.boost_localfunction.Implementation.parsing_macros.f0" href="#boost_localfunction.Implementation.parsing_macros.f0" class="para">24</a>] 
+ This technique is at the core of even more complex preprocessor parsing
+ macros like the ones that parse the Contract++
+ syntax.
+ </div>
+</div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2009-2012 Lorenzo
+ Caminiti
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="No_Variadic_Macros.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="Release_Notes.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: sandbox/closure/libs/local_function/doc/html/boost_localfunction/No_Variadic_Macros.html
==============================================================================
--- (empty file)
+++ sandbox/closure/libs/local_function/doc/html/boost_localfunction/No_Variadic_Macros.html 2012-01-21 13:28:36 EST (Sat, 21 Jan 2012)
@@ -0,0 +1,232 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Annex: No Variadic Macros</title>
+<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
+<link rel="home" href="../index.html" title="Chapter 1. Boost.LocalFunction 1.0.0">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.LocalFunction 1.0.0">
+<link rel="prev" href="Alternatives.html" title="Appendix: Alternatives">
+<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>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</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="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">
+<a name="boost_localfunction.No_Variadic_Macros"></a><a class="link" href="No_Variadic_Macros.html" title="Annex: No Variadic Macros">Annex: No Variadic
+ Macros</a>
+</h2></div></div></div>
+<div class="toc"><dl>
+<dt><a href="No_Variadic_Macros.html#boost_localfunction.No_Variadic_Macros.sequence_syntax">Sequence
+ Syntax</a></dt>
+<dt>Examples</dt>
+</dl></div>
+
+ This section illustrates an alternative syntax for compilers without variadic
+ macro support.
+ 
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.No_Variadic_Macros.sequence_syntax"></a><a class="link" href="No_Variadic_Macros.html#boost_localfunction.No_Variadic_Macros.sequence_syntax" title="Sequence Syntax">Sequence
+ Syntax</a>
+</h3></div></div></div>
+
+ Most modern compilers support <a href="http://en.wikipedia.org/wiki/Variadic_macro" target="_top">variaid
+ macros</a> (notably, these include GCC, MSVC, and all C++11
+ compilers). However, in the rare case that programmers need to use this library
+ on a compiler without variadic macros, this library also allows to specify
+ its macro parameters using a Boost.Preprocessor
+ sequence where tokens are separated by round parenthesis <code class="computeroutput">()</code>:
+ 
+<pre class="programlisting">(token1) (token2) ... // All compilers.
+</pre>
+
+ Instead of the comma-separated list that we have seen so far which requires
+ variadic macros:
+ 
+<pre class="programlisting">token1, token2, ... // Only compilers with varidic macros.
+</pre>
+
+ For example, the following syntax is accepted on all compilers with and without
+ variadic macros (see also "add_seq.cpp"):
+ 
+
+
+<pre class="programlisting">int sum = 0, factor = 10; // Variables in scope to bind.
+
+void BOOST_LOCAL_FUNCTION( (const bind factor) (bind& sum) (int num) ) {
+ sum += factor * num;
+} BOOST_LOCAL_FUNCTION_NAME(add)
+
+add(1); // Call the local function (with one parameter `num`).
+
+int nums[] = {2, 3};
+std::for_each(nums, nums + 2, add); // Pass it to an algorithm.
+</pre>
+
+ 
+
+ However, on compilers with variadic macros the comma-separated syntax we
+ have seen so far is preferred because more readable (see also "add.cpp"):
+ 
+
+
+<pre class="programlisting">{ // Some local scope.
+ int sum = 0, factor = 10; // Variables in scope to bind.
+
+ void BOOST_LOCAL_FUNCTION(const bind factor, bind& sum, int num) {
+ sum += factor * num;
+ } BOOST_LOCAL_FUNCTION_NAME(add)
+
+ add(1); // Call the local function (with one parameter `num`).
+ int nums[] = {2, 3};
+ std::for_each(nums, nums + 2, add); // Pass it to an algorithm.
+
+ BOOST_CHECK( sum == 60 ); // Assert final summation value.
+}
+</pre>
+
+ 
+
+ Note how the same macros accept both syntaxes on compilers with variadic
+ macros and only the sequence syntax on compilers without variadic macros.
+ Finally, an empty list is always specified using <code class="computeroutput">void</code>
+ on compilers with and without variadic macros.
+ 
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.No_Variadic_Macros.examples"></a><a class="link" href="No_Variadic_Macros.html#boost_localfunction.No_Variadic_Macros.examples" title="Examples">Examples</a>
+</h3></div></div></div>
+
+ The following is a list of most of the examples presented in this documentation
+ reprogrammed using the sequence syntax instead of the comma-separated list:
+ 
+<div class="informaltable"><table class="table">
+<colgroup><col></colgroup>
+<thead><tr><th>
+ 
+ Files
+ 
+ </th></tr></thead>
+<tbody>
+<tr><td>
+ 
+ "add_seq.cpp"
+ 
+ </td></tr>
+<tr><td>
+ 
+ "add_classifiers_seq.cpp"
+ 
+ </td></tr>
+<tr><td>
+ 
+ "add_default_seq.cpp"
+ 
+ </td></tr>
+<tr><td>
+ 
+ "add_except_seq.cpp"
+ 
+ </td></tr>
+<tr><td>
+ 
+ "add_inline_seq.cpp"
+ 
+ </td></tr>
+<tr><td>
+ 
+ "add_lambda_seq.cpp"
+ 
+ </td></tr>
+<tr><td>
+ 
+ "add_nobind_seq.cpp"
+ 
+ </td></tr>
+<tr><td>
+ 
+ "add_template_seq.cpp"
+ 
+ </td></tr>
+<tr><td>
+ 
+ "add_this_seq.cpp"
+ 
+ </td></tr>
+<tr><td>
+ 
+ "add_typed_seq.cpp"
+ 
+ </td></tr>
+<tr><td>
+ 
+ "add_with_default_seq.cpp"
+ 
+ </td></tr>
+<tr><td>
+ 
+ "nesting_seq.cpp"
+ 
+ </td></tr>
+<tr><td>
+ 
+ "overload_seq.cpp"
+ 
+ </td></tr>
+<tr><td>
+ 
+ "return_assign_seq.cpp"
+ 
+ </td></tr>
+<tr><td>
+ 
+ "ten_seq.cpp"
+ 
+ </td></tr>
+<tr><td>
+ 
+ "transform_seq.cpp"
+ 
+ </td></tr>
+<tr><td>
+ 
+ "typeof_seq.cpp"
+ 
+ </td></tr>
+<tr><td>
+ 
+ "typeof_template_seq.cpp"
+ 
+ </td></tr>
+</tbody>
+</table></div>
+</div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2009-2012 Lorenzo
+ Caminiti
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</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="Implementation.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: sandbox/closure/libs/local_function/doc/html/boost_localfunction/Release_Notes.html
==============================================================================
--- (empty file)
+++ sandbox/closure/libs/local_function/doc/html/boost_localfunction/Release_Notes.html 2012-01-21 13:28:36 EST (Sat, 21 Jan 2012)
@@ -0,0 +1,121 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Release Notes</title>
+<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
+<link rel="home" href="../index.html" title="Chapter 1. Boost.LocalFunction 1.0.0">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.LocalFunction 1.0.0">
+<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">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<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">
+<a name="boost_localfunction.Release_Notes"></a><a class="link" href="Release_Notes.html" title="Release Notes">Release Notes</a>
+</h2></div></div></div>
+
+ This section lists the major changes between different library releases (in
+ chronological order).
+ 
+<h6>
+<a name="boost_localfunction.Release_Notes.h0"></a>
+ <a name="boost_localfunction.Release_Notes.version_0_2_0__2011_05_14_"></a><a class="link" href="Release_Notes.html#boost_localfunction.Release_Notes.version_0_2_0__2011_05_14_">Version
+ 0.2.0 (2011-05-14)</a>
+ </h6>
+<div class="orderedlist"><ol class="orderedlist" type="1">
+<li class="listitem">
+ Replaced parenthesized syntax with variadic and sequencing macro syntaxes.
+ </li>
+<li class="listitem">
+ Profiled library performances against other approaches.
+ </li>
+<li class="listitem">
+ Replaced virtual functor trick with casting functor trick (for smaller
+ run-time).
+ </li>
+<li class="listitem">
+ Optimized library run-time (rearranging code and not using casting functor
+ trick on compilers that accept local classes as template parameters).
+ </li>
+<li class="listitem">
+ Supported inline and recursive local functions.
+ </li>
+<li class="listitem">
+ Added type-of macro to expose bound types.
+ </li>
+<li class="listitem">
+ Allowed to explicitly specify bound types.
+ </li>
+<li class="listitem">
+ Removed using <code class="computeroutput">boost::function</code> instead of exposing internal
+ local functor as public API.
+ </li>
+<li class="listitem">
+ Added functor to overload local functions (and functors in general).
+ </li>
+<li class="listitem">
+ Implemented support for nesting local functions, blocks, and exits into
+ one another.
+ </li>
+</ol></div>
+<h6>
+<a name="boost_localfunction.Release_Notes.h1"></a>
+ <a name="boost_localfunction.Release_Notes.version_0_1_1__2011_01_10_"></a><a class="link" href="Release_Notes.html#boost_localfunction.Release_Notes.version_0_1_1__2011_01_10_">Version
+ 0.1.1 (2011-01-10)</a>
+ </h6>
+<div class="orderedlist"><ol class="orderedlist" type="1">
+<li class="listitem">
+ Uploaded library source into Boost SVN sandbox.
+ </li>
+<li class="listitem">
+ Fixed prev/next arrows and other minor layouts in documentation.
+ </li>
+<li class="listitem">
+ Added Release section to documentation.
+ </li>
+</ol></div>
+<h6>
+<a name="boost_localfunction.Release_Notes.h2"></a>
+ <a name="boost_localfunction.Release_Notes.version_0_1_0__2011_01_03_"></a><a class="link" href="Release_Notes.html#boost_localfunction.Release_Notes.version_0_1_0__2011_01_03_">Version
+ 0.1.0 (2011-01-03)</a>
+ </h6>
+<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
+ Shared with Boost for first round of comments.
+ </li></ol></div>
+<h6>
+<a name="boost_localfunction.Release_Notes.h3"></a>
+ <a name="boost_localfunction.Release_Notes.version_0_0_1__2010_12_15_"></a><a class="link" href="Release_Notes.html#boost_localfunction.Release_Notes.version_0_0_1__2010_12_15_">Version
+ 0.0.1 (2010-12-15)</a>
+ </h6>
+<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
+ Completed development, examples, and documentation.
+ </li></ol></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2009-2012 Lorenzo
+ Caminiti
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<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>

Added: sandbox/closure/libs/local_function/doc/html/boost_localfunction/Tutorial.html
==============================================================================
--- (empty file)
+++ sandbox/closure/libs/local_function/doc/html/boost_localfunction/Tutorial.html 2012-01-21 13:28:36 EST (Sat, 21 Jan 2012)
@@ -0,0 +1,527 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Tutorial</title>
+<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
+<link rel="home" href="../index.html" title="Chapter 1. Boost.LocalFunction 1.0.0">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.LocalFunction 1.0.0">
+<link rel="prev" href="Getting_Started.html" title="Getting Started">
+<link rel="next" href="Advanced_Topics.html" title="Advanced Topics">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="Getting_Started.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="Advanced_Topics.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">
+<a name="boost_localfunction.Tutorial"></a><a class="link" href="Tutorial.html" title="Tutorial">Tutorial</a>
+</h2></div></div></div>
+<div class="toc"><dl>
+<dt>Local Functions</dt>
+<dt>Binding Variables</dt>
+<dt><a href="Tutorial.html#boost_localfunction.Tutorial.binding_the_object__this_">Binding
+ the Object <code class="computeroutput">this</code></a></dt>
+<dt>Templates</dt>
+</dl></div>
+
+ This section illustrates basic usages of this library.
+ 
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Tutorial.local_functions"></a><a class="link" href="Tutorial.html#boost_localfunction.Tutorial.local_functions" title="Local Functions">Local Functions</a>
+</h3></div></div></div>
+
+ Local functions are defined using macros from the header file <code class="computeroutput">boost/local_function.hpp</code>. The
+ macros must be used 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++11
+ lambda</a> functions which can instead be declared within expressions):
+ 
+<pre class="programlisting">#include <boost/local_function.hpp>
+
+...
+{ // Some declarative context.
+ ...
+ result-type BOOST_LOCAL_FUNCTION(parameters) {
+ body-code
+ } BOOST_LOCAL_FUNCTION_NAME(name)
+ ...
+}
+</pre>
+
+ The code expanded by the macros declares a function object (or functor)
+ with the local function name specified by <code class="computeroutput">BOOST_LOCAL_FUNCTION_NAME</code>.
+ [<a name="boost_localfunction.Tutorial.local_functions.f0" href="#ftn.boost_localfunction.Tutorial.local_functions.f0" class="footnote">3</a>] The usual C++ scope visibility rules apply to local functions
+ for which a local function is visible only within the enclosing scope in
+ which it is declared.
+ 
+
+ 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 related line numbers retain their
+ usual meaning and format. [<a name="boost_localfunction.Tutorial.local_functions.f1" href="#ftn.boost_localfunction.Tutorial.local_functions.f1" class="footnote">4</a>]
+ 
+
+ The local function parameters are passed to the <code class="computeroutput">BOOST_LOCAL_FUNCTION</code>
+ macro as a comma-separated list of tokens (see the <a class="link" href="../">No
+ Variadic Macros</a> section for compilers that do not support variadic
+ macros):
+ 
+<pre class="programlisting">BOOST_LOCAL_FUNCTION(<code class="literal">parameter-type1 parameter-name1</code>, <code class="literal">parameter-type2 parameter-name2, ...</code>)
+</pre>
+
+ The maximum number of parameters that can be passed to a local function (excluding
+ eventual bound variables) is controlled at compile-time by the configuration
+ macro <code class="computeroutput">BOOST_LOCAL_FUNCTION_CONFIG_ARITY_MAX</code>.
+ For example, let's program a local function named <code class="computeroutput">add</code>
+ that adds together two integers <code class="computeroutput">x</code>
+ and <code class="computeroutput">y</code> (see also "add_nobind.cpp"):
+ 
+
+
+<pre class="programlisting">int BOOST_LOCAL_FUNCTION(int x, int y) { // Local function.
+ return x + y;
+} BOOST_LOCAL_FUNCTION_NAME(add)
+
+BOOST_CHECK( add(1, 2) == 3 ); // Local function call.
+</pre>
+
+ 
+
+ If the local function has no parameter, it is possible to pass <code class="computeroutput">void</code> to the <code class="computeroutput">BOOST_LOCAL_FUNCTION</code>
+ macro (similarly to the C syntax that allows to use <code class="computeroutput">int
+ f(void)</code> for
+ a function with no parameter): [<a name="boost_localfunction.Tutorial.local_functions.f2" href="#ftn.boost_localfunction.Tutorial.local_functions.f2" class="footnote">5</a>]
+ 
+<pre class="programlisting">BOOST_LOCAL_FUNCTION(void) // No parameter.
+</pre>
+
+ For example, let's program a local function that always returns <code class="computeroutput">10</code> (see also "ten.cpp"):
+ 
+
+
+<pre class="programlisting">int BOOST_LOCAL_FUNCTION(void) { // No parameter.
+ return 10;
+} BOOST_LOCAL_FUNCTION_NAME(ten)
+
+BOOST_CHECK( ten() == 10 );
+</pre>
+
+ 
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Tutorial.Binding"></a><a class="link" href="Tutorial.html#boost_localfunction.Tutorial.Binding" title="Binding Variables">Binding Variables</a>
+</h3></div></div></div>
+
+ Variables in scope (local variables, enclosing function parameters, member
+ variables, etc) can be bound to a local function declaration. Only bound
+ variables, static variables, global variables, functions, and enumerations
+ from the enclosing scope are accessible from within the local function body.
+ The types of bound variables are automatically deduced by this library using
+ Boost.Typeof.
+ [<a name="boost_localfunction.Tutorial.Binding.f0" href="#ftn.boost_localfunction.Tutorial.Binding.f0" class="footnote">6</a>]
+ 
+<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 library implementation uses Boost.Typeof
+ to automatically deduce the types of the bound variables. In order to compile
+ code in type-of emulation mode, all types should be properly registered
+ with <code class="computeroutput">BOOST_TYPEOF_REGISTER_TYPE</code>
+ or <code class="computeroutput">BOOST_TYPEOF_REGISTER_TEMPLATE</code>
+ macros, or appropriate Boost.Typeof
+ headers should be included (see the Boost.Typeof
+ documentation for more detail).
+ </td></tr>
+</table></div>
+
+ This library introduces the new "keyword" <code class="computeroutput">bind</code>
+ [<a name="boost_localfunction.Tutorial.Binding.f1" href="#ftn.boost_localfunction.Tutorial.Binding.f1" class="footnote">7</a>] which is used in place of the parameter type to specify the name
+ of a variable in scope to bind (therefore, <code class="computeroutput">bind</code>
+ cannot be used as a local function parameter type). A variable can be bound
+ by value:
+ 
+<pre class="programlisting">bind variable-name // Bind by value.
+</pre>
+
+ Or by reference prefixing the variable name with <code class="computeroutput">&</code>:
+ 
+<pre class="programlisting">bind& variable-name // Bind by reference.
+</pre>
+
+ 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">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>
+
+ Note that when <code class="computeroutput">const</code> is used,
+ it must always precede <code class="computeroutput">bind</code>.
+ [<a name="boost_localfunction.Tutorial.Binding.f2" href="#ftn.boost_localfunction.Tutorial.Binding.f2" class="footnote">8</a>]
+ 
+
+ 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 declaration scope
+ of the local function otherwise the bound references will be invalid resulting
+ in undefined behaviour (in other words, the usual care in using C++ references
+ must be taken for variables bound by reference).
+ 
+
+ The type of a bound variable is automatically deduced and it is the exact
+ same type used to declare such a variable in the enclosing scope with the
+ following notes:
+ 
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem">
+ If a bound variable was declared constant in the enclosing scope, it
+ will be always bound by constant value or constant reference even if
+ <code class="computeroutput">bind</code> is used instead
+ of <code class="computeroutput">const bind</code>
+ . However, if a bound variable was not declared constant in the enclosing
+ scope 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++11
+ lambda</a> functions but it is supported by this library.) [<a name="boost_localfunction.Tutorial.Binding.f3" href="#ftn.boost_localfunction.Tutorial.Binding.f3" class="footnote">9</a>]
+ </li>
+<li class="listitem">
+ If a bound variable was declared as a reference in the enclosing scope,
+ it will still be bound by value unless it is explicitly bound by reference
+ using <code class="computeroutput">bind&</code>
+ or <code class="computeroutput">const bind&</code>. [<a name="boost_localfunction.Tutorial.Binding.f4" href="#ftn.boost_localfunction.Tutorial.Binding.f4" class="footnote">10</a>]
+ </li>
+</ul></div>
+
+ As with passing parameters to usual C++ functions, programmers might want
+ to bind variables of complex types by (possibly constant) reference instead
+ than by value to avoid expensive copy operations when these variables are
+ bound to a local function.
+ 
+
+ For example, let's program the local function <code class="computeroutput">add</code>
+ from the example in the <a class="link" href="../">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
+ (see also "add.cpp"):
+ 
+
+
+<pre class="programlisting">{ // Some local scope.
+ int sum = 0, factor = 10; // Variables in scope to bind.
+
+ void BOOST_LOCAL_FUNCTION(const bind factor, bind& sum, int num) {
+ sum += factor * num;
+ } BOOST_LOCAL_FUNCTION_NAME(add)
+
+ add(1); // Call the local function (with one parameter `num`).
+ int nums[] = {2, 3};
+ std::for_each(nums, nums + 2, add); // Pass it to an algorithm.
+
+ BOOST_CHECK( sum == 60 ); // Assert final summation value.
+}
+</pre>
+
+ 
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Tutorial.binding_the_object__this_"></a><a class="link" href="Tutorial.html#boost_localfunction.Tutorial.binding_the_object__this_" title="Binding the Object this">Binding
+ the Object <code class="computeroutput">this</code></a>
+</h3></div></div></div>
+
+ It is also possible to bind the object <code class="computeroutput">this</code>
+ when it is in scope (e.g., from an enclosing non-static member function).
+ This is done by using the special symbol <code class="computeroutput">this_</code>
+ [<a name="boost_localfunction.Tutorial.binding_the_object__this_.f0" href="#ftn.boost_localfunction.Tutorial.binding_the_object__this_.f0" class="footnote">11</a>] (instead of <code class="computeroutput">this</code>)
+ [<a name="boost_localfunction.Tutorial.binding_the_object__this_.f1" href="#ftn.boost_localfunction.Tutorial.binding_the_object__this_.f1" class="footnote">12</a>] as the name of the variable to bind in the local function declaration
+ and also to access the object within the local function body.
+ 
+
+ 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 and 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 pointed object is never copied even if <code class="computeroutput">this</code>
+ is bound by value (also it is not allowed to directly 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="[Warning]" src="../../../../../doc/src/images/warning.png"></td>
+<th align="left">Warning</th>
+</tr>
+<tr><td align="left" valign="top">
+ Unfortunately, mistakenly using <code class="computeroutput">this</code>
+ within the local function body instead of <code class="computeroutput">this_</code>
+ leads to undefined behaviour and it will not necessarily generate a compile-time
+ error. [<a name="boost_localfunction.Tutorial.binding_the_object__this_.f2" href="#ftn.boost_localfunction.Tutorial.binding_the_object__this_.f2" class="footnote">13</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 program a local function <code class="computeroutput">add</code>
+ similar to the one in the example from the <a class="link" href="../">Introduction</a>
+ section but using a member function to illustrate how to bind the object
+ <code class="computeroutput">this</code> (see also "add_this.cpp"):
+ 
+
+
+<pre class="programlisting">struct adder {
+ adder(): sum_(0) {}
+
+ int sum(const std::vector<int>& nums, const int factor = 10) {
+
+ void BOOST_LOCAL_FUNCTION(const bind factor, bind this_, int num) {
+ this_->sum_ += factor * num; // Use `this_` instead of `this`.
+ } BOOST_LOCAL_FUNCTION_NAME(add)
+
+ std::for_each(nums.begin(), nums.end(), add);
+ return sum_;
+ }
+private:
+ int sum_;
+};
+</pre>
+
+ 
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_localfunction.Tutorial.templates"></a><a class="link" href="Tutorial.html#boost_localfunction.Tutorial.templates" title="Templates">Templates</a>
+</h3></div></div></div>
+
+ When local functions are programmed within templates, they need to be declared
+ using the special macro <code class="computeroutput">BOOST_LOCAL_FUNCTION_TPL</code>
+ (see the Reference section): [<a name="boost_localfunction.Tutorial.templates.f0" href="#ftn.boost_localfunction.Tutorial.templates.f0" class="footnote">14</a>]
+ 
+<pre class="programlisting">#include <boost/local_function.hpp>
+
+...
+{ // Some declarative context within a template.
+ ...
+ result-type BOOST_LOCAL_FUNCTION_TPL(parameters) {
+ body-code
+ } BOOST_LOCAL_FUNCTION_NAME(name)
+ ...
+}
+</pre>
+
+ The <code class="computeroutput">BOOST_LOCAL_FUNCTION_TPL</code>
+ macro has the exact same syntax of the <code class="computeroutput">BOOST_LOCAL_FUNCTION</code>
+ macro that we have seen so far.
+ 
+
+ For example, let's rewrite a local function similar to the one from the
+ <a class="link" href="../">Introduction</a> section but
+ wrapped within a template:
+ 
+
+
+<pre class="programlisting">template<typename T>
+T total(const T& x, const T& y, const T& z) {
+ T sum = T(), factor = 10;
+
+ // Using the `..._TPL` macro.
+ T BOOST_LOCAL_FUNCTION_TPL(const bind factor, bind& sum, T num) {
+ return sum += factor * num;
+ } BOOST_LOCAL_FUNCTION_NAME(add)
+
+ add(x);
+
+ T nums[2]; nums[0] = y; nums[1] = z;
+ std::for_each(nums, nums + 2, add);
+
+ return sum;
+}
+</pre>
+
+ 
+</div>
+<div class="footnotes">
+ <hr width="100" align="left">
+<div class="footnote">[<a id="ftn.boost_localfunction.Tutorial.local_functions.f0" href="#boost_localfunction.Tutorial.local_functions.f0" class="para">3</a>] 
+ Rationale. The local function name must
+ be passed to the macro <code class="computeroutput">BOOST_LOCAL_FUNCTION_NAME</code>
+ ending the function definition so this macro can declare a local variable
+ with the local function name to hold the local function object.
+ </div>
+<div class="footnote">[<a id="ftn.boost_localfunction.Tutorial.local_functions.f1" href="#boost_localfunction.Tutorial.local_functions.f1" class="para">4</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 report the same value and
+ would no longer be useful to pinpoint the error.
+ </div>
+<div class="footnote">[<a id="ftn.boost_localfunction.Tutorial.local_functions.f2" href="#boost_localfunction.Tutorial.local_functions.f2" class="para">5</a>] 
+ Rationale. The C++03
+ standard does not allow pass empty parameters to a macro so the macro cannot
+ be invoked as <code class="computeroutput">BOOST_LOCAL_FUNCTION()</code>. On C99
+ compilers with properly implemented empty macro parameter support it would
+ be possible to allow <code class="computeroutput">BOOST_LOCAL_FUNCTION()</code> but this is already not the case for
+ MSVC so this syntax is never allowed to ensure better portability.
+ </div>
+<div class="footnote">[<a id="ftn.boost_localfunction.Tutorial.Binding.f0" href="#boost_localfunction.Tutorial.Binding.f0" 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,
+ this binding should be seen as an "extension" of the scope of
+ the bound variable from the enclosing scope to the scope of the local function
+ body. Therefore, contrary to the semantic of passing a function parameter,
+ the semantic of binding a variable does not depend on the variable type
+ but just on the variable name: "The variable in scope named x
+ should be accessible within the local function named f".
+ For example, this is useful for maintenance because if a bound variable
+ type is changed, the local function declaration does not have to change.
+ </div>
+<div class="footnote">[<a id="ftn.boost_localfunction.Tutorial.Binding.f1" href="#boost_localfunction.Tutorial.Binding.f1" class="para">7</a>] 
+ Obviously, the token <code class="computeroutput">bind</code>
+ is not a keyword of the C++ language. This library parses the token <code class="computeroutput">bind</code> during macro expansion using preprocessor
+ metaprogramming (see the <a class="link" href="../">Implementation</a>
+ section). 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.boost_localfunction.Tutorial.Binding.f2" href="#boost_localfunction.Tutorial.Binding.f2" class="para">8</a>] 
+ Rationale. The library macros could have
+ been implemented to accept both syntaxes <code class="computeroutput">const
+ bind ...</code>
+ and <code class="computeroutput">bind const
+ ...</code> equivalently. However, handling
+ both syntaxes would have complicated the macro implementation without adding
+ any feature so only one syntax (<code class="computeroutput">const
+ bind ...</code>)
+ is supported.
+ </div>
+<div class="footnote">[<a id="ftn.boost_localfunction.Tutorial.Binding.f3" href="#boost_localfunction.Tutorial.Binding.f3" class="para">9</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 conditions while these assertions were not supposed
+ to modify any of the variables they were using (see the Contract++
+ library). This was achieved by binding by constant reference <code class="computeroutput">const bind&</code> the variables needed by the assertions
+ and then by programming the local function body to check the assertions.
+ This way if any of the assertions mistakenly changes a bound variable
+ (for example confusing the operator <code class="computeroutput">==</code>
+ with <code class="computeroutput">=</code>), the compiler
+ correctly 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.boost_localfunction.Tutorial.Binding.f4" href="#boost_localfunction.Tutorial.Binding.f4" class="para">10</a>] 
+ Rationale. Variables originally declared
+ as references are bound by value unless <code class="computeroutput">[const] bind&</code>
+ is used so that references can be bound by both value <code class="computeroutput">[const] bind</code>
+ and reference <code class="computeroutput">[const] bind&</code> (this is the same binding semantic
+ adopted by Boost.ScopeExit).
+ On the other hand, variables originally declared as constants should
+ never loose their <code class="computeroutput">const</code>
+ qualifier (to prevent their modification not just in the enclosing
+ scope but also in the local scope) thus they are always bound by constant
+ even if <code class="computeroutput">bind[&]</code>
+ is used instead of <code class="computeroutput">const bind[&]</code>.
+ </div>
+<div class="footnote">[<a id="ftn.boost_localfunction.Tutorial.binding_the_object__this_.f0" href="#boost_localfunction.Tutorial.binding_the_object__this_.f0" class="para">11</a>] 
+ Rationale. The special name <code class="computeroutput">this_</code> was chosen following <a href="http://boost.2283326.n4.nabble.com/local-this-or-this-td3423912.html" target="_top">Boost
+ practises</a> which postfix with an underscore identifiers that are
+ named after keywords (the C++ keyword <code class="computeroutput">this</code>
+ in this case).
+ </div>
+<div class="footnote">[<a id="ftn.boost_localfunction.Tutorial.binding_the_object__this_.f1" href="#boost_localfunction.Tutorial.binding_the_object__this_.f1" class="para">12</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 parameter
+ that passes the bound object to the local function body. It would have
+ been possible to use <code class="computeroutput">this</code>
+ (instead of <code class="computeroutput">this_</code>) 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 <a href="http://groups.google.com/group/comp.lang.c++.moderated/browse_thread/thread/d3a86f27277f713b" target="_top">undefined
+ 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.boost_localfunction.Tutorial.binding_the_object__this_.f2" href="#boost_localfunction.Tutorial.binding_the_object__this_.f2" class="para">13</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">BOOST_LOCAL_FUNCTION_NAME</code>
+ macro only after the body so it must be made 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 variable so it is visible
+ in a local function nested within the body member function) -- see the
+ <a class="link" href="../">Implementation</a> section.
+ Therefore, from within the local function body the variable <code class="computeroutput">this</code> is visible but it refers to the local
+ functor and not to the bound object.
+ </div>
+<div class="footnote">[<a id="ftn.boost_localfunction.Tutorial.templates.f0" href="#boost_localfunction.Tutorial.templates.f0" 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++03
+ does not allow to use <code class="computeroutput">typename</code>
+ outside templates, the special <code class="computeroutput">TPL</code>
+ macro is used to indicate that the enclosing scope is a template so this
+ library can safely use <code class="computeroutput">typename</code>
+ to resolve expression type ambiguities.
+ </div>
+</div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2009-2012 Lorenzo
+ Caminiti
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="Getting_Started.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="Advanced_Topics.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: sandbox/closure/libs/local_function/doc/html/index.html
==============================================================================
--- (empty file)
+++ sandbox/closure/libs/local_function/doc/html/index.html 2012-01-21 13:28:36 EST (Sat, 21 Jan 2012)
@@ -0,0 +1,230 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Chapter 1. Boost.LocalFunction 1.0.0</title>
+<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
+<link rel="home" href="index.html" title="Chapter 1. Boost.LocalFunction 1.0.0">
+<link rel="next" href="boost_localfunction/Getting_Started.html" title="Getting Started">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav"><a accesskey="n" href="boost_localfunction/Getting_Started.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a></div>
+<div class="chapter">
+<div class="titlepage"><div>
+<div><h2 class="title">
+<a name="local_function"></a>Chapter 1. Boost.LocalFunction 1.0.0 </h2></div>
+<div><div class="author"><h3 class="author">
+Lorenzo Caminiti <code class="email"><<a class="email" href="mailto:lorcaminiti_at_[hidden]">lorcaminiti_at_[hidden]</a>></code>
+</h3></div></div>
+<div>Copyright © 2009-2012 Lorenzo
+ Caminiti</div>
+<div><div class="legalnotice">
+<a name="local_function.legal"></a>
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></div>
+</div></div>
+<div class="toc">
+Table of Contents
+<dl>
+<dt>Introduction</dt>
+<dt>Getting Started</dt>
+<dd><dl>
+<dt><a href="boost_localfunction/Getting_Started.html#boost_localfunction.Getting_Started.this_documentation">This
+ Documentation</a></dt>
+<dt><a href="boost_localfunction/Getting_Started.html#boost_localfunction.Getting_Started.compilers_and_platforms">Compilers
+ and Platforms</a></dt>
+<dt>Installation</dt>
+<dt><a href="boost_localfunction/Getting_Started.html#boost_localfunction.Getting_Started.compile_time_configuration">Compile-Time
+ Configuration</a></dt>
+</dl></dd>
+<dt>Tutorial</dt>
+<dd><dl>
+<dt>Local Functions</dt>
+<dt>Binding Variables</dt>
+<dt><a href="boost_localfunction/Tutorial.html#boost_localfunction.Tutorial.binding_the_object__this_">Binding
+ the Object <code class="computeroutput">this</code></a></dt>
+<dt>Templates</dt>
+</dl></dd>
+<dt>Advanced Topics</dt>
+<dd><dl>
+<dt><a href="boost_localfunction/Advanced_Topics.html#boost_localfunction.Advanced_Topics.default_parameters">Default
+ Parameters</a></dt>
+<dt><a href="boost_localfunction/Advanced_Topics.html#boost_localfunction.Advanced_Topics.commas_and_symbols_in_macros">Commas
+ and Symbols in Macros</a></dt>
+<dt><a href="boost_localfunction/Advanced_Topics.html#boost_localfunction.Advanced_Topics.assigning_and_returning">Assigning
+ and Returning</a></dt>
+<dt>Nesting</dt>
+<dt><a href="boost_localfunction/Advanced_Topics.html#boost_localfunction.Advanced_Topics.deducing_bound_types__concepts__etc_">Deducing
+ Bound Types (concepts, etc)</a></dt>
+<dt><a href="boost_localfunction/Advanced_Topics.html#boost_localfunction.Advanced_Topics.specifying_types">Specifying
+ Types</a></dt>
+<dt>Inlining</dt>
+<dt>Recursion</dt>
+<dt>Overloading</dt>
+<dt><a href="boost_localfunction/Advanced_Topics.html#boost_localfunction.Advanced_Topics.exception_specifications">Exception
+ Specifications</a></dt>
+<dt><a href="boost_localfunction/Advanced_Topics.html#boost_localfunction.Advanced_Topics.storage_classifiers___auto__and__register__">Storage
+ Classifiers (<code class="computeroutput">auto</code> and <code class="computeroutput">register</code>)</a></dt>
+<dt><a href="boost_localfunction/Advanced_Topics.html#boost_localfunction.Advanced_Topics.limitations__operators__etc_">Limitations
+ (operators, etc)</a></dt>
+</dl></dd>
+<dt>Appendix: Examples</dt>
+<dd><dl>
+<dt><a href="boost_localfunction/Examples.html#boost_localfunction.Examples.gcc_lambdas__without_c__11_">GCC
+ Lambdas (Without C++11)</a></dt>
+<dt><a href="boost_localfunction/Examples.html#boost_localfunction.Examples.constant_blocks">Constant
+ Blocks</a></dt>
+<dt>Scope Exits</dt>
+<dt><a href="boost_localfunction/Examples.html#boost_localfunction.Examples.gcc_nested_functions">GCC
+ Nested Functions</a></dt>
+<dt>N-Papers</dt>
+</dl></dd>
+<dt>Appendix: Alternatives</dt>
+<dd><dl>
+<dt>Features</dt>
+<dt>Performances</dt>
+</dl></dd>
+<dt><a href="boost_localfunction/No_Variadic_Macros.html">Annex: No Variadic
+ Macros</a></dt>
+<dd><dl>
+<dt><a href="boost_localfunction/No_Variadic_Macros.html#boost_localfunction.No_Variadic_Macros.sequence_syntax">Sequence
+ Syntax</a></dt>
+<dt>Examples</dt>
+</dl></dd>
+<dt>Appendix: Implementation</dt>
+<dd><dl>
+<dt><a href="boost_localfunction/Implementation.html#boost_localfunction.Implementation.local_classes_as_template_parameters">Local
+ Classes as Template Parameters</a></dt>
+<dt><a href="boost_localfunction/Implementation.html#boost_localfunction.Implementation.parsing_macros">Parsing
+ Macros</a></dt>
+<dt><a href="boost_localfunction/Implementation.html#boost_localfunction.Implementation.local_functions">Local
+ Functions</a></dt>
+</dl></dd>
+<dt>Release Notes</dt>
+<dt>Bibliography</dt>
+<dt>Acknowledgments</dt>
+</dl>
+</div>
+
+ This library allows to declare functions at local scope within an enclosing function.
+ 
+<div class="section">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="boost_localfunction.Introduction"></a><a class="link" href="index.html#boost_localfunction.Introduction" title="Introduction">Introduction</a>
+</h2></div></div></div>
+
+ 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 Pascal
+ and Ada,
+ yet lacking from C++03
+ (see also [N2511]).
+ 
+
+ Using <a href="http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions" target="_top">C++11
+ lambda</a> functions, it is possible to implement local functions by naming
+ the lambdas assigning them to local variables. For example (see also "add_lambda.cpp"):
+ 
+
+
+<pre class="programlisting">{ // Some local scope.
+ int sum = 0, factor = 10; // Variables in scope to bind.
+
+ auto add = [factor, &sum](int num) { // C++11 only.
+ sum += factor * num;
+ };
+
+ add(1); // Call the lambda (with one parameter `num`).
+ int nums[] = {2, 3};
+ std::for_each(nums, nums + 2, add); // Pass it to an algorithm.
+
+ BOOST_CHECK( sum == 60 ); // Assert final summation value.
+}
+</pre>
+
+ 
+
+ This library allows to program local functions portably between C++03
+ and C++11 (and
+ with performances comparable to lambdas on C++11
+ compilers, see the <a class="link" href="">Alternatives</a>
+ section). For example (see also "add.cpp"):
+ 
+
+
+<pre class="programlisting">{ // Some local scope.
+ int sum = 0, factor = 10; // Variables in scope to bind.
+
+ void BOOST_LOCAL_FUNCTION(const bind factor, bind& sum, int num) {
+ sum += factor * num;
+ } BOOST_LOCAL_FUNCTION_NAME(add)
+
+ add(1); // Call the local function (with one parameter `num`).
+ int nums[] = {2, 3};
+ std::for_each(nums, nums + 2, add); // Pass it to an algorithm.
+
+ BOOST_CHECK( sum == 60 ); // Assert final summation value.
+}
+</pre>
+
+ 
+
+ This library supports the following features for local functions:
+ 
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem">
+ Local functions can capture, or better bind,
+ any of the variables from the enclosing scope (a function together with
+ its captured variables is also called a closure).
+ </li>
+<li class="listitem">
+ The local function body is programmed using the usual C++ statement syntax
+ (as a consequence, compiler error messages retain their usual meaning and
+ format).
+ </li>
+<li class="listitem">
+ Local functions can be passed as template parameters so they can be conveniently
+ passed to STL algorithms, etc (this is a strength with respect to C++03
+ functors implemented using local classes, see [N2657]
+ and the <a class="link" href="">Alternatives</a> section).
+ </li>
+<li class="listitem">
+ 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 expressions (this is a weakness with respect to
+ <a href="http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions" target="_top">C++11
+ lambda</a> functions, see the <a class="link" href="">Alternatives</a>
+ section).
+ </li>
+</ul></div>
+
+ See the <a class="link" href="">Alternatives</a> section
+ for a comparison between this library, <a href="http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions" target="_top">C++11
+ lambda</a> functions, Boost.Phoenix,
+ and other C++ techniques implementing related features.
+ 
+</div>
+<xi:include></xi:include>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left">Last revised: January 21, 2012 at 18:28:00 GMT</td>
+<td align="right"><div class="copyright-footer"></div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav"><a accesskey="n" href="boost_localfunction/Getting_Started.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a></div>
+</body>
+</html>

Next message: lorcaminiti_at_[hidden]: "[Boost-commit] svn:boost r76624 - sandbox/closure/libs/local_function/doc/html"
Previous message: lorcaminiti_at_[hidden]: "[Boost-commit] svn:boost r76622 - sandbox/closure/libs/local_function/doc"

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