The Synopsis
namespace boost { namespace math { template <int N, typename T> calculated-result-type pow(T base); template <int N, typename T, class Policy> calculated-result-type pow(T base, const Policy& policy); }} Rationale and Usage
Computing the power of a number with an exponent that is known at compile
time is a common need for programmers. In such cases, the usual method
is to avoid the overhead implied by the // Hand-written 8th power of a 'base' variable double result = base*base*base*base*base*base*base*base; However, this kind of expression is not really readable (knowing the value of the exponent involves counting the number of occurrences of base), error-prone (it's easy to forget an occurrence), syntactically bulky, and non-optimal in terms of performance. The pow function of Boost.Math helps writing this kind expression along with solving all the problems listed above: // 8th power of a 'base' variable using math::pow double result = pow<8>(base);
The expression is now shorter, easier to read, safer, and even faster.
Indeed, // Internal effect of pow<8>(base) double result = ((base*base)*(base*base))*((base*base)*(base*base)); Only 3 different products were actually computed. Return TypeThe return type of these functions is computed using the result type calculation rules. For example:
Policies
The final Policy argument is optional and can be used to control the behaviour of the function: how it handles errors, what level of precision to use etc. Refer to the policy documentation for more details.
Error Handling
Two cases of errors can occur when using
The default overflow error policy is
The default indeterminate result error policy is
Here is an example of error handling customization where we want to specify
the result that has to be returned in case of error. We will thus use the
// First we open the boost::math::policies namespace and define the `user_overflow_error` // by making it return the value we want in case of error (-1 here) namespace boost { namespace math { namespace policies { template <class T> T user_overflow_error(const char*, const char*, const T&) { return -1; } }}} // Then we invoke pow and indicate that we want to use the user_error policy using boost::math::policies; double result = pow<-5>(base, policy<overflow_error<user_error> >()); // We can now test the returned value and treat the special case if needed: if (result == -1) { // there was an error, do something... }
Another way is to redefine the default // Redefine the default error_overflow policy #define BOOST_MATH_OVERFLOW_ERROR_POLICY user_error #include <boost/math/special_functions/pow.hpp> // From this point, passing a policy in argument is no longer needed, a call like this one // will return -1 in case of error: double result = pow<-5>(base); AcknowledgementsBruno Lalande submitted this addition to Boost.Math. Thanks to Joaqu?n L?pez Mu?oz and Scott McMurray for their help in improving the implementation. ReferencesD.E. Knuth, The Art of Computer Programming, Vol. 2: Seminumerical Algorithms, 2nd ed., Addison-Wesley, Reading, MA, 1981 |