path: root/devdocs/elisp/float-basics.html

 <h3 class="section">Floating-Point Basics</h3>  <p>Floating-point numbers are useful for representing numbers that are not integral. The range of floating-point numbers is the same as the range of the C data type <code>double</code> on the machine you are using. On all computers supported by Emacs, this is <acronym>IEEE</acronym> binary64 floating point format, which is standardized by <a href="https://standards.ieee.org/standard/754-2019.html">IEEE Std 754-2019</a> and is discussed further in David Goldberg’s paper “<a href="https://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html">What Every Computer Scientist Should Know About Floating-Point Arithmetic</a>”. On modern platforms, floating-point operations follow the IEEE-754 standard closely; however, results are not always rounded correctly on some obsolescent platforms, notably 32-bit x86. </p> <p>The read syntax for floating-point numbers requires either a decimal point, an exponent, or both. Optional signs (‘<samp>+</samp>’ or ‘<samp>-</samp>’) precede the number and its exponent. For example, ‘<samp>1500.0</samp>’, ‘<samp>+15e2</samp>’, ‘<samp>15.0e+2</samp>’, ‘<samp>+1500000e-3</samp>’, and ‘<samp>.15e4</samp>’ are five ways of writing a floating-point number whose value is 1500. They are all equivalent. Like Common Lisp, Emacs Lisp requires at least one digit after a decimal point in a floating-point number that does not have an exponent; ‘<samp>1500.</samp>’ is an integer, not a floating-point number. </p> <p>Emacs Lisp treats <code>-0.0</code> as numerically equal to ordinary zero with respect to numeric comparisons like <code>=</code>. This follows the <acronym>IEEE</acronym> floating-point standard, which says <code>-0.0</code> and <code>0.0</code> are numerically equal even though other operations can distinguish them. </p>     <p>The <acronym>IEEE</acronym> floating-point standard supports positive infinity and negative infinity as floating-point values. It also provides for a class of values called NaN, or “not a number”; numerical functions return such values in cases where there is no correct answer. For example, <code>(/ 0.0 0.0)</code> returns a NaN. A NaN is never numerically equal to any value, not even to itself. NaNs carry a sign and a significand, and non-numeric functions treat two NaNs as equal when their signs and significands agree. Significands of NaNs are machine-dependent, as are the digits in their string representation. </p> <p>When NaNs and signed zeros are involved, non-numeric functions like <code>eql</code>, <code>equal</code>, <code>sxhash-eql</code>, <code>sxhash-equal</code> and <code>gethash</code> determine whether values are indistinguishable, not whether they are numerically equal. For example, when <var>x</var> and <var>y</var> are the same NaN, <code>(equal x y)</code> returns <code>t</code> whereas <code>(= x y)</code> uses numeric comparison and returns <code>nil</code>; conversely, <code>(equal 0.0 -0.0)</code> returns <code>nil</code> whereas <code>(= 0.0 -0.0)</code> returns <code>t</code>. </p> <p>Here are read syntaxes for these special floating-point values: </p> <dl compact> <dt>infinity</dt> <dd><p>‘<samp>1.0e+INF</samp>’ and ‘<samp>-1.0e+INF</samp>’ </p></dd> <dt>not-a-number</dt> <dd><p>‘<samp>0.0e+NaN</samp>’ and ‘<samp>-0.0e+NaN</samp>’ </p></dd> </dl> <p>The following functions are specialized for handling floating-point numbers: </p> <dl> <dt id="isnan">Function: <strong>isnan</strong> <em>x</em>
</dt> <dd><p>This predicate returns <code>t</code> if its floating-point argument is a NaN, <code>nil</code> otherwise. </p></dd>
</dl> <dl> <dt id="frexp">Function: <strong>frexp</strong> <em>x</em>
</dt> <dd>
<p>This function returns a cons cell <code>(<var>s</var> . <var>e</var>)</code>, where <var>s</var> and <var>e</var> are respectively the significand and exponent of the floating-point number <var>x</var>. </p> <p>If <var>x</var> is finite, then <var>s</var> is a floating-point number between 0.5 (inclusive) and 1.0 (exclusive), <var>e</var> is an integer, and <var>x</var> = <var>s</var> * 2**<var>e</var>. If <var>x</var> is zero or infinity, then <var>s</var> is the same as <var>x</var>. If <var>x</var> is a NaN, then <var>s</var> is also a NaN. If <var>x</var> is zero, then <var>e</var> is 0. </p>
</dd>
</dl> <dl> <dt id="ldexp">Function: <strong>ldexp</strong> <em>s e</em>
</dt> <dd><p>Given a numeric significand <var>s</var> and an integer exponent <var>e</var>, this function returns the floating point number <var>s</var> * 2**<var>e</var>. </p></dd>
</dl> <dl> <dt id="copysign">Function: <strong>copysign</strong> <em>x1 x2</em>
</dt> <dd><p>This function copies the sign of <var>x2</var> to the value of <var>x1</var>, and returns the result. <var>x1</var> and <var>x2</var> must be floating point. </p></dd>
</dl> <dl> <dt id="logb">Function: <strong>logb</strong> <em>x</em>
</dt> <dd>
<p>This function returns the binary exponent of <var>x</var>. More precisely, if <var>x</var> is finite and nonzero, the value is the logarithm base 2 of <em>|x|</em>, rounded down to an integer. If <var>x</var> is zero or infinite, the value is infinity; if <var>x</var> is a NaN, the value is a NaN. </p> <div class="example"> <pre class="example">(logb 10)
     ⇒ 3
(logb 10.0e20)
     ⇒ 69
(logb 0)
     ⇒ -1.0e+INF
</pre>
</div> </dd>
</dl><div class="_attribution">
  <p class="_attribution-p">
    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Float-Basics.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Float-Basics.html</a>
  </p>
</div>