[Boost-commit] svn:boost r67367 - trunk/libs/math/doc/sf_and_dist

Subject: [Boost-commit] svn:boost r67367 - trunk/libs/math/doc/sf_and_dist
From: pbristow_at_[hidden]
Date: 2010-12-20 11:02:33

Author: pbristow
Date: 2010-12-20 11:02:33 EST (Mon, 20 Dec 2010)
New Revision: 67367
URL: http://svn.boost.org/trac/boost/changeset/67367

Log:
Add note and comment after assert for integer template type for factorial
Text files modified: 
   trunk/libs/math/doc/sf_and_dist/factorials.qbk |    41 ++++++++++++++++++++++++++++++++------- 
   1 files changed, 33 insertions(+), 8 deletions(-)

Modified: trunk/libs/math/doc/sf_and_dist/factorials.qbk
==============================================================================
--- trunk/libs/math/doc/sf_and_dist/factorials.qbk	(original)
+++ trunk/libs/math/doc/sf_and_dist/factorials.qbk	2010-12-20 11:02:33 EST (Mon, 20 Dec 2010)
@@ -27,18 +27,32 @@
 [h4 Description]
 
 [important
-The functions described below are templates where the template argument T can not be deduced from the
+The functions described below are templates where the template argument T CANNOT be deduced from the
 arguments passed to the function.  Therefore if you write something like:
 
    `boost::math::factorial(2);`
 
-You will get a compiler error, ususally indicating that there is no such function to be found.  Instead you need to specifiy
-the return type explicity and write:
+You will get a (perhaps perplexing) compiler error, ususally indicating that there is no such function to be found.
+Instead you need to specify the return type explicity and write:
 
    `boost::math::factorial<double>(2);`
 
-So that the return type is known.  Further, the template argument must be a real-valued type such as `float` or `double`
-and not an integer type - that would overflow far too easily!
+So that the return type is known.
+
+Furthermore, the template argument must be a real-valued type such as `float` or `double`
+and not an integer type - that would overflow far too easily for quite small values of parameter `i`!
+
+The source code `static_assert` and comment just after the  will be:
+
+``
+   BOOST_STATIC_ASSERT(!boost::is_integral<T>::value);
+   // factorial<unsigned int>(n) is not implemented
+   // because it would overflow integral type T for too small n
+   // to be useful. Use instead a floating-point type,
+   // and convert to an unsigned type if essential, for example:
+   // unsigned int nfac = static_cast<unsigned int>(factorial<double>(n));
+   // See factorial documentation for more detail.
+``
 ]
 
    template <class T>
@@ -128,13 +142,25 @@
 
    `boost::math::double_factorial(2);`
 
-You will get a compiler error, ususally indicating that there is no such function to be found.  Instead you need to specifiy
+You will get a (possibly perplexing) compiler error, ususally indicating that there is no such function to be found.  Instead you need to specifiy
 the return type explicity and write:
 
    `boost::math::double_factorial<double>(2);`
 
 So that the return type is known.  Further, the template argument must be a real-valued type such as `float` or `double`
 and not an integer type - that would overflow far too easily!
+
+The source code `static_assert` and comment just after the  will be:
+
+``
+   BOOST_STATIC_ASSERT(!boost::is_integral<T>::value);
+   // factorial<unsigned int>(n) is not implemented
+   // because it would overflow integral type T for too small n
+   // to be useful. Use instead a floating-point type,
+   // and convert to an unsigned type if essential, for example:
+   // unsigned int nfac = static_cast<unsigned int>(factorial<double>(n));
+   // See factorial documentation for more detail.
+``
 ]
 
 [h4 Accuracy]
@@ -339,9 +365,8 @@
 [endsect][/section:factorials Factorials]
 
 [/ 
-  Copyright 2006 John Maddock and Paul A. Bristow.
+  Copyright 2006, 2010 John Maddock and Paul A. Bristow.
   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).
 ]
-