local_function/include/boost/local_function.hpp

// Copyright (C) 2009-2012 Lorenzo Caminiti
// Distributed under 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)
// Home at http://www.boost.org/libs/local_function

#ifndef BOOST_LOCAL_FUNCTION_HPP_
#define BOOST_LOCAL_FUNCTION_HPP_

#ifndef DOXYGEN

#include <boost/local_function/aux_/macro/decl.hpp>
#include <boost/local_function/aux_/macro/name.hpp>
#include <boost/local_function/aux_/macro/typeof.hpp>
#include <boost/local_function/aux_/preprocessor/traits/decl.hpp>
#include <boost/local_function/detail/preprocessor/line_counter.hpp>
#include <boost/local_function/detail/preprocessor/void_list.hpp>
#include <boost/config.hpp>

// PUBLIC //

#ifdef BOOST_NO_CXX11_VARIADIC_MACROS
#   define BOOST_LOCAL_FUNCTION_ID(id, declarations) \
        BOOST_LOCAL_FUNCTION_AUX_DECL(id, 0 /* not within template */, \
                BOOST_LOCAL_FUNCTION_AUX_PP_DECL_TRAITS( \
                        BOOST_LOCAL_FUNCTION_DETAIL_PP_VOID_LIST( \
                                declarations)))
#   define BOOST_LOCAL_FUNCTION(declarations) \
        BOOST_LOCAL_FUNCTION_ID( \
                BOOST_LOCAL_FUNCTION_DETAIL_PP_LINE_COUNTER, declarations)
#   define BOOST_LOCAL_FUNCTION_ID_TPL(id, declarations) \
        BOOST_LOCAL_FUNCTION_AUX_DECL(id, 1 /* within template */, \
                BOOST_LOCAL_FUNCTION_AUX_PP_DECL_TRAITS( \
                        BOOST_LOCAL_FUNCTION_DETAIL_PP_VOID_LIST( \
                                declarations)))
#   define BOOST_LOCAL_FUNCTION_TPL(declarations) \
        BOOST_LOCAL_FUNCTION_ID_TPL( \
                BOOST_LOCAL_FUNCTION_DETAIL_PP_LINE_COUNTER, declarations)
#else // VARIADIC
#   define BOOST_LOCAL_FUNCTION_ID(id, ...) \
        BOOST_LOCAL_FUNCTION_AUX_DECL(id, 0 /* not within template */, \
                BOOST_LOCAL_FUNCTION_AUX_PP_DECL_TRAITS( \
                        BOOST_LOCAL_FUNCTION_DETAIL_PP_VOID_LIST(__VA_ARGS__)))
#   define BOOST_LOCAL_FUNCTION(...) \
        BOOST_LOCAL_FUNCTION_ID( \
                BOOST_LOCAL_FUNCTION_DETAIL_PP_LINE_COUNTER, __VA_ARGS__)
#   define BOOST_LOCAL_FUNCTION_ID_TPL(id, ...) \
        BOOST_LOCAL_FUNCTION_AUX_DECL(id, 1 /* within template */, \
                BOOST_LOCAL_FUNCTION_AUX_PP_DECL_TRAITS( \
                        BOOST_LOCAL_FUNCTION_DETAIL_PP_VOID_LIST(__VA_ARGS__)))
#   define BOOST_LOCAL_FUNCTION_TPL(...) \
        BOOST_LOCAL_FUNCTION_ID_TPL( \
                BOOST_LOCAL_FUNCTION_DETAIL_PP_LINE_COUNTER, __VA_ARGS__)
#endif // VARIADIC

#define BOOST_LOCAL_FUNCTION_NAME(qualified_name) \
    BOOST_LOCAL_FUNCTION_AUX_NAME(0 /* not within template */, qualified_name)
#define BOOST_LOCAL_FUNCTION_NAME_TPL(qualified_name) \
    BOOST_LOCAL_FUNCTION_AUX_NAME(1 /* within template */, qualified_name)

#define BOOST_LOCAL_FUNCTION_TYPEOF(bound_variable_name) \
    BOOST_LOCAL_FUNCTION_AUX_TYPEOF_TYPE(bound_variable_name)

// DOCUMENTATION //

#else // DOXYGEN

/** @file
@brief Local functions allow to program functions locally, within other
functions, and directly within the scope where they are needed.
*/

/**
@brief This macro is used to start a local function declaration.

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 @RefMacro{BOOST_LOCAL_FUNCTION_NAME} macro (see the
@RefSect{tutorial, Tutorial} and @RefSect{advanced_topics, Advanced Topics}
sections):
@code
{ // Some declarative context.
    ...
    result_type BOOST_LOCAL_FUNCTION(declarations) {
        ... // Body code.
    } BOOST_LOCAL_FUNCTION_NAME(qualified_name)
    ...
}
@endcode

As usual, exceptions specifications can be optionally programmed just after the
macro and before the body code block <c>{ ... }</c> (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
@RefSect{advanced_topics, Advanced Topics} section).

Within templates, the special macros @RefMacro{BOOST_LOCAL_FUNCTION_TPL}
and @RefMacro{BOOST_LOCAL_FUNCTION_NAME_TPL} must be used.

@Params
@Param{declarations,
On compilers that support variadic macros\, the parameter declarations are
defined by the following grammar:
@code
    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
@endcode
On compilers that do not support variadic macros\, <c>declaration_tuple</c>
cannot be used:
@code
    declarations:
            void | declaration_sequence
@endcode

(Lexical conventions: <c>token1 | token2</c> means either <c>token1</c> or
<c>token2</c>; <c>[token]</c> means either <c>token</c> or nothing;
<c>{expression}</c> means the token resulting from the expression.)
}
@EndParams
 
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 <c>()</c>.

When binding the object <c>this</c>, the special symbol <c>this_</c> needs to
be used instead of <c>this</c> as the name of the variable to bind and also
within the local function body to access the object.
(Mistakenly using <c>this</c> instead of <c>this_</c> 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 <c>return</c> (but not in both places).

Within the local function body it possible to access the result type using <c>result_type</c>, the type of the first parameter using <c>arg1_type</c>, the type of the second parameter using <c>arg2_type</c>, etc.
The bound variable types can be accessed using @RefMacro{BOOST_LOCAL_FUNCTION_TYPEOF}.

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

The maximum number of local function parameters (excluding bound variables) is
specified by the configuration macro
@RefMacro{BOOST_LOCAL_FUNCTION_CONFIG_ARITY_MAX}.
The maximum number of bound variables is specified by the configuration macro
@RefMacro{BOOST_LOCAL_FUNCTION_CONFIG_BIND_MAX}.
The configuration macro
@RefMacro{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 <c>boost::function</c> (see Boost.Function).

@See @RefSect{tutorial, Tutorial} section,
@RefSect{advanced_topics, Advanced Topics} section,
@RefMacro{BOOST_LOCAL_FUNCTION_NAME}, @RefMacro{BOOST_LOCAL_FUNCTION_TPL},
@RefMacro{BOOST_LOCAL_FUNCTION_NAME_TPL},
@RefMacro{BOOST_LOCAL_FUNCTION_TYPEOF}, @RefMacro{BOOST_LOCAL_FUNCTION_ID},
@RefMacro{BOOST_LOCAL_FUNCTION_CONFIG_ARITY_MAX},
@RefMacro{BOOST_LOCAL_FUNCTION_CONFIG_BIND_MAX},
@RefMacro{BOOST_LOCAL_FUNCTION_CONFIG_LOCALS_AS_TPARAMS}.
*/
#define BOOST_LOCAL_FUNCTION(declarations)

/**
@brief This macro is used to start a local function declaration within
templates.

This macro must be used instead of @RefMacro{BOOST_LOCAL_FUNCTION} when
declaring a local function within a template.
A part from that, this macro has the exact same syntax a
@RefMacro{BOOST_LOCAL_FUNCTION} (see @RefMacro{BOOST_LOCAL_FUNCTION} for more
information):
@code
{ // Some declarative context within a template.
    ...
    result_type BOOST_LOCAL_FUNCTION_TPL(declarations) {
        ... // Body code.
    } BOOST_LOCAL_FUNCTION_NAME_TPL(qualified_name)
    ...
}
@endcode

Note that @RefMacro{BOOST_LOCAL_FUNCTION_NAME_TPL} must be used with this
macro instead of @RefMacro{BOOST_LOCAL_FUNCTION_NAME}.

This macro cannot be portably expanded multiple times on the same line.
In these cases, use the @RefMacro{BOOST_LOCAL_FUNCTION_ID_TPL} macro instead.

@Note C++03 does not allow to use <c>typename</c> outside templates.
This library internally manipulates types, these operations require
<c>typename</c> but only within templates.
This macro is used to indicate to the library when the enclosing scope is a
template so the library can correctly use <c>typename</c>.

@See @RefSect{tutorial, Tutorial} section, @RefMacro{BOOST_LOCAL_FUNCTION},
@RefMacro{BOOST_LOCAL_FUNCTION_ID_TPL},
@RefMacro{BOOST_LOCAL_FUNCTION_NAME_TPL}.
*/
#define BOOST_LOCAL_FUNCTION_TPL(declarations)

/**
@brief This macro allows to declare multiple local functions on the same line.

This macro is equivalent to @RefMacro{BOOST_LOCAL_FUNCTION} but it can be
expanded multiple times on the same line if different identifiers <c>id</c> are
provided for each expansion (see the
@RefSect{advanced_topics, Advanced Topics} section).

@Params
@Param{id,
A unique identifier token which can be concatenated by the preprocessor
(<c>__LINE__</c>\, <c>local_function_number_1_on_line_123</c>\, etc).
}
@Param{declarations,
Same as the <c>declarations</c> parameter of the
@RefMacro{BOOST_LOCAL_FUNCTION} macro.
}
@EndParams

The @RefMacro{BOOST_LOCAL_FUNCTION_NAME} macro should be used to end each one
of the multiple local function declarations as usual (and it will specify a
unique name for each local function).

Within templates, the special macros @RefMacro{BOOST_LOCAL_FUNCTION_ID_TPL}
must be used.

@Note This macro can be useful when the local function macros are expanded
within user-defined macros (because macros all expand on the same line).
On some compilers (e.g., MSVC which supports the non-standard
<c>__COUNTER__</c> macro) it might not be necessary to use this macro but
the use of this macro when expanding multiple local function macros on the same
line is always necessary to ensure portability (this is because this library
can only portably use <c>__LINE__</c> to internally generate unique
identifiers).

@See @RefSect{advanced_topics, Advanced Topics} section,
@RefMacro{BOOST_LOCAL_FUNCTION}, @RefMacro{BOOST_LOCAL_FUNCTION_NAME},
@RefMacro{BOOST_LOCAL_FUNCTION_ID_TPL}.
*/
#define BOOST_LOCAL_FUNCTION_ID(id, declarations)

/**
@brief This macro allows to declare multiple local functions on the same line
within templates.

This macro must be used instead of @RefMacro{BOOST_LOCAL_FUNCTION_TPL} when
declaring multiple local functions on the same line within a template.
A part from that, this macro has the exact same syntax as
@RefMacro{BOOST_LOCAL_FUNCTION_TPL} (see @RefMacro{BOOST_LOCAL_FUNCTION_TPL}
for more information).

@Params
@Param{id,
A unique identifier token which can be concatenated by the preprocessor
(<c>__LINE__</c>\, <c>local_function_number_1_on_line_123</c>\, etc).
}
@Param{declarations,
Same as the <c>declarations</c> parameter of the
@RefMacro{BOOST_LOCAL_FUNCTION_TPL} macro.
}
@EndParams

The @RefMacro{BOOST_LOCAL_FUNCTION_NAME} macro should be used to end each one
of the multiple local function declarations as usual (and it will specify a
unique name for each local function).

Outside template, the macro @RefMacro{BOOST_LOCAL_FUNCTION_ID} should be used
to declare multiple local functions on the same line.

@Note This macro can be useful when the local function macros are expanded
within user-defined macros (because macros all expand on the same line).
On some compilers (e.g., MSVC which supports the non-standard
<c>__COUNTER__</c> macro) it might not be necessary to use this macro but
the use of this macro when expanding multiple local function macros on the same
line is always necessary to ensure portability (this is because this library
can only portably use <c>__LINE__</c> to internally generate unique
identifiers).

@See @RefSect{advanced_topics, Advanced Topics} section,
@RefMacro{BOOST_LOCAL_FUNCTION_TPL}, @RefMacro{BOOST_LOCAL_FUNCTION_NAME},
@RefMacro{BOOST_LOCAL_FUNCTION_ID}.
*/
#define BOOST_LOCAL_FUNCTION_ID_TPL(id, declarations)

/**
@brief This macro is used to end a local function declaration specifying its
name.

This macro must follow the local function body code block <c>{ ... }</c>:
@code
{ // Some declarative context.
    ...
    result_type BOOST_LOCAL_FUNCTION(declarations) {
        ... // Body code.
    } BOOST_LOCAL_FUNCTION_NAME(qualified_name)
    ...
}
@endcode

Within templates, the special macros @RefMacro{BOOST_LOCAL_FUNCTION_TPL} and
@RefMacro{BOOST_LOCAL_FUNCTION_NAME_TPL} must be used.

@Params
@Param{qualified_name,
The name of the local function optionally qualified as follow:
@code
    name:
            [inline] [recursive] local_function_name
@endcode
(Lexical conventions: <c>token1 | token2</c> means either <c>token1</c> or
<c>token2</c>; <c>[token]</c> means either <c>token</c> or nothing;
<c>{expression}</c> means the token resulting from the expression.)
}
@EndParams

The local function name can be qualified by prefixing it with the keyword
<c>inline</c> (see the @RefSect{advanced_topics, Advanced Topics} section):
@code
    BOOST_LOCAL_FUNCTION_NAME(inline local_function_name)
@endcode
This increases the chances that the compiler will be able to inline the local
function calls (thus reducing run-time).
However, inline local functions cannot be passed as template parameters (e.g., to <c>std::for_each</c>) or assigned to other functors (e.g., to
<c>boost::function</c>).
That is true on C++03 compilers but inline local functions can instead be
passed as template parameters on C++11 compilers.
On C++11 compilers, there is no need to declare a local function lined because
this library will automatically use C++11 specific features to inline the local
function while always allowing to pass it as a template parameter.
This optimization is automatically enabled when the Boost.Config macro
<c>BOOST_NO_CXX11_LOCAL_CLASS_TEMPLATE_PARAMETERS</c> is not defined but it also be
forced using @RefMacro{BOOST_LOCAL_FUNCTION_CONFIG_LOCALS_AS_TPARAMS}.

The local function name can also be qualified by prefixing it with the
"keyword" <c>recursive</c> (see the
@RefSect{advanced_topics, Advanced Topics} section):
@code
    BOOST_LOCAL_FUNCTION_NAME(recursive local_function_name)
@endcode
This allows the local function to recursively call itself from its body (as
usual in C++).
However, recursive local functions should only be called within their
declaration scope (otherwise the result is undefined behaviour).
Finally, 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:
@code
    BOOST_LOCAL_FUNCTION(inline recursive local_function_name)
@endcode

@Note The local function name cannot be the name of an operator
<c>operator...</c> and it cannot be the same name of another local function
declared within the same enclosing scope (but <c>boost::overloaded_function</c>
can be used to overload local functions, see
Boost.Functional/OverloadedFunction and the
@RefSect{advanced_topics, Advanced Topics} section).

@See @RefSect{tutorial, Tutorial} section,
@RefSect{advanced_topics, Advanced Topics} section,
@RefMacro{BOOST_LOCAL_FUNCTION},
@RefMacro{BOOST_LOCAL_FUNCTION_NAME_TPL}.
*/
#define BOOST_LOCAL_FUNCTION_NAME(qualified_name)

/**
@brief This macro is used to end a local function declaration specifying its
name within templates.

This macro must be used instead of @RefMacro{BOOST_LOCAL_FUNCTION_NAME} when
declaring a local function within a template.
A part from that, this macro has the exact same syntax a
@RefMacro{BOOST_LOCAL_FUNCTION_NAME} (see @RefMacro{BOOST_LOCAL_FUNCTION_NAME}
for more information):
@code
{ // Some declarative context within a template.
    ...
    result_type BOOST_LOCAL_FUNCTION_TPL(declarations) {
        ... // Body code.
    } BOOST_LOCAL_FUNCTION_NAME_TPL(qualified_name)
    ...
}
@endcode

Note that @RefMacro{BOOST_LOCAL_FUNCTION_TPL} must be used with this macro
instead of @RefMacro{BOOST_LOCAL_FUNCTION}.

@Note C++03 does not allow to use <c>typename</c> outside templates.
This library internally manipulates types, these operations require
<c>typename</c> but only within templates.
This macro is used to indicate to the library when the enclosing scope is a
template so the library can correctly use <c>typename</c>.

@See @RefSect{tutorial, Tutorial} section,
@RefMacro{BOOST_LOCAL_FUNCTION_NAME}, @RefMacro{BOOST_LOCAL_FUNCTION_TPL}.
*/
#define BOOST_LOCAL_FUNCTION_NAME_TPL(name)

/**
@brief This macro expands to the type of the specified bound variable.

This macro can be used within the local functions body to refer to the bound
variable types so to declare local variables, check concepts (using
Boost.ConceptCheck), etc (see the @RefSect{advanced_topics, Advanced Topics}
section).
This way the local function can be programmed entirely without explicitly
specifying the bound variable types thus facilitating maintenance (e.g., if
the type of a bound variable changes in the enclosing scope, the local function
code does not have to change).

@Params
@Param{bound_variable_name,
The name of one of the local function's bound variables.
}
@EndParams

The type returned by the macro is fully qualified in that it contains the extra
constant and reference qualifiers when the specified variable is bound by
constant and by reference.
For example, if a variable named <c>t</c> of type <c>T</c> is:
@li Bound by value using <c>bind t</c> then
<c>BOOST_LOCAL_FUNCTION_TYPEOF(t)</c> is <c>T</c>.
@li Bound by constant value using <c>const bind t</c> then
<c>BOOST_LOCAL_FUNCTION_TYPEOF(t)</c> is <c>const T</c>.
@li Bound by reference using <c>bind& t</c> then
<c>BOOST_LOCAL_FUNCTION_TYPEOF(t)</c> is <c>T&</c>.
@li Bound by constant reference using <c>const bind& t</c> then
<c>BOOST_LOCAL_FUNCTION_TYPEOF(t)</c> is <c>const T&</c>.

This macro must be prefixed by <c>typename</c> when used within templates.

@Note It is best to use this macro instead of Boost.Typeof so to reduce the
number of times Boost.Typeof is used to deduce types (see the
@RefSect{advanced_topics, Advanced Topics} section).

@See @RefSect{advanced_topics, Advanced Topics} section,
@RefMacro{BOOST_LOCAL_FUNCTION}.
*/
#define BOOST_LOCAL_FUNCTION_TYPEOF(bound_variable_name)

#endif // DOXYGEN

#endif // #include guard