If this macro is left undefined by the user, it has a default value of 5 (increasing this number might increase compilation time). When specified by the user, this macro must be a non-negative integer number.
If this macro is left undefined by the user, it has a default value of 5 (increasing this number might increase compilation time). When defined by the user, this macro must be an integer number greater or equal than 2 (because at least two distinct functions need to be specified in order to define an overload).
This function template creates and returns an overloaded_functionf1, f2, etc.
The function types are internally determined from the template parameter types so they do not need to be explicitly specified. Therefore, this function template usually has a more concise syntax when compared with overloaded_functionoverloaded_functionBOOST_AUTO (or C++11 auto) or when the overloaded function object is handled using a function template parameter, see the Tutorial section).
This function template creates and returns an overloaded_functionf1, f2, etc.
The function types are internally determined from the template parameter types so they do not need to be explicitly specified. Therefore, this function template usually has a more concise syntax when compared with overloaded_functionoverloaded_functionBOOST_AUTO, C++11 auto, or when the overloaded function object is handled using a function template parameter, see the Tutorial section).
The maximum number of functions to overload is given by the BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX
Note: In this documentation, __function_type__ is a placeholder for a symbol that is specific to implementation of this library.
Note: In this documentation, __function_type__ is a placeholder for a symbol that is specific to the implementation of this library.
See: Tutorial section, overloaded_functionBOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX
This function object aggregates together calls to functions of all the specified function types F1, F2, etc. The specified function types must have distinct parameters from one another and they must be in the following format (which is the Boost.Function preferred syntax):
result_type (argument1_type, argumgnet2_type, ...) --
In some cases, the make_overloaded_function function template can be useful to construct the overloaded function object without explicitly specifying the function types.
The maximum number of functions to overload is given by the BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX configuration macro. The maximum number of function parameters for each of the specified function types is given by the BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_ARITY_MAX configuration macro.
This function object aggregates together calls to functions of all the specified function types F1, F2, etc which must have distinct function signatures from one another.
Parameters:
+Fi |
+Each function type must be specified using the following syntax (which is Boost.Function's preferred syntax): result_type (argument1_type, argumgnet2_type, ...) + |
+
+
+In some cases, the make_overloaded_function function template can be useful to construct an overloaded function object without explicitly specifying the function types.
At least two distinct function types must be specified (because there is nothing to overload between one or zero functions). The maximum number of functions to overload is given by the BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX configuration macro. The maximum number of function parameters for each of the specified function types is given by the BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_ARITY_MAX configuration macro.
See: Tutorial section, make_overloaded_function, BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX, BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_ARITY_MAX, Boost.Function.
overloaded_function
public
construct/copy/destructoverloaded_function(const boost::function< F1 > &, - const boost::function< F2 > &, ...);Construct the overloaded function object.
Any function pointer, function reference, and monomorphic function object that can be converted to a boost::function function object can be specified as parameter.
overloaded_function(const boost::function< F1 > &, + const boost::function< F2 > &, ...);Construct the overloaded function object.
Any function pointer, function reference, and monomorphic function object that can be converted to a boost::function function object can be specified as parameter.
Note: Unfortunately, it is not possible to support polymorphic function objects (as explained here).
overloaded_function public member functionsoverloaded_function public member functionsboost::function_traits< F1 >::result_type -operator()(typename boost::function_traits< F1 >::arg1_type, +operator()(typename boost::function_traits< F1 >::arg1_type, typename boost::function_traits< F1 >::arg2_type, ...) const;Call operator matching the signature of the function type specified as 1st template parameter.
This will in turn invoke the call operator of the 1st function passed to the constructor.
boost::function_traits< F2 >::result_type -operator()(typename boost::function_traits< F2 >::arg1_type, +operator()(typename boost::function_traits< F2 >::arg1_type, typename boost::function_traits< F2 >::arg2_type, ...) const;Call operator matching the signature of the function type specified as 2nd template parameter.
This will in turn invoke the call operator of the 2nd function passed to the constructor.
Note: Similar call operators are present for all specified function types F1, F2, etc (even if not exhaustively listed by this documentation).
- The authors originally developed and tested the library on: + The authors originally developed and tested this library on:
See the library regressions
test results for detailed information on supported compilers and
- platforms.
+ platforms. Check the library regression test Jamfile.v2
+ for any special configuration that might be required for a specific compiler.
The maximum number of functions to overload is given by the BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX
configuration macro. The maximum number of function parameters for each of
- the specified function types is given by the BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_ARITY_MAX
+ the specified function type is given by the BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_ARITY_MAX
configuration macro. All configuration macros have appropriate default values
- when they are left undefined by the user.
+ when they are left undefined.
- Consider the following functions with distinct signatures: + Consider the following functions which have distinct signatures:
- [identity_decls] +
+const std::string& identity_s(const std::string& x) // Function (as pointer). + { return x; } + +int identity_i_impl(int x) { return x; } +int (&identity_i)(int) = identity_i_impl; // Function reference. + +double identity_d_impl(double x) { return x; } +boost::function<double (double)> identity_d = identity_d_impl; // Functor. ++
This library header boost/functional/overloaded_function.hpp
@@ -61,16 +71,15 @@
> identity(identity_s, identity_i, identity_d);
// All calls via single `identity` function.
-BOOST_CHECK(identity("abc") == "abc");
-BOOST_CHECK(identity(123) == 123);
-BOOST_CHECK(identity(1.23) == 1.23);
+BOOST_TEST(identity("abc") == "abc");
+BOOST_TEST(identity(123) == 123);
+BOOST_TEST(identity(1.23) == 1.23);
- Note how function types in the following format are passed as template parameters
- to boost::overloaded_function
- (this is the format of Boost.Function's
+ Note how each function type is passed as a template parameter of boost::overloaded_function using
+ the following syntax (this is Boost.Function's
preferred syntax):
result-type (argument1-type, argument2-type, ...) @@ -79,10 +88,10 @@ Then the relative function pointers, function references, or monomorphic function objects are passed to theboost::overloaded_functionconstructor matching the order of the specified template parameters. [2] In the above example,identity_s- is passed as function pointer (the function address is automatically taken - from the function name by compiler),identity_i- as function reference, andidentity_d- as function object. + is passed as a function pointer (the function address is automatically taken + from the function name by the compiler),identity_i+ as a function reference, andidentity_d+ as a function object.All specified function types must have distinct parameters from one another @@ -114,9 +123,9 @@
BOOST_AUTO(identity, boost::make_overloaded_function( identity_s, identity_i, identity_d)); -BOOST_CHECK(identity("abc") == "abc"); -BOOST_CHECK(identity(123) == 123); -BOOST_CHECK(identity(1.23) == 1.23); +BOOST_TEST(identity("abc") == "abc"); +BOOST_TEST(identity(123) == 123); +BOOST_TEST(identity(1.23) == 1.23);@@ -135,7 +144,7 @@
Another case where
@@ -143,9 +152,9 @@boost::make_overloaded_functioncan be useful is when the overloaded function object is passed to a function - template which can hide the specificboost::overloaded_function+ template which can hold the specificboost::overloaded_functiontype using a template parameter. For example (see alsomake_call.cppandidentity.hpp):template<typename F> void check(F identity) { - BOOST_CHECK(identity("abc") == "abc"); - BOOST_CHECK(identity(123) == 123); - BOOST_CHECK(identity(1.23) == 1.23); + BOOST_TEST(identity("abc") == "abc"); + BOOST_TEST(identity(123) == 123); + BOOST_TEST(identity(1.23) == 1.23); }@@ -154,6 +163,27 @@
check(boost::make_overloaded_function(identity_s, identity_i, identity_d));++
++ The library implementation of
+boost::make_overloaded_function+ uses Boost.Typeof + to automatically deduce some of the function types. In order to compile code + in Boost.Typeof + emulation mode, all types should be properly registered usingBOOST_TYPEOF_REGISTER_TYPEandBOOST_TYPEOF_REGISTER_TEMPLATE, or appropriate + Boost.Typeof headers + should be included (see Boost.Typeof + for more information). For the above examples, it is sufficient to include + the Boost.Typeof + header that registersstd::string+ (this library does not require to registerboost::function+ for Boost.Typeof + emulation): ++
+#include <boost/typeof/std/string.hpp> // No need to register `boost::function`. +@@ -171,6 +201,8 @@ pointers and function references). Finally, monomorphic function objects are instances of classes with a non-template call operator of the form
result-typeoperator()(argument1-type, ...). + Unfortunately, it is not possible to support polymorphic function objects + (see http://lists.boost.org/Archives/boost/2012/03/191744.php).[3] Note that in C++ the function result type is not used for overload resolution diff --git a/overloaded_function/doc/html/index.html b/overloaded_function/doc/html/index.html index 1ca359c..c5ac2b1 100644 --- a/overloaded_function/doc/html/index.html +++ b/overloaded_function/doc/html/index.html @@ -66,21 +66,31 @@ Introduction
- Consider the following functions with distinct signatures: + Consider the following functions which have distinct signatures:
- [identity_decls] +
+const std::string& identity_s(const std::string& x) // Function (as pointer). + { return x; } + +int identity_i_impl(int x) { return x; } +int (&identity_i)(int) = identity_i_impl; // Function reference. + +double identity_d_impl(double x) { return x; } +boost::function<double (double)> identity_d = identity_d_impl; // Functor. ++
- Instead of calling them using their separate names (here
BOOST_CHECK+ Instead of calling them using their separate names (hereBOOST_TESTis equivalent toassert): [1]-
BOOST_CHECK(identity_s("abc") == "abc"); -BOOST_CHECK(identity_i(123) == 123); -BOOST_CHECK(identity_d(1.23) == 1.23); +BOOST_TEST(identity_s("abc") == "abc"); +BOOST_TEST(identity_i(123) == 123); +BOOST_TEST(identity_d(1.23) == 1.23);@@ -100,9 +110,9 @@ > identity(identity_s, identity_i, identity_d); // All calls via single `identity` function. -BOOST_CHECK(identity("abc") == "abc"); -BOOST_CHECK(identity(123) == 123); -BOOST_CHECK(identity(1.23) == 1.23); +BOOST_TEST(identity("abc") == "abc"); +BOOST_TEST(identity(123) == 123); +BOOST_TEST(identity(1.23) == 1.23);
@@ -116,16 +126,19 @@
[1] - In the examples presented in this documentation,
BOOST_CHECK- is used instead ofassert- because it allows to write regression tests using Boost.Test. - The examples of this documentation are executed as part of the library test - suite to verify that they always compile and run correctly. + In most of the examples presented in this documentation, the Boost.Detail/LightweightTest + (boost/detail/lightweight_test.hpp) macroBOOST_TESTis used to check correctness + conditions (conceptually similar toassert). + A failure of the checked condition does not abort the execution of the program, + it will instead makeboost::report_errors+ return a non-zero program exit code. Using Boost.Detail/LightweightTest allows + to add the examples to the library regression tests so to make sure that + they always compile and run correctly.
Last revised: March 22, 2012 at 20:51:03 GMT |
+Last revised: April 10, 2012 at 20:37:20 GMT |
Overload distinct function pointers, function references, and function objects into a single function object.
+Overload distinct function pointers, function references, and monomorphic function objects into a single function object.
namespace boost { template<typename F1, typename F2, ... > class overloaded_function; template<typename F1, typename F2, ... > diff --git a/overloaded_function/doc/overloaded_function.qbk b/overloaded_function/doc/overloaded_function.qbk index 8d2bf06..5bda0df 100644 --- a/overloaded_function/doc/overloaded_function.qbk +++ b/overloaded_function/doc/overloaded_function.qbk @@ -27,6 +27,7 @@ [def __Boost_Function__ [@http://www.boost.org/libs/function Boost.Function]] [def __Boost_Typeof__ [@http://www.boost.org/doc/libs/typeof Boost.Typeof]] +[import ../test/identity.hpp] [import ../test/functor.cpp] [import ../test/make_decl.cpp] [import ../test/make_call.cpp] @@ -35,14 +36,15 @@ This library allows to overload different functions into a single function objec [section:Introduction Introduction] -Consider the following functions with distinct signatures: +Consider the following functions which have distinct signatures: [identity_decls] -Instead of calling them using their separate names (here `BOOST_CHECK` is equivalent to `assert`): +Instead of calling them using their separate names (here `BOOST_TEST` is equivalent to `assert`): [footnote -In the examples presented in this documentation, `BOOST_CHECK` is used instead of `assert` because it allows to write regression tests using __Boost_Test__. -The examples of this documentation are executed as part of the library test suite to verify that they always compile and run correctly. +In most of the examples presented in this documentation, the Boost.Detail/LightweightTest (=boost/detail/lightweight_test.hpp=) macro `BOOST_TEST` is used to check correctness conditions (conceptually similar to `assert`). +A failure of the checked condition does not abort the execution of the program, it will instead make `boost::report_errors` return a non-zero program exit code. +Using Boost.Detail/LightweightTest allows to add the examples to the library regression tests so to make sure that they always compile and run correctly. ] [identity_calls] @@ -61,12 +63,13 @@ This section explains how to setup a system to use this library. [section Compilers and Platforms] -The authors originally developed and tested the library on: +The authors originally developed and tested this library on: # GNU Compiler Collection (GCC) C++ 4.5.3 (with and without C++11 features enabled `-std=c++0x`) on Cygwin. # Miscrosoft Visual C++ (MSVC) 8.0 on Windows 7. See the library [@http://www.boost.org/development/tests/release/developer/functional-overloaded_function.html regressions test results] for detailed information on supported compilers and platforms. +Check the library regression test [@../../test/Jamfile.v2 =Jamfile.v2=] for any special configuration that might be required for a specific compiler. [endsect] @@ -77,8 +80,8 @@ Therefore there is no pre-compiled object file which needs to be installed. Programmers can simply instruct the compiler where to find the library header files (`-I` option on GCC, `/I` option on MSVC, etc) and compile code using the library. The maximum number of functions to overload is given by the [macroref BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_OVERLOAD_MAX] configuration macro. -The maximum number of function parameters for each of the specified function types is given by the [macroref BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_ARITY_MAX] configuration macro. -All configuration macros have appropriate default values when they are left undefined by the user. +The maximum number of function parameters for each of the specified function type is given by the [macroref BOOST_FUNCTIONAL_OVERLOADED_FUNCTION_CONFIG_ARITY_MAX] configuration macro. +All configuration macros have appropriate default values when they are left undefined. [endsect] @@ -90,7 +93,7 @@ This section explains how to use this library. [section Overloading] -Consider the following functions with distinct signatures: +Consider the following functions which have distinct signatures: [identity_decls] @@ -98,7 +101,7 @@ This library header [headerref boost/functional/overloaded_function.hpp] provide [identity_functor] -Note how function types in the following format are passed as template parameters to [classref boost::overloaded_function] (this is the format of __Boost_Function__'s preferred syntax): +Note how each function type is passed as a template parameter of [classref boost::overloaded_function] using the following syntax (this is __Boost_Function__'s preferred syntax): ``/result-type/`` (``/argument1-type/``, ``/argument2-type/``, ...) @@ -108,8 +111,9 @@ Function pointers are of the form [^['result-type ]]`(*)(`[^['argument1-type]]`, Function references are of the form [^['result-type ]]`(&)(`[^['argument1-type]]`, ...)`. Function types are of the form [^['result-type ]]`(`[^['argument1-type]]`, ...)` (note how they lack of both `*` and `&` when compared to function pointers and function references). Finally, monomorphic function objects are instances of classes with a non-template call operator of the form [^['result-type ]]`operator()(`[^['argument1-type]]`, ...)`. +Unfortunately, it is not possible to support polymorphic function objects (see [@http://lists.boost.org/Archives/boost/2012/03/191744.php]). ] -In the above example, `identity_s` is passed as function pointer (the function address is automatically taken from the function name by compiler), `identity_i` as function reference, and `identity_d` as function object. +In the above example, `identity_s` is passed as a function pointer (the function address is automatically taken from the function name by the compiler), `identity_i` as a function reference, and `identity_d` as a function object. All specified function types must have distinct parameters from one another (so the overloaded calls can be resolved by this library). [footnote @@ -128,17 +132,23 @@ The function types are automatically deduced from the specified functions and th The [funcref boost::make_overloaded_function] function template can be useful when used together with __Boost_Typeof__'s `BOOST_AUTO` (or C++11 `auto`). For example (see also [@../../test/make_decl.cpp =make_decl.cpp=] and [@../../test/identity.hpp =identity.hpp=]): -[identity_make] +[identity_make_decl] Note how the overloaded function object `identity` has been created specifying only the functions `identity_s`, `identity_i`, `identity_d` and without specifying the function types `const std::string& (const std::string&)`, `int (int)`, and `double (double)` as required instead by [classref boost::overloaded_function]. Therefore, [funcref boost::make_overloaded_function] provides a more concise syntax in this context when compared with [classref boost::overloaded_function]. -Another case where [funcref boost::make_overloaded_function] can be useful is when the overloaded function object is passed to a function template which can hide the specific [classref boost::overloaded_function] type using a template parameter. +Another case where [funcref boost::make_overloaded_function] can be useful is when the overloaded function object is passed to a function template which can hold the specific [classref boost::overloaded_function] type using a template parameter. For example (see also [@../../test/make_call.cpp =make_call.cpp=] and [@../../test/identity.hpp =identity.hpp=]): [identity_make_checks] [identity_make_call] +The library implementation of [funcref boost::make_overloaded_function] uses __Boost_Typeof__ to automatically deduce some of the function types. +In order to compile code in __Boost_Typeof__ emulation mode, all types should be properly registered using `BOOST_TYPEOF_REGISTER_TYPE` and `BOOST_TYPEOF_REGISTER_TEMPLATE`, or appropriate __Boost_Typeof__ headers should be included (see __Boost_Typeof__ for more information). +For the above examples, it is sufficient to include the __Boost_Typeof__ header that registers `std::string` (this library does not require to register `boost::function` for __Boost_Typeof__ emulation): + +[identity_typeof] + [endsect] [endsect] diff --git a/overloaded_function/test/identity.hpp b/overloaded_function/test/identity.hpp index 6602152..755a6da 100644 --- a/overloaded_function/test/identity.hpp +++ b/overloaded_function/test/identity.hpp @@ -9,10 +9,14 @@ #define IDENTITY_HPP_ #include+//[identity_typeof +#include // No need to register `boost::function`. +//] #include //[identity_decls -const std::string& identity_s(const std::string& x) { return x; } // As pointer. +const std::string& identity_s(const std::string& x) // Function (as pointer). + { return x; } int identity_i_impl(int x) { return x; } int (&identity_i)(int) = identity_i_impl; // Function reference. diff --git a/overloaded_function/test/make_decl.cpp b/overloaded_function/test/make_decl.cpp index 7aae187..6f5cbdf 100644 --- a/overloaded_function/test/make_decl.cpp +++ b/overloaded_function/test/make_decl.cpp @@ -7,12 +7,11 @@ #include "identity.hpp" #include -#include // For `BOOST_AUTO`. -#include // No need to register `boost::function`. +#include #include int main() { - //[identity_make + //[identity_make_decl BOOST_AUTO(identity, boost::make_overloaded_function( identity_s, identity_i, identity_d));