feedc0de/boost_functional
1
0
Fork 0
forked from boostorg/functional
Code Pull Requests Activity

Updated docs.

Browse Source 
[SVN r77899]
This commit is contained in:
Lorenzo Caminiti
2012-04-10 20:42:53 +00:00
parent 9e7ccedcfe
commit f6beb74abb
12 changed files with 175 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files
overloaded_function/doc/overloaded_function.qbk
+22 -12
View File
@@ -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]