[section pow] [section Rationale] Computing the power of a number with an exponent that is fixed and known in advance is a common need for programmers. In such cases, the usual method is to avoid the overhead implied by the pow, powf and powl C functions by hardcoding the expression: `` // 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 occurences of 'base'), error-prone (it's easy to forget an occurence), 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, pow will compute the expression such that only log2(N) products are made for a power of N. For instance in the example above, the resulting expression will be the same as if we had written this, with only one computation of each identical subexpression: `` // Internal effect of pow<8>(base) double result = ((base*base)*(base*base))*((base*base)*(base*base)); `` Only 3 different products were actually computed. [endsect] [section Return type] The return type depends on the type T of the argument passed to `pow`: * If T is a `float`, the return type is a `float`. * If T is a `long double`, the return type is a `long double`. * Otherwise, the return type is a `double`. [endsect] [section Error handling] In the case where a `pow` is called with a null base and a negative exponent, an error occurs since this operation is a division by 0 (it equals to 1/0). The error raised is an `overflow error` following the [@sf_and_dist/html/math_toolkit/main_overview/error_handling.html policies of error handling in Boost.Math]. The default overflow error policy is throw_on_error. A call like `pow<-2>(0)` will thus throw a `std::overflow_error` exception. Follow the link given above for a complete description of the different error handling possibilities. [endsect] [section Header File] This function can be used by including [@../../boost/math/pow.hpp ]. [endsect] [section Synopsis] Here is the synopsis of `pow`. As explained above, the return type depends on the type of the argument. The second overload allows to specify a different error handling policy (see section "Error Handling"). `` namespace boost { namespace math { template pow(T base); template pow(T base, const Policy& policy); } } `` [endsect] [section Acknowledgements] Thanks to Joaquín López Muñoz and Scott McMurray for their help in improving the implementation. [endsect] [endsect]