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]