Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

Click here to view the latest version of this page.
PrevUpHomeNext

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.


PrevUpHomeNext