[Boost-commit] svn:boost r65170 - trunk/libs/math/example

Subject: [Boost-commit] svn:boost r65170 - trunk/libs/math/example
From: pbristow_at_[hidden]
Date: 2010-09-01 13:46:10

Author: pbristow
Date: 2010-09-01 13:46:05 EDT (Wed, 01 Sep 2010)
New Revision: 65170
URL: http://svn.boost.org/trac/boost/changeset/65170

Log:
Minor editorial with some added comments.
Text files modified: 
   trunk/libs/math/example/policy_eg_4.cpp       |     5 +-                                      
   trunk/libs/math/example/policy_eg_5.cpp       |    39 ++++++++++++++++----                    
   trunk/libs/math/example/policy_eg_6.cpp       |    73 +++++++++++++++++++------------------   
   trunk/libs/math/example/policy_eg_7.cpp       |    77 +++++++++++++++++++++++---------------- 
   trunk/libs/math/example/policy_eg_8.cpp       |    77 ++++++++++++++++++--------------------- 
   trunk/libs/math/example/policy_eg_9.cpp       |    31 ++++++++-------                         
   trunk/libs/math/example/policy_ref_snip10.cpp |    24 +++++++++--                             
   trunk/libs/math/example/policy_ref_snip11.cpp |    31 ++++++++++++---                         
   trunk/libs/math/example/policy_ref_snip12.cpp |    43 +++++++++++++++------                   
   trunk/libs/math/example/policy_ref_snip2.cpp  |    31 +++++++++++----                         
   trunk/libs/math/example/policy_ref_snip3.cpp  |    18 +++++---                                
   trunk/libs/math/example/policy_ref_snip4.cpp  |     9 ++--                                    
   trunk/libs/math/example/policy_ref_snip5.cpp  |    24 +++++++++---                            
   trunk/libs/math/example/policy_ref_snip6.cpp  |    23 ++++++++---                             
   trunk/libs/math/example/policy_ref_snip7.cpp  |    25 ++++++++++--                            
   trunk/libs/math/example/policy_ref_snip8.cpp  |    24 +++++++++--                             
   trunk/libs/math/example/policy_ref_snip9.cpp  |     6 ++-                                     
   17 files changed, 357 insertions(+), 203 deletions(-)

Modified: trunk/libs/math/example/policy_eg_4.cpp
==============================================================================
--- trunk/libs/math/example/policy_eg_4.cpp	(original)
+++ trunk/libs/math/example/policy_eg_4.cpp	2010-09-01 13:46:05 EDT (Wed, 01 Sep 2010)
@@ -21,7 +21,7 @@
 */
 
 #include <boost/math/special_functions.hpp>
-using boost::math::tgamma;
+//using boost::math::tgamma; // Not needed because using C::tgamma.
 
 /*`
 Open up the "C" namespace that we'll use for our functions, and
@@ -75,12 +75,11 @@
 `boost::math::tgamma(z, C::c_policy())`:
 */
 
-
 int main()
 {
    errno = 0;
    cout << "Result of tgamma(30000) is: "
-      << C::tgamma(30000) << endl;
+      << C::tgamma(30000) << endl; // Note using C::tgamma
    cout << "errno = " << errno << endl; // errno = 34
    cout << "Result of tgamma(-10) is: "
       << C::tgamma(-10) << endl;

Modified: trunk/libs/math/example/policy_eg_5.cpp
==============================================================================
--- trunk/libs/math/example/policy_eg_5.cpp	(original)
+++ trunk/libs/math/example/policy_eg_5.cpp	2010-09-01 13:46:05 EDT (Wed, 01 Sep 2010)
@@ -1,4 +1,5 @@
 //  Copyright John Maddock 2007.
+//  Copyright Paul A. Bristow 2010
 //  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)
@@ -7,12 +8,17 @@
 // and comments, don't change any of the special comment mark-ups!
 
 #include <iostream>
+using std::cout;  using std::endl;
 
 //[policy_eg_5
 
 #include <boost/math/special_functions.hpp>
+ //using boost::math::tgamma; // Would create an ambiguity between 
+// 'double boost::math::tgamma<int>(T)' and
+// 'double 'anonymous-namespace'::tgamma<int>(RT)'.
 
-namespace {
+namespace
+{ // not named
 
 using namespace boost::math::policies;
 
@@ -24,18 +30,35 @@
 > c_policy;
 
 BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS(c_policy)
+/*`
+  So that when we call `tgamma(z)`, we really end up calling
+`boost::math::tgamma(z, anonymous-namespace::c_policy())`:
+*/
 
 } // close unnamed namespace
 
 int main()
 {
    errno = 0;
-   std::cout << "Result of tgamma(30000) is: " 
-      << tgamma(30000) << std::endl;
-   std::cout << "errno = " << errno << std::endl;
-   std::cout << "Result of tgamma(-10) is: " 
-      << tgamma(-10) << std::endl;
-   std::cout << "errno = " << errno << std::endl;
+   cout << "Result of tgamma(30000) is: " 
+      << tgamma(30000) << endl;
+      // tgamma in unnamed namespace in this translation unit (file) only.
+   cout << "errno = " << errno << endl;
+   cout << "Result of tgamma(-10) is: " 
+      << tgamma(-10) << endl;
+   cout << "errno = " << errno << endl;
+   // Default tgamma policy would throw an exception, and abort.
 }
 
-//]
+//] //[/policy_eg_5]
+
+/*
+Output:
+
+  Result of tgamma(30000) is: 1.#INF
+  errno = 34
+  Result of tgamma(-10) is: 1.#QNAN
+  errno = 33
+
+
+*/

Modified: trunk/libs/math/example/policy_eg_6.cpp
==============================================================================
--- trunk/libs/math/example/policy_eg_6.cpp	(original)
+++ trunk/libs/math/example/policy_eg_6.cpp	2010-09-01 13:46:05 EDT (Wed, 01 Sep 2010)
@@ -1,4 +1,5 @@
 //  Copyright John Maddock 2007.
+//  Copyright Paul A. Bristow 2010
 //  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)
@@ -7,6 +8,7 @@
 // and comments, don't change any of the special comment mark-ups!
 
 #include <iostream>
+using std::cout;  using std::endl;
 
 //[policy_eg_6
 
@@ -18,7 +20,7 @@
 * Return the closest integer result from the quantiles of discrete
 distributions.
 
-We'll begin by including the needed header:
+We'll begin by including the needed header for all the distributions:
 */
 
 #include <boost/math/distributions.hpp>
@@ -31,23 +33,24 @@
 
 */
 
-namespace my_distributions{
-
-using namespace boost::math::policies;
+namespace my_distributions
+{
+  using namespace boost::math::policies;
+  // using boost::math::policies::errno_on_error; // etc.
 
-typedef policy<
-   // return infinity and set errno rather than throw:
-   overflow_error<errno_on_error>,
-   // Don't promote double -> long double internally:
-   promote_double<false>,
-   // Return the closest integer result for discrete quantiles:
-   discrete_quantile<integer_round_nearest>
-> my_policy;
+  typedef policy<
+     // return infinity and set errno rather than throw:
+     overflow_error<errno_on_error>,
+     // Don't promote double -> long double internally:
+     promote_double<false>,
+     // Return the closest integer result for discrete quantiles:
+     discrete_quantile<integer_round_nearest>
+  > my_policy;
 
 /*`
 
 All we need do now is invoke the BOOST_MATH_DECLARE_DISTRIBUTIONS
-macro passing the floating point and policy types as arguments:
+macro passing the floating point type `double` and policy types `my_policy` as arguments:
 
 */
 
@@ -57,7 +60,7 @@
 
 /*`
 
-We now have a set of typedefs defined in namespace my_namespace
+We now have a set of typedefs defined in namespace my_distributions
 that all look something like this:
 
 ``
@@ -67,34 +70,32 @@
 // etc
 ``
 
-So that when we use my_namespace::normal we really end up using
+So that when we use my_distributions::normal we really end up using
 `boost::math::normal_distribution<double, my_policy>`:
 
 */
 
-
 int main()
 {
-   //
-   // Start with something we know will overflow:
-   //
-   my_distributions::normal norm(10, 2);
+   // Construct distribution with something we know will overflow
+  // (using double rather than if promoted to long double):
+   my_distributions::normal norm(10, 2); 
+
    errno = 0;
-   std::cout << "Result of quantile(norm, 0) is: " 
-      << quantile(norm, 0) << std::endl;
-   std::cout << "errno = " << errno << std::endl;
+   cout << "Result of quantile(norm, 0) is: " 
+      << quantile(norm, 0) << endl; // -infinity.
+   cout << "errno = " << errno << endl;
    errno = 0;
-   std::cout << "Result of quantile(norm, 1) is: " 
-      << quantile(norm, 1) << std::endl;
-   std::cout << "errno = " << errno << std::endl;
-   //
-   // Now try a discrete distribution:
-   //
+   cout << "Result of quantile(norm, 1) is: " 
+      << quantile(norm, 1) << endl; // +infinity.
+   cout << "errno = " << errno << endl;
+
+   // Now try a discrete distribution.
    my_distributions::binomial binom(20, 0.25);
-   std::cout << "Result of quantile(binom, 0.05) is: " 
-      << quantile(binom, 0.05) << std::endl;
-   std::cout << "Result of quantile(complement(binom, 0.05)) is: " 
-      << quantile(complement(binom, 0.05)) << std::endl;
+   cout << "Result of quantile(binom, 0.05) is: " 
+      << quantile(binom, 0.05) << endl; // To check we get integer results.
+   cout << "Result of quantile(complement(binom, 0.05)) is: " 
+      << quantile(complement(binom, 0.05)) << endl;
 }
 
 /*`
@@ -112,8 +113,8 @@
 
 This mechanism is particularly useful when we want to define a 
 project-wide policy, and don't want to modify the Boost source
-or set - possibly fragile and easy to forget - project wide 
-build macros.
+or set  project wide build macros (possibly fragile and easy to forget).
 
-*/ //] ends quickbook imported section
+*/
+//] //[/policy_eg_6]
 

Modified: trunk/libs/math/example/policy_eg_7.cpp
==============================================================================
--- trunk/libs/math/example/policy_eg_7.cpp	(original)
+++ trunk/libs/math/example/policy_eg_7.cpp	2010-09-01 13:46:05 EDT (Wed, 01 Sep 2010)
@@ -1,4 +1,5 @@
 //  Copyright John Maddock 2007.
+//  Copyright Paul A. Bristow 2010
 //  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)
@@ -7,51 +8,65 @@
 // and comments, don't change any of the special comment mark-ups!
 
 #include <iostream>
+using std::cout;  using std::endl;
 
 //[policy_eg_7
 
-#include <boost/math/distributions.hpp>
+#include <boost/math/distributions.hpp> // All distributions.
+// using boost::math::normal; // Would create an ambguity between
+// boost::math::normal_distribution<RealType> boost::math::normal and
+// 'anonymous-namespace'::normal'.
+
+namespace
+{ // anonymous or unnnamed (rather than named as in policy_eg_6.cpp).
+
+  using namespace boost::math::policies;
+   // using boost::math::policies::errno_on_error; // etc.
+  typedef policy<
+     // return infinity and set errno rather than throw:
+     overflow_error<errno_on_error>,
+     // Don't promote double -> long double internally:
+     promote_double<false>,
+     // Return the closest integer result for discrete quantiles:
+     discrete_quantile<integer_round_nearest>
+  > my_policy;
 
-namespace {
-
-using namespace boost::math::policies;
-
-typedef policy<
-   // return infinity and set errno rather than throw:
-   overflow_error<errno_on_error>,
-   // Don't promote double -> long double internally:
-   promote_double<false>,
-   // Return the closest integer result for discrete quantiles:
-   discrete_quantile<integer_round_nearest>
-> my_policy;
-
-BOOST_MATH_DECLARE_DISTRIBUTIONS(double, my_policy)
+  BOOST_MATH_DECLARE_DISTRIBUTIONS(double, my_policy)
 
 } // close namespace my_namespace
 
 int main()
 {
-   //
-   // Start with something we know will overflow:
-   //
-   normal norm(10, 2);
+   // Construct distribution with something we know will overflow.
+   normal norm(10, 2); // using 'anonymous-namespace'::normal
    errno = 0;
-   std::cout << "Result of quantile(norm, 0) is: " 
-      << quantile(norm, 0) << std::endl;
-   std::cout << "errno = " << errno << std::endl;
+   cout << "Result of quantile(norm, 0) is: " 
+      << quantile(norm, 0) << endl;
+   cout << "errno = " << errno << endl;
    errno = 0;
-   std::cout << "Result of quantile(norm, 1) is: " 
-      << quantile(norm, 1) << std::endl;
-   std::cout << "errno = " << errno << std::endl;
+   cout << "Result of quantile(norm, 1) is: " 
+      << quantile(norm, 1) << endl;
+   cout << "errno = " << errno << endl;
    //
    // Now try a discrete distribution:
-   //
    binomial binom(20, 0.25);
-   std::cout << "Result of quantile(binom, 0.05) is: " 
-      << quantile(binom, 0.05) << std::endl;
-   std::cout << "Result of quantile(complement(binom, 0.05)) is: " 
-      << quantile(complement(binom, 0.05)) << std::endl;
+   cout << "Result of quantile(binom, 0.05) is: " 
+      << quantile(binom, 0.05) << endl;
+   cout << "Result of quantile(complement(binom, 0.05)) is: " 
+      << quantile(complement(binom, 0.05)) << endl;
 }
 
-//] ends quickbook imported section
+//] //[/policy_eg_7]
+
+/*
+
+Output:
+
+  Result of quantile(norm, 0) is: -1.#INF
+  errno = 34
+  Result of quantile(norm, 1) is: 1.#INF
+  errno = 34
+  Result of quantile(binom, 0.05) is: 1
+  Result of quantile(complement(binom, 0.05)) is: 8
 
+*/

Modified: trunk/libs/math/example/policy_eg_8.cpp
==============================================================================
--- trunk/libs/math/example/policy_eg_8.cpp	(original)
+++ trunk/libs/math/example/policy_eg_8.cpp	2010-09-01 13:46:05 EDT (Wed, 01 Sep 2010)
@@ -1,5 +1,5 @@
 //  Copyright John Maddock 2007.
-//  Copyright Paul a. Bristow 2007
+//  Copyright Paul a. Bristow 2010
 //  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)
@@ -8,19 +8,18 @@
 // and comments, don't change any of the special comment mark-ups!
 
 #ifdef _MSC_VER
-# pragma warning (disable : 4100) // 'unreferenced formal parameter
+# pragma warning (disable : 4100) // unreferenced formal parameters
 #endif
 
-
 #include <iostream>
+using std::cout;  using std::endl; using std::cerr;
 
 //[policy_eg_8
 
 /*`
-
 Suppose we want our own user-defined error handlers rather than the
-any of the default ones supplied by the library to be used.  If
-we set the policy for a specific type of error to `user_error`
+any of the default ones supplied by the library to be used.
+If we set the policy for a specific type of error to `user_error`
 then the library will call a user-supplied error handler.
 These are forward declared, but not defined in
 boost/math/policies/error_handling.hpp like this:
@@ -45,38 +44,36 @@
    }}} // namespaces
 
 So out first job is to include the header we want to use, and then
-provide definitions for the user-defined error handlers we want to use:
-
+provide definitions for our user-defined error handlers that we want to use.
+We only provide our special domain and pole error handlers, other errors use the default.
 */
 
-#include <iostream>
 #include <boost/math/special_functions.hpp>
 
-namespace boost{ namespace math{ namespace policies{
-
-template <class T>
-T user_domain_error(const char* function, const char* message, const T& val)
+namespace boost{ namespace math
 {
-   std::cerr << "Domain Error." << std::endl;
-   return std::numeric_limits<T>::quiet_NaN();
-}
-
-template <class T>
-T user_pole_error(const char* function, const char* message, const T& val)
-{
-   std::cerr << "Pole Error." << std::endl;
-   return std::numeric_limits<T>::quiet_NaN();
-}
-
-
-}}} // namespaces
+  namespace policies
+  {
+    template <class T>
+    T user_domain_error(const char* function, const char* message, const T& val)
+    { // Ignoring function, message and val for this example, perhaps unhelpfully.
+       cerr << "Domain Error!" << endl;
+       return std::numeric_limits<T>::quiet_NaN();
+    }
+
+    template <class T>
+    T user_pole_error(const char* function, const char* message, const T& val)
+    { // Ignoring function, message and val for this example, perhaps unhelpfully.
+       cerr << "Pole Error!" << endl;
+       return std::numeric_limits<T>::quiet_NaN();
+    }
+  } // namespace policies
+}} // namespace boost{ namespace math
 
 
 /*`
-
 Now we'll need to define a suitable policy that will call these handlers,
 and define some forwarding functions that make use of the policy:
-
 */
 
 namespace{
@@ -93,7 +90,6 @@
 } // close unnamed namespace
 
 /*`
-
 We now have a set of forwarding functions defined in an unnamed namespace
 that all look something like this:
 
@@ -108,17 +104,15 @@
 
 So that when we call `tgamma(z)` we really end up calling
 `boost::math::tgamma(z, user_error_policy())`, and any
-errors will get directed to our own error handlers:
-
+errors will get directed to our own error handlers.
 */
 
-
 int main()
 {
-   std::cout << "Result of erf_inv(-10) is: "
-      << erf_inv(-10) << std::endl;
-   std::cout << "Result of tgamma(-10) is: "
-      << tgamma(-10) << std::endl;
+   cout << "Result of erf_inv(-10) is: "
+      << erf_inv(-10) << endl;
+   cout << "Result of tgamma(-10) is: "
+      << tgamma(-10) << endl;
 }
 
 /*`
@@ -126,12 +120,11 @@
 Which outputs:
 
 [pre
-Domain Error.
-Result of erf_inv(-10) is: 1.#QNAN
-Pole Error.
-Result of tgamma(-10) is: 1.#QNAN
+  Domain Error!
+  Pole Error!
+  Result of erf_inv(-10) is: 1.#QNAN
+  Result of tgamma(-10) is: 1.#QNAN
 ]
 */
 
-//]
-
+//] // //[/policy_eg_8]

Modified: trunk/libs/math/example/policy_eg_9.cpp
==============================================================================
--- trunk/libs/math/example/policy_eg_9.cpp	(original)
+++ trunk/libs/math/example/policy_eg_9.cpp	2010-09-01 13:46:05 EDT (Wed, 01 Sep 2010)
@@ -8,12 +8,11 @@
 // and comments, don't change any of the special comment mark-ups!
 
 #include <iostream>
-using std::cout; using std::endl;
+using std::cout; using std::endl; using std::cerr;
 
 //[policy_eg_9
 
 /*`
-
 The previous example was all well and good, but the custom error handlers
 didn't really do much of any use.  In this example we'll implement all
 the custom handlers and show how the information provided to them can be
@@ -54,33 +53,36 @@
 #include <boost/math/special_functions.hpp>
 
 /*`
-Next we'll implement the error handlers for each type of error, 
+Next we'll implement our own error handlers for each type of error, 
 starting with domain errors:
 */
 
-namespace boost{ namespace math{ namespace policies{
+namespace boost{ namespace math{
+namespace policies
+{
 
 template <class T>
 T user_domain_error(const char* function, const char* message, const T& val)
 {
    /*`
-   We'll begin with a bit of defensive programming:
+   We'll begin with a bit of defensive programming in case function or message are empty:
    */
    if(function == 0)
        function = "Unknown function with arguments of type %1%";
    if(message == 0)
        message = "Cause unknown with bad argument %1%";
    /*`
-   Next we'll format the name of the function with the name of type T:
+   Next we'll format the name of the function with the name of type T, perhaps double:
    */
    std::string msg("Error in function ");
    msg += (boost::format(function) % typeid(T).name()).str();
    /*`
    Then likewise format the error message with the value of parameter /val/,
-   making sure we output all the digits of /val/:
+   making sure we output all the potentially significant digits of /val/:
    */
    msg += ": \n";
    int prec = 2 + (std::numeric_limits<T>::digits * 30103UL) / 100000UL;
+   // int prec = std::numeric_limits<T>::max_digits10; //  For C++0X Standard Library
    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 
@@ -190,7 +192,7 @@
    if(function == 0)
        function = "Unknown function with arguments of type %1%";
    if(message == 0)
-       message = "An internal evaluation error occured with "
+       message = "An internal evaluation error occurred with "
                   "the best value calculated so far of %1%";
 
    std::string msg("Error in function ");
@@ -198,6 +200,7 @@
 
    msg += ": \n";
    int prec = 2 + (std::numeric_limits<T>::digits * 30103UL) / 100000UL;
+   // int prec = std::numeric_limits<T>::max_digits10; // For C++0X Standard Library
    msg += (boost::format(message) % boost::io::group(std::setprecision(prec), val)).str();
 
    std::cerr << msg << std::endl;
@@ -208,7 +211,8 @@
    return std::numeric_limits<T>::quiet_NaN();
 }
 
-}}} // namespaces
+} // policies
+}} // boost::math
 
 
 /*`
@@ -217,7 +221,7 @@
 */
 
 namespace
-{
+{ // unnamed.
 
 using namespace boost::math::policies;
 
@@ -232,7 +236,7 @@
 
 BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS(user_error_policy)
 
-} // close unnamed namespace
+} // unnamed namespace
 
 /*`
 We now have a set of forwarding functions, defined in an unnamed namespace,
@@ -252,7 +256,6 @@
 errors will get directed to our own error handlers:
 */
 
-
 int main()
 {
    // Raise a domain error:
@@ -303,8 +306,8 @@
 of the fact that many functions are implemented in terms of one or more
 sub-routines each of which may have it's own error handling.  For example
 `tgamma(-190.5)` is implemented in terms of `tgamma(190.5)` - which overflows -
-the reflection formula for `tgamma` then notices that it's dividing by
-infinity and underflows.
+the reflection formula for `tgamma` then notices that it is dividing by
+infinity and so underflows.
 */
 
 //] //[/policy_eg_9]

Modified: trunk/libs/math/example/policy_ref_snip10.cpp
==============================================================================
--- trunk/libs/math/example/policy_ref_snip10.cpp	(original)
+++ trunk/libs/math/example/policy_ref_snip10.cpp	2010-09-01 13:46:05 EDT (Wed, 01 Sep 2010)
@@ -1,4 +1,5 @@
 //  Copyright John Maddock 2007.
+//  Copyright Paul A. Bristow 2010
 //  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)
@@ -6,20 +7,33 @@
 // Note that this file contains quickbook mark-up as well as code
 // and comments, don't change any of the special comment mark-ups!
 
+// Setting precision in a single function call using make_policy.
+
+#include <iostream>
+using std::cout; using std::endl;
+
 //[policy_ref_snip10
 
 #include <boost/math/special_functions/gamma.hpp>
+using boost::math::tgamma;
 
-using namespace boost::math;
 using namespace boost::math::policies;
 
-double t = tgamma(12, policy<digits10<5> >());
+double t = tgamma(12, policy<digits10<5> >());  // Concise make_policy.
+
+//] //[/policy_ref_snip10]
 
-//]
 
-#include <iostream>
 
 int main()
 {
-   std::cout << t << std::endl;
+   cout << "tgamma(12, policy<digits10<5> >())  = "<< t << endl;
 }
+
+/*
+
+Output:
+
+ tgamma(12, policy<digits10<5> >())  = 3.99168e+007
+
+*/
\ No newline at end of file

Modified: trunk/libs/math/example/policy_ref_snip11.cpp
==============================================================================
--- trunk/libs/math/example/policy_ref_snip11.cpp	(original)
+++ trunk/libs/math/example/policy_ref_snip11.cpp	2010-09-01 13:46:05 EDT (Wed, 01 Sep 2010)
@@ -1,4 +1,5 @@
 //  Copyright John Maddock 2007.
+//  Copyright Paul A. Bristow 2010
 //  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)
@@ -6,22 +7,38 @@
 // Note that this file contains quickbook mark-up as well as code
 // and comments, don't change any of the special comment mark-ups!
 
+#include <iostream>
+using std::cout; using std::endl;
+
+// Setting (approximate) precision 25 bits in a single function call using make_policy.
+
 //[policy_ref_snip11
 
 #include <boost/math/distributions/normal.hpp>
+using boost::math::normal_distribution;
 
-using namespace boost::math;
 using namespace boost::math::policies;
 
-double q = quantile(
-      normal_distribution<double, policy<digits2<25> > >(), 
-      0.05);
+const int bits = 25; // approximate precision.
 
-//]
+double q = quantile(
+      normal_distribution<double, policy<digits2<bits> > >(), 
+      0.05); // 5% quantile.
 
-#include <iostream>
+//] //[/policy_ref_snip11]
 
 int main()
 {
-   std::cout << q << std::endl;
+  std::streamsize p = 2 + (bits * 30103UL) / 100000UL; 
+  // Approximate number of significant decimal digits for 25 bits.
+  cout.precision(p); 
+  cout << bits << " binary bits is approoximately equivalent to " << p << " decimal digits " << endl;
+  cout << "quantile(normal_distribution<double, policy<digits2<25> > >(), 0.05  = "
+     << q << endl; // -1.64485
 }
+
+/*
+Output:
+  25 binary bits is approoximately equivalent to 9 decimal digits 
+  quantile(normal_distribution<double, policy<digits2<25> > >(), 0.05  = -1.64485363
+  */
\ No newline at end of file

Modified: trunk/libs/math/example/policy_ref_snip12.cpp
==============================================================================
--- trunk/libs/math/example/policy_ref_snip12.cpp	(original)
+++ trunk/libs/math/example/policy_ref_snip12.cpp	2010-09-01 13:46:05 EDT (Wed, 01 Sep 2010)
@@ -1,4 +1,5 @@
 //  Copyright John Maddock 2007.
+//  Copyright Paul A. Bristow 2010
 //  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)
@@ -6,33 +7,49 @@
 // 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
+// Define tgamma function with a no overflow policy
+// into a specific namespace-scope.
 
-#include <boost/math/special_functions/gamma.hpp>
+#include <iostream>
+using std::cout; using std::endl;
 
-namespace myspace{
+//[policy_ref_snip12
 
-using namespace boost::math::policies;
+#include <boost/math/special_functions/gamma.hpp>
+//using boost::math::tgamma;
+// Need not declare using boost::math::tgamma here,
+// because will define tgamma in myspace using macro below.
 
-// Define a policy that does not throw on overflow:
-typedef policy<overflow_error<errno_on_error> > my_policy;
+namespace myspace
+{
+  using namespace boost::math::policies;
 
-// Define the special functions in this scope to use the policy:   
-BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS(my_policy)
+  // 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
+double t = myspace::tgamma(30.0); // Will *not* throw on overflow,
+// despite the large value of factorial 30 = 265252859812191058636308480000000
+// unlike default policy boost::math::tgamma;
 
 //]
 
-#include <iostream>
-
 int main()
 {
-   std::cout << t << std::endl;
+   cout << "myspace::tgamma(30.0) = " << t << endl;
 }
+
+/*
+
+Output:
+
+myspace::tgamma(30.0) = 8.84176e+030
+
+*/
+

Modified: trunk/libs/math/example/policy_ref_snip2.cpp
==============================================================================
--- trunk/libs/math/example/policy_ref_snip2.cpp	(original)
+++ trunk/libs/math/example/policy_ref_snip2.cpp	2010-09-01 13:46:05 EDT (Wed, 01 Sep 2010)
@@ -1,4 +1,5 @@
 //  Copyright John Maddock 2007.
+//  Copyright Paul A. Bristow 2010
 //  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)
@@ -6,29 +7,41 @@
 // Note that this file contains quickbook mark-up as well as code
 // and comments, don't change any of the special comment mark-ups!
 
+#include <iostream>
+using std::cout;  using std::endl;
+
 //[policy_ref_snip2
 
 #include <boost/math/distributions/normal.hpp>
+using boost::math::normal_distribution;
 
 using namespace boost::math::policies;
-using namespace boost::math;
 
-// Define a policy:
+// Define a specific policy:
 typedef policy<
       overflow_error<ignore_error>
       > my_policy;
       
-// Define the distribution:
+// Define the distribution, using my_policy:
 typedef normal_distribution<double, my_policy> my_norm;
 
-// Get a quantile:
-double q = quantile(my_norm(), 0.05);
+// Construct a my_norm distribution, using default mean and standard deviation,
+// and get a 0.05 or 5% quantile:
+double q = quantile(my_norm(), 0.05); // = -1.64485
 
-//]
-
-#include <iostream>
+//] //[/policy_ref_snip2]
 
 int main()
 {
-   std::cout << q << std::endl;
+  my_norm n; // Construct a my_norm distribution,
+  // using default mean zero and standard deviation unity.
+  double q = quantile(n, 0.05); // and get a quantile.
+  cout << "quantile(my_norm(), 0.05) = " << q << endl;
 }
+
+/*
+
+Output:
+
+  quantile(my_norm(), 0.05) = -1.64485
+*/

Modified: trunk/libs/math/example/policy_ref_snip3.cpp
==============================================================================
--- trunk/libs/math/example/policy_ref_snip3.cpp	(original)
+++ trunk/libs/math/example/policy_ref_snip3.cpp	2010-09-01 13:46:05 EDT (Wed, 01 Sep 2010)
@@ -1,4 +1,5 @@
 //  Copyright John Maddock 2007.
+//  Copyright Paul A. Bristow 2010
 //  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)
@@ -6,31 +7,34 @@
 // 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;
+double some_value = 2.;
 
 //[policy_ref_snip3
 
 #include <boost/math/special_functions/gamma.hpp>
 
 using namespace boost::math::policies;
-using namespace boost::math;
+using boost::math::tgamma;
 
-// Define a policy:
+// Define a new policy *not* internally promoting RealType to double:
 typedef policy<
       promote_double<false> 
       > my_policy;
       
-// Call the function:
+// Call the function, applying the new policy:
 double t1 = tgamma(some_value, my_policy());
 
-// Alternatively we could use make_policy and define everything at the call site:
+// Alternatively we could use helper function make_policy,
+// and concisely define everything at the call site:
 double t2 = tgamma(some_value, make_policy(promote_double<false>()));
 
-//]
+//] //[\policy_ref_snip3]
 
 #include <iostream>
+using std::cout;  using std::endl;
 
 int main()
 {
-   std::cout << t1 << " " << t2 << std::endl;
+   cout << "tgamma(some_value, my_policy()) = " << t1 
+     << ", tgamma(some_value, make_policy(promote_double<false>()) = " << t2 << endl;
 }

Modified: trunk/libs/math/example/policy_ref_snip4.cpp
==============================================================================
--- trunk/libs/math/example/policy_ref_snip4.cpp	(original)
+++ trunk/libs/math/example/policy_ref_snip4.cpp	2010-09-01 13:46:05 EDT (Wed, 01 Sep 2010)
@@ -1,5 +1,5 @@
 //  Copyright John Maddock 2007.
-//  Copyright Paul A. Bristow 2007.
+//  Copyright Paul A. Bristow 2010.
 //  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)
@@ -15,16 +15,16 @@
 //[policy_ref_snip4
 
 #include <boost/math/distributions/normal.hpp>
+using boost::math::normal_distribution;
 
 using namespace boost::math::policies;
-using namespace boost::math;
 
 // Define a policy:
 typedef policy<
       promote_float<false>
       > my_policy;
 
-// Define the distribution:
+// Define the new normal distribution using my_policy:
 typedef normal_distribution<float, my_policy> my_norm;
 
 // Get a quantile:
@@ -33,8 +33,9 @@
 //] [policy_ref_snip4]
 
 #include <iostream>
+using std::cout; using std::endl;
 
 int main()
 {
-   std::cout << q << std::endl;
+   cout << " quantile(my_norm(), 0.05f) = " << q << endl; //   -1.64485
 }

Modified: trunk/libs/math/example/policy_ref_snip5.cpp
==============================================================================
--- trunk/libs/math/example/policy_ref_snip5.cpp	(original)
+++ trunk/libs/math/example/policy_ref_snip5.cpp	2010-09-01 13:46:05 EDT (Wed, 01 Sep 2010)
@@ -1,4 +1,5 @@
 //  Copyright John Maddock 2007.
+//  Copyright Paul A. Bristow 2010.
 //  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)
@@ -9,25 +10,36 @@
 //[policy_ref_snip5
 
 #include <boost/math/distributions/negative_binomial.hpp>
+using boost::math::negative_binomial_distribution;
 
-using namespace boost::math;
 using namespace boost::math::policies;
 
 typedef negative_binomial_distribution<
       double, 
-      policy<discrete_quantile<integer_round_inwards> > 
+      policy<discrete_quantile<real> > 
    > dist_type;
    
-// Lower quantile:
+// Lower 5% quantile:
 double x = quantile(dist_type(20, 0.3), 0.05);
-// Upper quantile:
+// Upper 95% quantile:
 double y = quantile(complement(dist_type(20, 0.3), 0.05));
 
-//]
+//] //[/policy_ref_snip5]
 
 #include <iostream>
+using std::cout; using std::endl;
 
 int main()
 {
-   std::cout << x << " " << y << std::endl;
+  cout << "quantile(dist_type(20, 0.3), 0.05)  = " << x 
+    << "\nquantile(complement(dist_type(20, 0.3), 0.05) = " << y << endl;
 }
+
+/*
+
+Output:
+  quantile(dist_type(20, 0.3), 0.05)  = 27.3898
+  quantile(complement(dist_type(20, 0.3), 0.05) = 68.1584
+
+  */
+

Modified: trunk/libs/math/example/policy_ref_snip6.cpp
==============================================================================
--- trunk/libs/math/example/policy_ref_snip6.cpp	(original)
+++ trunk/libs/math/example/policy_ref_snip6.cpp	2010-09-01 13:46:05 EDT (Wed, 01 Sep 2010)
@@ -1,4 +1,5 @@
 //  Copyright John Maddock 2007.
+//  Copyright Paul A. Bristow 2010.
 //  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)
@@ -9,19 +10,29 @@
 //[policy_ref_snip6
 
 #include <boost/math/distributions/negative_binomial.hpp>
+using boost::math::negative_binomial;
 
-using namespace boost::math;
-
+// Use the default rounding policy integer_round_outwards.
 // Lower quantile rounded down:
-double x = quantile(negative_binomial(20, 0.3), 0.05);
+double x = quantile(negative_binomial(20, 0.3), 0.05); // rounded up 27 from 27.3898
 // Upper quantile rounded up:
-double y = quantile(complement(negative_binomial(20, 0.3), 0.05));
+double y = quantile(complement(negative_binomial(20, 0.3), 0.05)); // rounded down to 69 from 68.1584
 
-//]
+//] //[/policy_ref_snip6]
 
 #include <iostream>
+using std::cout; using std::endl;
 
 int main()
 {
-   std::cout << x << " " << y << std::endl;
+   cout << "quantile(negative_binomial(20, 0.3), 0.05) = "<< x <<endl
+     << "quantile(complement(negative_binomial(20, 0.3), 0.05)) = " << y << endl;
 }
+
+/*
+Output:
+
+  quantile(negative_binomial(20, 0.3), 0.05) = 27
+  quantile(complement(negative_binomial(20, 0.3), 0.05)) = 69
+*/
+

Modified: trunk/libs/math/example/policy_ref_snip7.cpp
==============================================================================
--- trunk/libs/math/example/policy_ref_snip7.cpp	(original)
+++ trunk/libs/math/example/policy_ref_snip7.cpp	2010-09-01 13:46:05 EDT (Wed, 01 Sep 2010)
@@ -1,4 +1,5 @@
 //  Copyright John Maddock 2007.
+//  Copyright Paul A. Bristow 2010.
 //  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)
@@ -9,8 +10,8 @@
 //[policy_ref_snip7
 
 #include <boost/math/distributions/negative_binomial.hpp>
+using boost::math::negative_binomial_distribution;
 
-using namespace boost::math;
 using namespace boost::math::policies;
 
 typedef negative_binomial_distribution<
@@ -19,15 +20,29 @@
    > dist_type;
    
 // Lower quantile rounded up:
-double x = quantile(dist_type(20, 0.3), 0.05);
+double x = quantile(dist_type(20, 0.3), 0.05); // 28 rounded up from 27.3898
 // Upper quantile rounded down:
-double y = quantile(complement(dist_type(20, 0.3), 0.05));
+double y = quantile(complement(dist_type(20, 0.3), 0.05)); // 68 rounded down from 68.1584
 
-//]
+//] //[/policy_ref_snip7]
 
 #include <iostream>
+using std::cout; using std::endl;
 
 int main()
 {
-   std::cout << x << " " << y << std::endl;
+   cout << "using policy<discrete_quantile<integer_round_inwards> > " << endl
+   << "quantile(dist_type(20, 0.3), 0.05) = " << x << endl 
+   << "quantile(complement(dist_type(20, 0.3), 0.05)) =  " << y << endl;
 }
+
+/*
+
+Output:
+  using policy<discrete_quantile<integer_round_inwards> > 
+  quantile(dist_type(20, 0.3), 0.05) = 28
+  quantile(complement(dist_type(20, 0.3), 0.05)) =  68
+
+
+*/
+

Modified: trunk/libs/math/example/policy_ref_snip8.cpp
==============================================================================
--- trunk/libs/math/example/policy_ref_snip8.cpp	(original)
+++ trunk/libs/math/example/policy_ref_snip8.cpp	2010-09-01 13:46:05 EDT (Wed, 01 Sep 2010)
@@ -1,4 +1,5 @@
 //  Copyright John Maddock 2007.
+//  Copyright Paul A. Bristow 2010.
 //  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)
@@ -9,8 +10,8 @@
 //[policy_ref_snip8
 
 #include <boost/math/distributions/negative_binomial.hpp>
+using boost::math::negative_binomial_distribution;
 
-using namespace boost::math;
 using namespace boost::math::policies;
 
 typedef negative_binomial_distribution<
@@ -19,15 +20,28 @@
    > dist_type;
    
 // Lower quantile rounded up:
-double x = quantile(dist_type(20, 0.3), 0.05);
+double x = quantile(dist_type(20, 0.3), 0.05); // 27
 // Upper quantile rounded down:
-double y = quantile(complement(dist_type(20, 0.3), 0.05));
+double y = quantile(complement(dist_type(20, 0.3), 0.05)); // 68
 
-//]
+//] //[/policy_ref_snip8]
 
 #include <iostream>
+using std::cout; using std::endl;
 
 int main()
 {
-   std::cout << x << " " << y << std::endl;
+   cout << "using policy<discrete_quantile<integer_round_nearest> " << endl
+     << "quantile(dist_type(20, 0.3), 0.05) = " << x << endl
+     << "quantile(complement(dist_type(20, 0.3), 0.05)) " << y << endl;
 }
+
+/*
+
+Output:
+
+  quantile(dist_type(20, 0.3), 0.05) = 27
+  quantile(complement(dist_type(20, 0.3), 0.05)) 68
+
+
+*/

Modified: trunk/libs/math/example/policy_ref_snip9.cpp
==============================================================================
--- trunk/libs/math/example/policy_ref_snip9.cpp	(original)
+++ trunk/libs/math/example/policy_ref_snip9.cpp	2010-09-01 13:46:05 EDT (Wed, 01 Sep 2010)
@@ -8,10 +8,11 @@
 // 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 <iostream>
 using std::cout; using std::endl;
 
+//[policy_ref_snip9
+
 #include <boost/math/special_functions/gamma.hpp>
 using boost::math::tgamma;
 using boost::math::policies::policy;
@@ -23,6 +24,7 @@
 
 int main()
 {
+  cout.precision(5); // To only show 5 (hopefully) accurate decimal digits.
   double t = tgamma(12, my_pol_5()); // Apply the 5 decimal digits accuracy policy to use of tgamma.
   cout << "tgamma(12, my_pol_5() = " << t << endl;
 }
@@ -30,5 +32,5 @@
 /*
 
 Output:
-    tgamma(12, my_pol_5() = 3.99168e+007
+     tgamma(12, my_pol_5() = 3.9917e+007
 */