ceph/src/boost/libs/math/doc/html/math_toolkit/powers/ct_pow.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Compile Time Power of a Runtime Base</title>
   5 <link rel="stylesheet" href="../../math.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
   7 <link rel="home" href="../../index.html" title="Math Toolkit 2.5.1">
   8 <link rel="up" href="../powers.html" title="Basic Functions">
   9 <link rel="prev" href="hypot.html" title="hypot">
  10 <link rel="next" href="../sinc.html" title="Sinus Cardinal and Hyperbolic Sinus Cardinal Functions">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <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>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h3 class="title">
  27 <a name="math_toolkit.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
  28       Base</a>
  29 </h3></div></div></div>
  30 <p>
  31         The <code class="computeroutput"><span class="identifier">pow</span></code> function effectively
  32         computes the compile-time integral power of a run-time base.
  33       </p>
  34 <h5>
  35 <a name="math_toolkit.powers.ct_pow.h0"></a>
  36         <span class="phrase"><a name="math_toolkit.powers.ct_pow.synopsis"></a></span><a class="link" href="ct_pow.html#math_toolkit.powers.ct_pow.synopsis">Synopsis</a>
  37       </h5>
  38 <p>
  39         <a href="../../../../../../boost/math/special_functions/pow.hpp" target="_top"><code class="computeroutput"><span class="preprocessor">#include</span> <span class="special">&lt;</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">&gt;</span></code></a>
  40       </p>
  41 <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>
  42
  43 <span class="keyword">template</span> <span class="special">&lt;</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">&gt;</span>
  44 <a class="link" href="../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>
  45
  46 <span class="keyword">template</span> <span class="special">&lt;</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">&gt;</span>
  47 <a class="link" href="../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">&amp;</span> <span class="identifier">policy</span><span class="special">);</span>
  48
  49 <span class="special">}}</span>
  50 </pre>
  51 <h5>
  52 <a name="math_toolkit.powers.ct_pow.h1"></a>
  53         <span class="phrase"><a name="math_toolkit.powers.ct_pow.rationale_and_usage"></a></span><a class="link" href="ct_pow.html#math_toolkit.powers.ct_pow.rationale_and_usage">Rationale
  54         and Usage</a>
  55       </h5>
  56 <p>
  57         Computing the power of a number with an exponent that is known at compile
  58         time is a common need for programmers. In such cases, the usual method is
  59         to avoid the overhead implied by the <code class="computeroutput"><span class="identifier">pow</span></code>,
  60         <code class="computeroutput"><span class="identifier">powf</span></code> and <code class="computeroutput"><span class="identifier">powl</span></code>
  61         C functions by hardcoding an expression such as:
  62       </p>
  63 <pre class="programlisting"><span class="comment">// Hand-written 8th power of a 'base' variable</span>
  64 <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>
  65 </pre>
  66 <p>
  67         However, this kind of expression is not really readable (knowing the value
  68         of the exponent involves counting the number of occurrences of <span class="emphasis"><em>base</em></span>),
  69         error-prone (it's easy to forget an occurrence), syntactically bulky, and
  70         non-optimal in terms of performance.
  71       </p>
  72 <p>
  73         The pow function of Boost.Math helps writing this kind expression along with
  74         solving all the problems listed above:
  75       </p>
  76 <pre class="programlisting"><span class="comment">// 8th power of a 'base' variable using math::pow</span>
  77 <span class="keyword">double</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">pow</span><span class="special">&lt;</span><span class="number">8</span><span class="special">&gt;(</span><span class="identifier">base</span><span class="special">);</span>
  78 </pre>
  79 <p>
  80         The expression is now shorter, easier to read, safer, and even faster. Indeed,
  81         <code class="computeroutput"><span class="identifier">pow</span></code> will compute the expression
  82         such that only log2(N) products are made for a power of N. For instance in
  83         the example above, the resulting expression will be the same as if we had
  84         written this, with only one computation of each identical subexpression:
  85       </p>
  86 <pre class="programlisting"><span class="comment">// Internal effect of pow&lt;8&gt;(base)</span>
  87 <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>
  88 </pre>
  89 <p>
  90         Only 3 different products were actually computed.
  91       </p>
  92 <h5>
  93 <a name="math_toolkit.powers.ct_pow.h2"></a>
  94         <span class="phrase"><a name="math_toolkit.powers.ct_pow.return_type"></a></span><a class="link" href="ct_pow.html#math_toolkit.powers.ct_pow.return_type">Return
  95         Type</a>
  96       </h5>
  97 <p>
  98         The return type of these functions is computed using the <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
  99         type calculation rules</em></span></a>. For example:
 100       </p>
 101 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 102 <li class="listitem">
 103             If T is a <code class="computeroutput"><span class="keyword">float</span></code>, the return
 104             type is a <code class="computeroutput"><span class="keyword">float</span></code>.
 105           </li>
 106 <li class="listitem">
 107             If T is a <code class="computeroutput"><span class="keyword">long</span> <span class="keyword">double</span></code>,
 108             the return type is a <code class="computeroutput"><span class="keyword">long</span> <span class="keyword">double</span></code>.
 109           </li>
 110 <li class="listitem">
 111             Otherwise, the return type is a <code class="computeroutput"><span class="keyword">double</span></code>.
 112           </li>
 113 </ul></div>
 114 <h5>
 115 <a name="math_toolkit.powers.ct_pow.h3"></a>
 116         <span class="phrase"><a name="math_toolkit.powers.ct_pow.policies"></a></span><a class="link" href="ct_pow.html#math_toolkit.powers.ct_pow.policies">Policies</a>
 117       </h5>
 118 <p>
 119         The final <a class="link" href="../../policy.html" title="Chapter&#160;15.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a> argument is optional and can
 120         be used to control the behaviour of the function: how it handles errors,
 121         what level of precision to use etc. Refer to the <a class="link" href="../../policy.html" title="Chapter&#160;15.&#160;Policies: Controlling Precision, Error Handling etc">policy
 122         documentation for more details</a>.
 123       </p>
 124 <h5>
 125 <a name="math_toolkit.powers.ct_pow.h4"></a>
 126         <span class="phrase"><a name="math_toolkit.powers.ct_pow.error_handling"></a></span><a class="link" href="ct_pow.html#math_toolkit.powers.ct_pow.error_handling">Error
 127         Handling</a>
 128       </h5>
 129 <p>
 130         Two cases of errors can occur when using <code class="computeroutput"><span class="identifier">pow</span></code>:
 131       </p>
 132 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 133 <li class="listitem">
 134             In case of null base and negative exponent, an <a class="link" href="../error_handling.html#math_toolkit.error_handling.overflow_error">overflow_error</a>
 135             occurs since this operation is a division by 0 (it equals to 1/0).
 136           </li>
 137 <li class="listitem">
 138             In case of null base and null exponent, an <a class="link" href="../error_handling.html#math_toolkit.error_handling.indeterminate_result_error">indeterminate_result_error</a>
 139             occurs since the result of this operation is indeterminate. Those errors
 140             follow the <a class="link" href="../error_handling.html" title="Error Handling">general policies
 141             of error handling in Boost.Math</a>.
 142           </li>
 143 </ul></div>
 144 <p>
 145         The default overflow error policy is <code class="computeroutput"><span class="identifier">throw_on_error</span></code>.
 146         A call like <code class="computeroutput"><span class="identifier">pow</span><span class="special">&lt;-</span><span class="number">2</span><span class="special">&gt;(</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>
 147         exception. As shown in the link given above, other error handling policies
 148         can be used:
 149       </p>
 150 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 151 <li class="listitem">
 152             <code class="computeroutput"><span class="identifier">errno_on_error</span></code>: Sets
 153             <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code>
 154             to <code class="computeroutput"><span class="identifier">ERANGE</span></code> and returns
 155             <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">infinity</span><span class="special">()</span></code>.
 156           </li>
 157 <li class="listitem">
 158             <code class="computeroutput"><span class="identifier">ignore_error</span></code>: Returns
 159             <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">infinity</span><span class="special">()</span></code>.
 160           </li>
 161 <li class="listitem">
 162             <code class="computeroutput"><span class="identifier">user_error</span></code>: Returns the
 163             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
 164             must be defined by the user.
 165           </li>
 166 </ul></div>
 167 <p>
 168         The default indeterminate result error policy is <code class="computeroutput"><span class="identifier">ignore_error</span></code>,
 169         which for this function returns 1 since it's the most commonly chosen result
 170         for a power of 0. Here again, other error handling policies can be used:
 171       </p>
 172 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 173 <li class="listitem">
 174             <code class="computeroutput"><span class="identifier">throw_on_error</span></code>: Throws
 175             <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">domain_error</span></code>
 176           </li>
 177 <li class="listitem">
 178             <code class="computeroutput"><span class="identifier">errno_on_error</span></code>: Sets
 179             <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code>
 180             to <code class="computeroutput"><span class="identifier">EDOM</span></code> and returns 1.
 181           </li>
 182 <li class="listitem">
 183             <code class="computeroutput"><span class="identifier">user_error</span></code>: Returns the
 184             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
 185             function must be defined by the user.
 186           </li>
 187 </ul></div>
 188 <p>
 189         Here is an example of error handling customization where we want to specify
 190         the result that has to be returned in case of error. We will thus use the
 191         <code class="computeroutput"><span class="identifier">user_error</span></code> policy, by passing
 192         as second argument an instance of an overflow_error policy templated with
 193         <code class="computeroutput"><span class="identifier">user_error</span></code>:
 194       </p>
 195 <pre class="programlisting"><span class="comment">// First we open the boost::math::policies namespace and define the `user_overflow_error`</span>
 196 <span class="comment">// by making it return the value we want in case of error (-1 here)</span>
 197
 198 <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>
 199 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
 200 <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">&amp;)</span>
 201 <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>
 202 <span class="special">}}}</span>
 203
 204
 205 <span class="comment">// Then we invoke pow and indicate that we want to use the user_error policy</span>
 206 <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>
 207 <span class="keyword">double</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">pow</span><span class="special">&lt;-</span><span class="number">5</span><span class="special">&gt;(</span><span class="identifier">base</span><span class="special">,</span> <span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">overflow_error</span><span class="special">&lt;</span><span class="identifier">user_error</span><span class="special">&gt;</span> <span class="special">&gt;());</span>
 208
 209 <span class="comment">// We can now test the returned value and treat the special case if needed:</span>
 210 <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>
 211 <span class="special">{</span>
 212     <span class="comment">// there was an error, do something...</span>
 213 <span class="special">}</span>
 214 </pre>
 215 <p>
 216         Another way is to redefine the default <code class="computeroutput"><span class="identifier">overflow_error</span></code>
 217         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
 218         as above, we can achieve the same result like this:
 219       </p>
 220 <pre class="programlisting"><span class="comment">// Redefine the default error_overflow policy</span>
 221 <span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_OVERFLOW_ERROR_POLICY</span> <span class="identifier">user_error</span>
 222 <span class="preprocessor">#include</span> <span class="special">&lt;</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">&gt;</span>
 223
 224 <span class="comment">// From this point, passing a policy in argument is no longer needed, a call like this one</span>
 225 <span class="comment">// will return -1 in case of error:</span>
 226
 227 <span class="keyword">double</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">pow</span><span class="special">&lt;-</span><span class="number">5</span><span class="special">&gt;(</span><span class="identifier">base</span><span class="special">);</span>
 228 </pre>
 229 <h5>
 230 <a name="math_toolkit.powers.ct_pow.h5"></a>
 231         <span class="phrase"><a name="math_toolkit.powers.ct_pow.acknowledgements"></a></span><a class="link" href="ct_pow.html#math_toolkit.powers.ct_pow.acknowledgements">Acknowledgements</a>
 232       </h5>
 233 <p>
 234         Bruno Lalande submitted this addition to Boost.Math.
 235       </p>
 236 <p>
 237         Thanks to Joaqu&#237;n L&#243;pez Mu&#241;oz and Scott McMurray for their help in
 238 improving the implementation.
 239       </p>
 240 <h5>
 241 <a name="math_toolkit.powers.ct_pow.h6"></a>
 242         <span class="phrase"><a name="math_toolkit.powers.ct_pow.references"></a></span><a class="link" href="ct_pow.html#math_toolkit.powers.ct_pow.references">References</a>
 243       </h5>
 244 <p>
 245         D.E. Knuth, <span class="emphasis"><em>The Art of Computer Programming, Vol. 2: Seminumerical
 246         Algorithms</em></span>, 2nd ed., Addison-Wesley, Reading, MA, 1981
 247       </p>
 248 </div>
 249 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 250 <td align="left"></td>
 251 <td align="right"><div class="copyright-footer">Copyright &#169; 2006-2010, 2012-2014 Nikhar Agrawal,
 252       Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert
 253       Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Johan R&#229;de, Gautam Sewani,
 254       Benjamin Sobotta, Thijs van den Berg, Daryle Walker and Xiaogang Zhang<p>
 255         Distributed under the Boost Software License, Version 1.0. (See accompanying
 256         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>)
 257       </p>
 258 </div></td>
 259 </tr></table>
 260 <hr>
 261 <div class="spirit-nav">
 262 <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>
 263 </div>
 264 </body>
 265 </html>