| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> |
| <title>Compile Time Power of a Runtime Base</title> |
| <link rel="stylesheet" href="../../../../../../../../doc/src/boostbook.css" type="text/css"> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.74.0"> |
| <link rel="home" href="../../../index.html" title="Math Toolkit"> |
| <link rel="up" href="../powers.html" title="Logs, Powers, Roots and Exponentials"> |
| <link rel="prev" href="hypot.html" title="hypot"> |
| <link rel="next" href="../sinc.html" title="Sinus Cardinal and Hyperbolic Sinus Cardinal Functions"> |
| </head> |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| <table cellpadding="2" width="100%"><tr> |
| <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td> |
| <td align="center"><a href="../../../../../../../../index.html">Home</a></td> |
| <td align="center"><a href="../../../../../../../../libs/libraries.htm">Libraries</a></td> |
| <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> |
| <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> |
| <td align="center"><a href="../../../../../../../../more/index.htm">More</a></td> |
| </tr></table> |
| <hr> |
| <div class="spirit-nav"> |
| <a accesskey="p" href="hypot.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../powers.html"><img src="../../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../sinc.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a> |
| </div> |
| <div class="section" lang="en"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="math_toolkit.special.powers.ct_pow"></a><a class="link" href="ct_pow.html" title="Compile Time Power of a Runtime Base"> Compile Time Power |
| of a Runtime Base</a> |
| </h4></div></div></div> |
| <p> |
| The <code class="computeroutput"><span class="identifier">pow</span></code> function effectively |
| computes the compile-time integral power of a run-time base. |
| </p> |
| <a name="math_toolkit.special.powers.ct_pow.synopsis"></a><h5> |
| <a name="id1149008"></a> |
| <a class="link" href="ct_pow.html#math_toolkit.special.powers.ct_pow.synopsis">Synopsis</a> |
| </h5> |
| <p> |
| <a href="../../../../../../../../boost/math/special_functions/pow.hpp" target="_top"><code class="computeroutput"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">pow</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code></a> |
| </p> |
| <pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span> <span class="special">{</span> |
| |
| <span class="keyword">template</span> <span class="special"><</span><span class="keyword">int</span> <span class="identifier">N</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">T</span><span class="special">></span> |
| <a class="link" href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">pow</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">base</span><span class="special">);</span> |
| |
| <span class="keyword">template</span> <span class="special"><</span><span class="keyword">int</span> <span class="identifier">N</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policy</span><span class="special">></span> |
| <a class="link" href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">pow</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">base</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Policy</span><span class="special">&</span> <span class="identifier">policy</span><span class="special">);</span> |
| |
| <span class="special">}}</span> |
| </pre> |
| <a name="math_toolkit.special.powers.ct_pow.rationale_and_usage"></a><h5> |
| <a name="id1149270"></a> |
| <a class="link" href="ct_pow.html#math_toolkit.special.powers.ct_pow.rationale_and_usage">Rationale |
| and Usage</a> |
| </h5> |
| <p> |
| 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 <code class="computeroutput"><span class="identifier">pow</span></code>, |
| <code class="computeroutput"><span class="identifier">powf</span></code> and <code class="computeroutput"><span class="identifier">powl</span></code> C functions by hardcoding an expression |
| such as: |
| </p> |
| <pre class="programlisting"><span class="comment">// Hand-written 8th power of a 'base' variable |
| </span><span class="keyword">double</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">base</span><span class="special">*</span><span class="identifier">base</span><span class="special">*</span><span class="identifier">base</span><span class="special">*</span><span class="identifier">base</span><span class="special">*</span><span class="identifier">base</span><span class="special">*</span><span class="identifier">base</span><span class="special">*</span><span class="identifier">base</span><span class="special">*</span><span class="identifier">base</span><span class="special">;</span> |
| </pre> |
| <p> |
| However, this kind of expression is not really readable (knowing the value |
| of the exponent involves counting the number of occurrences of <span class="emphasis"><em>base</em></span>), |
| error-prone (it's easy to forget an occurrence), syntactically bulky, and |
| non-optimal in terms of performance. |
| </p> |
| <p> |
| The pow function of Boost.Math helps writing this kind expression along |
| with solving all the problems listed above: |
| </p> |
| <pre class="programlisting"><span class="comment">// 8th power of a 'base' variable using math::pow |
| </span><span class="keyword">double</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">pow</span><span class="special"><</span><span class="number">8</span><span class="special">>(</span><span class="identifier">base</span><span class="special">);</span> |
| </pre> |
| <p> |
| The expression is now shorter, easier to read, safer, and even faster. |
| Indeed, <code class="computeroutput"><span class="identifier">pow</span></code> 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: |
| </p> |
| <pre class="programlisting"><span class="comment">// Internal effect of pow<8>(base) |
| </span><span class="keyword">double</span> <span class="identifier">result</span> <span class="special">=</span> <span class="special">((</span><span class="identifier">base</span><span class="special">*</span><span class="identifier">base</span><span class="special">)*(</span><span class="identifier">base</span><span class="special">*</span><span class="identifier">base</span><span class="special">))*((</span><span class="identifier">base</span><span class="special">*</span><span class="identifier">base</span><span class="special">)*(</span><span class="identifier">base</span><span class="special">*</span><span class="identifier">base</span><span class="special">));</span> |
| </pre> |
| <p> |
| Only 3 different products were actually computed. |
| </p> |
| <a name="math_toolkit.special.powers.ct_pow.return_type"></a><h5> |
| <a name="id1149542"></a> |
| <a class="link" href="ct_pow.html#math_toolkit.special.powers.ct_pow.return_type">Return Type</a> |
| </h5> |
| <p> |
| The return type of these functions is computed using the <a class="link" href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result |
| type calculation rules</em></span></a>. For example: |
| </p> |
| <div class="itemizedlist"><ul type="disc"> |
| <li> |
| If T is a <code class="computeroutput"><span class="keyword">float</span></code>, the return |
| type is a <code class="computeroutput"><span class="keyword">float</span></code>. |
| </li> |
| <li> |
| If T is a <code class="computeroutput"><span class="keyword">long</span> <span class="keyword">double</span></code>, |
| the return type is a <code class="computeroutput"><span class="keyword">long</span> <span class="keyword">double</span></code>. |
| </li> |
| <li> |
| Otherwise, the return type is a <code class="computeroutput"><span class="keyword">double</span></code>. |
| </li> |
| </ul></div> |
| <a name="math_toolkit.special.powers.ct_pow.policies"></a><h5> |
| <a name="id1149636"></a> |
| <a class="link" href="ct_pow.html#math_toolkit.special.powers.ct_pow.policies">Policies</a> |
| </h5> |
| <p> |
| </p> |
| <p> |
| The final <a class="link" href="../../policy.html" title="Policies">Policy</a> 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 |
| <a class="link" href="../../policy.html" title="Policies">policy documentation for more details</a>. |
| </p> |
| <p> |
| </p> |
| <a name="math_toolkit.special.powers.ct_pow.error_handling"></a><h5> |
| <a name="id1149666"></a> |
| <a class="link" href="ct_pow.html#math_toolkit.special.powers.ct_pow.error_handling">Error |
| Handling</a> |
| </h5> |
| <p> |
| Two cases of errors can occur when using <code class="computeroutput"><span class="identifier">pow</span></code>: |
| </p> |
| <div class="itemizedlist"><ul type="disc"> |
| <li> |
| In case of null base and negative exponent, an <a class="link" href="../../main_overview/error_handling.html#overflow_error">overflow_error</a> |
| occurs since this operation is a division by 0 (it equals to 1/0). |
| </li> |
| <li> |
| In case of null base and null exponent, an <a class="link" href="../../main_overview/error_handling.html#indeterminate_result_error">indeterminate_result_error</a> |
| occurs since the result of this operation is indeterminate. Those errors |
| follow the <a class="link" href="../../main_overview/error_handling.html" title="Error Handling">general |
| policies of error handling in Boost.Math</a>. |
| </li> |
| </ul></div> |
| <p> |
| The default overflow error policy is <code class="computeroutput"><span class="identifier">throw_on_error</span></code>. |
| A call like <code class="computeroutput"><span class="identifier">pow</span><span class="special"><-</span><span class="number">2</span><span class="special">>(</span><span class="number">0</span><span class="special">)</span></code> will thus throw a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">overflow_error</span></code> |
| exception. As shown in the link given above, other error handling policies |
| can be used: |
| </p> |
| <div class="itemizedlist"><ul type="disc"> |
| <li> |
| <code class="computeroutput"><span class="identifier">errno_on_error</span></code>: Sets |
| <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code> |
| to <code class="computeroutput"><span class="identifier">ERANGE</span></code> and returns |
| <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">infinity</span><span class="special">()</span></code>. |
| </li> |
| <li> |
| <code class="computeroutput"><span class="identifier">ignore_error</span></code>: Returns |
| <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">infinity</span><span class="special">()</span></code>. |
| </li> |
| <li> |
| <code class="computeroutput"><span class="identifier">user_error</span></code>: Returns |
| the result of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">user_overflow_error</span></code>: |
| this function must be defined by the user. |
| </li> |
| </ul></div> |
| <p> |
| The default indeterminate result error policy is <code class="computeroutput"><span class="identifier">ignore_error</span></code>, |
| which for this function returns 1 since it's the most commonly chosen result |
| for a power of 0. Here again, other error handling policies can be used: |
| </p> |
| <div class="itemizedlist"><ul type="disc"> |
| <li> |
| <code class="computeroutput"><span class="identifier">throw_on_error</span></code>: Throws |
| <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">domain_error</span></code> |
| </li> |
| <li> |
| <code class="computeroutput"><span class="identifier">errno_on_error</span></code>: Sets |
| <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code> |
| to <code class="computeroutput"><span class="identifier">EDOM</span></code> and returns |
| 1. |
| </li> |
| <li> |
| <code class="computeroutput"><span class="identifier">user_error</span></code>: Returns |
| the result of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">user_indeterminate_result_error</span></code>: |
| this function must be defined by the user. |
| </li> |
| </ul></div> |
| <p> |
| 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 |
| <code class="computeroutput"><span class="identifier">user_error</span></code> policy, by passing |
| as second argument an instance of an overflow_error policy templated with |
| <code class="computeroutput"><span class="identifier">user_error</span></code>: |
| </p> |
| <pre class="programlisting"><span class="comment">// First we open the boost::math::policies namespace and define the `user_overflow_error` |
| </span><span class="comment">// by making it return the value we want in case of error (-1 here) |
| </span> |
| <span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">policies</span> <span class="special">{</span> |
| <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> |
| <span class="identifier">T</span> <span class="identifier">user_overflow_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&)</span> |
| <span class="special">{</span> <span class="keyword">return</span> <span class="special">-</span><span class="number">1</span><span class="special">;</span> <span class="special">}</span> |
| <span class="special">}}}</span> |
| |
| |
| <span class="comment">// Then we invoke pow and indicate that we want to use the user_error policy |
| </span><span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span> |
| <span class="keyword">double</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">pow</span><span class="special"><-</span><span class="number">5</span><span class="special">>(</span><span class="identifier">base</span><span class="special">,</span> <span class="identifier">policy</span><span class="special"><</span><span class="identifier">overflow_error</span><span class="special"><</span><span class="identifier">user_error</span><span class="special">></span> <span class="special">>());</span> |
| |
| <span class="comment">// We can now test the returned value and treat the special case if needed: |
| </span><span class="keyword">if</span> <span class="special">(</span><span class="identifier">result</span> <span class="special">==</span> <span class="special">-</span><span class="number">1</span><span class="special">)</span> |
| <span class="special">{</span> |
| <span class="comment">// there was an error, do something... |
| </span><span class="special">}</span> |
| </pre> |
| <p> |
| Another way is to redefine the default <code class="computeroutput"><span class="identifier">overflow_error</span></code> |
| policy by using the BOOST_MATH_OVERFLOW_ERROR_POLICY macro. Once the <code class="computeroutput"><span class="identifier">user_overflow_error</span></code> function is defined |
| as above, we can achieve the same result like this: |
| </p> |
| <pre class="programlisting"><span class="comment">// Redefine the default error_overflow policy |
| </span><span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_OVERFLOW_ERROR_POLICY</span> <span class="identifier">user_error</span> |
| <span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">pow</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> |
| |
| <span class="comment">// From this point, passing a policy in argument is no longer needed, a call like this one |
| </span><span class="comment">// will return -1 in case of error: |
| </span> |
| <span class="keyword">double</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">pow</span><span class="special"><-</span><span class="number">5</span><span class="special">>(</span><span class="identifier">base</span><span class="special">);</span> |
| </pre> |
| <a name="math_toolkit.special.powers.ct_pow.acknowledgements"></a><h5> |
| <a name="id1151189"></a> |
| <a class="link" href="ct_pow.html#math_toolkit.special.powers.ct_pow.acknowledgements">Acknowledgements</a> |
| </h5> |
| <p> |
| Bruno Lalande submitted this addition to Boost.Math. |
| </p> |
| <p> |
| Thanks to Joaquín López Muñoz and Scott McMurray for their help in |
| improving the implementation. |
| </p> |
| <a name="math_toolkit.special.powers.ct_pow.references"></a><h5> |
| <a name="id1151209"></a> |
| <a class="link" href="ct_pow.html#math_toolkit.special.powers.ct_pow.references">References</a> |
| </h5> |
| <p> |
| D.E. Knuth, <span class="emphasis"><em>The Art of Computer Programming, Vol. 2: Seminumerical |
| Algorithms</em></span>, 2nd ed., Addison-Wesley, Reading, MA, 1981 |
| </p> |
| </div> |
| <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> |
| <td align="left"></td> |
| <td align="right"><div class="copyright-footer">Copyright © 2006 , 2007, 2008, 2009, 2010 John Maddock, Paul A. Bristow, |
| Hubert Holin, Xiaogang Zhang, Bruno Lalande, Johan Råde, Gautam Sewani and |
| Thijs van den Berg<p> |
| Distributed under the Boost Software License, Version 1.0. (See accompanying |
| file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) |
| </p> |
| </div></td> |
| </tr></table> |
| <hr> |
| <div class="spirit-nav"> |
| <a accesskey="p" href="hypot.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../powers.html"><img src="../../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../sinc.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a> |
| </div> |
| </body> |
| </html> |
