[Boost-commit] svn:boost r38554 - in sandbox/math_toolkit/libs/math: doc example

From: john_at_[hidden]
Date: 2007-08-09 12:34:25

Author: johnmaddock
Date: 2007-08-09 12:34:23 EDT (Thu, 09 Aug 2007)
New Revision: 38554
URL: http://svn.boost.org/trac/boost/changeset/38554

Log:
Big proof-read of policy docs, moved all examples into separate source files, and made sure they compile etc.
Added:
   sandbox/math_toolkit/libs/math/example/policy_ref_snip1.cpp   (contents, props changed)
   sandbox/math_toolkit/libs/math/example/policy_ref_snip10.cpp   (contents, props changed)
   sandbox/math_toolkit/libs/math/example/policy_ref_snip11.cpp   (contents, props changed)
   sandbox/math_toolkit/libs/math/example/policy_ref_snip12.cpp   (contents, props changed)
   sandbox/math_toolkit/libs/math/example/policy_ref_snip13.cpp   (contents, props changed)
   sandbox/math_toolkit/libs/math/example/policy_ref_snip2.cpp   (contents, props changed)
   sandbox/math_toolkit/libs/math/example/policy_ref_snip3.cpp   (contents, props changed)
   sandbox/math_toolkit/libs/math/example/policy_ref_snip4.cpp   (contents, props changed)
   sandbox/math_toolkit/libs/math/example/policy_ref_snip5.cpp   (contents, props changed)
   sandbox/math_toolkit/libs/math/example/policy_ref_snip6.cpp   (contents, props changed)
   sandbox/math_toolkit/libs/math/example/policy_ref_snip7.cpp   (contents, props changed)
   sandbox/math_toolkit/libs/math/example/policy_ref_snip8.cpp   (contents, props changed)
   sandbox/math_toolkit/libs/math/example/policy_ref_snip9.cpp   (contents, props changed)
Text files modified: 
   sandbox/math_toolkit/libs/math/doc/Jamfile.v2                     |     8 +                                       
   sandbox/math_toolkit/libs/math/doc/policy.qbk                     |   276 ++++++++++----------------------------- 
   sandbox/math_toolkit/libs/math/doc/policy_tutorial.qbk            |    27 ++-                                     
   sandbox/math_toolkit/libs/math/example/Jamfile.v2                 |    25 +++                                     
   sandbox/math_toolkit/libs/math/example/error_handling_example.cpp |     3                                         
   sandbox/math_toolkit/libs/math/example/policy_eg_8.cpp            |     2                                         
   sandbox/math_toolkit/libs/math/example/policy_eg_9.cpp            |     6                                         
   7 files changed, 128 insertions(+), 219 deletions(-)

Modified: sandbox/math_toolkit/libs/math/doc/Jamfile.v2
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/Jamfile.v2	(original)
+++ sandbox/math_toolkit/libs/math/doc/Jamfile.v2	2007-08-09 12:34:23 EDT (Thu, 09 Aug 2007)
@@ -10,6 +10,13 @@
     :
         math
     :
+        # Path for links to Boost:
+        <xsl:param>boost.root=$(boost-root)
+        # Path for libraries index:
+        <xsl:param>boost.libraries=$(boost-root)/libs/libraries.htm
+        # Use the main Boost stylesheet:
+        <xsl:param>html.stylesheet=../../../../../../trunk/doc/html/boostbook.css
+
         # HTML options first:
         # Use graphics not text for navigation:
         <xsl:param>navig.graphics=1
@@ -48,4 +55,3 @@
 
 
 
-

Modified: sandbox/math_toolkit/libs/math/doc/policy.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/policy.qbk	(original)
+++ sandbox/math_toolkit/libs/math/doc/policy.qbk	2007-08-09 12:34:23 EDT (Thu, 09 Aug 2007)
@@ -3,7 +3,9 @@
 [section:pol_overview Policy Overview]
 
 Policies are a powerful fine-grain mechanism that allow you to customise the
-behaviour of this library according to your needs.
+behaviour of this library according to your needs.  There is more information
+available in the [link math_toolkit.policy.pol_tutorial policy tutorial] 
+and the [link math_toolkit.policy.pol_ref policy reference].
 
 Unless you find that the default policy behaviour
 when encountering 'bad' argument values does not meet your needs,
@@ -23,7 +25,7 @@
 * How [link math_toolkit.policy.pol_ref.internal_promotion accuracy is controlled by internal promotion] to use more precise types.
 * What working [link math_toolkit.policy.pol_ref.precision_pol precision] should be used to calculate results.
 * What do to when a [link math_toolkit.policy.pol_ref.assert_undefined mathematically undefined function]
-  is used. Compile or not?
+  is used:  Should this raise a run-time or compile-time error?
 * Whether [link math_toolkit.policy.pol_ref.discrete_quant_ref discrete functions],
   like the binomial, should return real or only integral values, and how they are rounded.
   
@@ -31,6 +33,9 @@
 
 * Using [link math_toolkit.policy.pol_ref.policy_defaults macros] to change any default policy.
 * At your chosen [link math_toolkit.policy.pol_ref.namespace_pol namespace scope] for distributions and/or functions.
+* In an ad-hoc manner [link math_toolkit.policy.pol_tutorial.ad_hoc_sf_policies 
+by passing a specific policy to a special function], or to a 
+[link math_toolkit.policy.pol_tutorial.ad_hoc_dist_policies statistical distribution].
 
 [endsect][/section:pol_overview Policy Overview]
 
@@ -112,6 +117,8 @@
 in boost/math/policies/error_handling.hpp, but the actual definitions
 must be provided by the user:
 
+   namespace boost{ namespace math{ namespace policies{
+   
    template <class T>
    T user_domain_error(const char* function, const char* message, const T& val);
    
@@ -129,13 +136,20 @@
    
    template <class T>
    T user_evaluation_error(const char* function, const char* message, const T& val);
+   
+   }}} // namespaces
 
-Note that the strings ['function] and ['message] contain "%1%" format specifiers
+Note that the strings ['function] and ['message] may contain "%1%" format specifiers
 designed to be used in conjunction with Boost.Format.  
 If these strings are to be presented to the program's end-user then 
 the "%1%" format specifier
-should be replaced with the name of type T in the ['function] string, and the
-specifier in the ['message] string should be replaced with the value of ['val].
+should be replaced with the name of type T in the ['function] string, and 
+if there is a %1% specifier in the ['message] string then it 
+should be replaced with the value of ['val].
+
+There is more information on user-defined error handlers in
+the [link math_toolkit.policy.pol_tutorial.user_defined_error_policies 
+tutorial here].
 
 [h4 Kinds of Error Raised]                  
 
@@ -208,48 +222,16 @@
 `::errno` rather than throw an exception, we can achieve this at the call site
 using:
 
-   #include <boost/math/special_functions/gamma.hpp>
-   
-   using namespace boost::math::policies;
-   using namespace boost::math;
-   
-   // Define a policy:
-   typedef policy<
-         domain_error<errno_on_error>, 
-         pole_error<errno_on_error>,
-         overflow_error<errno_on_error>,
-         evaluation_error<errno_on_error> 
-         > my_policy;
-         
-   // call the function:
-   double t = tgamma(some_value, my_policy());
-   
-   // Alternatively we could use make_policy and define everything at the call site:
-   t = tgamma(some_value, make_policy(
-            domain_error<errno_on_error>(), 
-            pole_error<errno_on_error>(),
-            overflow_error<errno_on_error>(),
-            evaluation_error<errno_on_error>() 
-         ));
+[import ../example/policy_ref_snip1.cpp]
+
+[policy_ref_snip1]
    
 Suppose we want a statistical distribution to return infinities,
 rather than throw exceptions, then we can use:
 
-   #include <boost/math/distributions/normal.hpp>
-   
-   using namespace boost::math::policies;
-   using namespace boost::math;
-   
-   // Define a policy:
-   typedef policy<
-         overflow_error<ignore_error>
-         > my_policy;
-         
-   // Define the distribution:
-   typedef normal_distribution<double, my_policy> my_norm;
-   
-   // Get a quantile:
-   double q = quantile(my_norm(), 0.05);
+[import ../example/policy_ref_snip2.cpp]
+
+[policy_ref_snip2]
 
 [endsect][/section:error_handling_policies Error Handling Policies]
 
@@ -275,40 +257,16 @@
 Suppose we want `tgamma` to be evaluated without internal promotion to
 `long double`, then we could use:
 
-   #include <boost/math/special_functions/gamma.hpp>
-   
-   using namespace boost::math::policies;
-   using namespace boost::math;
-   
-   // Define a policy:
-   typedef policy<
-         promote_double<false> 
-         > my_policy;
-         
-   // Call the function:
-   double t = tgamma(some_value, my_policy());
-   
-   // Alternatively we could use make_policy and define everything at the call site:
-   t = tgamma(some_value, make_policy(promote_double<false>()));
+[import policy_ref_snip3]
+
+[policy_ref_snip3]
    
 Alternatively, suppose we want a distribution to perform calculations
 without promoting `float` to `double`, then we could use:
 
-   #include <boost/math/distributions/normal.hpp>
-   
-   using namespace boost::math::policies;
-   using namespace boost::math;
-   
-   // Define a policy:
-   typedef policy<
-         promote_float<false>
-         > my_policy;
-         
-   // Define the distribution:
-   typedef normal_distribution<float, my_policy> my_norm;
-   
-   // Get a quantile:
-   float q = quantile(my_norm(), 0.05f);
+[import ../example/policy_ref_snip4.cpp]
+
+[policy_ref_snip4]
    
 [endsect][/section:internal_promotion Internal Promotion Policies]
 
@@ -386,22 +344,9 @@
 Ignores the discreteness of the distribution, and returns a real-valued 
 result.  For example:
 
-   #include <boost/math/distributions/negative_binomial.hpp>
-   
-   using namespace boost::math;
-   using namespace boost::math::policies;
-   
-   typedef negative_binomial_distribution<
-         double, 
-         policy<discrete_quantile<integer_inside> > 
-      > dist_type;
-      
-   double x, y;
-   
-   // Lower quantile:
-   x = quantile(dist_type(20, 0.3), 0.05);
-   // Upper quantile:
-   y = quantile(complement(dist_type(20, 0.3), 0.05));
+[import ../example/policy_ref_snip5.cpp]
+
+[policy_ref_snip5]
    
 Results in `x = 27.3898` and `y = 68.1584`.
 
@@ -417,16 +362,9 @@
 one and two sided intervals are guaranteed to have ['at least] 
 the requested coverage.  For example:
 
-   #include <boost/math/distributions/negative_binomial.hpp>
-   
-   using namespace boost::math;
-   
-   double x, y;
-   
-   // Lower quantile rounded down:
-   x = quantile(negative_binomial(20), 0.05);
-   // Upper quantile rounded up:
-   y = quantile(complement(negative_binomial(20), 0.05));
+[import ../example/policy_ref_snip6.cpp]
+
+[policy_ref_snip6]
    
 Results in `x = 27` (rounded down from 27.3898) and `y = 69` (rounded up from 68.1584).
 
@@ -448,22 +386,9 @@
 
 For example:
 
-   #include <boost/math/distributions/negative_binomial.hpp>
-   
-   using namespace boost::math;
-   using namespace boost::math::policies;
-   
-   typedef negative_binomial_distribution<
-         double, 
-         policy<discrete_quantile<integer_inside> > 
-      > dist_type;
-      
-   double x, y;
-   
-   // Lower quantile rounded up:
-   x = quantile(dist_type(20), 0.05);
-   // Upper quantile rounded down:
-   y = quantile(complement(dist_type(20), 0.05));
+[import ../example/policy_ref_snip7.cpp]
+
+[policy_ref_snip7]
    
 Results in `x = 28` (rounded up from 27.3898) and `y = 68` (rounded down from 68.1584).
 
@@ -495,22 +420,9 @@
 
 For example:
 
-   #include <boost/math/distributions/negative_binomial.hpp>
-   
-   using namespace boost::math;
-   using namespace boost::math::policies;
-   
-   typedef negative_binomial_distribution<
-         double, 
-         policy<discrete_quantile<integer_nearest> > 
-      > dist_type;
-      
-   double x, y;
-   
-   // Lower quantile rounded up:
-   x = quantile(dist_type(20), 0.05);
-   // Upper quantile rounded down:
-   y = quantile(complement(dist_type(20), 0.05));
+[import ../example/policy_ref_snip8.cpp]
+
+[policy_ref_snip8]
 
 Results in `x = 27` (rounded from 27.3898) and `y = 68` (rounded from 68.1584).
 
@@ -544,34 +456,21 @@
 
 For example we could calculate `tgamma` to approximately 5 decimal digits using:
 
-   #include <boost/math/special_functions/gamma.hpp>
-   
-   using namespace boost::math;
-   using namespace boost::math::policies;
-   
-   typedef policy<digits10<5> > pol;
-   
-   double t = tgamma(12, pol());
+[import ../example/policy_ref_snip9.cpp]
+
+[policy_ref_snip9]
    
 Or again using ['make_policy]:
 
-   #include <boost/math/special_functions/gamma.hpp>
-   
-   using namespace boost::math;
-   using namespace boost::math::policies;
-   
-   double t = tgamma(12, policy<digits10<5> >());
+[import ../example/policy_ref_snip10.cpp]
+
+[policy_ref_snip10]
 
 And for a quantile of a distribution to approximately 25-bit precision:
 
-   #include <boost/math/distributions/normal.hpp>
-   
-   using namespace boost::math;
-   using namespace boost::math::policies;
-   
-   double q = quantile(
-         normal_distribution<double, policy<digits2<25> >(), 
-         0.05);
+[import ../example/policy_ref_snip11.cpp]
+
+[policy_ref_snip11]
 
 [endsect][/section:precision_pol Precision Policies]
 
@@ -582,18 +481,18 @@
 You can make a local change by placing a macro definition *before*
 a function or distribution #include.
 
-[caution If you place it after the #include it will have no effect,
-(and it will affect only any other following #includes).
-This is probably not what you intend!]
-
 [caution There is a danger of One-Definition-Rule violations if you 
 add ad-hock macros to more than one source files: these must be set the same in *every 
 translation unit*.]
 
+[caution If you place it after the #include it will have no effect,
+(and it will affect only any other following #includes).
+This is probably not what you intend!]
+
 If you want to alter the defaults for any or all of 
 the policies for *all* functions and distributions, installation-wide,
 then you can do so by defining various macros in
-boost/math/tools/user.hpp.
+[@../../../../boost/math/tools/user.hpp boost/math/tools/user.hpp].
 
 [h5 BOOST_MATH_DOMAIN_ERROR_POLICY]
 
@@ -714,25 +613,9 @@
 You can use either of these macros after including any special function
 or distribution header.  For example:
 
-   #include <boost/math/special_functions/gamma.hpp>
-   
-   namespace myspace{
-   
-   using namespace boost::math::policies;
-   
-   // Define a policy that does not throw on overflow:
-   typedef policy<overflow_error<errno_on_error> > my_policy;
+[import ../example/policy_ref_snip12.cpp]
 
-   // Define the special functions in this scope to use the policy:   
-   BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS(my_policy)
-   
-   }
-   
-   //
-   // Now we can use myspace::tgamma etc.
-   // They will automatically use "my_policy":
-   //
-   double t = myspace::tgamma(30.0); // will not throw on overflow
+[policy_ref_snip12]
 
 In this example, using BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS results in
 a set of thin inline forwarding functions being defined:
@@ -743,35 +626,18 @@
    template <class T>
    inline T lgamma(T a) ( return ::boost::math::lgamma(a, mypolicy()); }
    
-and so on.  Note that a forwarding function is defined for all the special
+and so on.  Note that while a forwarding function is defined for all the special
 functions, however, unless you include the specific header for the special
-function you use (or boost/math/special_functions.hpp), you will get 
-linker errors from undefined functions.
+function you use (or boost/math/special_functions.hpp to include everything), 
+you will get linker errors from functions that are forward declared, but not
+defined.
 
 We can do the same thing with the distributions, but this time we need to
 specify the floating-point type to use:
 
-   #include <boost/math/distributions/cauchy.hpp>
-   
-   namespace myspace{
-   
-   using namespace boost::math::policies;
-   
-   // Define a policy to use, in this case we want all the distribution
-   // accessor functions to compile, even if they are mathematically
-   // undefined:
-   typedef policy<assert_undefined<false> > my_policy;
-   
-   BOOST_MATH_DECLARE_DISTRIBUTIONS(double, my_policy)
-   
-   }
-   
-   // Now we can use myspace::cauchy etc, which will use policy
-   // myspace::mypolicy:
-   //
-   // This compiles but raises a domain error at runtime:
-   //
-   double d = mean(myspace::cauchy()); 
+[import ../example/policy_ref_snip13.cpp]
+
+[policy_ref_snip13]
    
 In this example the result of BOOST_MATH_DECLARE_DISTRIBUTIONS is to
 declare a typedef for each distribution like this:
@@ -942,7 +808,15 @@
 `policy` class into a normalised form.  This is used internally
 to reduce code bloat: so that instantiating a special function
 on `policy<A,B>` or `policy<B,A>` actually both generate the same
-code internally.
+code internally.  
+
+Further more, `normalise` can be used to combine
+a policy with one or more policies: for example many of the
+special functions will use this to set policies which they don't
+make use of to their default values, before forwarding to the actual
+implementation.  In this way code bloat is reduced, since the
+actual implementation depends only on the policy types that they
+actually use.
 
 [endsect][/section:pol_ref_ref Policy Class Reference]
 

Modified: sandbox/math_toolkit/libs/math/doc/policy_tutorial.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/policy_tutorial.qbk	(original)
+++ sandbox/math_toolkit/libs/math/doc/policy_tutorial.qbk	2007-08-09 12:34:23 EDT (Thu, 09 Aug 2007)
@@ -21,7 +21,7 @@
 
 For this reason a Policy is a /type/: in fact it's an instance of the 
 class template `boost::math::policies::policy<>`.  This class is just a 
-compile-time-container of user-defined policies (sometimes called a type-list):
+compile-time-container of user-selected policies (sometimes called a type-list):
 
    using namespace boost::math::policies;
    //
@@ -43,7 +43,7 @@
 [[Pole Error][Occurs when a function is evaluated at a pole: throws a `std::domain_error` exception.]]
 [[Overflow Error][Throws a `std::overflow_error` exception.]]
 [[Underflow][Ignores the underflow, and returns zero.]]
-[[Denormalised Result][Ignores the fact that the result is denormalised, and returns it]]
+[[Denormalised Result][Ignores the fact that the result is denormalised, and returns it.]]
 [[Internal Evaluation Error][Throws a `boost::math::evaluation_error` exception.]]
 [[Promotion of float to double][Does occur by default - gives full float precision results.]]
 [[Promotion of double to long double][Does occur by default if long double offers
@@ -73,16 +73,16 @@
 
 The details follow later, but basically policies can be set by either:
 
-* Defining some macros that change the default behaviour: this is the 
-   recommended method for setting installation-wide policies.
+* Defining some macros that change the default behaviour: [*this is the 
+   recommended method for setting installation-wide policies].
 * By instantiating a distribution object with an explicit policy:
    this is mainly reserved for ad hoc policy changes.
 * By passing a policy to a special function as an optional final argument:
    this is mainly reserved for ad hoc policy changes.
 * By using some helper macros to define a set of functions or distributions
-in the current namespace that use a specific policy: this is the
+in the current namespace that use a specific policy: [*this is the
 recommended method for setting policies on a project- or translation-unit-wide
-basis.
+basis].
 
 The following sections introduce these methods in more detail.
 
@@ -121,7 +121,7 @@
 
 And, yes, you will find examples in our test programs where we break this
 rule: but only because we know there will always be a single
-translation unit only: don't say that you weren't warned!
+translation unit only: ['don't say that you weren't warned!]
 
 [import ../example/error_handling_example.cpp]
 
@@ -144,7 +144,9 @@
    
    }}
    
-So if you use the shorthand-typedef for the distribution, then you get
+This policy gets used by all the accessor functions that accept
+a distribution as an argument, and forwarded to all the functions called
+by these.  So if you use the shorthand-typedef for the distribution, then you get
 `double` precision arithmetic and all the default policies.
 
 However, say for example we wanted to evaluate the quantile
@@ -197,7 +199,7 @@
 
 [policy_eg_1]
 
-that outputs:
+which outputs:
 
 [pre 
 Result of tgamma(30000) is: 1.#INF
@@ -261,6 +263,13 @@
 
 [policy_eg_6]
 
+[note
+There is an important limitation to note: you can not use the macros
+BOOST_MATH_DECLARE_DISTRIBUTIONS and BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS
+['in the same namespace],  as doing so creates ambiguities between functions
+and distributions of the same name.
+]
+
 As before, the same mechanism works well at file scope as well: by using an unnamed 
 namespace, we can ensure that these declarations don't conflict with any
 alternate policies present in other translation units:

Modified: sandbox/math_toolkit/libs/math/example/Jamfile.v2
==============================================================================
--- sandbox/math_toolkit/libs/math/example/Jamfile.v2	(original)
+++ sandbox/math_toolkit/libs/math/example/Jamfile.v2	2007-08-09 12:34:23 EDT (Thu, 09 Aug 2007)
@@ -24,17 +24,17 @@
       <include>../../..
     ;
 
-run C_error_policy_example.cpp ;
-run Neg_binomial_confidence_limits.cpp ;
 run binomial_confidence_limits.cpp ;
 run binomial_example3.cpp ;
 run binomial_sample_sizes.cpp ;
+run c_error_policy_example.cpp ;
 run chi_square_std_dev_test.cpp ;
 run distribution_construction.cpp ;
 run error_handling_example.cpp ;
 run error_policies_example.cpp ;
 run error_policy_example.cpp ;
 run f_test.cpp ;
+run neg_binomial_confidence_limits.cpp ;
 run neg_binomial_sample_sizes.cpp ;
 run negative_binomial_construction_examples.cpp ;
 run negative_binomial_example1.cpp ;
@@ -45,10 +45,29 @@
 run policy_eg_3.cpp ;
 run policy_eg_4.cpp ;
 run policy_eg_5.cpp ;
-# run statistics_functions_example1.cpp ; needs update to use accumulator
+run policy_eg_6.cpp ;
+run policy_eg_7.cpp ;
+run policy_eg_8.cpp ;
+run policy_eg_9.cpp ;
+run policy_ref_snip1.cpp ;
+run policy_ref_snip10.cpp ;
+run policy_ref_snip11.cpp ;
+run policy_ref_snip12.cpp ;
+run policy_ref_snip13.cpp ;
+run policy_ref_snip2.cpp ;
+run policy_ref_snip3.cpp ;
+run policy_ref_snip4.cpp ;
+run policy_ref_snip5.cpp ;
+run policy_ref_snip6.cpp ;
+run policy_ref_snip7.cpp ;
+run policy_ref_snip8.cpp ;
+run policy_ref_snip9.cpp ;
+#run statistics_functions_example1.cpp ;
 run students_t_example1.cpp ;
 run students_t_example2.cpp ;
 run students_t_example3.cpp ;
 run students_t_single_sample.cpp ;
 run students_t_two_samples.cpp ;
 
+
+

Modified: sandbox/math_toolkit/libs/math/example/error_handling_example.cpp
==============================================================================
--- sandbox/math_toolkit/libs/math/example/error_handling_example.cpp	(original)
+++ sandbox/math_toolkit/libs/math/example/error_handling_example.cpp	2007-08-09 12:34:23 EDT (Thu, 09 Aug 2007)
@@ -109,7 +109,8 @@
 BOOST_MATH_DOMAIN_ERROR_POLICY is set to: throw_on_error
 
 Message from thrown exception was:
-   Error in function boost::math::students_t_distribution<double>::students_t_distribution: Degrees of freedom argument is -1, but must be > 0 !
+   Error in function boost::math::students_t_distribution<double>::students_t_distribution: 
+   Degrees of freedom argument is -1, but must be > 0 !
 ]
 
 Alternatively let's build with:

Modified: sandbox/math_toolkit/libs/math/example/policy_eg_8.cpp
==============================================================================
--- sandbox/math_toolkit/libs/math/example/policy_eg_8.cpp	(original)
+++ sandbox/math_toolkit/libs/math/example/policy_eg_8.cpp	2007-08-09 12:34:23 EDT (Thu, 09 Aug 2007)
@@ -94,7 +94,7 @@
 inline typename boost::math::tools::promote_args<RT>::type
    tgamma(RT z)
 {
-   return boost::math::tgamma(z, c_policy());
+   return boost::math::tgamma(z, user_error_policy());
 }
 ``
 

Modified: sandbox/math_toolkit/libs/math/example/policy_eg_9.cpp
==============================================================================
--- sandbox/math_toolkit/libs/math/example/policy_eg_9.cpp	(original)
+++ sandbox/math_toolkit/libs/math/example/policy_eg_9.cpp	2007-08-09 12:34:23 EDT (Thu, 09 Aug 2007)
@@ -83,13 +83,13 @@
    msg += ": \n";
    int prec = 2 + (std::numeric_limits<T>::digits * 30103UL) / 100000UL;
    msg += (boost::format(message) % boost::io::group(std::setprecision(prec), val)).str();
-   /*
+   /*`
    Now we just have to do something with the message, we could throw an 
    exception, but for the purposes of this example we'll just dump the message
    to std::cerr:
    */
    std::cerr << msg << std::endl;
-   /*
+   /*`
    Finally the only sensible value we can return from a domain error is a NaN:
    */
    return std::numeric_limits<T>::quiet_NaN();
@@ -246,7 +246,7 @@
 inline typename boost::math::tools::promote_args<RT>::type
    tgamma(RT z)
 {
-   return boost::math::tgamma(z, c_policy());
+   return boost::math::tgamma(z, user_error_policy());
 }
 ``
 

Added: sandbox/math_toolkit/libs/math/example/policy_ref_snip1.cpp
==============================================================================
--- (empty file)
+++ sandbox/math_toolkit/libs/math/example/policy_ref_snip1.cpp	2007-08-09 12:34:23 EDT (Thu, 09 Aug 2007)
@@ -0,0 +1,44 @@
+//  Copyright John Maddock 2007.
+//  Use, modification and distribution are subject to 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)
+
+// Note that this file contains quickbook mark-up as well as code
+// and comments, don't change any of the special comment mark-ups!
+
+double some_value = 0;
+
+//[policy_ref_snip1
+
+#include <boost/math/special_functions/gamma.hpp>
+
+using namespace boost::math::policies;
+using namespace boost::math;
+
+// Define a policy:
+typedef policy<
+      domain_error<errno_on_error>, 
+      pole_error<errno_on_error>,
+      overflow_error<errno_on_error>,
+      policies::evaluation_error<errno_on_error> 
+      > my_policy;
+      
+// call the function:
+double t1 = tgamma(some_value, my_policy());
+
+// Alternatively we could use make_policy and define everything at the call site:
+double t2 = tgamma(some_value, make_policy(
+         domain_error<errno_on_error>(), 
+         pole_error<errno_on_error>(),
+         overflow_error<errno_on_error>(),
+         policies::evaluation_error<errno_on_error>() 
+      ));
+
+//]
+
+#include <iostream>
+
+int main()
+{
+   std::cout << t1 << " " << t2 << std::endl;
+}

Added: sandbox/math_toolkit/libs/math/example/policy_ref_snip10.cpp
==============================================================================
--- (empty file)
+++ sandbox/math_toolkit/libs/math/example/policy_ref_snip10.cpp	2007-08-09 12:34:23 EDT (Thu, 09 Aug 2007)
@@ -0,0 +1,25 @@
+//  Copyright John Maddock 2007.
+//  Use, modification and distribution are subject to 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)
+
+// Note that this file contains quickbook mark-up as well as code
+// and comments, don't change any of the special comment mark-ups!
+
+//[policy_ref_snip10
+
+#include <boost/math/special_functions/gamma.hpp>
+
+using namespace boost::math;
+using namespace boost::math::policies;
+
+double t = tgamma(12, policy<digits10<5> >());
+
+//]
+
+#include <iostream>
+
+int main()
+{
+   std::cout << t << std::endl;
+}

Added: sandbox/math_toolkit/libs/math/example/policy_ref_snip11.cpp
==============================================================================
--- (empty file)
+++ sandbox/math_toolkit/libs/math/example/policy_ref_snip11.cpp	2007-08-09 12:34:23 EDT (Thu, 09 Aug 2007)
@@ -0,0 +1,27 @@
+//  Copyright John Maddock 2007.
+//  Use, modification and distribution are subject to 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)
+
+// Note that this file contains quickbook mark-up as well as code
+// and comments, don't change any of the special comment mark-ups!
+
+//[policy_ref_snip11
+
+#include <boost/math/distributions/normal.hpp>
+
+using namespace boost::math;
+using namespace boost::math::policies;
+
+double q = quantile(
+      normal_distribution<double, policy<digits2<25> > >(), 
+      0.05);
+
+//]
+
+#include <iostream>
+
+int main()
+{
+   std::cout << q << std::endl;
+}

Added: sandbox/math_toolkit/libs/math/example/policy_ref_snip12.cpp
==============================================================================
--- (empty file)
+++ sandbox/math_toolkit/libs/math/example/policy_ref_snip12.cpp	2007-08-09 12:34:23 EDT (Thu, 09 Aug 2007)
@@ -0,0 +1,38 @@
+//  Copyright John Maddock 2007.
+//  Use, modification and distribution are subject to 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)
+
+// Note that this file contains quickbook mark-up as well as code
+// and comments, don't change any of the special comment mark-ups!
+
+//[policy_ref_snip12
+
+#include <boost/math/special_functions/gamma.hpp>
+
+namespace myspace{
+
+using namespace boost::math::policies;
+
+// Define a policy that does not throw on overflow:
+typedef policy<overflow_error<errno_on_error> > my_policy;
+
+// Define the special functions in this scope to use the policy:   
+BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS(my_policy)
+
+}
+
+//
+// Now we can use myspace::tgamma etc.
+// They will automatically use "my_policy":
+//
+double t = myspace::tgamma(30.0); // will not throw on overflow
+
+//]
+
+#include <iostream>
+
+int main()
+{
+   std::cout << t << std::endl;
+}

Added: sandbox/math_toolkit/libs/math/example/policy_ref_snip13.cpp
==============================================================================
--- (empty file)
+++ sandbox/math_toolkit/libs/math/example/policy_ref_snip13.cpp	2007-08-09 12:34:23 EDT (Thu, 09 Aug 2007)
@@ -0,0 +1,49 @@
+//  Copyright John Maddock 2007.
+//  Use, modification and distribution are subject to 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)
+
+// Note that this file contains quickbook mark-up as well as code
+// and comments, don't change any of the special comment mark-ups!
+
+//[policy_ref_snip13
+
+#include <boost/math/distributions/cauchy.hpp>
+
+namespace myspace{
+
+using namespace boost::math::policies;
+
+// Define a policy to use, in this case we want all the distribution
+// accessor functions to compile, even if they are mathematically
+// undefined:
+typedef policy<assert_undefined<false> > my_policy;
+
+BOOST_MATH_DECLARE_DISTRIBUTIONS(double, my_policy)
+
+}
+
+// Now we can use myspace::cauchy etc, which will use policy
+// myspace::mypolicy:
+//
+// This compiles but raises a domain error at runtime:
+//
+void test_cauchy()
+{
+   try{
+      double d = mean(myspace::cauchy()); 
+   }
+   catch(const std::domain_error& e)
+   {
+      std::cout << e.what() << std::endl;
+   }
+}
+
+//]
+
+#include <iostream>
+
+int main()
+{
+   test_cauchy();
+}

Added: sandbox/math_toolkit/libs/math/example/policy_ref_snip2.cpp
==============================================================================
--- (empty file)
+++ sandbox/math_toolkit/libs/math/example/policy_ref_snip2.cpp	2007-08-09 12:34:23 EDT (Thu, 09 Aug 2007)
@@ -0,0 +1,34 @@
+//  Copyright John Maddock 2007.
+//  Use, modification and distribution are subject to 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)
+
+// Note that this file contains quickbook mark-up as well as code
+// and comments, don't change any of the special comment mark-ups!
+
+//[policy_ref_snip2
+
+#include <boost/math/distributions/normal.hpp>
+
+using namespace boost::math::policies;
+using namespace boost::math;
+
+// Define a policy:
+typedef policy<
+      overflow_error<ignore_error>
+      > my_policy;
+      
+// Define the distribution:
+typedef normal_distribution<double, my_policy> my_norm;
+
+// Get a quantile:
+double q = quantile(my_norm(), 0.05);
+
+//]
+
+#include <iostream>
+
+int main()
+{
+   std::cout << q << std::endl;
+}

Added: sandbox/math_toolkit/libs/math/example/policy_ref_snip3.cpp
==============================================================================
--- (empty file)
+++ sandbox/math_toolkit/libs/math/example/policy_ref_snip3.cpp	2007-08-09 12:34:23 EDT (Thu, 09 Aug 2007)
@@ -0,0 +1,36 @@
+//  Copyright John Maddock 2007.
+//  Use, modification and distribution are subject to 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)
+
+// Note that this file contains quickbook mark-up as well as code
+// and comments, don't change any of the special comment mark-ups!
+
+double some_value = 2;
+
+//[policy_ref_snip3
+
+#include <boost/math/special_functions/gamma.hpp>
+
+using namespace boost::math::policies;
+using namespace boost::math;
+
+// Define a policy:
+typedef policy<
+      promote_double<false> 
+      > my_policy;
+      
+// Call the function:
+double t1 = tgamma(some_value, my_policy());
+
+// Alternatively we could use make_policy and define everything at the call site:
+double t2 = tgamma(some_value, make_policy(promote_double<false>()));
+
+//]
+
+#include <iostream>
+
+int main()
+{
+   std::cout << t1 << " " << t2 << std::endl;
+}

Added: sandbox/math_toolkit/libs/math/example/policy_ref_snip4.cpp
==============================================================================
--- (empty file)
+++ sandbox/math_toolkit/libs/math/example/policy_ref_snip4.cpp	2007-08-09 12:34:23 EDT (Thu, 09 Aug 2007)
@@ -0,0 +1,34 @@
+//  Copyright John Maddock 2007.
+//  Use, modification and distribution are subject to 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)
+
+// Note that this file contains quickbook mark-up as well as code
+// and comments, don't change any of the special comment mark-ups!
+
+//[policy_ref_snip4
+
+#include <boost/math/distributions/normal.hpp>
+
+using namespace boost::math::policies;
+using namespace boost::math;
+
+// Define a policy:
+typedef policy<
+      promote_float<false>
+      > my_policy;
+      
+// Define the distribution:
+typedef normal_distribution<float, my_policy> my_norm;
+
+// Get a quantile:
+float q = quantile(my_norm(), 0.05f);
+
+//]
+
+#include <iostream>
+
+int main()
+{
+   std::cout << q << std::endl;
+}

Added: sandbox/math_toolkit/libs/math/example/policy_ref_snip5.cpp
==============================================================================
--- (empty file)
+++ sandbox/math_toolkit/libs/math/example/policy_ref_snip5.cpp	2007-08-09 12:34:23 EDT (Thu, 09 Aug 2007)
@@ -0,0 +1,33 @@
+//  Copyright John Maddock 2007.
+//  Use, modification and distribution are subject to 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)
+
+// Note that this file contains quickbook mark-up as well as code
+// and comments, don't change any of the special comment mark-ups!
+
+//[policy_ref_snip5
+
+#include <boost/math/distributions/negative_binomial.hpp>
+
+using namespace boost::math;
+using namespace boost::math::policies;
+
+typedef negative_binomial_distribution<
+      double, 
+      policy<discrete_quantile<integer_inside> > 
+   > dist_type;
+   
+// Lower quantile:
+double x = quantile(dist_type(20, 0.3), 0.05);
+// Upper quantile:
+double y = quantile(complement(dist_type(20, 0.3), 0.05));
+
+//]
+
+#include <iostream>
+
+int main()
+{
+   std::cout << x << " " << y << std::endl;
+}

Added: sandbox/math_toolkit/libs/math/example/policy_ref_snip6.cpp
==============================================================================
--- (empty file)
+++ sandbox/math_toolkit/libs/math/example/policy_ref_snip6.cpp	2007-08-09 12:34:23 EDT (Thu, 09 Aug 2007)
@@ -0,0 +1,27 @@
+//  Copyright John Maddock 2007.
+//  Use, modification and distribution are subject to 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)
+
+// Note that this file contains quickbook mark-up as well as code
+// and comments, don't change any of the special comment mark-ups!
+
+//[policy_ref_snip6
+
+#include <boost/math/distributions/negative_binomial.hpp>
+
+using namespace boost::math;
+
+// Lower quantile rounded down:
+double x = quantile(negative_binomial(20, 0.3), 0.05);
+// Upper quantile rounded up:
+double y = quantile(complement(negative_binomial(20, 0.3), 0.05));
+
+//]
+
+#include <iostream>
+
+int main()
+{
+   std::cout << x << " " << y << std::endl;
+}

Added: sandbox/math_toolkit/libs/math/example/policy_ref_snip7.cpp
==============================================================================
--- (empty file)
+++ sandbox/math_toolkit/libs/math/example/policy_ref_snip7.cpp	2007-08-09 12:34:23 EDT (Thu, 09 Aug 2007)
@@ -0,0 +1,33 @@
+//  Copyright John Maddock 2007.
+//  Use, modification and distribution are subject to 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)
+
+// Note that this file contains quickbook mark-up as well as code
+// and comments, don't change any of the special comment mark-ups!
+
+//[policy_ref_snip7
+
+#include <boost/math/distributions/negative_binomial.hpp>
+
+using namespace boost::math;
+using namespace boost::math::policies;
+
+typedef negative_binomial_distribution<
+      double, 
+      policy<discrete_quantile<integer_inside> > 
+   > dist_type;
+   
+// Lower quantile rounded up:
+double x = quantile(dist_type(20, 0.3), 0.05);
+// Upper quantile rounded down:
+double y = quantile(complement(dist_type(20, 0.3), 0.05));
+
+//]
+
+#include <iostream>
+
+int main()
+{
+   std::cout << x << " " << y << std::endl;
+}

Added: sandbox/math_toolkit/libs/math/example/policy_ref_snip8.cpp
==============================================================================
--- (empty file)
+++ sandbox/math_toolkit/libs/math/example/policy_ref_snip8.cpp	2007-08-09 12:34:23 EDT (Thu, 09 Aug 2007)
@@ -0,0 +1,33 @@
+//  Copyright John Maddock 2007.
+//  Use, modification and distribution are subject to 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)
+
+// Note that this file contains quickbook mark-up as well as code
+// and comments, don't change any of the special comment mark-ups!
+
+//[policy_ref_snip8
+
+#include <boost/math/distributions/negative_binomial.hpp>
+
+using namespace boost::math;
+using namespace boost::math::policies;
+
+typedef negative_binomial_distribution<
+      double, 
+      policy<discrete_quantile<integer_nearest> > 
+   > dist_type;
+   
+// Lower quantile rounded up:
+double x = quantile(dist_type(20, 0.3), 0.05);
+// Upper quantile rounded down:
+double y = quantile(complement(dist_type(20, 0.3), 0.05));
+
+//]
+
+#include <iostream>
+
+int main()
+{
+   std::cout << x << " " << y << std::endl;
+}

Added: sandbox/math_toolkit/libs/math/example/policy_ref_snip9.cpp
==============================================================================
--- (empty file)
+++ sandbox/math_toolkit/libs/math/example/policy_ref_snip9.cpp	2007-08-09 12:34:23 EDT (Thu, 09 Aug 2007)
@@ -0,0 +1,27 @@
+//  Copyright John Maddock 2007.
+//  Use, modification and distribution are subject to 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)
+
+// Note that this file contains quickbook mark-up as well as code
+// and comments, don't change any of the special comment mark-ups!
+
+//[policy_ref_snip9
+
+#include <boost/math/special_functions/gamma.hpp>
+
+using namespace boost::math;
+using namespace boost::math::policies;
+
+typedef policy<digits10<5> > pol;
+
+double t = tgamma(12, pol());
+
+//]
+
+#include <iostream>
+
+int main()
+{
+   std::cout << t << std::endl;
+}