[Boost-commit] svn:boost r76567 - in sandbox/closure/libs/functional/overloaded_function: . doc test

Subject: [Boost-commit] svn:boost r76567 - in sandbox/closure/libs/functional/overloaded_function: . doc test
From: lorcaminiti_at_[hidden]
Date: 2012-01-17 17:30:01

Author: lcaminiti
Date: 2012-01-17 17:30:00 EST (Tue, 17 Jan 2012)
New Revision: 76567
URL: http://svn.boost.org/trac/boost/changeset/76567

Log:
Overload.
Added:
   sandbox/closure/libs/functional/overloaded_function/doc/Jamfile.v2   (contents, props changed)
   sandbox/closure/libs/functional/overloaded_function/doc/overloaded_function.qbk   (contents, props changed)
   sandbox/closure/libs/functional/overloaded_function/index.html   (contents, props changed)
   sandbox/closure/libs/functional/overloaded_function/test/Jamfile.v2   (contents, props changed)
Properties modified: 
   sandbox/closure/libs/functional/overloaded_function/doc/   (props changed)

Added: sandbox/closure/libs/functional/overloaded_function/doc/Jamfile.v2
==============================================================================
--- (empty file)
+++ sandbox/closure/libs/functional/overloaded_function/doc/Jamfile.v2	2012-01-17 17:30:00 EST (Tue, 17 Jan 2012)
@@ -0,0 +1,35 @@
+
+# Copyright 2006 Alexander Nasonov.
+# 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)
+
+import quickbook ;
+using boostbook ;
+
+doxygen reference
+    :
+        ../../../../boost/functional/overloaded_function.hpp
+        ../../../../boost/functional/overloaded_function/config.hpp
+    :
+        <doxygen:param>QUIET=YES
+        <doxygen:param>WARN_IF_UNDOCUMENTED=NO
+        <doxygen:param>HIDE_UNDOC_MEMBERS=YES
+        <doxygen:param>HIDE_UNDOC_CLASSES=YES
+        <doxygen:param>ALIASES=" Params=\"<b>Parameters:</b> <table border="0">\" Param{2}=\"<tr><td><b><tt>\\1</tt></b></td><td>\\2</td></tr>\" EndParams=\"</table>\" Returns=\"<b>Returns:</b>\" Note=\"<b>Note:</b>\" Warning=\"<b>Warning:</b>\" See=\"<b>See:</b>\" RefSect{1}=\"\\xmlonly<link linkend='functional_overloaded_function.\\1'>\\1</link>\\endxmlonly\" RefSectId{2}=\"\\xmlonly<link linkend='functional_overloaded_function.\\1'>\\2</link>\\endxmlonly\" RefClass{1}=\"\\xmlonly<computeroutput><classname alt='\\1'>\\1</classname></computeroutput>\\endxmlonly\" RefFunc{1}=\"\\xmlonly<computeroutput><functionname alt='\\1'>\\1</functionname></computeroutput>\\endxmlonly\" RefMacro{1}=\"\\xmlonly<computeroutput><macroname alt='\\1'>\\1</macroname></computeroutput>\\endxmlonly\" "
+
+        # Extract Doxygen that comments non-variant macros.
+        <doxygen:param>PREDEFINED="BOOST_LOCAL_CONFIG_COMPLIANT DOXY"
+        <reftitle>"Reference"
+    ;
+
+xml functional_overloaded_function : overloaded_function.qbk :
+    <dependency>reference
+;
+
+boostbook standalone : functional_overloaded_function :
+    # Path for links to Boost:
+    <xsl:param>boost.root=../../../../..
+    <xsl:param>boost.defaults=Boost
+    <format>pdf:<xsl:param>boost.url.prefix=http://www.boost.org/doc/libs/release/libs/functional/overloaded_function/doc/html
+;
+

Added: sandbox/closure/libs/functional/overloaded_function/doc/overloaded_function.qbk
==============================================================================
--- (empty file)
+++ sandbox/closure/libs/functional/overloaded_function/doc/overloaded_function.qbk	2012-01-17 17:30:00 EST (Tue, 17 Jan 2012)
@@ -0,0 +1,143 @@
+
+[library Boost.Functional/OverloadedFunction
+    [quickbook 1.5]
+    [version 1.0.0]
+    [copyright 2012Lorenzo Caminiti]
+    [purpose overload functions]
+    [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, Lorenzo]]
+    [category Function Objects and Higher-Order Programming]
+    [id functional_overloaded_function]
+]
+
+[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_Test__ [@http://www.boost.org/doc/libs/release/libs/test/doc/html/index.html Boost.Test]]
+[def __Boost_Function__ [@http://www.boost.org/doc/libs/release/libs/function/doc/html/index.html Boost.Function]]
+[def __Boost_Typeof__ [@http://www.boost.org/doc/libs/release/doc/html/typeof.html Boost.Typeof]]
+
+[import ../test/overloaded_function.cpp]
+
+This library allows to overload function pointers, function references, and function objects into a single function object.
+
+[section:Introduction Introduction]
+
+Consider the following functions with distinct signatures:
+
+[test_overloaded_function_declarations]
+
+Instead of calling them using their separate names (`BOOST_CHECK` 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.
+]
+
+[test_overloaded_function_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/overloaded_function.cpp `"overloaded_function.cpp"`]):
+
+[test_overloaded_function]
+
+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 Getting Started]
+
+This section explains how to setup a system to use this library.
+
+[section Compilers and Platforms]
+
+The library was tested by the authors on GCC 4.5.3 (with and without C++11 features [^-std=c++0x]) and MSVC 8.0 under Linux, Cygwin, and Windows 7.
+
+[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 specified 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_OVERLOAD_MAX] configuration macro.
+All configuration macros have appropriate default values when they are left undefined by the user.
+
+[endsect]
+
+[endsect]
+
+[section:Tutorial Tutorial]
+
+This section explains how to use this library.
+
+[section Function Object]
+
+Consider the following functions with distinct signatures:
+
+[test_overloaded_function_declarations]
+
+This library provides a [classref boost::overloaded_function] class template that creates a single overloaded function object that can be used to call all the specified functions instead of using the separate function names (see also [@../../test/overloaded_function.cpp `"overloaded_function.cpp"`]):
+
+[test_overloaded_function]
+
+Note how function types in the following format (this is the format of __Boost_Function__'s preferred syntax):
+
+    result_type (argument1_type, argument2_type, ...)
+
+are passed as template parameters to the [classref boost::overloaded_function] class template.
+Then the relative function pointers, function references, or 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, ...)`.
+]
+All specified function types must be distinct from one another.
+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 Making the Function Object]
+
+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] type is returned by [funcref boost::make_overloaded_function].
+
+The [funcref boost::make_overloaded_function] function template can useful when used together with __Boost_Typeof__'s `BOOST_AUTO` (or C++11 `auto`).
+For example (see also [@../../test/overloaded_function.cpp `"overloaded_function.cpp"`]):
+
+[test_make_overloaded_function]
+
+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&)`, etc as required instead by [classref boost::overloaded_function].
+Therefore, [funcref boost::make_overloaded_function] provides a more concise syntax when compared to [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.
+For example (see also [@../../test/overloaded_function.cpp `"overloaded_function.cpp"`]):
+
+[test_make_overloaded_function_check]
+[test_make_overloaded_function_call]
+
+[endsect]
+
+[endsect]
+
+[xinclude reference.xml]
+
+[section Acknowledgments]
+
+May 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]
+

Added: sandbox/closure/libs/functional/overloaded_function/index.html
==============================================================================
--- (empty file)
+++ sandbox/closure/libs/functional/overloaded_function/index.html	2012-01-17 17:30:00 EST (Tue, 17 Jan 2012)
@@ -0,0 +1,15 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+  <head>
+    <meta http-equiv="refresh" content="0; URL=doc/html/index.html">
+  </head>
+  <body>
+    Automatic redirection failed, click this 
+    link &nbsp;<hr>
+    <p>© Copyright Lorenzo Caminiti, 2012</p>
+    <p>Distributed under the Boost Software License, Version 1.0. (See 
+    accompanying file <a href="../../../LICENSE_1_0.txt">
+    LICENSE_1_0.txt</a> or copy at
+    www.boost.org/LICENSE_1_0.txt)</p>
+  </body>
+</html>

Added: sandbox/closure/libs/functional/overloaded_function/test/Jamfile.v2
==============================================================================
--- (empty file)
+++ sandbox/closure/libs/functional/overloaded_function/test/Jamfile.v2	2012-01-17 17:30:00 EST (Tue, 17 Jan 2012)
@@ -0,0 +1,12 @@
+
+import testing ;
+
+project : requirements
+    <library>/boost//unit_test_framework
+    <link>static
+;
+
+test-suite world_tests :
+    [ run overloaded_function.cpp ]
+;
+