Squashed 'third_party/boostorg/functional/' content from commit 7516442
Change-Id: I0e437294bc2af9d32de5022be6ac788cc67244d1
git-subtree-dir: third_party/boostorg/functional
git-subtree-split: 7516442815900430cc9c4a6190354e11bcbe72dd
diff --git a/overloaded_function/doc/overloaded_function.qbk b/overloaded_function/doc/overloaded_function.qbk
new file mode 100644
index 0000000..378793c
--- /dev/null
+++ b/overloaded_function/doc/overloaded_function.qbk
@@ -0,0 +1,171 @@
+
+[/ 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/functional/overloaded_function ]
+
+[library Boost.Functional/OverloadedFunction
+ [quickbook 1.5]
+ [version 1.0.0]
+ [copyright 2011-2012 Lorenzo Caminiti]
+ [purpose overload functions with one function object]
+ [license
+ Distributed under the Boost Software License, Version 1.0
+ (see accompanying file LICENSE_1_0.txt or copy at
+ [@http://www.boost.org/LICENSE_1_0.txt])
+ ]
+ [authors [Caminiti <email>lorcaminiti@gmail.com</email>, Lorenzo]]
+ [category Function Objects and Higher-Order Programming]
+]
+
+[def __Introduction__ [link functional_overloaded_function.introduction Introduction]]
+[def __Getting_Started__ [link functional_overloaded_function.getting_started Getting Started]]
+[def __Tutorial__ [link functional_overloaded_function.tutorial Tutorial]]
+[def __Boost__ [@http://www.boost.org Boost]]
+[def __Boost_Test__ [@http://www.boost.org/libs/test Boost.Test]]
+[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]
+
+This library allows to overload different functions into a single function object.
+
+[section Introduction]
+
+Consider the following functions which have distinct signatures:
+
+[identity_decls]
+
+Instead of calling them using their separate names (here `BOOST_TEST` is equivalent to `assert`):
+[footnote
+In most of the examples presented in this documentation, the Boost.Core/LightweightTest (=boost/core/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.Core/LightweightTest allows to add the examples to the library regression tests so to make sure that they always compile and run correctly.
+]
+
+[identity_calls]
+
+It is possible to use this library to create a single [@http://en.wikipedia.org/wiki/Function_overloading overloaded] function object (or [@http://en.wikipedia.org/wiki/Functor functor]) named `identity` that aggregates together the calls to the specific functions (see also [@../../test/functor.cpp =functor.cpp=] and [@../../test/identity.hpp =identity.hpp=]):
+
+[identity_functor]
+
+Note how the functions are called via a single overloaded function object `identity` instead of using their different names `identity_s`, `identity_i`, and `identity_d`.
+
+[endsect]
+
+[section Getting Started]
+
+This section explains how to setup a system to use this library.
+
+[section Compilers and Platforms]
+
+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]
+
+[section Installation]
+
+This library is composed of header files only.
+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 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]
+
+[endsect]
+
+[section Tutorial]
+
+This section explains how to use this library.
+
+[section Overloading]
+
+Consider the following functions which have distinct signatures:
+
+[identity_decls]
+
+This library header [headerref boost/functional/overloaded_function.hpp] provides a [classref boost::overloaded_function] class template that creates a single overloaded function object that can be used to call the specified functions instead of using the separate function names (see also [@../../test/functor.cpp =functor.cpp=] and [@../../test/identity.hpp =identity.hpp=]):
+
+[identity_functor]
+
+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/``, ...)
+
+Then the relative function pointers, function references, or [@http://en.wikipedia.org/wiki/Polymorphism_(computer_science) monomorphic function] objects are passed to the [classref boost::overloaded_function] constructor matching the order of the specified template parameters.
+[footnote
+Function pointers are of the form [^['result-type ]]`(*)(`[^['argument1-type]]`, ...)` (the C++ compiler is usually able to automatically promote a function name to a function pointer in a context where a function pointer is expected even if the function name is not prefixed by `&`).
+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 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
+Note that in C++ the function result type is not used for overload resolution (to avoid making the overload resolution context dependent).
+Therefore, at least one of the function parameters must be distinct for each specified function type.
+]
+In order to create an overloaded function object, it is necessary to specify at least two function types (because there is nothing to overload between one or zero functions).
+
+[endsect]
+
+[section Without Function Types]
+
+For convenience, this library also provides the [funcref boost::make_overloaded_function] function template which allows to create the overloaded function object without explicitly specifying the function types.
+The function types are automatically deduced from the specified functions and the appropriate [classref boost::overloaded_function] instantiation is returned by [funcref boost::make_overloaded_function].
+
+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_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 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]
+
+[xinclude reference.xml]
+
+[section Acknowledgments]
+
+Many thanks to Mathias Gaunard for suggesting to implement [classref boost::overloaded_function] and for some sample code.
+
+Thanks to John Bytheway for suggesting to implement [funcref boost::make_overloaded_function].
+
+Thanks to Nathan Ridge for suggestions on how to implement [funcref boost::make_overloaded_function].
+
+Thanks to Robert Stewart for commenting on the library name.
+
+Many thanks to the entire __Boost__ community and mailing list for providing valuable comments about this library and great insights on the C++ programming language.
+
+[endsect]
+