1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Obtaining the Size of a Unit In the Last Place - ULP</title> 5<link rel="stylesheet" href="../../math.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../../index.html" title="Math Toolkit 2.12.0"> 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_advance.html" title="Advancing a floating-point Value by a Specific Representation Distance (ULP) float_advance"> 10<link rel="next" href="../float_comparison.html" title="Floating-point Comparison"> 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_advance.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_comparison.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.next_float.ulp"></a><a class="link" href="ulp.html" title="Obtaining the Size of a Unit In the Last Place - ULP">Obtaining the Size of a 28 Unit In the Last Place - ULP</a> 29</h3></div></div></div> 30<p> 31 Function <code class="computeroutput"><span class="identifier">ulp</span></code> gives the size 32 of a unit-in-the-last-place for a specified floating-point value. 33 </p> 34<h5> 35<a name="math_toolkit.next_float.ulp.h0"></a> 36 <span class="phrase"><a name="math_toolkit.next_float.ulp.synopsis"></a></span><a class="link" href="ulp.html#math_toolkit.next_float.ulp.synopsis">Synopsis</a> 37 </h5> 38<pre class="programlisting"><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">ulp</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 39</pre> 40<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> 41 42<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">FPT</span><span class="special">></span> 43<span class="identifier">FPT</span> <span class="identifier">ulp</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">FPT</span><span class="special">&</span> <span class="identifier">x</span><span class="special">);</span> 44 45<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">FPT</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policy</span><span class="special">></span> 46<span class="identifier">FPT</span> <span class="identifier">ulp</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">FPT</span><span class="special">&</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Policy</span><span class="special">&);</span> 47 48<span class="special">}}</span> <span class="comment">// namespaces</span> 49</pre> 50<h5> 51<a name="math_toolkit.next_float.ulp.h1"></a> 52 <span class="phrase"><a name="math_toolkit.next_float.ulp.description_ulp"></a></span><a class="link" href="ulp.html#math_toolkit.next_float.ulp.description_ulp">Description 53 - ulp</a> 54 </h5> 55<p> 56 Returns one <a href="http://en.wikipedia.org/wiki/Unit_in_the_last_place" target="_top">unit 57 in the last place</a> of <span class="emphasis"><em>x</em></span>. 58 </p> 59<p> 60 Corner cases are handled as follows: 61 </p> 62<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 63<li class="listitem"> 64 If the argument is a NaN, then raises a <a class="link" href="../error_handling.html#math_toolkit.error_handling.domain_error">domain_error</a>. 65 </li> 66<li class="listitem"> 67 If the argument is an infinity, then raises an <a class="link" href="../error_handling.html#math_toolkit.error_handling.overflow_error">overflow_error</a>. 68 </li> 69<li class="listitem"> 70 If the argument is zero then returns the smallest representable value: 71 for example for type <code class="computeroutput"><span class="keyword">double</span></code> 72 this would be either <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special"><</span><span class="keyword">double</span><span class="special">>::</span><span class="identifier">min</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special"><</span><span class="keyword">double</span><span class="special">>::</span><span class="identifier">denorm_min</span><span class="special">()</span></code> depending whether denormals are supported 73 (which have the values <code class="computeroutput"><span class="number">2.2250738585072014e-308</span></code> 74 and <code class="computeroutput"><span class="number">4.9406564584124654e-324</span></code> 75 respectively). 76 </li> 77<li class="listitem"> 78 If the result is too small to represent, then returns the smallest representable 79 value. 80 </li> 81<li class="listitem"> 82 Always returns a positive value such that <code class="computeroutput"><span class="identifier">ulp</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">==</span> <span class="identifier">ulp</span><span class="special">(-</span><span class="identifier">x</span><span class="special">)</span></code>. 83 </li> 84</ul></div> 85<p> 86 <span class="bold"><strong>Important:</strong></span> The behavior of this function 87 is aligned to that of <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Math.html#ulp%28double%29" target="_top">Java's 88 ulp function</a>, please note however that this function should only 89 ever be used for rough and ready calculations as there are enough corner 90 cases to trap even careful programmers. In particular: 91 </p> 92<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 93<li class="listitem"> 94 The function is asymmetrical, which is to say, given <code class="computeroutput"><span class="identifier">u</span> 95 <span class="special">=</span> <span class="identifier">ulp</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span></code> if <code class="computeroutput"><span class="identifier">x</span> 96 <span class="special">></span> <span class="number">0</span></code> 97 then <code class="computeroutput"><span class="identifier">x</span> <span class="special">+</span> 98 <span class="identifier">u</span></code> is the next floating-point 99 value, but <code class="computeroutput"><span class="identifier">x</span> <span class="special">-</span> 100 <span class="identifier">u</span></code> is not necessarily the previous 101 value. Similarly, if <code class="computeroutput"><span class="identifier">x</span> <span class="special"><</span> <span class="number">0</span></code> 102 then <code class="computeroutput"><span class="identifier">x</span> <span class="special">-</span> 103 <span class="identifier">u</span></code> is the previous floating-point 104 value, but <code class="computeroutput"><span class="identifier">x</span> <span class="special">+</span> 105 <span class="identifier">u</span></code> is not necessarily the next 106 value. The corner cases occur at power of 2 boundaries. 107 </li> 108<li class="listitem"> 109 When the argument becomes very small, it may be that there is no floating-point 110 value that represents one ULP. Whether this is the case or not depends 111 not only on whether the hardware may <span class="emphasis"><em>sometimes</em></span> support 112 denormals (as signalled by <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">FPT</span><span class="special">>::</span><span class="identifier">has_denorm</span></code>), 113 but also whether these are currently enabled at runtime (for example 114 on SSE hardware, the DAZ or FTZ flags will disable denormal support). 115 In this situation, the <code class="computeroutput"><span class="identifier">ulp</span></code> 116 function may return a value that is many orders of magnitude too large. 117 </li> 118</ul></div> 119<p> 120 In light of the issues above, we recommend that: 121 </p> 122<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 123<li class="listitem"> 124 To move between adjacent floating-point values always use <a class="link" href="float_next.html" title="Finding the Next Greater Representable Value (float_next)">float_next</a>, 125 <a class="link" href="float_prior.html" title="Finding the Next Smaller Representable Value (float_prior)">float_prior</a> 126 or <a class="link" href="nextafter.html" title="Finding the Next Representable Value in a Specific Direction (nextafter)">nextafter</a> 127 (<code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">nextafter</span></code> is another candidate, but 128 our experience is that this also often breaks depending which optimizations 129 and hardware flags are in effect). 130 </li> 131<li class="listitem"> 132 To move several floating-point values away use <a class="link" href="float_advance.html" title="Advancing a floating-point Value by a Specific Representation Distance (ULP) float_advance">float_advance</a>. 133 </li> 134<li class="listitem"> 135 To calculate the edit distance between two floats use <a href="../../../../../../libs/math/doc/html/math_toolkit/next_float/float_distance.html" target="_top">Boost.Math 136 float_distance</a>. 137 </li> 138</ul></div> 139<p> 140 There is none the less, one important use case for this function: 141 </p> 142<p> 143 If it is known that the true result of some function is x<sub>t</sub> and the calculated 144 result is x<sub>c</sub>, then the error measured in ulp is simply <code class="literal">fabs(x<sub>t</sub> - 145 x<sub>c</sub>) / ulp(x<sub>t</sub>)</code>. 146 </p> 147</div> 148<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 149<td align="left"></td> 150<td align="right"><div class="copyright-footer">Copyright © 2006-2019 Nikhar 151 Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, 152 Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan 153 Råde, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg, 154 Daryle Walker and Xiaogang Zhang<p> 155 Distributed under the Boost Software License, Version 1.0. (See accompanying 156 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>) 157 </p> 158</div></td> 159</tr></table> 160<hr> 161<div class="spirit-nav"> 162<a accesskey="p" href="float_advance.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_comparison.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 163</div> 164</body> 165</html> 166
