[boost] [local] local functions ready for review

Subject: [boost] [local] local functions ready for review
From: Lorenzo Caminiti (lorcaminiti_at_[hidden])
Date: 2011-01-03 12:22:20

Hello all,

A few months ago, I probed for interest in a library for local
functions with Boost.ScopeExit's variable binding. Based on that
discussion, I have now implemented the Boost.Local library.

I have uploaded the source files boost-local_0_1_0-818.zip in the
Boost Vault under Function Objects:
http://www.boostpro.com/vault/index.php?&direction=0&order=&directory=Function%20Objects

The documentation on the web:
http://contractpp.sourceforge.net/boost-local_0_1_0-818/libs/local/doc/html/index.html

Any comment?

As far as I can tell, Boost.Local is ready for a formal review so I am
looking for a review manager. Any volunteer?

Thanks,
Lorenzo

________________________________________________
P.S. A preview from Boost.Local's documentation:

The Boost Local library implements local functions, local blocks, and
local exits for the C++ programming language.

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 Pascal and Ada, yet lacking from C++
(see also [N2511]).

This library supports the following features for local functions (see
the Alternatives section for a comparison between this library and
features offered by C++ local class members, C++0x lambda functions,
Boost.Lambda, Boost.Phoenix, and Boost.ScopeExit):
    * Local functions can access, or better bind, any of the variables
from the enclosing scope. Furthermore, local functions defined within
a member function can bind the enclosing object this.
    * The local function body is programmed using the usual C++ syntax.
    * Local functions can be passed as template parameters (so they
can be conveniently passed to STL algorithms, etc).
    * However, local functions must be defined within a declarative
context (e.g., at a point in the code where local variables can be
declared) thus they cannot be defined within an expression.

In addition to local functions, this library also supports the
following features:
    * Local blocks which define blocks of code that bind variables
from the enclosing scope. Local blocks allow programmers to bind
variables as constants (constant binding) so to prevent local chunks
of code from modifying selected variables.
    * Local exits which define blocks of code that are executed when
the enclosing scope is exited (again with support for constant binding
and binding of the object this).

AN EXAMPLE

The following example illustrates a simple use of this library and it
starts introducing the library API (see the Tutorial section for more
details on how to use this library):
    * A local function is passed to the STL std::for_each() algorithm
to add together the values of an array. Variables in scope are bound
to the local function by both constant value and non-constant
reference.
    * A local exit is used to automatically release the array's memory
at scope exit.
    * A local block is used to assert the correct final value of the
summation in a constant-correct context (therefore preventing the
assertion from mistakenly changing any of the variables in scope).

    #include <boost/local/function.hpp>
    #include <boost/local/block.hpp>
    #include <boost/local/exit.hpp>
    #include <algorithm>
    #include <iostream>
    #include <cassert>

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

        BOOST_LOCAL_FUNCTION(
        (void) (add)( (double)(num) (const bind)((factor))  (bind)((&sum))  )
        ) {
            sum += factor * num;
            std::clog << "Summed: " << sum << std::endl;
        } BOOST_LOCAL_FUNCTION_END(add)
        add(100.0);

        size_t size = 2;
        double* nums = new double[size];
        BOOST_LOCAL_EXIT( (const bind)((&size)) (bind)((nums)) ) {
            if (size && nums) delete[] nums;
            std::clog << "Freed array: " << nums << std::endl;
        } BOOST_LOCAL_EXIT_END

        nums[0] = 90.5; nums[1] = 7.0;
        std::for_each(nums, nums + size, add);

        BOOST_LOCAL_BLOCK( (const bind)((&sum)) ) {
            // So far: sum = 10 * 100.0 + 10 * 90.5 + 10 * 7.0 = 1975.0
            assert(sum == 1975.0);
            std::clog << "Asserted summation: " << sum << std::endl;
        } BOOST_LOCAL_BLOCK_END

        return 0;
    }