libs/math/doc/sf_and_dist/html/math_toolkit/utils/next_float/float_distance.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Calculating the Representation Distance Between Two Floating Point Values (ULP) float_distance</title>
   5 <link rel="stylesheet" href="../../../../../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="../../../index.html" title="Math Toolkit">
   8 <link rel="up" href="../next_float.html" title="Floating-Point Representation Distance (ULP), and Finding Adjacent Floating-Point Values">
   9 <link rel="prev" href="float_prior.html" title="Finding the Next Smaller Representable Value (float_prior)">
  10 <link rel="next" href="float_advance.html" title="Advancing a Floating Point Value by a Specific Representation Distance (ULP) float_advance">
  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="float_prior.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../next_float.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="float_advance.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section math_toolkit_utils_next_float_float_distance">
  26 <div class="titlepage"><div><div><h4 class="title">
  27 <a name="math_toolkit.utils.next_float.float_distance"></a><a class="link" href="float_distance.html" title="Calculating the Representation Distance Between Two Floating Point Values (ULP) float_distance">Calculating
  28         the Representation Distance Between Two Floating Point Values (ULP) float_distance</a>
  29 </h4></div></div></div>
  30 <p>
  31           Function float_distance finds the number of gaps/bits/ULP between any two
  32           floating-point values. If the significands of floating-point numbers are
  33           viewed as integers, then their difference is the number of ULP/gaps/bits
  34           different.
  35         </p>
  36 <h5>
  37 <a name="math_toolkit.utils.next_float.float_distance.h0"></a>
  38           <span><a name="math_toolkit.utils.next_float.float_distance.synopsis"></a></span><a class="link" href="float_distance.html#math_toolkit.utils.next_float.float_distance.synopsis">Synopsis</a>
  39         </h5>
  40 <p>
  41 </p>
  42 <pre class="programlisting"><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">next</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
  43 </pre>
  44 <p>
  45         </p>
  46 <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>
  47
  48 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">FPT</span><span class="special">&gt;</span>
  49 <span class="identifier">FPT</span> <span class="identifier">float_distance</span><span class="special">(</span><span class="identifier">FPT</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">FPT</span> <span class="identifier">b</span><span class="special">);</span>
  50
  51 <span class="special">}}</span> <span class="comment">// namespaces</span>
  52 </pre>
  53 <h5>
  54 <a name="math_toolkit.utils.next_float.float_distance.h1"></a>
  55           <span><a name="math_toolkit.utils.next_float.float_distance.description___float_distance"></a></span><a class="link" href="float_distance.html#math_toolkit.utils.next_float.float_distance.description___float_distance">Description
  56           - float_distance</a>
  57         </h5>
  58 <p>
  59           Returns the distance between <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>b</em></span>:
  60           the result is always a signed integer value (stored in floating-point type
  61           FPT) representing the number of distinct representations between <span class="emphasis"><em>a</em></span>
  62           and <span class="emphasis"><em>b</em></span>.
  63         </p>
  64 <p>
  65           Note that
  66         </p>
  67 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
  68 <li class="listitem">
  69               <code class="computeroutput"><span class="identifier">float_distance</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span> <span class="identifier">a</span><span class="special">)</span></code>
  70               always returns 0.
  71             </li>
  72 <li class="listitem">
  73               <code class="computeroutput"><span class="identifier">float_distance</span><span class="special">(</span><span class="identifier">float_next</span><span class="special">(</span><span class="identifier">a</span><span class="special">),</span> <span class="identifier">a</span><span class="special">)</span></code>
  74               always returns 1.
  75             </li>
  76 <li class="listitem">
  77               <code class="computeroutput"><span class="identifier">float_distance</span><span class="special">(</span><span class="identifier">float_prior</span><span class="special">(</span><span class="identifier">a</span><span class="special">),</span> <span class="identifier">a</span><span class="special">)</span></code>
  78               always returns -1.
  79             </li>
  80 </ul></div>
  81 <p>
  82           The function <code class="computeroutput"><span class="identifier">float_distance</span></code>
  83           is equivalent to calculating the number of ULP (Units in the Last Place)
  84           between <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>b</em></span> except that it
  85           returns a signed value indicating whether <code class="computeroutput"><span class="identifier">a</span>
  86           <span class="special">&gt;</span> <span class="identifier">b</span></code>
  87           or not.
  88         </p>
  89 <p>
  90           If the distance is too great then it may not be able to be represented
  91           as an exact integer by type FPT, but in practice this is unlikely to be
  92           a issue.
  93         </p>
  94 </div>
  95 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
  96 <td align="left"></td>
  97 <td align="right"><div class="copyright-footer">Copyright &#169; 2006-2010 John Maddock, Paul A. Bristow, Hubert Holin, Xiaogang Zhang, Bruno
  98       Lalande, Johan R&#229;de, Gautam Sewani, Thijs van den Berg and Benjamin Sobotta<p>
  99         Distributed under the Boost Software License, Version 1.0. (See accompanying
 100         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>)
 101       </p>
 102 </div></td>
 103 </tr></table>
 104 <hr>
 105 <div class="spirit-nav">
 106 <a accesskey="p" href="float_prior.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../next_float.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="float_advance.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>
 107 </div>
 108 </body>
 109 </html>