[Boost-commit] svn:boost r76622 - sandbox/closure/libs/local_function/doc

Subject: [Boost-commit] svn:boost r76622 - sandbox/closure/libs/local_function/doc
From: lorcaminiti_at_[hidden]
Date: 2012-01-21 13:27:26

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

Log:
Examples, tests, and docs.
Added:
   sandbox/closure/libs/local_function/doc/Jamfile.v2   (contents, props changed)
   sandbox/closure/libs/local_function/doc/acknowledgements.qbk   (contents, props changed)
   sandbox/closure/libs/local_function/doc/advanced_topics.qbk   (contents, props changed)
   sandbox/closure/libs/local_function/doc/alternatives.qbk   (contents, props changed)
   sandbox/closure/libs/local_function/doc/bibliography.qbk   (contents, props changed)
   sandbox/closure/libs/local_function/doc/examples.qbk   (contents, props changed)
   sandbox/closure/libs/local_function/doc/getting_started.qbk   (contents, props changed)
   sandbox/closure/libs/local_function/doc/implementation.qbk   (contents, props changed)
   sandbox/closure/libs/local_function/doc/introduction.qbk   (contents, props changed)
   sandbox/closure/libs/local_function/doc/local_function.qbk   (contents, props changed)
   sandbox/closure/libs/local_function/doc/no_variadic_macros.qbk   (contents, props changed)
   sandbox/closure/libs/local_function/doc/release_notes.qbk   (contents, props changed)
   sandbox/closure/libs/local_function/doc/tutorial.qbk   (contents, props changed)
Properties modified: 
   sandbox/closure/libs/local_function/doc/   (props changed)

Added: sandbox/closure/libs/local_function/doc/Jamfile.v2
==============================================================================
--- (empty file)
+++ sandbox/closure/libs/local_function/doc/Jamfile.v2	2012-01-21 13:27:24 EST (Sat, 21 Jan 2012)
@@ -0,0 +1,46 @@
+
+# Copyright (C) 2009-2011 Lorenzo Caminiti
+# Use, modification, and distribution is subject to the Boost Software
+# License, Version 1.0 (see accompanying file LICENSE_1_0.txt or a
+# copy at http://www.boost.org/LICENSE_1_0.txt).
+
+import quickbook ;
+using boostbook ;
+
+doxygen reference
+    :
+        ../../../boost/local_function.hpp
+        ../../../boost/local_function/config.hpp
+    :
+        <doxygen:param>QUIET=YES
+        <doxygen:param>WARN_IF_UNDOCUMENTED=NO
+        <doxygen:param>HIDE_UNDOC_MEMBERS=YES
+        <doxygen:param>HIDE_UNDOC_CLASSES=YES
+        <doxygen:param>ALIASES=" Params=\"<b>Parameters:</b> <table border="0">\" Param{2}=\"<tr><td><b><tt>\\1</tt></b></td><td>\\2</td></tr>\" EndParams=\"</table>\" Returns=\"<b>Returns:</b>\" Note=\"<b>Note:</b>\" Warning=\"<b>Warning:</b>\" See=\"<b>See:</b>\" RefSect{1}=\"\\xmlonly<link linkend='local_function.\\1'>\\1</link>\\endxmlonly\" RefSectId{2}=\"\\xmlonly<link linkend='local_function.\\1'>\\2</link>\\endxmlonly\" RefClass{1}=\"\\xmlonly<computeroutput><classname alt='\\1'>\\1</classname></computeroutput>\\endxmlonly\" RefFunc{1}=\"\\xmlonly<computeroutput><functionname alt='\\1'>\\1</functionname></computeroutput>\\endxmlonly\" RefMacro{1}=\"\\xmlonly<computeroutput><macroname alt='\\1'>\\1</macroname></computeroutput>\\endxmlonly\" "
+
+        # Extract Doxygen that comments non-variant macros.
+        <doxygen:param>PREDEFINED="DOXY"
+        <reftitle>"Reference"
+    ;
+
+xml doc : local_function.qbk :
+    <dependency>introduction.qbk
+    <dependency>getting_started.qbk
+    <dependency>tutorial.qbk
+    <dependency>advanced_topics.qbk
+#    <dependency>reference
+    <dependency>examples.qbk
+    <dependency>alternatives.qbk
+    <dependency>no_variadic_macros.qbk
+    <dependency>implementation.qbk
+    <dependency>release_notes.qbk
+    <dependency>bibliography.qbk
+    <dependency>acknowledgements.qbk
+;
+
+boostbook standalone : doc :
+    <xsl:param>boost.root=../../../..
+    <xsl:param>boost.defaults=Boost
+    <format>pdf:<xsl:param>boost.url.prefix=http://www.boost.org/doc/libs/release/libs/scope_exit/doc/html
+;
+

Added: sandbox/closure/libs/local_function/doc/acknowledgements.qbk
==============================================================================
--- (empty file)
+++ sandbox/closure/libs/local_function/doc/acknowledgements.qbk	2012-01-21 13:27:24 EST (Sat, 21 Jan 2012)
@@ -0,0 +1,31 @@
+
+[/ Copyright (C) 2009-2011 Lorenzo Caminiti ]
+[/ Use, modification, and distribution is subject to the Boost Software ]
+[/ License, Version 1.0 (see accompanying file LICENSE_1_0.txt or a ]
+[/ copy at http://www.boost.org/LICENSE_1_0.txt). ]
+
+[section:Acknowledgments Acknowledgments]
+
+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 [@http://boost.2283326.n4.nabble.com/contract-diff-n1962-tt2671482.html#none emulate local functions].
+Many thanks to Alexander Nasonov for clarifying how __Boost_ScopeExit__ binding could be used to implement local functions and for some [@http://thread.gmane.org/gmane.comp.lib.boost.devel/168612 early work] in this direction.
+
+Many thanks to Gregory Crosswhite for using an early version of this library in [@https://github.com/gcross/CodeSearch one of his projects].
+
+Thanks to David Abrahams, Vicente Botet, et al. for suggesting to provide the [@http://lists.boost.org/Archives/boost/2011/02/176712.php variadic macro syntax] on compilers that support variadic macros.
+
+Thanks to Pierre Morcello for suggesting to use `return;` to exit local blocks (in the context of a discussion about a possible [@http://lists.boost.org/Archives/boost/2009/09/156012.php 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" `bind` to bind variables in scope and for suggesting to use [^bind(/type/)] 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 __Alternatives__ section and with the profiling of the different alternatives.
+
+Finally, many thanks to the entire __Boost__ community and [@http://lists.boost.org mailing list] for providing valuable comments about this library and great insights on the C++ programming language.
+
+[endsect]
+

Added: sandbox/closure/libs/local_function/doc/advanced_topics.qbk
==============================================================================
--- (empty file)
+++ sandbox/closure/libs/local_function/doc/advanced_topics.qbk	2012-01-21 13:27:24 EST (Sat, 21 Jan 2012)
@@ -0,0 +1,475 @@
+
+[/ Copyright (C) 2009-2011 Lorenzo Caminiti ]
+[/ Use, modification, and distribution is subject to the Boost Software ]
+[/ License, Version 1.0 (see accompanying file LICENSE_1_0.txt or a ]
+[/ copy at http://www.boost.org/LICENSE_1_0.txt). ]
+
+[section:Advanced_Topics Advanced Topics]
+
+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.
+
+[section Default Parameters]
+
+This library also allows to specify default values for the local function parameters.
+However, the usual C++ syntax for default parameters that uses the assignment symbol `=` cannot be used.
+[footnote
+*Rationale.*
+The assignment symbol `=` cannot be used to specify default parameter values because default values are not part of the parameter type so they cannot be handled using template metaprogamming.
+Default parameter values need to be separated from the rest of the parameter declaration using the preprocessor.
+Specifically, this library needs to use preprocessor mataprogramming to remove default values when constructing the local function type and then to count the number of default values to provide the correct set of call operators for the local functor.
+Therefore, the symbol `=` 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).
+]
+The keyword `default` is used instead:
+
+    ``[^/parameter-type parameter-name/]``, default`` [^/parameter-default-value/]``, ...
+
+For example, let's program a local function `add(x, y)` where the second parameter `y` is optional and has a default value of `2` (see also [@../../test/add_default.cpp `"add_default.cpp"`]):
+
+[test_add_default]
+
+Programmers can define a `WITH_DEFAULT` macro similar to the following if they think it improves readability over the syntax above (see also [@../../test/add_with_default.cpp `"add_with_default.cpp"`]):
+[footnote
+The authors do not personally find the use of the `WITH_DEFAULT` macro more readable and they prefer to use the `default` "keyword" directly.
+Furthermore, `WITH_DEFAULT` need to be defined differently for compilers without variadic macros `#define WITH_DEFAULT (default)` so it can only be defined by programmers based on the syntax they decide to use.
+]
+
+[test_add_with_default_macro]
+[test_add_with_default]
+
+[endsect]
+
+[section Commas and Symbols in Macros]
+
+The C++ preprocessor does not allow commas `,` within macro parameters unless they are wrapped by round parenthesis `()`.
+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 `()` as explained here.
+
+[note
+Macro parameters with commas which are already wrapped by round parenthesis `()` are fine (function calls, etc).
+However, macro parameters with commas that are not wrapped by round parenthesis need to be wrapped by an extra set of round parenthesis `()` as described here.
+Also macro parameters with commas wrapped by angular parenthesis `<>` (templates, etc) or square parenthesis `[]` (multidimensional array access, etc) need to be wrapped by the extra round parenthesis `()` as explained here (this is because the preprocessor only recognizes the round parenthesis and it does not recognize angular, square, or any other type of parenthesis).
+]
+
+In addition, local function parameter types cannot start with non-alphanumeric symbols (alphanumeric symbols are `A-Z`, `a-z`, and `0-9`).
+[footnote
+*Rationale.*
+This limitation derives from the fact that `BOOST_LOCAL_FUNCTION` uses preprocessor token concatenation [^##] 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.
+]
+The library will generate (cryptic) preprocessor errors if a parameter type starts with a non-alphanumeric symbol.
+
+Let's consider the following example:
+
+    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)
+
+[*(1)] The parameter type `const std::map<std::string, size_t>&` contains a comma `,` after the first template parameter `std::string`.
+This comma is not wrapped by any round parenthesis `()` thus it will cause a preprocessor error.
+The __Boost_Utility__ macro `BOOST_IDENTITY_TYPE(`/parenthesized-type/`)` from the header `"boost/utility/identity_type.hpp"` can be used to wrap a type within extra parenthesis `()` so to overcome this issue:
+
+    #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)
+
+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 `()` are needed: The parenthesis to invoke the `BOOST_IDENTITY_TYPE(..)` macro plus the parenthesis to wrap the type expression (and therefore any comma `,` that it contains) passed as parameter to the `BOOST_IDENTITY_TYPE((...)` macro.
+[footnote
+*Rationale.*
+Using variadic macros, this extra set of parenthesis could be eliminated requiring only the parenthesis to invoke the `BOOST_IDENTITY_TYPE` macro.
+However, this feature is currently not implemented and the double parenthesis are always needed when invoking this macro.
+]
+Finally, the `BOOST_IDENTITY_TYPE` macro must be prefixed by the `typename` keyword as in `typename BOOST_IDENTITY_TYPE(`/parenthesized-type/`)` when used within [macroref BOOST_LOCAL_FUNCTION_TPL] for templates.
+
+[note
+Often, there might be better ways to overcome this limitation that lead to code which is more readable than the one using the `BOOST_IDENTITY_TYPE` macro.
+For example, in this case a `typedef` could have been used in the enclosing scope to obtain the following valid and perhaps more readable code:
+]
+
+    typedef std::map<std::string, size_t> map_type;
+    void BOOST_LOCAL_FUNCTION(
+        const map_type& m,  // OK.
+        ...
+    ) BOOST_LOCAL_FUNCTION_NAME(f)
+
+[*(2)] The parameter type `::sign_t` starts with the non-alphanumeric symbols `::` thus it will generate preprocessor errors if used as a local function parameter type.
+The macros `BOOST_IDENTITY_TYPE` can also be used to overcome this issue:
+
+    void BOOST_LOCAL_FUNCTION(
+        ...
+        BOOST_IDENTITY_TYPE((::sign_t)) sign, // OK.
+        ...
+    ) {
+        ...
+    } BOOST_LOCAL_FUNCTION_NAME(f)
+
+[note
+Often, there might be better ways to overcome this limitation that lead to code which is more readable than the one using the `BOOST_IDENTITY_TYPE` macro.
+For example, in this case the symbols `::` could have been simply dropped to obtain the following valid and perhaps more readable code:
+]
+
+    void BOOST_LOCAL_FUNCTION(
+        ...
+        sign_t sign, // OK.
+        ...
+    ) {
+        ...
+    } BOOST_LOCAL_FUNCTION_NAME(f)
+
+[*(3)] The default parameter value `key_size<std::string, size_t>::value` contains a comma `,` after the first template parameter `std::string`.
+Again, this comma is not wrapped by any parenthesis `()` so it will cause a preprocessor error.
+Because this is a value expression (and not a type expression), it can be simply wrapped within an extra set of round parenthesis `()`:
+
+    void BOOST_LOCAL_FUNCTION(
+        ...
+        const size_t& factor, default
+                (key_size<std::string, size_t>::value), // OK.
+        ...
+    ) {
+        ...
+    } BOOST_LOCAL_FUNCTION_NAME(f)
+
+[*(4)] The default parameter value `cat(":", " ")` is instead fine because it contains a comma `,` which is already wrapped by the parenthesis `()` of the function call `cat(...)`.
+
+[endsect]
+
+[section Assigning and Returning]
+
+Local functions are function objects so it is possible to assign them to other functors like __Boost_Function__ `boost::function` 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 [@../../test/return_assign.cpp `"return_assign.cpp"`]):
+
+[test_return_assign]
+
+Note that:
+
+[important
+As with __CPP11_lambda__ functions, programmers are responsible to ensure that bound references are valid in any scope where the local function object is called.
+]
+
+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 __Examples__ section).
+
+In addition, a local function can bind and call another local function.
+Local functions should always be bound by constant reference `const bind&` to avoid unnecessary copies.
+For example, the following local function `inc_sum` binds the local function `inc` so `inc_sum` can call `inc` (see aslo [@../../test/transform.cpp `"transform.cpp"`]):
+
+[test_transform]
+
+[endsect]
+
+[section Nesting]
+
+It is possible to nest local functions into one another.
+For example (see also [@../../test/nesting.cpp `"nesting.cpp"`]):
+
+[test_nesting]
+
+[endsect]
+
+[section Deducing Bound Types (concepts, etc)]
+
+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:
+
+    BOOST_LOCAL_FUNCTION_TYPEOF(``/bound-variable-name/``)
+
+The [macroref BOOST_LOCAL_FUNCTION_TYPEOF] macro expands to a type expression that evaluates (at compile-time) to the fully qualified type of the bound variable with the specified name.
+
+[note
+This type expression is fully qualified in the sense that it will be constant if the variable is bound by constant `const bind[&]` and it will also be a reference is the variable is bound by reference `[const] bind&` (if needed, programmers can strip away the `const` and `&` qualifiers using `boost::remove_const` and `boost::remove_reference`, see __Boost_TypeTraits__).
+]
+
+The deduced bound type can be used within the body to declare a local variable, to check concepts, etc.
+For example (see also [@../../test/typeof.cpp `"typeof.cpp"`] and [@../../test/addable.hpp `"addable.hpp"`]):
+
+[test_typeof]
+
+Within templates, [macroref BOOST_LOCAL_FUNCTION_TYPEOF] does not require to be prefixed by the `typename` keyword but eventual type manipulations need the `typename` prefix as usual (see also [@../../test/typeof_template.cpp `"typeof_template.cpp"`] and [@../../test/addable.hpp `"addable.hpp"`]):
+
+[test_typeof_template]
+
+[endsect]
+
+[section Specifying Types]
+
+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 `bind` "keyword" and it must be wrapped within round parenthesis `()`:
+
+    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.
+
+Note that within the local function body it is always possible to abstract the access to the type of a bound variable using [macroref BOOST_LOCAL_FUNCTION_TYPEOF] (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 [macroref BOOST_LOCAL_FUNCTION] macro.
+Thus it is also possible to specify the local function result type as one of the [macroref BOOST_LOCAL_FUNCTION] macro parameters prefixed by `return` so the library will not use __Boost_Typeof__ to deduce it:
+
+    BOOST_LOCAL_FUNCTION_TYPE(return ``[^/result-type/]``, ...)
+
+The following example specifies the type of all bound variables and of the local function result (see also [@../../test/add_typed.cpp `"add_typed.cpp"`]):
+[footnote
+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 __CPP11_lambda__ functions.
+However, the library accepts bound variables, function parameters, and the result type in any order.
+]
+
+[test_add_typed]
+
+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).
+
+[note
+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 __Implementation__ 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.
+]
+
+[endsect]
+
+[section Inlining]
+
+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 [macroref BOOST_LOCAL_FUNCTION_NAME] macro with the "keyword" `inline`:
+
+    ``/result-type/`` BOOST_LOCAL_FUNCTION(``/parameters/``) {
+        ... // Body.
+    } BOOST_LOCAL_FUNCTION_NAME(inline ``/name/``) // Inlining.
+
+When inlining a local function, note the following:
+
+* On __CPP03__ compliant compilers, inlined local functions always have a run-time comparable to their equivalent implementation that uses local functors (see the __Alternatives__ section).
+However, inlined local functions have the important limitation that they cannot be assigned to other functors (like `boost::function`) and they cannot be passed as template parameters.
+[footnote
+*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 __Implementation__ 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 __CPP03__ but it is not needed on __CPP11__ (see __N2657__) thus this library automatically generates local function calls that can be inlined on __CPP11__ compilers (even when the local function is not declared inline).
+]
+* On __CPP11__ compilers, `inline` has no effect because this library will automatically generate code that uses __CPP11__ specific features to inline the local function calls whenever possible even if the local function is not declared inline.
+Furthermore, non __CPP11__ local functions can always be passes as template parameters even when they are declared inline.
+
+[important
+It is recommended to not declare a local function inlined unless it is strictly necessary for optimizing pure __CPP03__ compliant code (because in all other cases this library will automatically take advantage of __CPP11__ features to optimize the local function calls while always allowing to pass the local function as a template parameter).
+]
+
+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 `std::for_each` algorithm, see also [@../../test/add_inline.cpp `"add_inline.cpp"`]):
+
+[test_add_inline]
+
+[endsect]
+
+[section Recursion]
+
+Local functions can be declared [@http://en.wikipedia.org/wiki/Recursion_(computer_science)#Recursive_procedures 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 [macroref BOOST_LOCAL_FUNCTION_NAME] macro with the "keyword" `recursive`:
+
+    ``/result-type/`` BOOST_LOCAL_FUNCTION(``/parameters/``) {
+        ... // Body.
+    } BOOST_LOCAL_FUNCTION_NAME(recursive ``/name/``) // Recursive.
+
+For example, the following local function is used to recursively calculate the factorials of all the numbers in the specified vector (see also [@../../test/factorial.cpp `"factorial.cpp"`]):
+
+[test_factorial]
+
+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).
+
+[warning
+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 `boost::function`, returned from the enclosing function, and called in a different scope, the result in undefined behaviour (which will likely generate a run-time error).
+[footnote
+*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 `recursive`.
+]
+This is not a limitation with respect to __CPP11_lambda__ 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).
+]
+
+[endsect]
+
+[section Overloading]
+
+It is possible to overload local functions using __Boost_FunctionalOverloadedFunction__ `boost::overloaded_function` from the header `"boost/functional/overloaded_function.hpp"` (see the __Boost_FunctionalOverloadedFunction__ documentation for more detail).
+
+In the following example, the overloaded function object `add` can be called with signatures from either the local function `add_s`, or the local function `add_d`, or the local function `add_d` with its extra default parameter, or the function pointer `add_i` (see also [@../../test/overload.cpp `"overload.cpp"`]):
+
+[test_overload]
+
+[endsect]
+
+[section Exception Specifications]
+
+It is possible to program exception specifications for local functions by specifying them after the [macroref BOOST_LOCAL_FUNCTION] macro and before the body code block `{ ... }`.
+
+[important
+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 `throw () { ... }`, the execution of the library code automatically generated by the macros could still throw (if there is no memory, etc).
+]
+
+For example (see also [@../../test/add_except.cpp `"add_except.cpp"`]):
+
+[test_add_except]
+
+[endsect]
+
+[section Storage Classifiers (`auto` and `register`)]
+
+Local function parameters support the storage classifiers as usual in __CPP03__.
+The `auto` storage classifier is specified as:
+[footnote
+The `auto` storage classifier is part of the __CPP03__ standard and therefore supported by this library.
+However, the meaning and usage of the `auto` keyword changed in __CPP11__.
+Therefore, use the `auto` storage classifier with the usual care in order to avoid writing __CPP03__ code that might not work on __CPP11__.
+]
+
+	auto ``/parameter-type parameter-name/``
+
+The `register` storage classifier is specified as:
+
+	register ``/parameter-type parameter-name/``
+
+For example (see also [@../../test/add_classifiers.cpp `"add_classifiers.cpp"`]):
+
+[test_add_classifiers]
+
+[endsect]
+
+[section Limitations (operators, etc)]
+
+The following table summarizes all C++ function features indicating those features that are not supported by this library for local functions.
+
+[table
+[
+    [ C++ Function Feature ]
+    [ Local Function Support ]
+    [ Reason ]
+]
+[
+    [ `export` ]
+    [ No ]
+    [ This is not supported because local functions cannot be templates (plus most C++ compilers do not implement `export`). ]
+]
+[
+    [ `template<`/template-parameter-list/`>` ]
+    [ No ]
+    [ This is not supported because local functions are implemented using local classes and __CPP03__ local classes cannot be templates. ]
+]
+[
+    [ `explicit` ]
+    [ No ]
+    [ This is not supported because local functions are not constructors. ]
+]
+[
+    [ `inline` ]
+    [ Yes ]
+    [ Local functions can be specified `inline` to improve the chances that __CPP03__ standard compilers can optimize the local function call run-time (but `inline` local functions cannot be passes as template parameters on __CPP03__ standard compilers). ]
+]
+[
+    [ `extern` ]
+    [ No ]
+    [ This is not supported because local functions are always defined locally within the enclosing scope and together with their declarations. ]
+]
+[
+    [ `static` ]
+    [ No ]
+    [ This is not supported because local functions are not member functions. ]
+]
+[
+    [ `virtual` ]
+    [ No ]
+    [ This is not supported because local functions are not member functions.
+[footnote
+*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 [@http://lists.boost.org/Archives/boost/2010/09/170895.php no use] 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.
+]
+    ]
+]
+[
+    [ [^/result-type/] ]
+    [ Yes ]
+    [ This is supported (see the __Tutorial__ section). ]
+]
+[
+    [ [^/function-name/] ]
+    [ Yes ]
+    [ Local functions are named and they can call themselves recursively but they cannot be overloaded and they cannot be operators (see the __Tutorial__ and __Advanced_Topics__ sections). ]
+]
+[
+    [ [^/parameter-list/] ]
+    [ Yes ]
+    [ This is supported and it also supports the `auto` and `register` storage classifiers, default parameters, and binding of variables in scope (see the __Tutorial__ and __Advanced_Topics__ sections). ]
+]
+[
+    [ Trailing `const` qualifier ]
+    [ No ]
+    [ This is not supported because local functions are not member functions. ]
+]
+[
+    [ Trailing `volatile` qualifier ]
+    [ No ]
+    [ This is not supported because local functions are not member functions. ]
+]
+]
+
+[h5 Operators]
+
+Local functions cannot be operators.
+Naming a local function `operator...` will generate a compile-time error.
+[footnote
+*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.
+]
+
+For example, the following code will *not* compile:
+
+    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==`.
+
+        ...
+    }
+
+[h5 Goto]
+
+It is not possible to jump with a `goto` 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:
+
+    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;
+    }
+
+[endsect]
+
+[endsect]
+

Added: sandbox/closure/libs/local_function/doc/alternatives.qbk
==============================================================================
--- (empty file)
+++ sandbox/closure/libs/local_function/doc/alternatives.qbk	2012-01-21 13:27:24 EST (Sat, 21 Jan 2012)
@@ -0,0 +1,240 @@
+
+[/ Copyright (C) 2009-2011 Lorenzo Caminiti ]
+[/ Use, modification, and distribution is subject to the Boost Software ]
+[/ License, Version 1.0 (see accompanying file LICENSE_1_0.txt or a ]
+[/ copy at http://www.boost.org/LICENSE_1_0.txt). ]
+
+[section:Alternatives Appendix: Alternatives]
+
+This section compares the features offered by this library with similar features offered by other libraries and by the new __CPP11__ standard.
+
+[section Features]
+
+The following table compares local function features.
+
+[table
+[
+    [ Local Function Feature ]
+    [ Boost.Local (this library) ]
+    [ Local Functor ]
+    [ Global Functor (not local) ]
+    [ __CPP0x_Lambda__ (not __CPP03__) ]
+    [ __Boost_Lambda__ ]
+    [ __Boost_Phoenix__ ]
+]
+[
+    [ ['Can be defined locally] ]
+    [ Yes. ]
+    [ Yes. ]
+    [ No.
+Therefore this not really an alternative implementation of local functions but it is listed here just for comparison. ]
+    [ Yes. ]
+    [ Yes. ]
+    [ Yes. ]
+]
+[
+    [ ['Can be defined using C++ statement syntax] ]
+    [ Yes.
+Plus eventual compiler errors follow the usual format of C++ statement errors. ]
+    [ Yes.
+Plus eventual compiler errors follow the usual format of C++ statement errors. ]
+    [ Yes.
+Plus eventual compiler errors follow the usual format of C++ statement errors. ]
+    [ Yes.
+Plus eventual compiler errors follow the usual format of C++ statement errors. ]
+    [ No (it uses C++ __expression_template__ syntax). ]
+    [ No (it uses C++ __expression_template__ syntax). ]
+]
+[
+    [ ['Can be defined within expressions] ]
+    [ No. It can be defined only within declarations. ]
+    [ No. It can be defined only within declarations. ]
+    [ No. It can be defined only within declarations. ]
+    [ Yes (plus the local function can be unnamed). ]
+    [ Yes (plus the local function can be unnamed). ]
+    [ Yes (plus the local function can be unnamed). ]
+]
+[
+    [ ['Can be passed as template parameter (e.g., to STL algorithms)] ]
+    [ Yes.
+The __CPP03__ 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 __Implementation__ section). ]
+    [ No on __CPP03__ compilers (but yes on __CPP11__ compilers and some compilers like MSVC 8.0, see __N2657__). ]
+    [ Yes. ]
+    [ Yes. ]
+    [ Yes. ]
+    [ Yes. ]
+]
+[
+    [ ['Access variables in scope] ]
+    [ 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 `this` can also be bound). ]
+    [ No.
+Programmers must manually manage functor member variables and explicitly specify their types to access variables in scope. ]
+    [ No.
+Programmers must manually manage functor member variables and explicitly specify their types to access variables in scope. ]
+    [ 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 `this` can also be bound).
+However, variables cannot be bound by constant references and non-constant value (see below). ]
+    [ Yes (variables in scope are accessible as usual within expressions). ]
+    [ Yes (variables in scope are accessible as usual within expressions) plus `boost::phoenix::let` can be used to bind variables by constant reference. ]
+]
+[
+    [ ['[@http://en.wikipedia.org/wiki/Type_polymorphism#Parametric_polymorphism Polymorphic] in the unbound parameter types] ]
+    [ No (local functions cannot be function templates). ]
+    [ No (local classes cannot have member function templates). ]
+    [ Yes. ]
+    [ No (__CPP11__ lambdas cannot be function templates). ]
+    [ Yes. ]
+    [ Yes. ]
+]
+]
+
+[h5 Comparison with __CPP0x_Lambda__ Functions]
+
+__CPP0x_lambda__ functions have most of the features that __Boost_Local__ local functions have, key pro and cons of the two approaches are:
+
+* __CPP0x_lambda__ functions can be defined within expressions while __Boost_Local__ local functions can only be defined within declarations.
+* __CPP0x_lambda__ functions are only supported by the __CPP11__ standard so they are not supported by all C++ compilers.
+__Boost_Local__ local functions use only __CPP03__ compliant features so they are supported on all C++ compliant compilers.
+* __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__.
+
+For example, for non-copyable objects:
+
+[table
+[ [__CPP0x_Lambda__] [__Boost_Local__ __Variadic_Macro_Syntax__] [__Boost_Local__ __Sequencing_Macro_Syntax__] ]
+[ [ [noncopyable_0x_lambda_cpp] ] [ [noncopyable_boost_local_va_cpp] ] [ [noncopyable_boost_local_cpp] ] ]
+]
+
+Or, for objects with expensive copy operations:
+
+[table
+[ [__CPP0x_Lambda__] [__Boost_Local__ __Variadic_Macro_Syntax__] [__Boost_Local__ __Sequencing_Macro_Syntax__] ]
+[ [ [expensive_copy_0x_lambda_cpp] ] [ [expensive_copy_boost_local_va_cpp] ] [ [expensive_copy_boost_local_cpp] ] ]
+]
+
+[h5 Examples]
+
+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:
+
+[table
+[ [__Variadic_Macro_Syntax__] [__Sequencing_Macro_Syntax__] ]
+[ [ [add_using_boost_local_va_cpp] ] [ [add_using_boost_local_cpp] ] ]
+]
+
+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 __CPP03__ 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]
+
+[endsect]
+
+[section Performances]
+
+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 __CPP03__ compliant compilers (see "__Boost_Local__ Compliant" below) were measured to be larger than other approaches when compiler optimization is enabled (using `bjam release ...`).
+However, on compilers that allow to pass local types as template parameters (e.g., MSVC 8.0 or GCC 4.5.1 with __CPP11__ 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 `inline` (see "__Boost_Local__ Inline For-Loop" below and the __Advanced_Topics__ 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 `std::for_each` is replaced by a for-loop).
+Finally, this library run-times are always among the fastest when no compiler optimization is enabled (using `bjam debug ...`).
+
+[note
+The run-time performances of this library local functions are explained because on __CPP03__ 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 __Implementation__ 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 __CPP11__ 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).
+]
+
+This run-time performance cost on __CPP03__ 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 `profile_...` 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).
+
+[table
+[ [ Legend, Source Files, and Commands ] ]
+[ [ [$../../example/profile_legend.png [width 13in] [height 10in]] ] ]
+[ [
+The local function was called =1e8= times to add together all the elements of a vector and the run-time was measured using __Boost_Chrono__ averaging over =10= executions of the vector summation (see source files
+[@../../example/profile_boost_local.cpp =profile_boost_local.cpp=],
+[@../../example/profile_boost_local_inline.cpp =profile_boost_local_inline.cpp=],
+[@../../example/profile_local_functor.cpp =profile_local_functor.cpp=],
+[@../../example/profile_global_functor.cpp =profile_global_functor.cpp=],
+[@../../example/profile_0x_lambda.cpp =profile_0x_lambda.cpp=],
+[@../../example/profile_boost_lambda.cpp =profile_boost_lambda.cpp=], and
+[@../../example/profile_boost_phoenix.cpp =profile_boost_phoenix.cpp=]).
+] ]
+[ [
+The following commands were executed from the library example directory to measure compile-time, binary size, and run-time respectively:
+``
+> python chrono.py bjam {release|debug} <PROGRAM> # compile-time
+> size <PROGRAM> # binary size (Linux and Gygwin)
+> <PROGRAM> # run-time
+``
+] ]
+]
+
+[table
+[ [
+GCC 4.5.1 With __CPP11__ Lambdas and "Local Types as Template Parameters" ([^bjam cxxflags=-std=c++0x ...]) on Ubuntu Linux 10
+] ]
+[ [ 
+[*Compiled with =bjam release ...= for maximum optimization (=-O3 -finline-functions=)]
+[$../../example/profile_gcc-4.5.1-0x_release.png [width 13in] [height 10in]]
+] ]
+[ [ 
+[*Compiled with =bjam debug ...= for no optimization (=-O0 -fno-inline=)]
+[$../../example/profile_gcc-4.5.1-0x_debug.png [width 13in] [height 10in]]
+] ]
+]
+
+[table
+[ [
+MSVC 8.0 With "Local Types as Template Parameters" (Without __CPP11__ Lambdas) on Windows XP
+] ]
+[ [ 
+[*Compiled with =bjam release ...= for maximum optimization (=/O2 /Ob2=)]
+[$../../example/profile_msvc-8.0_release.png [width 13in] [height 10in]]
+] ]
+[ [ 
+[*Compiled with =bjam debug ...= for no optimization (=/Od /Ob0=)]
+[$../../example/profile_msvc-8.0_debug.png [width 13in] [height 10in]]
+] ]
+]
+
+[table
+[ [
+GCC 4.3.4 With __CPP03__ Only (Without __CPP11__ Lambdas and Without "Local Types as Template Parameters) on Cygwin
+] ]
+[ [ 
+[*Compiled with =bjam release ...= for maximum optimization (=-O3 -finline-functions=)]
+[$../../example/profile_gcc-4.3.4_release.png [width 13in] [height 10in]]
+] ]
+[ [ 
+[*Compiled with =bjam debug ...= for no optimization (=-O0 -fno-inline=)]
+[$../../example/profile_gcc-4.3.4_debug.png [width 13in] [height 10in]]
+] ]
+]
+
+[endsect]
+
+[endsect]
+

Added: sandbox/closure/libs/local_function/doc/bibliography.qbk
==============================================================================
--- (empty file)
+++ sandbox/closure/libs/local_function/doc/bibliography.qbk	2012-01-21 13:27:24 EST (Sat, 21 Jan 2012)
@@ -0,0 +1,20 @@
+
+[/ Copyright (C) 2009-2011 Lorenzo Caminiti ]
+[/ Use, modification, and distribution is subject to the Boost Software ]
+[/ License, Version 1.0 (see accompanying file LICENSE_1_0.txt or a ]
+[/ copy at http://www.boost.org/LICENSE_1_0.txt). ]
+
+[section:Bibliography Bibliography]
+
+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.
+
+[endsect]
+

Added: sandbox/closure/libs/local_function/doc/examples.qbk
==============================================================================
--- (empty file)
+++ sandbox/closure/libs/local_function/doc/examples.qbk	2012-01-21 13:27:24 EST (Sat, 21 Jan 2012)
@@ -0,0 +1,138 @@
+
+[/ Copyright (C) 2009-2011 Lorenzo Caminiti ]
+[/ Use, modification, and distribution is subject to the Boost Software ]
+[/ License, Version 1.0 (see accompanying file LICENSE_1_0.txt or a ]
+[/ copy at http://www.boost.org/LICENSE_1_0.txt). ]
+
+[section:Examples Appendix: Examples]
+
+This sections lists some (interesting) examples that use this library features.
+
+[section GCC Lambdas (Without C++11)]
+
+Combing local functions with the [@http://gcc.gnu.org/onlinedocs/gcc/Statement-Exprs.html statement expression] GCC extension, it is possible to implement lambda functions for GCC compilers even without __CPP11__ support.
+
+[warning
+This code only works on compilers that support the statement expression GCC extension or that support __CPP11_lambda__ functions.
+]
+
+For example (see also [@../../example/gcc_lambda.cpp `"gcc_lambda.cpp"`] and [@../../example/gcc_lambda_cpp11.cpp `"gcc_lambda_cpp11.cpp"`]):
+
+[table
+    [ [With Local Functions (GCC only)] [C++11 Lambdas] ]
+    [ [[example_gcc_lambda]] [[example_gcc_lambda_cpp11]] ]
+]
+
+The macros are defined in [@../../example/gcc_lambda.hpp `"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 __CPP11_lambda__ functions in which case the implementation uses native lambdas instead of local functions.
+However, __CPP11_lambda__ functions do not support constant binding so it is best to only use `const bind variable` (same as __CPP11_lambda__ `=variable`) and `bind& variable` (same as __CPP11_lambda__ `&variable`) because these have the exact same semantic between the local function and native lambda implementation.
+Unfortunately, the __CPP11_lambda__ short-hand binds `&` and `=` (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 `return `[^/result-type/] is optional and it is assumed `void` when it is not specified (as with __CPP11_lambda__ functions).
+
+[endsect]
+
+[section Constant Blocks]
+
+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 `operator=` instead of `operator==`:
+
+    int x = 1, y = 2;
+    assert(x = y); // Mistakenly `=` instead of `==`.
+
+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 `operator=` is mistakenly used instead of `operator==` because both `x` and `y` are constants within the block of code performing the assertion (see also [@../../example/const_block.cpp `"const_block.cpp"`]):
+
+[table
+    [ [With Local Functions] [N1613 Constant Block] ]
+    [ [[example_const_block]] [``
+    int x = 1, y = 2;
+    const { // Constant block.
+        assert(x = y); // Compiler error.
+    }
+    ``] ]
+]
+
+The macros are defined in [@../../example/const_block.hpp `"const_block.hpp"`].
+
+The constant block macros are implemented using a local function which binds by constant reference `const bind&` all the specified variables, it executes the `assert` 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 __CPP11_lambda__ functions because these do not support constant binding.
+Ideally, __CPP11_lambda__ functions would allow to bind variables also using `const& variable` (constant reference) and `const&` (all variables by constant reference).
+Variables bound by value using __CPP11_lambda__ functions (`variable`, `=variable`, and `=`) are constant but they are required to be `CopyConstructible` and they introduce potentially expensive copy operations.
+
+[endsect]
+
+[section Scope Exits]
+
+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 `const` local variable, assign it to the value to bind, and then bind the `const` 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 `p` 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 [@../../example/scope_exit.cpp `"scope_exit.cpp"`]):
+
+[table
+    [ [With Local Functions] [Boost.ScopeExit] ]
+    [ [[example_scope_exit]] [``
+    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
+    ``] ]
+]
+
+The macros are defined in [@../../example/scope_exit.hpp `"scope_exit.hpp"`].
+
+The scope exit macros are implemented by passing a local function to the constructor of the following object:
+
+[example_scope_exit_object]
+
+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 `void` result type but it supports binding and constant binding.
+
+[endsect]
+
+[section GCC Nested Functions]
+
+The GCC C compiler supports local functions under the name of [@http://gcc.gnu.org/onlinedocs/gcc/Nested-Functions.html nested functions].
+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:
+
+[table
+    [ [Files] ]
+    [ [[@../../example/gcc_square.cpp `"gcc_square.cpp"`]] ]
+    [ [[@../../example/gcc_access.cpp `"gcc_access.cpp"`]] ]
+    [ [[@../../example/gcc_store.cpp `"gcc_store.cpp"`]] ]
+]
+
+[endsect]
+
+[section N-Papers]
+
+The following examples are taken from a number of N-papers and programmed using this library.
+
+[table
+    [ [Files] [Notes] ]
+    [ [[@../../example/n2550_find_if.cpp "n2550_find_if.cpp"]] [
+This example is adapted from __N2550__ (__CPP11_lambda__ functions): It passes a local function to the STL algorithm `std::find_if`.
+    ] ]
+    [ [[@../../example/n2529_this.cpp "n2529_this.cpp"]] [
+This example is adapted from __N2529__ (__CPP11_lambda__ functions): It binds the object in scope `this` to a local function.
+    ] ]
+]
+
+[endsect]
+
+[endsect]
+

Added: sandbox/closure/libs/local_function/doc/getting_started.qbk
==============================================================================
--- (empty file)
+++ sandbox/closure/libs/local_function/doc/getting_started.qbk	2012-01-21 13:27:24 EST (Sat, 21 Jan 2012)
@@ -0,0 +1,78 @@
+
+[/ Copyright (C) 2009-2011 Lorenzo Caminiti ]
+[/ Use, modification, and distribution is subject to the Boost Software ]
+[/ License, Version 1.0 (see accompanying file LICENSE_1_0.txt or a ]
+[/ copy at http://www.boost.org/LICENSE_1_0.txt). ]
+
+[section:Getting_Started Getting Started]
+
+This section explains how to setup a system to use this library.
+
+[section This Documentation]
+
+Programmers should have enough knowledge to use this library after reading the __Introduction__, __Getting_Started__, and __Tutorial__ sections.
+The __Advanced_Topics__ 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 `BOOST_CHECK` is used equivalently to `assert` and __Boost_Test__ `BOOST_AUTO_TEST_CASE` equivalently to `main`.
+[footnote
+*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.
+]
+
+[endsect]
+
+[section Compilers and Platforms]
+
+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 __CPP03__ standard.
+At present, this library has been successfully compiled and tested on the following compilers and platforms:
+
+# GNU Compiler Collection (GCC) 4.5.1 (with and without __CPP11__ features enabled) on Ubuntu Linux 10.
+# GCC 4.3.4 on Cygwin.
+# Miscrosoft Visual Studio Compiler (MSVC) 8.0 on Windows XP and Windows 7.
+
+This library has not yet been tested on any other compiler or platform.
+
+[endsect]
+
+[section Installation]
+
+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 (`-I` option for GCC, `/I` 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:
+[footnote
+*Rationale.*
+This library concatenates symbols specified by the programmers (e.g., the local function name) with other symbols (e.g., special prefixes or preprocessor line numbers) to make internal symbols with unique names to avoid name clashes.
+These symbols are separated by the letter "`X`" when they are concatenated so they read more easily during debugging.
+The underscore character "`_`" could not be used instead of the letter "`X`" because if the original symbols already contained a leading or trailing underscore, the concatenation could result in a symbol with double underscores "`__`" 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.
+]
+
+* Any symbol defined by files within the `"boost/local_function/aux_/"` or `"boost/local_function/detail"` directories (these header files should not be directly included by programmers).
+* Any symbol prefixed by `BOOST_LOCAL_FUNCTION_AUX_...` or `BOOST_LOCAL_FUNCTION_DETAIL_...` (regardless of its namespace).
+* Any symbol within the `boost::local_function::aux` or `boost::local_function::detail` namespace.
+* Any symbol prefixed by `boost_local_function_aux_...` or `boost_local_function_detail_...` (regardless of its namespace).
+
+[endsect]
+
+[section Compile-Time Configuration]
+
+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 `BOOST_LOCAL_CONFIG_...` (see the __Reference__ section).
+It is strongly recommended not to change the library configuration macro definitions unless strictly necessary.
+
+[endsect]
+
+[endsect]
+

Added: sandbox/closure/libs/local_function/doc/implementation.qbk
==============================================================================
--- (empty file)
+++ sandbox/closure/libs/local_function/doc/implementation.qbk	2012-01-21 13:27:24 EST (Sat, 21 Jan 2012)
@@ -0,0 +1,59 @@
+
+[/ Copyright (C) 2009-2011 Lorenzo Caminiti ]
+[/ Use, modification, and distribution is subject to the Boost Software ]
+[/ License, Version 1.0 (see accompanying file LICENSE_1_0.txt or a ]
+[/ copy at http://www.boost.org/LICENSE_1_0.txt). ]
+
+[section:Implementation Appendix: Implementation]
+
+This section gives an overview of the key programming techniques used to implement this library.
+
+[note
+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.
+]
+
+[section Local Classes as Template Parameters]
+
+This library uses a local class to implement the local function object.
+However, in __CPP03__ local classes (and therefore the local function objects they implement) cannot be passed as template parameters (e.g., to the `std::for_each` algorithm), this is instead possible on __CPP11__, 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):
+
+# 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 `void*` pointer (local classes can always be used for type casting).
+
+# The /virtual functor trick/ derives the local functor class from a non-local base class.
+The correct overridden implementation of the virtual `operator()` is then called via polymorphism.
+
+[example_impl_tparam_tricks]
+
+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 [@http://en.wikipedia.org/wiki/Virtual_method_table virtual function table]).
+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, __CPP11__, 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.
+
+[endsect]
+
+[section Parsing Macros]
+
+This library macros can parse the list of specified parameters and detect if any of the bound parameter name matches the token `this_` (to generate special code to bind the object in scope), or if the parameter is bound by `const` (to generate special code to bind by constant), etc.
+The parameter tokens are inspected using preprocessor metaprogramming, specifically using the macros from `"boost/local_function/detail/preprocessor/keyword/"`.
+[footnote
+This technique is at the core of even more complex preprocessor parsing macros like the ones that parse the __Contractpp__ syntax.
+]
+
+For example, the following code defines a macro that allows the preprocessor to detect if a set of space-separated tokens end with `this_` or not:
+
+[example_impl_pp_keyword]
+
+[endsect]
+
+[section Local Functions]
+
+The local function macros expand to code equivalent to the following:
+
+[example_impl_factorial]
+
+[endsect]
+
+[endsect]
+

Added: sandbox/closure/libs/local_function/doc/introduction.qbk
==============================================================================
--- (empty file)
+++ sandbox/closure/libs/local_function/doc/introduction.qbk	2012-01-21 13:27:24 EST (Sat, 21 Jan 2012)
@@ -0,0 +1,33 @@
+
+[/ Copyright (C) 2009-2011 Lorenzo Caminiti ]
+[/ Use, modification, and distribution is subject to the Boost Software ]
+[/ License, Version 1.0 (see accompanying file LICENSE_1_0.txt or a ]
+[/ copy at http://www.boost.org/LICENSE_1_0.txt). ]
+
+[section:Introduction Introduction]
+
+/Local functions/ are a form of /information hiding/ and are useful for dividing procedural tasks into subtasks which are only meaningful locally, avoiding cluttering other parts of the program with functions, variables, etc unrelated to those parts.
+Local functions therefore complement other structuring possibilities such as namespaces and classes.
+Local functions are a feature of many programming languages, notably [@http://en.wikipedia.org/wiki/Nested_function#An_example Pascal] and [@http://en.wikipedia.org/wiki/Nesting_(computing)#In_programming Ada], yet lacking from __CPP03__ (see also __N2511__).
+
+Using __CPP11_lambda__ functions, it is possible to implement local functions by naming the lambdas assigning them to local variables.
+For example (see also [@../../test/add_lambda.cpp `"add_lambda.cpp"`]):
+
+[test_add_lambda]
+
+This library allows to program local functions portably between __CPP03__ and __CPP11__ (and with performances comparable to lambdas on __CPP11__ compilers, see the __Alternatives__ section).
+For example (see also [@../../test/add.cpp `"add.cpp"`]):
+
+[test_add]
+
+This library supports the following features for local functions:
+
+* Local functions can capture, or better [@http://en.wikipedia.org/wiki/Name_binding /bind/], any of the variables from the enclosing scope (a function together with its captured variables is also called a [@http://en.wikipedia.org/wiki/Closure_(computer_science) /closure/]).
+* The local function body is programmed using the usual C++ statement syntax (as a consequence, compiler error messages retain their usual meaning and format).
+* 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 __CPP03__ functors implemented using local classes, see __N2657__ and the __Alternatives__ section).
+* 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 __CPP11_lambda__ functions, see the __Alternatives__ section).
+
+See the __Alternatives__ section for a comparison between this library, __CPP11_lambda__ functions, __Boost_Phoenix__, and other C++ techniques implementing related features.
+
+[endsect]
+

Added: sandbox/closure/libs/local_function/doc/local_function.qbk
==============================================================================
--- (empty file)
+++ sandbox/closure/libs/local_function/doc/local_function.qbk	2012-01-21 13:27:24 EST (Sat, 21 Jan 2012)
@@ -0,0 +1,109 @@
+
+[/ Copyright (C) 2009-2011 Lorenzo Caminiti ]
+[/ Use, modification, and distribution is subject to the Boost Software ]
+[/ License, Version 1.0 (see accompanying file LICENSE_1_0.txt or a ]
+[/ copy at http://www.boost.org/LICENSE_1_0.txt). ]
+
+[library Boost.LocalFunction
+    [quickbook 1.5]
+    [version 1.0.0 ]
+    [copyright 2009-2012 Lorenzo Caminiti]
+    [purpose declare functions at local scope]
+    [license
+        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])
+    ]
+    [authors [Caminiti <email>lorcaminiti_at_[hidden]</email>, Lorenzo]]
+    [category Function Objects and Higher-Order Programming]
+    [id local_function]
+    [dirname local_function]
+]
+
+[def __CPP03__ [@http://www.open-std.org/JTC1/SC22/WG21/docs/standards C++03]]
+[def __CPP11__ [@http://www.open-std.org/JTC1/SC22/WG21/ C++11]]
+[def __C99__ [@http://www.open-std.org/jtc1/sc22/wg14/www/projects#9899 C99]]
+[def __Boost__ [@http://www.boost.org/ Boost]]
+[def __Boost_LocalFunction__ [@http://www.boost.org/doc/libs/release/libs/local_function/doc/html/index.html Boost.LocalFunction]]
+[def __Boost_ScopeExit__ [@http://www.boost.org/doc/libs/release/libs/scope_exit/doc/html/index.html Boost.ScopeExit]]
+[def __Boost_Test__ [@http://www.boost.org/doc/libs/release/libs/test/doc/html/index.html Boost.Test]]
+[def __Boost_Lambda__ [@http://www.boost.org/doc/libs/release/doc/html/lambda.html Boost.Lambda]]
+[def __Boost_Phoenix__ [@http://www.boost.org/doc/libs/release/libs/spirit/phoenix/index.html Boost.Phoenix]]
+[def __Boost_Preprocessor__ [@http://www.boost.org/doc/libs/release/libs/preprocessor/doc/index.html Boost.Preprocessor]]
+[def __Boost_MPL__ [@http://www.boost.org/doc/libs/release/libs/mpl/doc/index.html Boost.MPL]]
+[def __Boost_ConceptCheck__ [@http://www.boost.org/doc/libs/release/libs/concept_check/doc/index.html Boost.ConceptCheck]]
+[def __Boost_Parameter__ [@http://www.boost.org/doc/libs/release/libs/parameter/doc/index.html Boost.Paramater]]
+[def __Boost_Typeof__ [@http://www.boost.org/doc/libs/release/doc/html/typeof.html Boost.Typeof]]
+[def __Boost_Function__ [@http://www.boost.org/doc/libs/release/doc/html/function.html Boost.Function]]
+[def __Boost_TypeTraits__ [@http://www.boost.org/doc/libs/release/libs/type_traits/doc/html/index.html Boost.TypeTraits]]
+[def __Boost_Utility__ [@http://www.boost.org/doc/libs/release/libs/utility/doc/html/index.html Boost.Utility]]
+[def __Boost_Chrono__ [@http://www.boost.org/doc/libs/release/libs/chrono/doc/html/index.html Boost.Chrono]]
+[def __CPP11_lambda__ [@http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions C++11 lambda]]
+[def __LISP__ [@http://en.wikipedia.org/wiki/Lisp_(programming_language) LISP]]
+[def __Contractpp__ [@http://sourceforge.net/projects/contractpp Contract++]]
+[def __D_Programming_Language__ [@http://d.digitalmars.com D Programming Language]]
+[def __expression_template__ [@http://en.wikibooks.org/wiki/More_C%2B%2B_Idioms/Expression-template expression template]]
+[def __N1613__ [@http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2004/n1613.pdf \[N1613\]]]
+[def __N2511__ [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2511.html \[N2511\]]]
+[def __N2529__ [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2529.pdf \[N2529\]]]
+[def __N2550__ [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2550.pdf \[N2550\]]]
+[def __N2657__ [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2657.htm \[N2657\]]]
+
+[def __Introduction__ [link boost_local.Introduction Introduction]]
+[def __Getting_Started__ [link boost_local.Getting_Started Getting Started]]
+[def __Tutorial__ [link boost_local.Tutorial Tutorial]]
+[def __Advanced_Topics__ [link boost_local.Advanced_Topics Advanced Topics]]
+[def __Reference__ [@reference.html Reference]]
+[def __Examples__ [link boost_local.Examples Examples]]
+[def __Alternatives__ [link boost_local.Alternatives Alternatives]]
+[def __No_Variadic_Macros__ [link boost_local.No_Variadic_Macros No Variadic Macros]]
+[def __Implementation__ [link boost_local.Implementation Implementation]]
+[def __Release_Notes__ [link boost_local.Release_Notes Release Notes]]
+[def __Bibliography__ [link boost_local.Bibliography Bibliography]]
+[def __Acknowledgments__ [link boost_local.Acknowledgments Acknowledgments]]
+
+[import ../test/add.cpp]
+[import ../test/add_seq.cpp]
+[import ../test/add_lambda.cpp]
+[import ../test/add_nobind.cpp]
+[import ../test/ten.cpp]
+[import ../test/add_this.cpp]
+[import ../test/add_template.cpp]
+[import ../test/add_default.cpp]
+[import ../test/add_with_default.cpp]
+[import ../test/return_assign.cpp]
+[import ../test/transform.cpp]
+[import ../test/typeof.cpp]
+[import ../test/typeof_template.cpp]
+[import ../test/add_typed.cpp]
+[import ../test/add_inline.cpp]
+[import ../test/nesting.cpp]
+[import ../test/factorial.cpp]
+[import ../test/overload.cpp]
+[import ../test/add_except.cpp]
+[import ../test/add_classifiers.cpp]
+
+[import ../example/const_block.cpp]
+[import ../example/gcc_lambda.cpp]
+[import ../example/gcc_lambda_cpp11.cpp]
+[import ../example/scope_exit.cpp]
+[import ../example/scope_exit.hpp]
+[import ../example/impl_tparam_tricks.cpp]
+[import ../example/impl_pp_keyword.cpp]
+[import ../example/impl_factorial.cpp]
+
+This library allows to declare functions at local scope within an enclosing function.
+
+[include introduction.qbk]
+[include getting_started.qbk]
+[include tutorial.qbk]
+[include advanced_topics.qbk]
+[xinclude ../reference.xml]
+[include examples.qbk]
+[include alternatives.qbk]
+[include no_variadic_macros.qbk]
+[include implementation.qbk]
+[include release_notes.qbk]
+[include bibliography.qbk]
+[include acknowledgements.qbk]
+

Added: sandbox/closure/libs/local_function/doc/no_variadic_macros.qbk
==============================================================================
--- (empty file)
+++ sandbox/closure/libs/local_function/doc/no_variadic_macros.qbk	2012-01-21 13:27:24 EST (Sat, 21 Jan 2012)
@@ -0,0 +1,59 @@
+
+[section:No_Variadic_Macros Annex: No Variadic Macros]
+
+This section illustrates an alternative syntax for compilers without variadic macro support.
+
+[section Sequence Syntax]
+
+Most modern compilers support [@http://en.wikipedia.org/wiki/Variadic_macro variaid macros] (notably, these include GCC, MSVC, and all __CPP11__ 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 `()`:
+
+    (token1) (token2) ... // All compilers.
+
+Instead of the comma-separated list that we have seen so far which requires variadic macros:
+
+    token1, token2, ... // Only compilers with varidic macros.
+
+For example, the following syntax is accepted on all compilers with and without variadic macros (see also [@../../test/add_seq.cpp `"add_seq.cpp"`]):
+
+[test_add_seq]
+
+However, on compilers with variadic macros the comma-separated syntax we have seen so far is preferred because more readable (see also [@../../test/add.cpp `"add.cpp"`]):
+
+[test_add]
+
+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 `void` on compilers with and without variadic macros.
+
+[endsect]
+
+[section Examples]
+
+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:
+
+[table
+    [ [Files] ]
+    [ [[@../../test/add_seq.cpp `"add_seq.cpp"`]] ]
+    [ [[@../../test/add_classifiers_seq.cpp `"add_classifiers_seq.cpp"`]] ]
+    [ [[@../../test/add_default_seq.cpp `"add_default_seq.cpp"`]] ]
+    [ [[@../../test/add_except_seq.cpp `"add_except_seq.cpp"`]] ]
+    [ [[@../../test/add_inline_seq.cpp `"add_inline_seq.cpp"`]] ]
+    [ [[@../../test/add_lambda_seq.cpp `"add_lambda_seq.cpp"`]] ]
+    [ [[@../../test/add_nobind_seq.cpp `"add_nobind_seq.cpp"`]] ]
+    [ [[@../../test/add_template_seq.cpp `"add_template_seq.cpp"`]] ]
+    [ [[@../../test/add_this_seq.cpp `"add_this_seq.cpp"`]] ]
+    [ [[@../../test/add_typed_seq.cpp `"add_typed_seq.cpp"`]] ]
+    [ [[@../../test/add_with_default_seq.cpp `"add_with_default_seq.cpp"`]] ]
+    [ [[@../../test/nesting_seq.cpp `"nesting_seq.cpp"`]] ]
+    [ [[@../../test/overload_seq.cpp `"overload_seq.cpp"`]] ]
+    [ [[@../../test/return_assign_seq.cpp `"return_assign_seq.cpp"`]] ]
+    [ [[@../../test/ten_seq.cpp `"ten_seq.cpp"`]] ]
+    [ [[@../../test/transform_seq.cpp `"transform_seq.cpp"`]] ]
+    [ [[@../../test/typeof_seq.cpp `"typeof_seq.cpp"`]] ]
+    [ [[@../../test/typeof_template_seq.cpp `"typeof_template_seq.cpp"`]] ]
+]
+
+[endsect]
+
+[endsect]
+

Added: sandbox/closure/libs/local_function/doc/release_notes.qbk
==============================================================================
--- (empty file)
+++ sandbox/closure/libs/local_function/doc/release_notes.qbk	2012-01-21 13:27:24 EST (Sat, 21 Jan 2012)
@@ -0,0 +1,39 @@
+
+[/ Copyright (C) 2009-2011 Lorenzo Caminiti ]
+[/ Use, modification, and distribution is subject to the Boost Software ]
+[/ License, Version 1.0 (see accompanying file LICENSE_1_0.txt or a ]
+[/ copy at http://www.boost.org/LICENSE_1_0.txt). ]
+
+[section:Release_Notes Release Notes]
+
+This section lists the major changes between different library releases (in chronological order).
+
+[h5 Version 0.2.0 (2011-05-14)]
+
+# Replaced parenthesized syntax with variadic and sequencing macro syntaxes.
+# Profiled library performances against other approaches.
+# Replaced virtual functor trick with casting functor trick (for smaller run-time).
+# Optimized library run-time (rearranging code and not using casting functor trick on compilers that accept local classes as template parameters).
+# Supported inline and recursive local functions.
+# Added type-of macro to expose bound types.
+# Allowed to explicitly specify bound types.
+# Removed using `boost::function` instead of exposing internal local functor as public API.
+# Added functor to overload local functions (and functors in general).
+# Implemented support for nesting local functions, blocks, and exits into one another.
+
+[h5 Version 0.1.1 (2011-01-10)]
+
+# Uploaded library source into Boost SVN sandbox.
+# Fixed prev/next arrows and other minor layouts in documentation.
+# Added Release section to documentation.
+
+[h5 Version 0.1.0 (2011-01-03)]
+
+# Shared with Boost for first round of comments.
+
+[h5 Version 0.0.1 (2010-12-15)]
+
+# Completed development, examples, and documentation.
+
+[endsect]
+

Added: sandbox/closure/libs/local_function/doc/tutorial.qbk
==============================================================================
--- (empty file)
+++ sandbox/closure/libs/local_function/doc/tutorial.qbk	2012-01-21 13:27:24 EST (Sat, 21 Jan 2012)
@@ -0,0 +1,220 @@
+
+[/ Copyright (C) 2009-2011 Lorenzo Caminiti ]
+[/ Use, modification, and distribution is subject to the Boost Software ]
+[/ License, Version 1.0 (see accompanying file LICENSE_1_0.txt or a ]
+[/ copy at http://www.boost.org/LICENSE_1_0.txt). ]
+
+[section:Tutorial Tutorial]
+
+This section illustrates basic usages of this library.
+
+[section Local Functions]
+
+Local functions are defined using macros from the header file [headerref boost/local_function.hpp].
+The macros must be used from within a declarative context (this is a limitation with respect to __CPP11_lambda__ functions which can instead be declared within expressions):
+
+    #include <boost/local_function.hpp>
+
+    ...
+    { // Some declarative context.
+        ...
+        ``/result-type/`` BOOST_LOCAL_FUNCTION(``/parameters/``) {
+            ``/body-code/``
+        } BOOST_LOCAL_FUNCTION_NAME(``/name/``)
+        ...
+    }
+
+The code expanded by the macros declares a function object (or [@http://en.wikipedia.org/wiki/Functor functor]) with the local function name specified by [macroref BOOST_LOCAL_FUNCTION_NAME].
+[footnote
+*Rationale.*
+The local function name must be passed to the macro [macroref BOOST_LOCAL_FUNCTION_NAME] ending the function definition so this macro can declare a local variable with the local function name to hold the local function object.
+]
+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 `{ ... }` 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.
+[footnote
+*Rationale.*
+If the local function body were instead passed as a macro parameter, it would be expanded on a single line of code (because macros always expand as a single line of code).
+Therefore, eventual compiler error line numbers would all report the same value and would no longer be useful to pinpoint the error.
+]
+
+The local function parameters are passed to the [macroref BOOST_LOCAL_FUNCTION] macro as a comma-separated list of tokens (see the __No_Variadic_Macros__ section for compilers that do not support variadic macros):
+
+    BOOST_LOCAL_FUNCTION(``[^/parameter-type1 parameter-name1/]``,`` [^/parameter-type2 parameter-name2, .../]``)
+
+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 [macroref BOOST_LOCAL_FUNCTION_CONFIG_ARITY_MAX].
+For example, let's program a local function named `add` that adds together two integers `x` and `y` (see also [@../../test/add_nobind.cpp `"add_nobind.cpp"`]):
+
+[test_add_nobind]
+
+If the local function has no parameter, it is possible to pass `void` to the [macroref BOOST_LOCAL_FUNCTION] macro (similarly to the C syntax that allows to use `int f(void)` for a function with no parameter):
+[footnote
+*Rationale.*
+The __CPP03__ standard does not allow pass empty parameters to a macro so the macro cannot be invoked as `BOOST_LOCAL_FUNCTION()`.
+On __C99__ compilers with properly implemented empty macro parameter support it would be possible to allow `BOOST_LOCAL_FUNCTION()` but this is already not the case for MSVC so this syntax is never allowed to ensure better portability.
+]
+
+    BOOST_LOCAL_FUNCTION(void) // No parameter.
+
+For example, let's program a local function that always returns `10` (see also [@../../test/ten.cpp `"ten.cpp"`]):
+
+[test_ten]
+
+[endsect]
+
+[section:Binding Binding Variables]
+
+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__.
+[footnote
+*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.
+]
+
+[important
+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 `BOOST_TYPEOF_REGISTER_TYPE` or `BOOST_TYPEOF_REGISTER_TEMPLATE` macros, or appropriate __Boost_Typeof__ headers should be included (see the __Boost_Typeof__ documentation for more detail).
+]
+
+This library introduces the new "keyword" `bind`
+[footnote
+Obviously, the token `bind` is not a keyword of the C++ language.
+This library parses the token `bind` during macro expansion using preprocessor metaprogramming (see the __Implementation__ section).
+Therefore, `bind` can be considered a new "keyword" only at the preprocessor metaprogramming level within the syntax defined by the macros of this library- thus it is referred to as a "keyword" only within quotes.
+]
+which is used in place of the parameter type to specify the name of a variable in scope to bind (therefore, `bind` cannot be used as a local function parameter type).
+A variable can be bound by value:
+    
+    bind ``/variable-name/`` // Bind by value.
+    
+Or by reference prefixing the variable name with `&`:
+
+    bind& ``/variable-name/`` // Bind by reference.
+    
+Furthermore, the "keyword" `bind` can be prefixed by `const` to bind the variable by constant value:
+    
+    const bind ``/variable-name/`` // Bind by constant value.
+
+Or by constant reference:
+    
+    const bind& ``/variable-name/`` // Bind by constant value.
+
+Note that when `const` is used, it must always precede `bind`.
+[footnote
+*Rationale.*
+The library macros could have been implemented to accept both syntaxes `const bind ...` and `bind const ...` equivalently.
+However, handling both syntaxes would have complicated the macro implementation without adding any feature so only one syntax (`const bind ...`) is supported.
+]
+    
+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:
+
+* If a bound variable was declared constant in the enclosing scope, it will be always bound by constant value or constant reference even if `bind` is used instead of `const bind` .
+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 `const bind`.
+(Note that binding by constant reference is not supported by __CPP11_lambda__ functions but it is supported by this library.)
+[footnote
+An historical note: Constant binding of variables in scope was the main use case that originally motivated the authors in developing this library.
+The authors needed to locally create a chuck of code to assert some correctness conditions while these assertions were not supposed to modify any of the variables they were using (see the __Contractpp__ library).
+This was achieved by binding by constant reference `const bind&` 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 `==` with `=`), the compiler correctly generates an error because the bound variable is of `const` type within the local function body.
+]
+* 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 `bind&` or `const bind&`.
+[footnote
+*Rationale.*
+Variables originally declared as references are bound by value unless `[const] bind&` is used so that references can be bound by both value `[const] bind` and reference `[const] bind&` (this is the same binding semantic adopted by __Boost_ScopeExit__).
+On the other hand, variables originally declared as constants should never loose their `const` 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 `bind[&]` is used instead of `const bind[&]`.
+]
+
+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 `add` from the example in the __Introduction__ section.
+We bind the local variable `factor` by constant value, the local variable `sum` by (non-constant) reference, and program the body to perform the summation (see also [@../../test/add.cpp `"add.cpp"`]):
+
+[test_add]
+
+[endsect]
+
+[section Binding the Object `this`]
+
+It is also possible to bind the object `this` when it is in scope (e.g., from an enclosing non-static member function).
+This is done by using the special symbol `this_`
+[footnote
+*Rationale.*
+The special name `this_` was chosen following [@http://boost.2283326.n4.nabble.com/local-this-or-this-td3423912.html Boost practises] which postfix with an underscore identifiers that are named after keywords (the C++ keyword `this` in this case).
+]
+(instead of `this`)
+[footnote
+*Rationale.*
+This limitation comes from the fact that `this` is a reserved C++ keyword so it cannot be used as the name of the internal parameter that passes the bound object to the local function body.
+It would have been possible to use `this` (instead of `this_`) within the local function body either at the expenses of copying the bound object (which would introduce run-time overhead and also the stringent requirement that the bound object must have a deep copy constructor) or by relying on an [@http://groups.google.com/group/comp.lang.c++.moderated/browse_thread/thread/d3a86f27277f713b undefined behaviour of `static_cast`] (which might not work on all platforms at the cost of portability).
+]
+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 `this` can be bound by value:
+
+    bind this_ // Bind the object `this` by value.
+
+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 `this` can be bound by constant value:
+
+    const bind this_ // Bind the object `this` by constant value.
+
+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 `this` can never be bound by reference because C++ does not allow to obtain a reference to `this` (the library will generate a compile-time error if programmers try to use `bind& this` or `const bind& this`).
+Note that `this` is a pointer so the pointed object is never copied even if `this` is bound by value (also it is not allowed to directly bind `*this` because `*this` is an expression and not a valid name of a variable in scope).
+
+[warning
+Unfortunately, mistakenly using `this` within the local function body instead of `this_` leads to undefined behaviour and it will not necessarily generate a compile-time error.
+[footnote
+*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 [macroref BOOST_LOCAL_FUNCTION_NAME] 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 __Implementation__ section.
+Therefore, from within the local function body the variable `this` is visible but it refers to the local functor and not to the bound object.
+]
+Programmers are responsible to make sure that `this` is never used within a local function body which should only use the special symbol `this_`.
+]
+
+For example, let's program a local function `add` similar to the one in the example from the __Introduction__ section but using a member function to illustrate how to bind the object `this` (see also [@../../test/add_this.cpp `"add_this.cpp"`]):
+
+[test_add_this]
+
+[endsect]
+
+[section Templates]
+
+When local functions are programmed within templates, they need to be declared using the special macro [macroref BOOST_LOCAL_FUNCTION_TPL] (see the __Reference__ section):
+[footnote
+*Rationale.*
+Within templates, this library needs to use `typename` to explicitly indicate that some expressions evaluate to a type.
+Because __CPP03__ does not allow to use `typename` outside templates, the special `TPL` macro is used to indicate that the enclosing scope is a template so this library can safely use `typename` to resolve expression type ambiguities.
+]
+
+    #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/``)
+        ...
+    }
+
+The [macroref BOOST_LOCAL_FUNCTION_TPL] macro has the exact same syntax of the [macroref BOOST_LOCAL_FUNCTION] macro that we have seen so far.
+
+For example, let's rewrite a local function similar to the one from the __Introduction__ section but wrapped within a template:
+
+[test_add_template]
+
+[endsect]
+
+[endsect]
+