Subject: [Boost-commit] svn:boost r70141 - in sandbox/local/boost: local utility
From: lorcaminiti_at_[hidden]
Date: 2011-03-18 17:41:11
Author: lcaminiti
Date: 2011-03-18 17:41:09 EDT (Fri, 18 Mar 2011)
New Revision: 70141
URL: http://svn.boost.org/trac/boost/changeset/70141
Log:
Updating docs.
Text files modified:
sandbox/local/boost/local/block.hpp | 98 +++++++++++++-----
sandbox/local/boost/local/config.hpp | 48 ++++++--
sandbox/local/boost/local/exit.hpp | 91 ++++++++++++-----
sandbox/local/boost/local/function.hpp | 205 ++++++++++++++++++++++++++++++++-------
sandbox/local/boost/local/typeof.hpp | 40 +++++++
sandbox/local/boost/utility/identity.hpp | 12 +-
6 files changed, 378 insertions(+), 116 deletions(-)
Modified: sandbox/local/boost/local/block.hpp
==============================================================================
--- sandbox/local/boost/local/block.hpp (original)
+++ sandbox/local/boost/local/block.hpp 2011-03-18 17:41:09 EDT (Fri, 18 Mar 2011)
@@ -23,53 +23,93 @@
* @brief This macro starts the declaration of a local block.
*
* This macro must be used within a declarative context, it must be followed by
- * the local block body code <c>{ ... }</c> and then by the
- * @RefMacro{CONTRACT_DETAIL_LOCAL_BLOCK_END} macro (see the Tutorial section):
+ * the local block body code and then by the @RefMacro{BOOST_LOCAL_BLOCK_END}
+ * macro (see the Tutorial section):
* @code
* { // Some declarative context.
* ...
- *
- * CONTRACT_DETAIL_LOCAL_BLOCK(
- * parenthesized_binding
- * ) exception_specifications_optional {
- * ... // Block body.
- * } CONTRACT_DETAIL_LOCAL_BLOCK_END
- *
+ * BOOST_LOCAL_BLOCK(bindings) {
+ * ... // Body code.
+ * } BOOST_LOCAL_BLOCK_END
* ...
* }
* @endcode
*
- * Within templates, the special macro
- * @RefMacro{CONTRACT_DETAIL_LOCAL_BLOCK_TPL} must be used instead of
- * @RefMacro{CONTRACT_DETAIL_LOCAL_BLOCK}.
+ * As usual, exceptions specifications can be optionally programmed before the
+ * body code block (but the specifications will only apply the body code and
+ * not to the library code automatically generated by the macro expansion,
+ * see @RefSect2{Advanced, Topics}).
+ *
+ * Within templates, the special macro @RefMacro{BOOST_LOCAL_BLOCK_TPL} must be
+ * used instead of @RefMacro{BOOST_LOCAL_BLOCK}.
*
* @Note A <c>return;</c> instruction from within a local block body jumps to
* the end of the local block body and it does not return the enclosing scope.
*
* @Params
- * @Param{parenthesized_binding,
- * A Boost.Preprocessor sequence that uses the parenthesized syntax to specify
- * the variables in scope to bind (see the Grammar section).
+ * @Param{bindings,
+ * On all C++ compilers\, the <em>sequencing macro syntax</em> defined by the
+ * following grammar is used to specify the variables in scope to bind:
+ * @code
+ * bindings:
+ * void_list | bound_list
+ * void_list:
+ * (void)
+ * bound_list:
+ * (bound_parameter1) (bound_parameter2) ...
+ * bound_parameter:
+ * [const] bind[&] variable_name
+ * @endcode
+ * Where the following lexical conventions have been used:
+ * <c>token1 | token2</c> means either <c>token1</c> or <c>token2</c>;
+ * <c>[token]</c> means either <c>token</c> or nothing (i.e.\, <c>token</c> is
+ * optional).
+ *
+ * On C99 and later compilers which support variadic macros\, the above
+ * grammar can be modified as follow to define the <em>variadic macro
+ * syntax</em> that can also be used to specify the variables in scope to
+ * bind:
+ * @code
+ * void_list:
+ * void
+ * bound_list:
+ * bound_parameter1\, bound_parameter2\, ...
+ * @endcode
+ * Note that the variadic macro syntax uses commas <c>\,</c> instead of
+ * parenthesis <c>()</c> to separate the parameters and therefore resembles
+ * the usual C++ function parameter declaration syntax more closely than the
+ * sequencing macro syntax. However\, the variadic macro syntax will only work
+ * on C++ compilers that support variadic macros so it should be used with
+ * care in order to avoid portability issues.
+ *
+ * Finally\, on C++ compilers which support empty macro parameters\, the above
+ * grammars can be modified as follow to define the <em>empty macro
+ * syntax</em> that can can also be used to specify an empty list of variables
+ * to bind:
+ * @code
+ * void_list:
+ * ()
+ * @endcode
+ * Note that the empty macro parameter syntax uses the usual C++ syntax to
+ * specify empty bound variable list but it will only work on compilers
+ * that support empty macro parameters so it should be used with care in order
+ * to avoid portability issues.
* }
* @EndParams
*
- * As usual, exception specifications can be optionally programmed before the
- * body code block (see the Advanced section).
- *
- * @See @RefSect{Tutorial} section, @RefSect{Advanced} section,
- * @RefSect{Grammar} section, @RefMacro{CONTRACT_DETAIL_LOCAL_BLOCK_TPL},
- * @RefMacro{CONTRACT_DETAIL_LOCAL_BLOCK_END}.
+ * @See @RefSect{Tutorial} section, @RefSect2{Advanced, Topics} section,
+ * @RefMacro{BOOST_LOCAL_BLOCK_TPL}, @RefMacro{BOOST_LOCAL_BLOCK_END}.
*/
-#define BOOST_LOCAL_BLOCK(binding_list) \
- BOOST_LOCAL_AUX_BLOCK(BOOST_LOCAL_FUNCTION_PARAMS, binding_list)
+#define BOOST_LOCAL_BLOCK(bindings) \
+ BOOST_LOCAL_AUX_BLOCK(BOOST_LOCAL_FUNCTION_PARAMS, bindings)
/**
- * @brief This macro is the same as @RefMacro{CONTRACT_DETAIL_LOCAL_BLOCK} but
+ * @brief This macro is the same as @RefMacro{BOOST_LOCAL_BLOCK} but
* it must be used when declaring local blocks within templates.
*
- * @See @RefMacro{CONTRACT_DETAIL_LOCAL_BLOCK}, @RefSect{Tutorial} section.
+ * @See @RefMacro{BOOST_LOCAL_BLOCK}, @RefSect{Tutorial} section.
*/
-#define BOOST_LOCAL_BLOCK_TPL(binding_list) \
- BOOST_LOCAL_AUX_BLOCK(BOOST_LOCAL_FUNCTION_PARAMS_TPL, binding_list)
+#define BOOST_LOCAL_BLOCK_TPL(bindings) \
+ BOOST_LOCAL_AUX_BLOCK(BOOST_LOCAL_FUNCTION_PARAMS_TPL, bindings)
#else // BOOST_NO_VARIADIC_MACROS
@@ -91,9 +131,9 @@
* @brief This macro ends the definition of a local block.
*
* This macro must follow the local block body code <c>{ ... }</c> as
- * shown in the @RefMacro{CONTRACT_DETAIL_LOCAL_BLOCK} documentation.
+ * shown in the @RefMacro{BOOST_LOCAL_BLOCK} documentation.
*
- * @See @RefMacro{CONTRACT_DETAIL_LOCAL_BLOCK}, @RefSect{Tutorial} section.
+ * @See @RefMacro{BOOST_LOCAL_BLOCK}, @RefSect{Tutorial} section.
*/
#define BOOST_LOCAL_BLOCK_END \
BOOST_LOCAL_AUX_BLOCK_END(__LINE__)
Modified: sandbox/local/boost/local/config.hpp
==============================================================================
--- sandbox/local/boost/local/config.hpp (original)
+++ sandbox/local/boost/local/config.hpp 2011-03-18 17:41:09 EDT (Fri, 18 Mar 2011)
@@ -13,29 +13,48 @@
#define BOOST_LOCAL_CONFIG_HPP_
/**
- * @brief Force to use C++ standard feature only.
+ * @def BOOST_LOCAL_CONFIG_COMPLIANT
+ * @brief Force to use ISO C++ standard features only.
*
- * @Note If programmers leave this macro #undefined, its default value is
- * undefined.
+ * If programmers leave this configuration macro undefined, its default
+ * value is to be left not defined.
*
* If this macro is defined, variadic macros and empty macro parameters are not
- * supported.
- * Variadic macros, are supported by most recent compilers (like MSVC and GCC)
- * and they were first introduced by the C99 preprocessor.
- * However, they are not part of the official ISO C++ standard.
+ * used by this library. Using variadic macros and empty macro parameters
+ * allows this library to provide the <em>variadic macro</em> and <em>empty
+ * macro</em> syntaxes which some programmers might find more readable than the
+ * <em>sequencing macro</em> syntax (see
+ * @RefMacro{BOOST_LOCAL_FUNCTION_PARAMS}, @RefMacro{BOOST_LOCAL_BLOCK}, and
+ * @RefMacro{BOOST_LOCAL_EXIT}). If this configuration macro is defined then
+ * only the sequencing macro syntax is allowed (regardless of whether the
+ * compiler supports variadic and empty macros or not).
+ *
+ * @Warning The variadic and empty macro syntaxes are not supported by all C++
+ * compilers so they should be used with care to avoid portability issues
+ * (and this configuration macro can be defined to disable them).
+ *
+ * Variadic macros, are supported by most recent compilers (like MSVC and
+ * GCC) and they were first introduced by the C99 standard but they are not
+ * part of the official ISO C++ standard. Empty macro parameters are also
+ * supported by the C99 standards but they are not supported by all modern
+ * compilers (for example, they are not supported by MSVC).
*
- * @See @RefSect{Tutorial} section.
+ *
+ * @See @RefSect{Tutorial} section, @RefSect2{Getting, Started} section.
*/
#ifndef BOOST_LOCAL_CONFIG_COMPLIANT
#undef BOOST_LOCAL_CONFIG_COMPLIANT
+#else
+#define BOOST_LOCAL_CONFIG_COMPLIANT
#endif
/**
+ * @def BOOST_LOCAL_CONFIG_FUNCTION_ARITY_MAX
* @brief Maximum number of function parameters supported for the local
* functions.
*
- * @Note If programmers leave this macro #undefined, its default value is
- * <c>5</c>.
+ * If programmers leave this configuration macro undefined, its default
+ * value is <c>5</c>.
*
* This only refers to the number of local function parameters and not to the
* number of bound variables in scope (the limit on the number of bound
@@ -44,25 +63,26 @@
*
* @Warning Increasing this number will increase compilation time.
*
- * @See @RefSect{Starting} section.
+ * @See @RefSect2{Getting, Starting} section.
*/
#ifndef BOOST_LOCAL_CONFIG_FUNCTION_ARITY_MAX
#define BOOST_LOCAL_CONFIG_FUNCTION_ARITY_MAX 5
#endif
/**
+ * @def BOOST_LOCAL_CONFIG_THIS_PARAM_NAME
* @brief The name of the special symbol used to access the bound object
* <c>this</c>.
*
- * @Note If programmers leave this macro #undefined, the default symbol used is
- * <c>this_</c>.
+ * If programmers leave this configuration macro undefined, the default
+ * symbol used is <c>this_</c>.
*
* @Warning Programmers should not #define this macro unless it is absolutely
* necessary (e.g., to avoid name clashes with another library which cannot be
* changed). Changing the symbol <c>this_</c> effectively changes the public
* API of this library.
*
- * @See @RefSect{Starting} section.
+ * @See @RefSect2{Getting, Started} section.
*/
#ifndef BOOST_LOCAL_CONFIG_THIS_PARAM_NAME
#define BOOST_LOCAL_CONFIG_THIS_PARAM_NAME this_
Modified: sandbox/local/boost/local/exit.hpp
==============================================================================
--- sandbox/local/boost/local/exit.hpp (original)
+++ sandbox/local/boost/local/exit.hpp 2011-03-18 17:41:09 EDT (Fri, 18 Mar 2011)
@@ -23,52 +23,91 @@
* @brief This macro starts the declaration of a local exit.
*
* This macro must be used within a declarative context, it must be followed by
- * the local exit body code <c>{ ... }</c> and then by the
- * @RefMacro{CONTRACT_DETAIL_LOCAL_EXIT_END} macro (see the @RefSect{Tutorial}
- * section):
+ * the local exit body code and then by the @RefMacro{BOOST_LOCAL_EXIT_END}
+ * macro (see the @RefSect{Tutorial} section):
* @code
* { // Some declarative context.
* ...
- *
- * CONTRACT_DETAIL_LOCAL_EXIT(
- * parenthesized_binding
- * ) exception_specifications_optional {
- * ... // Block body.
- * } CONTRACT_DETAIL_LOCAL_EXIT_END
- *
+ * BOOST_LOCAL_EXIT(bindings) {
+ * ... // Block code.
+ * } BOOST_LOCAL_EXIT_END
* ...
* }
* @endcode
*
- * Within templates, the special macro
- * @RefMacro{CONTRACT_DETAIL_LOCAL_EXIT_TPL} must be used instead of
- * @RefMacro{CONTRACT_DETAIL_LOCAL_EXIT}.
+ * As usual, exceptions specifications can be optionally programmed before the
+ * body code block (but the specifications will only apply the body code and
+ * not to the library code automatically generated by the macro expansion,
+ * see @RefSect2{Advanced, Topics}).
+ *
+ * Within templates, the special macro @RefMacro{BOOST_LOCAL_EXIT_TPL} must be
+ * used instead of @RefMacro{BOOST_LOCAL_EXIT}.
*
* @Note A <c>return;</c> instruction from within a local exit body jumps to
* the end of the local exit body and it does not return the enclosing scope.
*
* @Params
- * @Param{parenthesized_binding,
- * A Boost.Preprocessor sequence that uses the parenthesized syntax to specify
- * the variables in scope to bind (see the @RefSect{Grammar} section).
+ * @Param{bindings,
+ * On all C++ compilers\, the <em>sequencing macro syntax</em> defined by the
+ * following grammar is used to specify the variables in scope to bind:
+ * @code
+ * bindings:
+ * void_list | bound_list
+ * void_list:
+ * (void)
+ * bound_list:
+ * (bound_parameter1) (bound_parameter2) ...
+ * bound_parameter:
+ * [const] bind[&] variable_name
+ * @endcode
+ * Where the following lexical conventions have been used:
+ * <c>token1 | token2</c> means either <c>token1</c> or <c>token2</c>;
+ * <c>[token]</c> means either <c>token</c> or nothing (i.e.\, <c>token</c> is
+ * optional).
+ *
+ * On C99 and later compilers which support variadic macros\, the above
+ * grammar can be modified as follow to define the <em>variadic macro
+ * syntax</em> that can also be used to specify the variables in scope to
+ * bind:
+ * @code
+ * void_list:
+ * void
+ * bound_list:
+ * bound_parameter1\, bound_parameter2\, ...
+ * @endcode
+ * Note that the variadic macro syntax uses commas <c>\,</c> instead of
+ * parenthesis <c>()</c> to separate the parameters and therefore resembles
+ * the usual C++ function parameter declaration syntax more closely than the
+ * sequencing macro syntax. However\, the variadic macro syntax will only work
+ * on C++ compilers that support variadic macros so it should be used with
+ * care in order to avoid portability issues.
+ *
+ * Finally\, on C++ compilers which support empty macro parameters\, the above
+ * grammars can be modified as follow to define the <em>empty macro
+ * syntax</em> that can can also be used to specify an empty list of variables
+ * to bind:
+ * @code
+ * void_list:
+ * ()
+ * @endcode
+ * Note that the empty macro parameter syntax uses the usual C++ syntax to
+ * specify empty bound variable list but it will only work on compilers
+ * that support empty macro parameters so it should be used with care in order
+ * to avoid portability issues.
* }
* @EndParams
*
- * As usual, exception specifications can be optionally programmed before the
- * body code block (see the @RefSect{Advanced} section).
- *
- * @See @RefSect{Tutorial} section, @RefSect{Advanced} section,
- * @RefSect{Grammar} section, @RefMacro{CONTRACT_DETAIL_LOCAL_EXIT_TPL},
- * @RefMacro{CONTRACT_DETAIL_LOCAL_EXIT_END}.
+ * @See @RefSect{Tutorial} section, @RefSect2{Advanced, Topics} section,
+ * @RefMacro{BOOST_LOCAL_EXIT_TPL}, @RefMacro{BOOST_LOCAL_EXIT_END}.
*/
#define BOOST_LOCAL_EXIT(binding_list) \
BOOST_LOCAL_AUX_EXIT(BOOST_LOCAL_FUNCTION_PARAMS, binding_list)
/**
- * @brief This macro is the same as @RefMacro{CONTRACT_DETAIL_LOCAL_EXIT} but
+ * @brief This macro is the same as @RefMacro{BOOST_LOCAL_EXIT} but
* it must used when declaring local exits within templates.
*
- * @See @RefMacro{CONTRACT_DETAIL_LOCAL_EXIT}, @RefSect{Tutorial} section.
+ * @See @RefMacro{BOOST_LOCAL_EXIT}, @RefSect{Tutorial} section.
*/
#define BOOST_LOCAL_EXIT_TPL(binding_list) \
BOOST_LOCAL_AUX_EXIT(BOOST_LOCAL_FUNCTION_PARAMS_TPL, binding_list)
@@ -93,9 +132,9 @@
* @brief This macro ends the definition of a local exit.
*
* This macro must follow the local exit body code <c>{ ... }</c> as
- * shown in the @RefMacro{CONTRACT_DETAIL_LOCAL_EXIT} documentation.
+ * shown in the @RefMacro{BOOST_LOCAL_EXIT} documentation.
*
- * @See @RefMacro{CONTRACT_DETAIL_LOCAL_EXIT}, @RefSect{Tutorial} section.
+ * @See @RefMacro{BOOST_LOCAL_EXIT}, @RefSect{Tutorial} section.
*/
#define BOOST_LOCAL_EXIT_END \
BOOST_LOCAL_AUX_EXIT_END(__LINE__)
Modified: sandbox/local/boost/local/function.hpp
==============================================================================
--- sandbox/local/boost/local/function.hpp (original)
+++ sandbox/local/boost/local/function.hpp 2011-03-18 17:41:09 EDT (Fri, 18 Mar 2011)
@@ -5,8 +5,8 @@
// copy at http://www.boost.org/LICENSE_1_0.txt).
/** @file
- * @brief Local function references can be passed as function and template
- * parameters, they can be assigned to variables, etc.
+ * @brief Local functions allows to program functions locally within the scope
+ * where they are needed (within enclosing functions, etc).
*/
#ifndef BOOST_LOCAL_FUNCTION_HPP_
@@ -25,12 +25,113 @@
// params and nothing `` for no params.
#if defined(BOOST_NO_VARIADIC_MACROS) || defined(BOOST_LOCAL_CONFIG_COMPLIANT)
-#define BOOST_LOCAL_FUNCTION_PARAMS(parameter_list) \
- BOOST_LOCAL_AUX_FUNCTION_PARAMS(parameter_list, \
+/**
+ * @brief This macro is used to declare the local function parameters.
+ *
+ * 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} and @RefSect2{Advanced, Topics} sections):
+ * @code
+ * { // Some declarative context.
+ * ...
+ * result_type BOOST_LOCAL_FUNCTION_PARAMS(parameters) {
+ * ... // Body code.
+ * } BOOST_LOCAL_FUNCTION_NAME(name)
+ * ...
+ * }
+ * @endcode
+ *
+ * As usual, exceptions specifications can be optionally programmed before the
+ * body code block (but the specifications will only apply the body code and
+ * not to the library code automatically generated by the macro expansion,
+ * see @RefSect2{Advanced, Topics}).
+ *
+ * Within templates, the special macro
+ * @RefMacro{BOOST_LOCAL_FUNCTION_PARAMS_TPL} must be used instead of
+ * @RefMacro{BOOST_LOCAL_FUNCTION_PARAMS}.
+ *
+ * @Params
+ * @Param{parameters,
+ * On all C++ compilers\, the <em>sequencing macro syntax</em> defined by the
+ * following grammar is used to specify the local function parameters:
+ * @code
+ * parameters:
+ * void_list | parameter_list
+ * void_list:
+ * (void)
+ * parameter_list:
+ * (parameter1) (parameter2) ...
+ * parameter:
+ * normal_parameter | bound_parameter
+ * normal_parameter:
+ * [auto | register] parameter_type parameter_name
+ * [default_parameter_value]
+ * default_parameter_value:
+ * (default_value)
+ * default_value:
+ * default default_vale_expression
+ * bound_parameter:
+ * [const] bind[&] variable_name
+ * @endcode
+ * Where the following lexical conventions have been used:
+ * <c>token1 | token2</c> means either <c>token1</c> or <c>token2</c>;
+ * <c>[token]</c> means either <c>token</c> or nothing (i.e.\, <c>token</c> is
+ * optional).
+ *
+ * On C99 and later compilers which support variadic macros\, the above
+ * grammar can be modified as follow to define the <em>variadic macro
+ * syntax</em> that can also be used to specify the local functions
+ * parameters:
+ * @code
+ * void_list:
+ * void
+ * parameter_list:
+ * parameter1\, parameter2\, ...
+ * default_parameter_value:
+ * \, default_value
+ * @endcode
+ * Note that the variadic macro syntax uses commas <c>\,</c> instead of
+ * parenthesis <c>()</c> to separate the parameters and therefore resembles
+ * the usual C++ function parameter declaration syntax more closely than the
+ * sequencing macro syntax. However\, the variadic macro syntax will only work
+ * on C++ compilers that support variadic macros so it should be used with
+ * care in order to avoid portability issues.
+ *
+ * Finally\, on C++ compilers which support empty macro parameters\, the above
+ * grammars can be modified as follow to define the <em>empty macro
+ * syntax</em> that can can also be used to specify an empty parameter list:
+ * @code
+ * void_list:
+ * ()
+ * @endcode
+ * Note that the empty macro parameter syntax uses the usual C++ syntax to
+ * specify empty function parameter list but it will only work on compilers
+ * that support empty macro parameters so it should be used with care in order
+ * to avoid portability issues.
+ * }
+ * @EndParams
+ *
+ * @Note Local functions are functors. They cannot be copied but they can be
+ * assigned to other functor objects like @RefClass{boost::local::function}.
+ *
+ * @See @RefSect{Tutorial} section, @RefSect2{Advanced, Topics} section,
+ * @RefMacro{BOOST_LOCAL_FUNCTION_PARAMS_TPL},
+ * @RefMacro{BOOST_LOCAL_FUNCTION_NAME},
+ * @RefClass{boost::local::function}.
+ */
+#define BOOST_LOCAL_FUNCTION_PARAMS(parameters) \
+ BOOST_LOCAL_AUX_FUNCTION_PARAMS(parameters, \
__LINE__, 0 /* no template */)
-#define BOOST_LOCAL_FUNCTION_PARAMS_TPL(parameter_list) \
- BOOST_LOCAL_AUX_FUNCTION_PARAMS(parameter_list, \
+/**
+ * @brief This macro is the same as @RefMacro{BOOST_LOCAL_FUNCTION_PARAMS} but
+ * it must be used when declaring local functions within templates.
+ *
+ * @See @RefMacro{BOOST_LOCAL_FUNCTION_PARAMS}, @RefSect{Tutorial} section.
+ */
+#define BOOST_LOCAL_FUNCTION_PARAMS_TPL(parameters) \
+ BOOST_LOCAL_AUX_FUNCTION_PARAMS(parameters, \
__LINE__, 1 /* template */)
#else // BOOST_NO_VARIADIC_MACROS
@@ -49,19 +150,37 @@
#endif // BOOST_NO_VARIADIC_MACROS
-#define BOOST_LOCAL_FUNCTION_NAME(local_function_name) \
- BOOST_LOCAL_AUX_FUNCTION_NAME(local_function_name)
+/**
+ * @brief This macro is used to specify the local function name.
+ *
+ * This macro must follow the local function body code block <c>{ ... }</c> as
+ * shown in the @RefMacro{BOOST_LOCAL_FUNCTION_PARAMS} documentation.
+ *
+ * @Params
+ * @Param{name,
+ * The name of the local function. This 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 (i.e.\, it is not possible to
+ * overload local function declarations) -- see the @RefSect2{Advanced\,
+ * Topics} section.
+ * }
+ * @EndParams
+ *
+ * @See @RefMacro{BOOST_LOCAL_FUNCTION_PARAMS}, @RefSect{Tutorial} section,
+ * @RefSect2{Advanced, Topics} section.
+ */
+#define BOOST_LOCAL_FUNCTION_NAME(name) \
+ BOOST_LOCAL_AUX_FUNCTION_NAME(name)
namespace boost { namespace local {
/**
- * @brief Template to hold a reference to a local function while supporting
- * eventual default function parameters.
+ * @brief Functor with support for default function parameters.
*
* This template defines several specializations to handle a generic number
- * <c>N</c> of function parameters some of which can have default values.
- * The number of supported function parameters goes from <c>0</c> (for a
- * function with no parameter) to a maximum of
+ * of function parameters some of which can have default values.
+ * The number of supported function parameters <c>N</c> goes from <c>0</c> (for
+ * a function with no parameter) to a maximum of
* @RefMacro{BOOST_LOCAL_CONFIG_FUNCTION_ARITY_MAX}.
*
* Each template specialization defines call operators <c>operator()(...)</c>
@@ -69,17 +188,18 @@
* parameters specified by <c>defaults</c> (see @RefSect{Advanced} section):
* @code
* template<typename Result, typename Arg1, ..., typename ArgN, size_t defaults = 0>
- * class function_ref<Result (Arg1, ..., ArgN), defaults> {
+ * class function<Result (Arg1, ..., ArgN), defaults> {
* public:
* Result operator()(Arg1, ..., ArgN-2, ArgN-1, ArgN);
* // Call operators to handle default parameters:
- * Result operator()(Arg1, ..., ArgN-2, ArgN-1); // iff defaults >= 1
- * Result operator()(Arg1, ..., ArgN-2); // iff defaults >= 2
- * ... // etc
- *
- * // Copy constructor and assignment operator for local functions:
- * function_ref(local_function<F, defaults>& ref);
- * function_ref& operator=(local_function<F, defaults>& ref);
+ * Result operator()(Arg1, ..., ArgN-2, ArgN-1); // iff defaults >= 1
+ * Result operator()(Arg1, ..., ArgN-2); // iff defaults >= 2
+ * ... // etc
+ *
+ * // Default and copy constructors, and assignment operator.
+ * function();
+ * function(local_function_type<F, defaults> local_function);
+ * function& operator=(local_function_type<F, defaults> local_function);
* };
* @endcode
* Where:
@@ -87,30 +207,36 @@
* It can be <c>void</c>.
* - <c>ArgN</c> is the last function parameter type, <c>ArgN-1</c> is the
* second last function parameter type, etc.
- * These are all optional (none is specified for a function with no
- * parameter, only <c>Arg1</c> is specified for a function with only one
- * parameter, etc).
+ * These are all optional: None is specified for a function with no
+ * parameter; Only <c>Arg1</c> is specified for a function with only one
+ * parameter; Etc.
* - The operator <c>Result operator()(Arg1, ..., ArgN-2, ArgN-1)</c> is
- * defined if and only if there are one or more default parameters
+ * declared if and only if there are one or more default parameters
* (<c>defaults >= 1</c>), the operator
* <c>Result operator()(Arg1, ..., ArgN-2)</c> is defined if and only if
* there are two or more default parameters (<c>defaults >= 2</c>), etc.
- * - <c>local_function<F, defaults></c> is an internal type for a local
- * function with a signature matching <c>F</c> and with a number of default
- * parameters equal to <c>defaults</c>.
- * - The copy constructor and assignment operator <c>operator=</c> allow to
- * assign this template to a reference to a local function with a signature
+ * - <c>local_function_type<F, defaults></c> is an internal (i.e.,
+ * implementation specific) type for a local function with a signature
* matching <c>F</c> and with a number of default parameters equal to
* <c>defaults</c>.
+ * - The default constructor allows to constructor this functor without
+ * assigning it to any function. A run-time error is generated if the call
+ * operator <c>operator()</c> is invoked for a functor not assigned to any
+ * function.
+ * - The copy constructor and assignment operator <c>operator=</c> allow to
+ * assign this functor to a local function with a signature matching <c>F</c>
+ * and with a number of default parameters equal to <c>defaults</c>.
*
- * @Warning Programmers must make sure that the local function survives the
- * scope of the function reference (otherwise the reference will be invalid
- * and its use will generate a run-time error as usual with C++ references).
+ * @Warning Programmers must make sure that the local function assigned to this
+ * functor survives the scope of the functor (otherwise the functor will be
+ * invalid and its use will generate a run-time error as usual with C++
+ * functors).
*
* @Params
* @Param{F,
- * The function signature expressed using the Boost.Function's
- * preferred syntax: <c>F = Result (Arg1\, ...\, ArgN)</c>.
+ * The function type specifying function signature expressed using the same
+ * syntax as Boost.Function's preferred syntax:
+ * <c>F = Result (Arg1\, ...\, ArgN)</c>.
* }
* @Param{defaults,
* The number of the function default parameters in
@@ -124,12 +250,13 @@
* }
* @EndParams
*
- * @Note This template is similar to <c>boost::function<></c> but it also
- * supports eventual default parameters.
+ * @Note This functor is similar to Boost.Funciton's <c>boost::function<></c>
+ * but it also supports eventual default parameters.
*
- * @See @RefSect{Advanced} section,
+ * @See @RefSect2{Advanced, Topics} section,
* @RefMacro{BOOST_LOCAL_CONFIG_FUNCTION_ARITY_MAX},
- * @RefMacro{BOOST_LOCAL_FUNCTION},
+ * @RefMacro{BOOST_LOCAL_FUNCTION_PARAMS},
+ * @RefMacro{BOOST_LOCAL_FUNCTION_NAME},
* <a href='http://www.boost.org/doc/libs/release/doc/html/function.html'>Boost.Function</a>.
*/
template<typename F, size_t defaults = 0> // Defaults count is opt.
Modified: sandbox/local/boost/local/typeof.hpp
==============================================================================
--- sandbox/local/boost/local/typeof.hpp (original)
+++ sandbox/local/boost/local/typeof.hpp 2011-03-18 17:41:09 EDT (Fri, 18 Mar 2011)
@@ -4,6 +4,11 @@
// License, Version 1.0 (see accompanying file LICENSE_1_0.txt or a
// copy at http://www.boost.org/LICENSE_1_0.txt).
+/** @file
+ * @brief Deduce the type of variables that are bound to local functions,
+ * local blocks, and local exits.
+ */
+
#ifndef BOOST_LOCAL_TYPEOF_HPP_
#define BOOST_LOCAL_TYPEOF_HPP_
@@ -12,8 +17,39 @@
// Bound variable name. Expand to qualified bound type (i.e., bound variable
// type with extra const and/or & for const and/or reference binds).
// Can be used with local functions, blocks, and exits. It accepts `this`.
-#define BOOST_LOCAL_TYPEOF(bound_variable) \
- BOOST_LOCAL_AUX_SYMBOL_TYPEOF_TYPE(bound_variable)
+/**
+ * @brief This macro expands to the fully qualified type of a variable bound
+ * to to local functions, local blocks, and local exits.
+ *
+ * The type is fully qualified in that it contains the extra constant and
+ * reference qualifiers when they are specified for binding by constant and by
+ * reference.
+ * For example, if a variable named <c>x</c> of type <c>T</c> is:
+ * @li Bound by value using <c>bind x</c> then
+ * <c>BOOST_LOCAL_TYPEOF(x)</c> is <c>T</c>.
+ * @li Bound by constant value using <c>const bind x</c>
+ * then <c>BOOST_LOCAL_TYPEOF(x)</c> is <c>const T</c>.
+ * @li Bound by reference using <c>bind& x</c>
+ * then <c>BOOST_LOCAL_TYPEOF(x)</c> is <c>T&</c>.
+ * @li Bound by constant reference using <c>const bind& x</c>
+ * then <c>BOOST_LOCAL_TYPEOF(x)</c> is <c>const T&</c>.
+ *
+ * Within local functions, local blocks, and local exits, this macro can be
+ * used to deduce the bound variable types to declare local variables, check
+ * concepts (using Boost.ConceptCheck), etc (see @RefSect2{Advanced, Topics}
+ * section).
+ *
+ * @Params
+ * @Param{bound_variable_name,
+ * The name of the bound variable for which the type is being deduced.
+ * }
+ * @EndParams
+ *
+ * @See @RefMacro{BOOST_LOCAL_FUNCTION_PARAMS}, @RefMacro{BOOST_LOCAL_BLOCK},
+ * @RefMacro{BOOST_LOCAL_EXIT}, @RefSect2{Advanced, Topics} section.
+ */
+#define BOOST_LOCAL_TYPEOF(bound_variable_name) \
+ BOOST_LOCAL_AUX_SYMBOL_TYPEOF_TYPE(bound_variable_name)
#endif // #include guard
Modified: sandbox/local/boost/utility/identity.hpp
==============================================================================
--- sandbox/local/boost/utility/identity.hpp (original)
+++ sandbox/local/boost/utility/identity.hpp 2011-03-18 17:41:09 EDT (Fri, 18 Mar 2011)
@@ -45,7 +45,7 @@
* }
* @EndParams
*
- * @See @RefSect{Advanced} section.
+ * @See @RefSect2{Advanced, Topics} section.
*/
#define BOOST_IDENTITY_TYPE(parenthesized_type) \
/* must NOT prefix this with `::` to work with parenthesized syntax */ \
@@ -60,11 +60,11 @@
* parameter even if it contains commas and that evaluates to the specified
* value at run-time (see the @RefSect{Advanced} section).
*
- * For example <c>BOOST_IDENTITY_VALUE((key_size<int, double>::value))</c>
+ * For example <c>BOOST_IDENTITY_VALUE((key_sizeof<int, double>::value))</c>
* can be passed as a single macro parameter when instead
- * <c>key_size<int, double>::value</c> cannot (because it contains a comma not
- * wrapped by round parenthesis so it will be interpreted as two separate macro
- * parameters by the preprocessor).
+ * <c>key_sizeof<int, double>::value</c> cannot (because it contains a comma
+ * not wrapped by round parenthesis so it will be interpreted as two separate
+ * macro parameters by the preprocessor).
*
* @Params
* @Param{parenthesize_value,
@@ -74,7 +74,7 @@
* }
* @EndParams
*
- * @See @RefSect{Advanced} section.
+ * @See @RefSect2{Advanced, Topics} section.
*/
#define BOOST_IDENTITY_VALUE(parenthesized_value) \
/* must NOT prefix this with `::` to work with parenthesized syntax */ \