[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 <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 <int N, typename T>
    <depends_on_T> pow(T base);

    template <int N, typename T, class Policy>
    <depends_on_T> 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]