From: mrcekets_at_[hidden]
Date: 2007-11-05 09:50:43
Author: mcecchetti
Date: 2007-11-05 09:50:42 EST (Mon, 05 Nov 2007)
New Revision: 40788
URL: http://svn.boost.org/trac/boost/changeset/40788
Log:
added library tutorial in quickbook format, boostbook cascading style sheet and default images
Added:
sandbox/overload/trunk/libs/overload/docs/html/
sandbox/overload/trunk/libs/overload/docs/html/boostbook.css (contents, props changed)
sandbox/overload/trunk/libs/overload/docs/html/images/
sandbox/overload/trunk/libs/overload/docs/html/images/blank.png (contents, props changed)
sandbox/overload/trunk/libs/overload/docs/html/images/caution.png (contents, props changed)
sandbox/overload/trunk/libs/overload/docs/html/images/draft.png (contents, props changed)
sandbox/overload/trunk/libs/overload/docs/html/images/home.png (contents, props changed)
sandbox/overload/trunk/libs/overload/docs/html/images/important.png (contents, props changed)
sandbox/overload/trunk/libs/overload/docs/html/images/next.png (contents, props changed)
sandbox/overload/trunk/libs/overload/docs/html/images/next_disabled.png (contents, props changed)
sandbox/overload/trunk/libs/overload/docs/html/images/note.png (contents, props changed)
sandbox/overload/trunk/libs/overload/docs/html/images/prev.png (contents, props changed)
sandbox/overload/trunk/libs/overload/docs/html/images/prev_disabled.png (contents, props changed)
sandbox/overload/trunk/libs/overload/docs/html/images/tip.png (contents, props changed)
sandbox/overload/trunk/libs/overload/docs/html/images/toc-blank.png (contents, props changed)
sandbox/overload/trunk/libs/overload/docs/html/images/toc-minus.png (contents, props changed)
sandbox/overload/trunk/libs/overload/docs/html/images/toc-plus.png (contents, props changed)
sandbox/overload/trunk/libs/overload/docs/html/images/up.png (contents, props changed)
sandbox/overload/trunk/libs/overload/docs/html/images/up_disabled.png (contents, props changed)
sandbox/overload/trunk/libs/overload/docs/html/images/warning.png (contents, props changed)
sandbox/overload/trunk/libs/overload/docs/tutorial.qbk (contents, props changed)
Text files modified:
sandbox/overload/trunk/libs/overload/docs/overload.qbk | 88 +++++++++++++++++++++++++--------------
sandbox/overload/trunk/libs/overload/tests/Jamfile.v2 | 2
2 files changed, 57 insertions(+), 33 deletions(-)
Added: sandbox/overload/trunk/libs/overload/docs/html/boostbook.css
==============================================================================
--- (empty file)
+++ sandbox/overload/trunk/libs/overload/docs/html/boostbook.css 2007-11-05 09:50:42 EST (Mon, 05 Nov 2007)
@@ -0,0 +1,542 @@
+/*=============================================================================
+ Copyright (c) 2004 Joel de Guzman
+ http://spirit.sourceforge.net/
+
+ Distributed under the Boost Software License, Version 1.0. (See accompany-
+ ing file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+=============================================================================*/
+
+/*=============================================================================
+ Body defaults
+=============================================================================*/
+
+ body
+ {
+ margin: 1em;
+ font-family: sans-serif;
+ }
+
+/*=============================================================================
+ Paragraphs
+=============================================================================*/
+
+ p
+ {
+ text-align: left;
+ font-size: 10pt;
+ line-height: 1.15;
+ }
+
+/*=============================================================================
+ Program listings
+=============================================================================*/
+
+ /* Code on paragraphs */
+ p tt.computeroutput
+ {
+ font-size: 9pt;
+ }
+
+ pre.synopsis
+ {
+ font-size: 90%;
+ margin: 1pc 4% 0pc 4%;
+ padding: 0.5pc 0.5pc 0.5pc 0.5pc;
+ }
+
+ .programlisting,
+ .screen
+ {
+ font-size: 9pt;
+ display: block;
+ margin: 1pc 4% 0pc 4%;
+ padding: 0.5pc 0.5pc 0.5pc 0.5pc;
+ }
+
+ /* Program listings in tables don't get borders */
+ td .programlisting,
+ td .screen
+ {
+ margin: 0pc 0pc 0pc 0pc;
+ padding: 0pc 0pc 0pc 0pc;
+ }
+
+/*=============================================================================
+ Headings
+=============================================================================*/
+
+ h1, h2, h3, h4, h5, h6
+ {
+ text-align: left;
+ margin: 1em 0em 0.5em 0em;
+ font-weight: bold;
+ }
+
+ h1 { font: 140% }
+ h2 { font: bold 140% }
+ h3 { font: bold 130% }
+ h4 { font: bold 120% }
+ h5 { font: italic 110% }
+ h6 { font: italic 100% }
+
+ /* Top page titles */
+ title,
+ h1.title,
+ h2.title
+ h3.title,
+ h4.title,
+ h5.title,
+ h6.title,
+ .refentrytitle
+ {
+ font-weight: bold;
+ margin-bottom: 1pc;
+ }
+
+ h1.title { font-size: 140% }
+ h2.title { font-size: 140% }
+ h3.title { font-size: 130% }
+ h4.title { font-size: 120% }
+ h5.title { font-size: 110% }
+ h6.title { font-size: 100% }
+
+ .section h1
+ {
+ margin: 0em 0em 0.5em 0em;
+ font-size: 140%;
+ }
+
+ .section h2 { font-size: 140% }
+ .section h3 { font-size: 130% }
+ .section h4 { font-size: 120% }
+ .section h5 { font-size: 110% }
+ .section h6 { font-size: 100% }
+
+ /* Code on titles */
+ h1 tt.computeroutput { font-size: 140% }
+ h2 tt.computeroutput { font-size: 140% }
+ h3 tt.computeroutput { font-size: 130% }
+ h4 tt.computeroutput { font-size: 120% }
+ h5 tt.computeroutput { font-size: 110% }
+ h6 tt.computeroutput { font-size: 100% }
+
+/*=============================================================================
+ Author
+=============================================================================*/
+
+ h3.author
+ {
+ font-size: 100%
+ }
+
+/*=============================================================================
+ Lists
+=============================================================================*/
+
+ li
+ {
+ font-size: 10pt;
+ line-height: 1.3;
+ }
+
+ /* Unordered lists */
+ ul
+ {
+ text-align: left;
+ }
+
+ /* Ordered lists */
+ ol
+ {
+ text-align: left;
+ }
+
+/*=============================================================================
+ Links
+=============================================================================*/
+
+ a
+ {
+ text-decoration: none; /* no underline */
+ }
+
+ a:hover
+ {
+ text-decoration: underline;
+ }
+
+/*=============================================================================
+ Spirit style navigation
+=============================================================================*/
+
+ .spirit-nav
+ {
+ text-align: right;
+ }
+
+ .spirit-nav a
+ {
+ padding-left: 0.5em;
+ }
+
+ .spirit-nav img
+ {
+ border-width: 0px;
+ }
+
+/*=============================================================================
+ Table of contents
+=============================================================================*/
+
+ .toc
+ {
+ margin: 1pc 4% 0pc 4%;
+ padding: 0.1pc 1pc 0.1pc 1pc;
+ font-size: 80%;
+ line-height: 1.15;
+ }
+
+ .boost-toc
+ {
+ float: right;
+ padding: 0.5pc;
+ }
+
+/*=============================================================================
+ Tables
+=============================================================================*/
+
+ .table-title,
+ div.table p.title
+ {
+ margin-left: 4%;
+ padding-right: 0.5em;
+ padding-left: 0.5em;
+ }
+
+ .informaltable table,
+ .table table
+ {
+ width: 92%;
+ margin-left: 4%;
+ margin-right: 4%;
+ }
+
+ div.informaltable table,
+ div.table table
+ {
+ padding: 4px;
+ }
+
+ /* Table Cells */
+ div.informaltable table tr td,
+ div.table table tr td
+ {
+ padding: 0.5em;
+ text-align: left;
+ font-size: 9pt;
+ }
+
+ div.informaltable table tr th,
+ div.table table tr th
+ {
+ padding: 0.5em 0.5em 0.5em 0.5em;
+ border: 1pt solid white;
+ font-size: 80%;
+ }
+
+ table.simplelist
+ {
+ width: auto !important;
+ margin: 0em !important;
+ padding: 0em !important;
+ }
+ table.simplelist td
+ {
+ margin: 0em !important;
+ padding: 0em !important;
+ text-align: left !important;
+ font-size: 9pt !important;
+ }
+
+/*=============================================================================
+ Blurbs
+=============================================================================*/
+
+ div.note,
+ div.tip,
+ div.important,
+ div.caution,
+ div.warning,
+ p.blurb
+ {
+ font-size: 9pt; /* A little bit smaller than the main text */
+ line-height: 1.2;
+ display: block;
+ margin: 1pc 4% 0pc 4%;
+ padding: 0.5pc 0.5pc 0.5pc 0.5pc;
+ }
+
+ p.blurb img
+ {
+ padding: 1pt;
+ }
+
+/*=============================================================================
+ Variable Lists
+=============================================================================*/
+
+ /* Make the terms in definition lists bold */
+ div.variablelist dl dt,
+ span.term
+ {
+ font-weight: bold;
+ font-size: 10pt;
+ }
+
+ div.variablelist table tbody tr td
+ {
+ text-align: left;
+ vertical-align: top;
+ padding: 0em 2em 0em 0em;
+ font-size: 10pt;
+ margin: 0em 0em 0.5em 0em;
+ line-height: 1;
+ }
+
+ div.variablelist dl dt
+ {
+ margin-bottom: 0.2em;
+ }
+
+ div.variablelist dl dd
+ {
+ margin: 0em 0em 0.5em 2em;
+ font-size: 10pt;
+ }
+
+ div.variablelist table tbody tr td p,
+ div.variablelist dl dd p
+ {
+ margin: 0em 0em 0.5em 0em;
+ line-height: 1;
+ }
+
+/*=============================================================================
+ Misc
+=============================================================================*/
+
+ /* Title of books and articles in bibliographies */
+ span.title
+ {
+ font-style: italic;
+ }
+
+ span.underline
+ {
+ text-decoration: underline;
+ }
+
+ span.strikethrough
+ {
+ text-decoration: line-through;
+ }
+
+ /* Copyright, Legal Notice */
+ div div.legalnotice p
+ {
+ text-align: left
+ }
+
+/*=============================================================================
+ Colors
+=============================================================================*/
+
+ @media screen
+ {
+ /* Links */
+ a
+ {
+ color: #005a9c;
+ }
+
+ a:visited
+ {
+ color: #9c5a9c;
+ }
+
+ h1 a, h2 a, h3 a, h4 a, h5 a, h6 a,
+ h1 a:hover, h2 a:hover, h3 a:hover, h4 a:hover, h5 a:hover, h6 a:hover,
+ h1 a:visited, h2 a:visited, h3 a:visited, h4 a:visited, h5 a:visited, h6 a:visited
+ {
+ text-decoration: none; /* no underline */
+ color: #000000;
+ }
+
+ /* Syntax Highlighting */
+ .keyword { color: #0000AA; }
+ .identifier { color: #000000; }
+ .special { color: #707070; }
+ .preprocessor { color: #402080; }
+ .char { color: teal; }
+ .comment { color: #800000; }
+ .string { color: teal; }
+ .number { color: teal; }
+ .white_bkd { background-color: #FFFFFF; }
+ .dk_grey_bkd { background-color: #999999; }
+
+ /* Copyright, Legal Notice */
+ .copyright
+ {
+ color: #666666;
+ font-size: small;
+ }
+
+ div div.legalnotice p
+ {
+ color: #666666;
+ }
+
+ /* Program listing */
+ pre.synopsis
+ {
+ border: 1px solid #DCDCDC;
+ }
+
+ .programlisting,
+ .screen
+ {
+ border: 1px solid #DCDCDC;
+ }
+
+ td .programlisting,
+ td .screen
+ {
+ border: 0px solid #DCDCDC;
+ }
+
+ /* Blurbs */
+ div.note,
+ div.tip,
+ div.important,
+ div.caution,
+ div.warning,
+ p.blurb
+ {
+ border: 1px solid #DCDCDC;
+ }
+
+ /* Table of contents */
+ .toc
+ {
+ border: 1px solid #DCDCDC;
+ }
+
+ /* Tables */
+ div.informaltable table tr td,
+ div.table table tr td
+ {
+ border: 1px solid #DCDCDC;
+ }
+
+ div.informaltable table tr th,
+ div.table table tr th
+ {
+ background-color: #F0F0F0;
+ border: 1px solid #DCDCDC;
+ }
+
+ table.simplelist tr td
+ {
+ border: none !important;
+ }
+
+ /* Misc */
+ span.highlight
+ {
+ color: #00A000;
+ }
+ }
+
+ @media print
+ {
+ /* Links */
+ a
+ {
+ color: black;
+ }
+
+ a:visited
+ {
+ color: black;
+ }
+
+ .spirit-nav
+ {
+ display: none;
+ }
+
+ /* Program listing */
+ pre.synopsis
+ {
+ border: 1px solid gray;
+ }
+
+ .programlisting,
+ .screen
+ {
+ border: 1px solid gray;
+ }
+
+ td .programlisting,
+ td .screen
+ {
+ border: 0px solid #DCDCDC;
+ }
+
+ /* Table of contents */
+ .toc
+ {
+ border: 1px solid gray;
+ }
+
+ .informaltable table,
+ .table table
+ {
+ border: 1px solid gray;
+ border-collapse: collapse;
+ }
+
+ /* Tables */
+ div.informaltable table tr td,
+ div.table table tr td
+ {
+ border: 1px solid gray;
+ }
+
+ div.informaltable table tr th,
+ div.table table tr th
+ {
+ border: 1px solid gray;
+ }
+
+ table.simplelist tr td
+ {
+ border: none !important;
+ }
+
+ /* Misc */
+ span.highlight
+ {
+ font-weight: bold;
+ }
+ }
+
+/*=============================================================================
+ Images
+=============================================================================*/
+
+ span.inlinemediaobject img
+ {
+ vertical-align: middle;
+ }
\ No newline at end of file
Added: sandbox/overload/trunk/libs/overload/docs/html/images/blank.png
==============================================================================
Binary file. No diff available.
Added: sandbox/overload/trunk/libs/overload/docs/html/images/caution.png
==============================================================================
Binary file. No diff available.
Added: sandbox/overload/trunk/libs/overload/docs/html/images/draft.png
==============================================================================
Binary file. No diff available.
Added: sandbox/overload/trunk/libs/overload/docs/html/images/home.png
==============================================================================
Binary file. No diff available.
Added: sandbox/overload/trunk/libs/overload/docs/html/images/important.png
==============================================================================
Binary file. No diff available.
Added: sandbox/overload/trunk/libs/overload/docs/html/images/next.png
==============================================================================
Binary file. No diff available.
Added: sandbox/overload/trunk/libs/overload/docs/html/images/next_disabled.png
==============================================================================
Binary file. No diff available.
Added: sandbox/overload/trunk/libs/overload/docs/html/images/note.png
==============================================================================
Binary file. No diff available.
Added: sandbox/overload/trunk/libs/overload/docs/html/images/prev.png
==============================================================================
Binary file. No diff available.
Added: sandbox/overload/trunk/libs/overload/docs/html/images/prev_disabled.png
==============================================================================
Binary file. No diff available.
Added: sandbox/overload/trunk/libs/overload/docs/html/images/tip.png
==============================================================================
Binary file. No diff available.
Added: sandbox/overload/trunk/libs/overload/docs/html/images/toc-blank.png
==============================================================================
Binary file. No diff available.
Added: sandbox/overload/trunk/libs/overload/docs/html/images/toc-minus.png
==============================================================================
Binary file. No diff available.
Added: sandbox/overload/trunk/libs/overload/docs/html/images/toc-plus.png
==============================================================================
Binary file. No diff available.
Added: sandbox/overload/trunk/libs/overload/docs/html/images/up.png
==============================================================================
Binary file. No diff available.
Added: sandbox/overload/trunk/libs/overload/docs/html/images/up_disabled.png
==============================================================================
Binary file. No diff available.
Added: sandbox/overload/trunk/libs/overload/docs/html/images/warning.png
==============================================================================
Binary file. No diff available.
Modified: sandbox/overload/trunk/libs/overload/docs/overload.qbk
==============================================================================
--- sandbox/overload/trunk/libs/overload/docs/overload.qbk (original)
+++ sandbox/overload/trunk/libs/overload/docs/overload.qbk 2007-11-05 09:50:42 EST (Mon, 05 Nov 2007)
@@ -1,19 +1,34 @@
[article Boost.Overload
[quickbook 1.4]
[version 0.3.0]
- [authors [Ceccheti, Marco], [Berris, Dean Michael]]
- [copyright 2007 Marco Ceccheti, Dean Michael Berris]
+ [authors [Cecchetti, Marco], [Berris, Dean Michael]]
+ [copyright 2007 Marco Cecchetti, 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 $]
+ [last-revision $Date: 2007/11/05 15:00 $]
]
[/ Boost Overload Document Version 0.3.0 ]
+
+[def __empty_line__ \n\n ]
+
+[def __overload__ [link overload overload]]
+[def __set__ [link set set]]
+[def __set_sig__ [link set_sig set<signature> ]]
+[def __empty_sig__ [link empty_sig empty<signature_type> ]]
+[def __empty_all__ [link empty_all empty_all ]]
+[def __get_sig__ [link get_sig get<signature_type> ]]
+[def __clear_sig__ [link clear_sig clear<signature_type> ]]
+[def __clear_all__ [link clear_all clear_all ]]
+[def __swap_func__ [link swap_func swap_function ]]
+
+[warning At present Boost.Overload *IS NOT* a Boost Library ]
+
[section:intro Introduction]
There are cases where you might want to have a function object which
@@ -68,11 +83,14 @@
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].
+function overload type deduction.
[endsect]
+
+[include tutorial.qbk]
+
+
[section:design Design]
The library is succinctly implemented in one header file requiring only
@@ -84,7 +102,7 @@
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
+[note `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.]
@@ -102,13 +120,15 @@
A Function Object is polymorphic if:
- * The base type used to refer to the Function Object is virtual.
+* The base type used to refer to the Function Object is virtual.
+__empty_line__
+
+* The type of the Function Object referred to is derived from the base type.
+__empty_line__
- * 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 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
@@ -149,27 +169,31 @@
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.
-
+* 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.
+__empty_line__
+
+* overload.set<S>(F) -- Maps a function object/pointer F to the
+ Boost.Function object which supports the signature S.
+__empty_line__
+
+* overload.set<N>(F) -- Maps a function object/pointer F to the N'th
+ signature supported by the Overload Set.
+__empty_line__
+
+* overload.get<S>() -- Returns the actual Boost.Function object which
+ supports the signature S from those supported and encapsulated by the
+ Overload Set.
+__empty_line__
+
+* 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]
Added: sandbox/overload/trunk/libs/overload/docs/tutorial.qbk
==============================================================================
--- (empty file)
+++ sandbox/overload/trunk/libs/overload/docs/tutorial.qbk 2007-11-05 09:50:42 EST (Mon, 05 Nov 2007)
@@ -0,0 +1,529 @@
+
+[section:tutorial Tutorial]
+
+[section:basic_usage Basic usage]
+
+In order to instantiate a template class __overload__ you have to specify the
+required signatures as template arguments and then you can set the callable
+targets through the __set__ method which support automatic signature deduction
+of the passed argument.
+
+[:*Example 1 - Basic usage*]
+ int int_sum(int x, int y)
+ {
+ return x + y;
+ }
+
+ float float_inc(float x )
+ {
+ return x + 1.0f;
+ }
+
+ int main()
+ {
+ overload<int (int, int ), float (float )> f;
+
+ f.set(&int_sum); // here automatic signature
+ f.set(&float_inc); // deduction occurs
+
+ int r1 = f(1, 2); // calls int_sum
+ float r2 = f(3.0f); // calls float_inc
+
+ BOOST_ASSERT(r1 == 3);
+ BOOST_ASSERT(r2 == 4.0f);
+
+ return 0;
+ }
+
+[important If you try to instantiate a template class __overload__ using the
+same signature as template argument more than once you get a compile time
+error.]
+
+Even if the callable targets are set at run-time, the function call relies on
+standard C++ overload resolution: [_the right callable target is selected at
+compile time], so the run-time overhead for the call is the same that you have
+using [@http://www.boost.org/doc/html/function/misc.html#id1215718
+Boost.Function].
+
+[endsect]
+
+[section:supported_callable_entity Supported types of callable entities]
+
+You can utilize different kinds of callable entities: free functions, function
+objects, function objects wrapped with boost::ref and boost::functions.
+Moreover you have support for member functions too. Given a member function
+/mf/ of a class T, all you have to do is to specify a const or non-const
+explicit signature of T::/mf/ as a template argument of __overload__ and pass a
+pointer to the member function to the __set__ method. You'll get an overloaded
+function call operator that is able to perform a forwarding call to T::/mf/
+using any object of type T.
+
+[: *Example 2 - Using different types of callable entities*]
+
+ /* free function */
+ void foo1(std::string s1, std::string s2, std::string s3)
+ {
+ std::cout << s1 << s2 << s3 << std::endl;
+ }
+ typedef void signature1_t (std::string , std::string , std::string );
+
+ /* member function */
+ struct bar2
+ {
+ int foo2(char )
+ {
+ return 123;
+ }
+ };
+ typedef int signature2_t (bar2*, char ); // explicit non-const signature
+
+ /* free function that will be wrapped by a boost::function */
+ char bar3(std::string )
+ {
+ return 'x';
+ }
+ typedef char signature3_t (std::string );
+
+ /* class type function */
+ struct bar4
+ {
+ double operator() (int, char ) const
+ {
+ return 123.456;
+ }
+ };
+ typedef double signature4_t (int, char );
+
+ /* another class type function */
+ struct bar5
+ {
+ int operator() (char )
+ {
+ return 123;
+ }
+ };
+ typedef int signature5_t (char );
+
+
+ int main()
+ {
+ overload<signature1_t, signature2_t,
+ signature3_t, signature4_t, signature5_t> f;
+
+ /* instance that will be used for invoking the member function */
+ bar2 b2;
+ /* boost::function object that uses bar3 as callable target */
+ boost::function<signature3_t> foo3(&bar3);
+ /* function object */
+ bar4 foo4;
+ /* function object that will be wrapped with boost::ref */
+ bar5 foo5;
+
+
+ f.set(&foo1);
+ f.set(&bar2::foo2);
+ // sets the callable target of foo3 as
+ // callable target of f tied to the signature 3
+ f.set(foo3);
+ f.set(foo4);
+ f.set(boost::ref(foo5));
+
+
+ f("Hello", " ", "world !"); // calls foo1 and print "Hello world !"
+ int r2 = f(&b2, 'x'); // calls b2.foo2
+ char r3 = f("hi"); // calls bar3
+ double r4 = f(1, 'x'); // calls foo4
+ int r5 = f('x'); // calls foo5
+
+ BOOST_ASSERT(r2 == 123);
+ BOOST_ASSERT(r3 == 'x' );
+ BOOST_ASSERT(r4 > 123.455 && r4 < 123.457);
+ BOOST_ASSERT(r5 == 123);
+
+ return 0;
+ }
+
+For simplifying the setting of callable targets the __set__ method has been
+overloaded in order to support until BOOST_OVERLOAD_LIMIT arguments (defaults
+to 10), the same is true for the constructors provided by the template class
+__overload__. So in the above example we could write:
+
+ overload<signature1_t, signature2_t, signature3_t, signature4_t, signature5_t>
+ f(&bar2::foo2, &foo1, foo4, boost::ref(foo5), foo3);
+
+or:
+
+ f.set(&bar2::foo2, &foo1, foo4, boost::ref(foo5), foo3);
+
+as you can see the order of the passed arguments doesn't matter.
+
+[important If you try to set a callable entity with a signature not supported
+by the given instantiation of the template class __overload__ you get a compile
+time error.]
+
+[endsect]
+
+[section:multi_sig_func_obj Multi-signature function objects]
+
+The __set__ method can manage multi-signature function objects (i.e. function
+objects whose operator() is overloaded or is a template function) and it
+handles them in a special way. The passed function object sets/replaces all the
+existent callable targets tied to the signatures supported by both the given
+instantiation of the template class __overload__ and the passed function object
+itself.
+
+[warning Signature deduction of multi-signature function objects is not
+supported with Microsoft Visual C++ 7.1, you have to use the
+[link boost_overload.tutorial.sig_based_syntax signature based syntax] ]
+
+[: *Example 3 - Overloaded function object*]
+ char foo2(std::string )
+ {
+ return 'x';
+ }
+
+ struct bar
+ {
+ double operator() (float x)
+ {
+ return x + 1;
+ }
+
+ double operator() (float x, float y)
+ {
+ return x + y;
+ }
+ };
+
+ int main()
+ {
+ overload<char (std::string ), double (float ), double (float, float )> f;
+
+ bar foo;
+
+
+ f.set(foo); // sets foo as callable target for both the signature
+ // double (float ) and the signature double (float, float )
+
+
+ f.set(&foo2);
+
+ char r1 = f("hi");
+ double r2 = f(1.0f); // calls the double foo(float ) overload
+ double r3 = f(2.0f, 3.0f); // calls the double foo(float, float ) overload
+
+ BOOST_ASSERT(r1 == 'x');
+ BOOST_ASSERT(r2 == 2.0);
+ BOOST_ASSERT(r3 == 5.0);
+
+ return 0;
+ }
+
+[: *Example 4 - Template function object*]
+ char foo2(std::string )
+ {
+ return 'x';
+ }
+
+ struct bar
+ {
+ template<typename T>
+ T operator()(T x)
+ {
+ return x + 1;
+ }
+ };
+
+ int main()
+ {
+ overload<char (std::string ), int (int ), double (double )> f;
+
+ bar foo;
+
+ f.set(foo); // sets foo as callable target for both the signature
+ // int (int ) and the signature double (double )
+
+
+ f.set(&foo2);
+
+ char r1 = f("hi");
+ int r2 = f(1); // calls int foo(int ) template instantiation
+ double r3 = f(2.0); // calls double foo(double ) template instantiation
+
+ BOOST_ASSERT(r1 == 'x');
+ BOOST_ASSERT(r2 == 2);
+ BOOST_ASSERT(r3 == 3.0);
+
+ return 0;
+ }
+
+[tip In order to decrease the risk of run time side effects due to unexpected
+assignments it's a good practice to set multi-signature function objects first.]
+
+[endsect]
+
+[section:sig_based_syntax The signature based syntax]
+
+If you need to set a multi-signature function object as the callable target for
+only one specific supported signature you can always use the __set_sig__ method.
+Look at the following example:
+
+[: *Example 5 - Using the signature based syntax with multi-signature function objects*]
+
+ struct bar
+ {
+ template<typename T>
+ T operator()(T x)
+ {
+ return x;
+ }
+ };
+
+ int main()
+ {
+ overload<int (int ), std::string (std::string )> f;
+
+ bar foo;
+
+ f.set<int (int )>(foo); // we are using the signature syntax that sets foo
+ // as callable target for the signature int (int ) only
+
+ int r1 = f(1); // calls int foo(int ) template instantiation
+
+ /* Warning !!
+ This call produces a comiler error because there is no callable target
+ tied to the "std::string (std::string )" signature
+ std:string r2 = f( std::string("hi") );
+ */
+
+ BOOST_ASSERT(r1 == 1);
+
+ return 0;
+ }
+
+[important When you work with an instantiation of the template class
+__overload__ that supports both the non-const and the const explicit signature
+of a function member which is const qualified the __set__ method version that
+relies on signature deduction will set the given member function as callable
+target for both the signatures, however you'll get an ambiguous call error if
+you try to pass a non-const pointer to an object of the related class type. In
+this case the signature based syntax should be used to tie the member function
+to only one of the two supported explicit signatures.]
+
+[endsect]
+
+[section:helper_methods Helper Methods]
+
+There are some helper methods provided by the template class __overload__ and
+that mimic the ones offered by the boost::function template class:
+
+* we have the __empty_sig__ method that tell us if it's set a callable target
+related to the specified signature;
+__empty_line__
+
+* the __empty_all__ method that tell us if all callable targets are empty;
+__empty_line__
+
+* the __get_sig__ method return a (const) reference to the embedded object of
+type boost::function<signature_type>;
+__empty_line__
+
+* the __clear_sig__ method clears the callable target related to the specified
+signature;
+__empty_line__
+
+* the __clear_all__ method that clears all the callable targets;
+__empty_line__
+
+* finally we have the __swap_func__ method that takes only callable entities of
+type boost::function<signature_type> where signature_type has to be a
+supported signature by the given instantiation of the template class
+__overload__; its action is to swap the callable target of the passed
+boost::function<signature_type> instance with the callable target of the
+embedded boost::function<signature_type> object.
+
+[: *Example 6 - Using helper methods*]
+
+ void foo1(std::string s1, std::string s2, std::string s3)
+ {
+ std::cout << s1 << s2 << s3 << std::endl;
+ }
+ typedef void signature1_t (std::string , std::string , std::string );
+
+
+ int foo2(int x)
+ {
+ return x + 1;
+ }
+ typedef int signature2_t (int );
+
+
+ int main()
+ {
+ overload<signature1_t, signature2_t> f(&foo1, &foo2);
+
+ f("Hello", " ", "world !"); // print "Hello world !"
+
+ f.clear<signature1_t>();
+ BOOST_ASSERT( f.empty<signature1_t>() ); // f has no callable target
+ // associated with signature 1
+
+ boost::function<signature1_t> g(&foo1); // g has foo1 as callable target
+ f.swap_function(g); // after swapping f has foo1
+ // as callable target
+ f("I'm ", "back ", "again !"); // associated with signature 1
+ BOOST_ASSERT( g.empty() ); // and g has no callable target
+
+ g = f.get<signature1_t>(); // g is set to the embedded object
+ g("That's ", "all ", "folks !"); // of f with type
+ // boost::function<signature1_t>
+
+ f.clear_all(); // now f has no callable target
+ BOOST_ASSERT( f.empty_all() ); // associated to any signature
+
+ return 0;
+ }
+
+[endsect]
+
+[section:overloaded_func Non-member and member overloaded functions]
+
+In order to set a free function overload as callable target there are two
+options :
+
+[: *Example 7a - Setting a free function overload as callable target*]
+
+ int foo(int )
+ {
+ return 1;
+ }
+
+ int foo(std::string )
+ {
+ return 2;
+ }
+
+ int main()
+ {
+ overload<int (int ), int (std::string )> f;
+
+ int (*foo1) (int ) = &foo;
+ int (*foo2) (std::string ) = &foo;
+
+ f.set(foo1);
+ f.set(foo2);
+
+ BOOST_ASSERT( f(0) == 1 );
+ BOOST_ASSERT( f("hi") == 2 );
+
+ return 0;
+ }
+
+The above example shows the classic solution. The second example shows how it's
+possible to achieve the same result using the signature based syntax.
+
+[: *Example 7b - Setting a free function overload as callable target*]
+
+ int foo(int )
+ {
+ return 1;
+ }
+
+ int foo(std::string )
+ {
+ return 2;
+ }
+
+ int main()
+ {
+ overload<int (int ), int (std::string )> f;
+
+ // disambiguation through the signature based syntax
+ f.set<int (int )>(&foo);
+ f.set<int (std::string )>(&foo);
+
+ BOOST_ASSERT( f(0) == 1 );
+ BOOST_ASSERT( f("hi") == 2 );
+
+ return 0;
+ }
+
+For member function overloads you have the same options :
+
+[: *Example 8a - Setting a member function overload as callable target*]
+
+ struct bar
+ {
+ int foo(int )
+ {
+ return 1;
+ }
+
+ int foo(std::string )
+ {
+ return 2;
+ }
+ };
+
+ int main()
+ {
+ overload<int (bar*, int ), int (bar*, std::string )> f;
+
+ bar b;
+
+ int (bar::*foo1) (int ) = &bar::foo;
+ int (bar::*foo2) (std::string ) = &bar::foo;
+
+ f.set(foo1);
+ f.set(foo2);
+
+ BOOST_ASSERT( f(&b, 0) == 1 );
+ BOOST_ASSERT( f(&b, "hi") == 2 );
+
+ return 0;
+ }
+
+the above example shows the classic solution. The second example shows how it's
+possible to achieve the same result using the signature based syntax.
+
+[: *Example 8b - Setting a member function overload as callable target*]
+
+ struct bar
+ {
+ int foo(int )
+ {
+ return 1;
+ }
+
+ int foo(std::string )
+ {
+ return 2;
+ }
+ };
+
+ int main()
+ {
+ overload<int (bar*, int ), int (bar*, std::string )> f;
+
+ bar b;
+
+ // disambiguation through the signature based syntax
+ // note that you have to use the explicit signature
+ // of the related member function
+ f.set<int (bar*, int )>(&bar::foo);
+ f.set<int (bar*, std::string )>(&bar::foo);
+
+ BOOST_ASSERT( f(&b, 0) == 1 );
+ BOOST_ASSERT( f(&b, "hi") == 2 );
+
+ return 0;
+ }
+
+[important If the explicit signature supported by the instantiation of the
+template class __overload__ is the non-const qualified version, the signature
+based syntax is not able to manage the case of two member function overloads
+with the same signature that differ for the const qualifier only.]
+
+[endsect]
+
+[endsect]
Modified: sandbox/overload/trunk/libs/overload/tests/Jamfile.v2
==============================================================================
--- sandbox/overload/trunk/libs/overload/tests/Jamfile.v2 (original)
+++ sandbox/overload/trunk/libs/overload/tests/Jamfile.v2 2007-11-05 09:50:42 EST (Mon, 05 Nov 2007)
@@ -1,4 +1,4 @@
-# Copyright 2007 (c) Dean Michael Berris, Marco Ceccheti
+# Copyright 2007 (c) Dean Michael Berris, Marco Cecchetti
# Released under the Boost Software License Version 1.0
# See http://boost.org/LICENSE_1_0.txt for full license text.