From 7523045cd0a413aef6ee73bce5a047117841aff8 Mon Sep 17 00:00:00 2001 From: "Paul A. Bristow" Date: Mon, 20 Dec 2010 16:02:33 +0000 Subject: [PATCH] Add note and comment after assert for integer template type for factorial [SVN r67367] --- doc/sf_and_dist/factorials.qbk | 41 +++++++++++++++++++++++++++------- 1 file changed, 33 insertions(+), 8 deletions(-) diff --git a/doc/sf_and_dist/factorials.qbk b/doc/sf_and_dist/factorials.qbk index 6318c56a8..d1747303d 100644 --- a/doc/sf_and_dist/factorials.qbk +++ b/doc/sf_and_dist/factorials.qbk @@ -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(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::value); + // factorial(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(factorial(n)); + // See factorial documentation for more detail. +`` ] template @@ -128,13 +142,25 @@ arguments passed to the function. Therefore if you write something like: `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(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::value); + // factorial(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(factorial(n)); + // See factorial documentation for more detail. +`` ] [h4 Accuracy] @@ -339,9 +365,8 @@ and [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). ] -