| Home | Libraries | People | FAQ | More

## Macro BOOST_LOCAL_FUNCTION

BOOST_LOCAL_FUNCTION — This macro is used to start a local function declaration.

## Synopsis

    // In header: <boost/local_function.hpp>

    BOOST_LOCAL_FUNCTION(declarations)

## Description

This macro must be used within a declarative context, it must follow the local function result type, it must be followed by the local function body code, and then by the `BOOST_LOCAL_FUNCTION_NAME` macro (see the Tutorial and Advanced Topics sections):

    { // Some declarative context.
        ...
        result_type BOOST_LOCAL_FUNCTION(declarations) {
            ... // Body code.
        } BOOST_LOCAL_FUNCTION_NAME(qualified_name)
        ...
    }

As usual, exceptions specifications can be optionally programmed just after the macro and before the body code block `{ ... }` (but the exception specifications will only apply to the body code and not to the library code automatically generated by the macro expansion, see the Advanced Topics section).

Within templates, the special macros `BOOST_LOCAL_FUNCTION_TPL` and `BOOST_LOCAL_FUNCTION_NAME_TPL` must be used.

Parameters:

`declarations`

On compilers that support variadic macros, the parameter declarations are defined by the following grammar:

    declarations:
            void | declaration_tuple | declaration_sequence
    declaration_tuple:
            declaration, declaration, ...
    declaration_sequence:
            (declaration) (declaration) ...
    declaration:
            bound_variable | parameter | default_value | result_type
    bound_variable:
            [const] bind [(variable_type)] [&] variable_name
    parameter:
            [auto | register] parameter_type parameter_name
    default_value:
            default parameter_default_value
    result_type:
            return function_result_type

On compilers that do not support variadic macros, `declaration_tuple` cannot be used:

    declarations:
            void | declaration_sequence

(Lexical conventions: `token1 | token2` means either `token1` or `token2`; `[token]` means either `token` or nothing; `{expression}` means the token resulting from the expression.)

Note that on compilers that support variadic macros, commas can be used to separate the declarations resembling more closely the usual C++ function declaration syntax (this is the preferred syntax). However, for portability, on all C++ compilers (with and without variadic macros) the same library macros also accept parameter declarations specified as a Boost.Preprocessor sequence separated by round parenthesis `()`.

When binding the object `this`, the special symbol `this_` needs to be used instead of `this` as the name of the variable to bind and also within the local function body to access the object. (Mistakenly using `this` instead of `this_` might not always result in a compiler error and will in general result in undefined behaviour.)

The result type must either be specified just before the macro or within the macro declarations prefixed by `return` (but not in both places).

Within the local function body it possible to access the result type using `result_type`, the type of the first parameter using `arg1_type`, the type of the second parameter using `arg2_type`, etc. The bound variable types can be accessed using `BOOST_LOCAL_FUNCTION_TYPEOF`.

This macro cannot be portably expanded multiple times on the same line. In these cases, use the `BOOST_LOCAL_FUNCTION_ID` macro instead.

The maximum number of local function parameters (excluding bound variables) is specified by the configuration macro `BOOST_LOCAL_FUNCTION_CONFIG_ARITY_MAX`. The maximum number of bound variables is specified by the configuration macro `BOOST_LOCAL_FUNCTION_CONFIG_BIND_MAX`. The configuration macro `BOOST_LOCAL_FUNCTION_CONFIG_LOCALS_AS_TPARAMS` can be used to force optimizations that reduce the local function call run-time overhead.

Note: Local functions are functors so they can be assigned to other functors like `boost::function` (see Boost.Function).

See: Tutorial section, Advanced Topics section, `BOOST_LOCAL_FUNCTION_NAME`, `BOOST_LOCAL_FUNCTION_TPL`, `BOOST_LOCAL_FUNCTION_NAME_TPL`, `BOOST_LOCAL_FUNCTION_TYPEOF`, `BOOST_LOCAL_FUNCTION_ID`, `BOOST_LOCAL_FUNCTION_CONFIG_ARITY_MAX`, `BOOST_LOCAL_FUNCTION_CONFIG_BIND_MAX`, `BOOST_LOCAL_FUNCTION_CONFIG_LOCALS_AS_TPARAMS`.