[Boost-commit] svn:boost r42640 - sandbox/switch/libs/switch/doc

From: steven_at_[hidden]
Date: 2008-01-09 14:26:57

Author: steven_watanabe
Date: 2008-01-09 14:26:56 EST (Wed, 09 Jan 2008)
New Revision: 42640
URL: http://svn.boost.org/trac/boost/changeset/42640

Log:
Made documentation more precise
Text files modified: 
   sandbox/switch/libs/switch/doc/Jamfile.v2 |     6 ++--                                    
   sandbox/switch/libs/switch/doc/switch.qbk |    53 +++++++++++++++++++++++++++++++++------ 
   2 files changed, 47 insertions(+), 12 deletions(-)

Modified: sandbox/switch/libs/switch/doc/Jamfile.v2
==============================================================================
--- sandbox/switch/libs/switch/doc/Jamfile.v2	(original)
+++ sandbox/switch/libs/switch/doc/Jamfile.v2	2008-01-09 14:26:56 EST (Wed, 09 Jan 2008)
@@ -7,8 +7,8 @@
 # accompanying file LICENSE_1_0.txt or copy at
 # http://www.boost.org/LICENSE_1_0.txt
 
-using quickbook ;
+import quickbook ;
 
-xml switch_ : switch.qbk ;
+using boostbook ;
 
-boostbook standalone : switch_ ;
+boostbook standalone : switch.qbk ;

Modified: sandbox/switch/libs/switch/doc/switch.qbk
==============================================================================
--- sandbox/switch/libs/switch/doc/switch.qbk	(original)
+++ sandbox/switch/libs/switch/doc/switch.qbk	2008-01-09 14:26:56 EST (Wed, 09 Jan 2008)
@@ -15,7 +15,8 @@
 The built in C/C++ switch statement is very efficient.
 Unfortunately, unlike a chained if/else construct there
 is no easy way to use it when the number of cases depends
-on a template parameter.
+on a template parameter.  This library attempts to provide
+for such usage.
 
 [endsect]
 
@@ -36,17 +37,32 @@
     #include <boost/switch.hpp>
 
 [variablelist Parameters
-    [[[^Cases]][MPL Forward Sequence of integer constants]]
-    [[[^n]][Integer]]
-    [[[^f]][Function object]]
-    [[[^default_]][Function object]]
+    [[[^Cases]][MPL Forward Sequence.  Each of the elements must have a nested integral
+        constant ::value suitable for use in a case statement]]
+    [[[^n]][Must be of a built-in integal type]]
+    [[[^f]][Unary function object.  f(T()) must be defined for every T in Cases and must
+        return a type convertible to F::result_type]]
+    [[[^default_]][Unary function object such that default_(n) returns a type convertible to the result type]]
 ]
 
-Generates a switch statement. If the value of one
+Generates a switch statement. If the nested ::value of one
 of the elements of `Cases` is equal to `n`, then this function
-will call `f` with a parameter of that type.  Otherwise
-it will pass `n` to `default_` or throw an exception depending
-on whether `default_` was specified.  For example
+will call `f` with a default constructed parameter of that type.
+Otherwise it will either pass `n` to `default_` or throw an exception
+depending on whether `default_` was specified.
+
+Thus, `switch<Cases>(n, f, default_)` is equivalent to
+
+    switch(n) {
+        case mpl::at_c<Cases, 0>::type::value: return(f(mpl::at_c<Cases, 0>::type()));
+        case mpl::at_c<Cases, 1>::type::value: return(f(mpl::at_c<Cases, 1>::type()));
+        case mpl::at_c<Cases, 2>::type::value: return(f(mpl::at_c<Cases, 2>::type()));
+        ...
+        case mpl::at_c<Cases, N>::type::value: return(f(mpl::at_c<Cases, N>::type()));
+        default: return(default_(n));
+    }
+
+For example
 
     template<class FusionSequence>
     struct print_nth_function {
@@ -107,3 +123,22 @@
 as it is the same in every translation unit.
 
 [endsect]
+
+[section:Alternatives Alternatives]
+
+Another way to achieve similar functionality is to use a map to
+function pointers or Boost.Functions.  The advantages of this
+approach are
+
+* The number of cases is only limited by memory contraints.
+* The key can be any type, not just built-in integers
+
+The disadvantages are:
+
+* The extra indirection makes it harder for the
+  compiler to optimize.
+* The table needs to be initialized somehow.  The
+  easy method of using a local static variable is not
+  thread-safe.  Making it thread-safe adds more overhead.
+
+[endsect]