Boost C++ Libraries

Local functions are defined using macros from the header file boost/local_function.hpp. The macros must be used from within a declarative context (this is a limitation with respect to C++11 lambda functions which can instead be declared also within expressions):

#include <boost/local_function.hpp> // This library header.

...
{ // 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 functor) with the local function name specified by BOOST_LOCAL_FUNCTION_NAME. ^[5] 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 result type is specified just before the BOOST_LOCAL_FUNCTION macro.

The local function body is specified using the usual C++ statement syntax in a code block { ... } between the BOOST_LOCAL_FUNCTION and BOOST_LOCAL_FUNCTION_NAME macros. The body is specified outside any of the macros so eventual compiler error messages and related line numbers retain their usual meaning and format. ^[6]

The local function parameters are passed to the 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 is controlled at compile-time by the configuration macro 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 add_params_only.cpp):

int BOOST_LOCAL_FUNCTION(int x, int y) { // Local function.
    return x + y;
} BOOST_LOCAL_FUNCTION_NAME(add)

BOOST_TEST(add(1, 2) == 3); // Local function call.

If the local function has no parameter, it is possible to pass void to the BOOST_LOCAL_FUNCTION macro (similarly to the C++ syntax that allows to use result-type function-name(void) to declare a function with no parameter): ^[7]

BOOST_LOCAL_FUNCTION(void) // No parameter.

For example, let's program a local function that always returns 10 (see also ten_void.cpp):

int BOOST_LOCAL_FUNCTION(void) { // No parameter.
    return 10;
} BOOST_LOCAL_FUNCTION_NAME(ten)

BOOST_TEST(ten() == 10);

Variables in scope (local variables, enclosing function parameters, data members, 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 deduced automatically by this library using Boost.Typeof. ^[8]

This library introduces the new "keyword" bind ^[9] 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. ^[10]

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 existence scope of the local function otherwise the bound references will be invalid when the local function is called 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 using Boost.Typeof and it is the exact same type used to declare such a variable in the enclosing scope with the following notes:

When a variable is bound by value (constant or not), its type must be CopyConstructible (i.e., its must provide a copy constructor). As with passing parameters to usual C++ functions, programmers might want to bind variables of complex types by (possibly constant) reference instead of 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 (because its value should not be modified by the local function), the local variable sum by non-constant reference (because its value needs to be updated with the summation result), and program the body to perform the summation (see also add.cpp):

int main(void) {                            // Some local scope.
    int sum = 0, factor = 10;               // Variables in scope to bind.

    void BOOST_LOCAL_FUNCTION(const bind factor, bind& sum, int num) {
        sum += factor * num;
    } BOOST_LOCAL_FUNCTION_NAME(add)

    add(1);                                 // Call the local function.
    int nums[] = {2, 3};
    std::for_each(nums, nums + 2, add);     // Pass it to an algorithm.

    BOOST_TEST(sum == 60);                  // Assert final summation value.
    return boost::report_errors();
}

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_ (instead of this) as the name of the variable to bind in the local function declaration and also to access the object within the local function body. ^[13]

Warning

The library will generate a compile-time error if this is mistakenly used instead of this_ to bind the object in the local function declaration. However, mistakenly using this instead of this_ to access the object within the local function body will leads to undefined behaviour and it will not necessarily generate a compile-time error. [14] Programmers are ultimately responsible to make sure that this is never used within a local function.

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 possible to directly bind *this because *this is an expression and not a variable name).

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 add_this.cpp):

struct adder {
    adder() : sum_(0) {}

    int sum(const std::vector<int>& nums, const int factor = 10) {

        void BOOST_LOCAL_FUNCTION(const bind factor, bind this_, int num) {
            this_->sum_ += factor * num; // Use `this_` instead of `this`.
        } BOOST_LOCAL_FUNCTION_NAME(add)

        std::for_each(nums.begin(), nums.end(), add);
        return sum_;
    }

private:
    int sum_;
};

Note that the local function has access to all class members via the bound object this_ regardless of their access level (public, protected, or private). ^[15] Specifically, in the example above the local function updates the private data member sum_.

When local functions are programmed within templates, they need to be declared using the special macros BOOST_LOCAL_FUNCTION_TPL and BOOST_LOCAL_FUNCTION_NAME_TPL: ^[16]

#include <boost/local_function.hpp> // This library header.

...
{ // Some declarative context within a template.
    ...
    result-type BOOST_LOCAL_FUNCTION_TPL(parameters) {
        body-code
    } BOOST_LOCAL_FUNCTION_NAME_TPL(name)
    ...
}

The BOOST_LOCAL_FUNCTION_TPL and BOOST_LOCAL_FUNCTION_NAME_TPL macros have the exact same syntax of the BOOST_LOCAL_FUNCTION and BOOST_LOCAL_FUNCTION_NAME macros that we have seen so far.

For example, let's program a local function similar to the one from the Introduction section but within a template (see also add_template.cpp):

template<typename T>
T total(const T& x, const T& y, const T& z) {
    T sum = T(), factor = 10;

    // Must use the `..._TPL` macros within templates.
    T BOOST_LOCAL_FUNCTION_TPL(const bind factor, bind& sum, T num) {
        return sum += factor * num;
    } BOOST_LOCAL_FUNCTION_NAME_TPL(add)

    add(x);
    T nums[2]; nums[0] = y; nums[1] = z;
    std::for_each(nums, nums + 2, add);

    return sum;
}