Boost logo

Boost-Commit :

From: mikhailberis_at_[hidden]
Date: 2007-11-01 15:09:28


Author: mikhailberis
Date: 2007-11-01 15:09:27 EDT (Thu, 01 Nov 2007)
New Revision: 40658
URL: http://svn.boost.org/trac/boost/changeset/40658

Log:
Initial documentation in quickbook format derived almost verbatim from online documentation.
Added:
   sandbox/overload/trunk/libs/overload/docs/Jamfile.v2 (contents, props changed)
   sandbox/overload/trunk/libs/overload/docs/overload.qbk (contents, props changed)

Added: sandbox/overload/trunk/libs/overload/docs/Jamfile.v2
==============================================================================
--- (empty file)
+++ sandbox/overload/trunk/libs/overload/docs/Jamfile.v2 2007-11-01 15:09:27 EDT (Thu, 01 Nov 2007)
@@ -0,0 +1,20 @@
+project overload/docs ;
+
+import boostbook : boostbook ;
+
+using quickbook ;
+
+xml overload : overload.qbk ;
+
+boostbook standalone
+ :
+ overload
+ :
+ <xsl:param>boost.image.src=images/dispatcher.png
+ <xsl:param>boost.image.alt="Boost.Overload"
+ <xsl:param>generate.section.toc.level=3
+ <xsl:param>chunk.section.depth=2
+ <xsl:param>chunk.first.sections=1
+ <xsl:param>nav.layout=none
+ ;
+

Added: sandbox/overload/trunk/libs/overload/docs/overload.qbk
==============================================================================
--- (empty file)
+++ sandbox/overload/trunk/libs/overload/docs/overload.qbk 2007-11-01 15:09:27 EDT (Thu, 01 Nov 2007)
@@ -0,0 +1,213 @@
+[article Boost.Overload
+ [quickbook 1.4]
+ [version 0.3.0]
+ [authors [Ceccheti, Marco], [Berris, Dean Michael]]
+ [copyright 2007 Marco Ceccheti, Dean Michael Berris]
+ [purpose Multi Signature Overloaded Function Set]
+ [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])
+ ]
+ [last-revision $Date: 2007/01/11 14:07:16 $]
+]
+
+[/ Boost Overload Document Version 0.3.0 ]
+
+[section:intro Introduction]
+
+There are cases where you might want to have a function object which
+accepts different function overloads mapped to different implementations.
+There are also some cases where you have the same function object be
+able to accept different signatures so that it may be used in different
+contexts using different signatures. As of the moment, Boost.Function is
+monomorphic -- which means it can only hold one reference to a function
+conforming to just one signature.
+
+Boost.Overload is a multi-signature overloaded Boost.Function wrapper,
+which wraps multiple Boost.Function objects of different signatures as a
+single multi-signature overloaded function wrapper.
+
+[endsect]
+
+[section:overview Overview]
+
+Boost.Function already supports wrapping function objects, member
+function pointers, and function pointers in general. By itself,
+Boost.Function is already powerful and already useful enough in situations
+where you want to be able to pass around generic function objects.
+The only limitation of Boost.Function is that you can only wrap one
+function with one instance of the wrapper, and only functions or function
+objects that all have the same signatures. This becomes a problem in
+many settings where an overloaded function set is required.
+
+Boost.Overload allows this functionality of supporting multiple signatures
+by wrapping multiple Boost.Function objects in a single object that
+overloads the function operator to support the various overloads defined.
+This allows us to map many functions to a single overload instance,
+provided that these functions have a signature that the overload instance
+supports. To illustrate the usage of the Boost.Overload library, the
+following code snippet is provided:
+
+ #include <boost/overload.hpp>
+
+ int foo(int a) { return a + 1; };
+ long bar(int a, int b) { return a + b; };
+
+ int main(int argc, char * argv[]) {
+ boost::overload<int(int), long(int, int)> functions;
+ functions.set(&foo);
+ functions.set(&bar);
+
+ assert(functions(1) == 2);
+ assert(functions(2, 3) == 5L);
+ return 0;
+ }
+
+In the above example we have two functions 'foo' and 'bar', both having
+different signatures and return types. This illustrates the powerful
+features which Boost.Overload allows us to exploit: compile-time function
+argument deduction and registration, and static function dispatch using
+function overload type deduction. For a quick start you can read the
+[link tutorial1 tutorial].
+
+[endsect]
+
+[section:design Design]
+
+The library is succinctly implemented in one header file requiring only
+that Boost.Function be available. This library also requires the Boost.PP
+(Preprocessor Programming) library if in case you don't want to get the
+preprocessed header file. The library is configured by default to handle
+overloads with 10 unique signatures and can be configured to support more
+by changing the BOOST_OVERLOAD_LIMIT macro when building the application that
+uses Boost.Overload. There are a few concepts documented below which defines
+the terms and details of the implementation.
+
+[blurb `BOOST_OVERLOAD_LIMIT` by default is set to 10. This means the
+Boost.Overload template by default can handle 10 unique signatures to provide
+as function overloads.]
+
+[endsect]
+
+[section:concepts Concepts]
+
+[section:poly_objs Polymorphic Function Objects]
+
+Polymorphic Function Objects are objects which have dynamic implementations
+or overloads to the function operator. Typical Polymorphic Function Objects
+usually imply run-time polymorphism, when a reference to a base type
+instance is registered to the Overload Set -- and the actual implementation
+depends on the type of the object being referred to by the given reference.
+
+A Function Object is polymorphic if:
+
+ * The base type used to refer to the Function Object is virtual.
+
+ * The type of the Function Object referred to is derived from the base type.
+
+ * The implementation or actual behavior of the Function Object is
+ determined during run-time.
+
+The Overload Set treats a Polymorphic Function Object as a normal function
+object, and the reference to the base type is used to determine at
+run-time which actual implementation is invoked when the Overload Set is
+invoked.
+
+[endsect]
+
+[section:multi_func_obj Multi-Signature Overloaded Function Object]
+
+Multi-Signature Overloaded Function Objects are objects which have two
+or more overloads of the function operator.
+
+A Function Object is a Multi-Signature Overloaded Function Object if
+the Function Object has at least two overloads to the function operator.
+
+The Overload Set treats a Multi-Signature Overloaded Function in a
+special manner, in which it tries to match each unique function operator
+overload defined in the Multi-Signature Overloaded Function Object to the
+supported signature types. This allows multiple overloads of the function
+operator defined in the Multi-Signature Overloaded Function Object to be
+mapped to supported signatures in the Overload Set.
+
+[endsect]
+
+[section:overload_set Overload Set]
+
+An Overload Set is a Multi-Signature Overloaded Function Object which
+wraps different Boost.Function wrappers and exposes multiple overloads to
+the function operator. This allows the Overload Set to expose multiple
+function operator overloads used in turn to perform static dispatch to
+the appropriate supported Boost.Function wrapper. An Overload Set is a
+parametric type (a template) which takes N signature type arguments
+-- where N is defined as the BOOST_OVERLOAD_LIMIT, configurable at
+compile time and defaults to 10 -- to define both the signatures of
+the supported function operator overloads as well as the supported
+function object signatures it can encapsulate.
+
+An Overload Set allows the following operations: (assumes overload is
+an instance of Boost.Overload)
+
+ * overload.set(F) -- Maps a function object/pointer F to the appropriate
+ supported signature. F's signature is deduced at compile time, and the
+ static dispatch mechanism allows F to be matched to the appropriately typed
+ Boost.Function wrapper. In the case of F being a Multi-Signature Overloaded
+ Function Object, all the function operator overloads provided by F will be
+ mapped to the appropriately typed Boost.Function wrappers contained by the
+ Overload Set.
+
+ * overload.set<S>(F) -- Maps a function object/pointer F to the
+ Boost.Function object which supports the signature S.
+
+ * overload.set<N>(F) -- Maps a function object/pointer F to the N'th
+ signature supported by the Overload Set.
+
+ * overload.get<S>() -- Returns the actual Boost.Function object which
+ supports the signature S from those supported and encapsulated by the
+ Overload Set.
+
+ * overload.empty<S>() -- Returns whether the actual Boost.Function
+ object which supports the signature S is not mapped to an existing function.
+
+The Overload Set is default constructable, copyable, and swappable.
+
+[endsect]
+
+[endsect]
+
+[section:implementation Implementation]
+
+TODO: Fill this up!
+
+[endsect]
+
+[section:api_guide API Guide]
+
+TODO: Fill this up! (Use doxygen?)
+
+[endsect]
+
+[section:references References]
+
+TODO: Fill this up!
+
+[endsect]
+
+[section:acknowledgements Acknowledgements]
+
+Thanks go to Joel De Guzman for posting an implementation of a
+minimal overload implementation to the Boost C++ Developer Mailing
+List, and to Douglas Gregor for Boost.Function -- without which all
+this would not have been possible.
+
+[endsect]
+
+[section:credits Credits]
+
+Prepared by Dean Michael Berris mikhailberis_at_[hidden]
+Released under the Boost Software License version 1.0 (http://boost.org/LICENSE_1_0.txt)
+Initial Date Written: October 09, 2007
+
+[endsect]
+


Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk