<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<link rel="stylesheet" href="style.css" type="text/css">
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<link rel="Start" href="index.html">
<link rel="next" href="Gg.V2.html">
<link rel="Up" href="Gg.html">
<link title="Index of types" rel=Appendix href="index_types.html">
<link title="Index of values" rel=Appendix href="index_values.html">
<link title="Index of modules" rel=Appendix href="index_modules.html">
<link title="Index of module types" rel=Appendix href="index_module_types.html">
<link title="Gg" rel="Chapter" href="Gg.html"><link title="Constants" rel="Section" href="#constants">
<link title="Functions" rel="Section" href="#functions">
<link title="Predicates and comparisons" rel="Section" href="#comparisons">
<link title="Printers" rel="Section" href="#printers">
<link title="Quick recall on OCaml's floats" rel="Section" href="#floatrecall">
<title>Gg.Float</title>
</head>
<body>
<div class="navbar"> <a class="up" href="Gg.html" title="Gg">Up</a>
<a class="post" href="Gg.V2.html" title="Gg.V2">Next</a>
</div>
<h1>Module <a href="type_Gg.Float.html">Gg.Float</a></h1>
<pre><span class="keyword">module</span> Float: <code class="code"><span class="keyword">sig</span></code> <a href="Gg.Float.html">..</a> <code class="code"><span class="keyword">end</span></code></pre><div class="info">
Floating point number utilities.
<p>
This module defines a few useful <a href="Gg.Float.html#constants">constants</a>,
<a href="Gg.Float.html#functions">functions</a>, <a href="Gg.Float.html#comparisons">predicates and
comparisons</a> on floating point numbers. The <a href="Gg.Float.html#printers">printers</a>
output a lossless textual representation of floats.
<p>
<a href="Gg.Float.html#floatrecall">Quick recall</a> on OCaml's floating
point representation.<br>
</div>
<hr width="100%">
<pre><span id="TYPEt"><span class="keyword">type</span> <code class="type"></code>t</span> = <code class="type">float</code> </pre>
<div class="info">
The type for floating point numbers.<br>
</div>
<br>
<h1 id="constants">Constants</h1><br>
<pre><span id="VALe"><span class="keyword">val</span> e</span> : <code class="type">float</code></pre><div class="info">
The constant <a href="http://mathworld.wolfram.com/e.html">e</a>.<br>
</div>
<pre><span id="VALpi"><span class="keyword">val</span> pi</span> : <code class="type">float</code></pre><div class="info">
The constant <a href="http://mathworld.wolfram.com/Pi.html">pi</a>.<br>
</div>
<pre><span id="VALtwo_pi"><span class="keyword">val</span> two_pi</span> : <code class="type">float</code></pre><div class="info">
<code class="code">2 *. pi</code><br>
</div>
<pre><span id="VALpi_div_2"><span class="keyword">val</span> pi_div_2</span> : <code class="type">float</code></pre><div class="info">
<code class="code">pi /. 2</code>.<br>
</div>
<pre><span id="VALpi_div_4"><span class="keyword">val</span> pi_div_4</span> : <code class="type">float</code></pre><div class="info">
<code class="code">pi /. 4</code>.<br>
</div>
<pre><span id="VALinv_pi"><span class="keyword">val</span> inv_pi</span> : <code class="type">float</code></pre><div class="info">
<code class="code">1 /. pi</code>.<br>
</div>
<pre><span id="VALmax_sub_float"><span class="keyword">val</span> max_sub_float</span> : <code class="type">float</code></pre><div class="info">
The greatest positive subnormal floating point number.<br>
</div>
<pre><span id="VALmin_sub_float"><span class="keyword">val</span> min_sub_float</span> : <code class="type">float</code></pre><div class="info">
The smallest positive subnormal floating point number.<br>
</div>
<pre><span id="VALmax_frac_float"><span class="keyword">val</span> max_frac_float</span> : <code class="type">float</code></pre><div class="info">
The greatest positive floating point number with a fractional
part (the <code class="code">float</code> before 2<sup class="superscript">52</sup>). Any number outside
[<code class="code">-max_frac_float;max_frac_float</code>] is an integer.<br>
</div>
<pre><span id="VALmax_int_arith"><span class="keyword">val</span> max_int_arith</span> : <code class="type">float</code></pre><div class="info">
The greatest positive floating point number (2<sup class="superscript">53</sup>) such that
any <em>integer</em> in the range
[<code class="code">-max_int_arith;max_int_arith</code>] is represented exactly.
Integer arithmetic can be performed exactly in this interval.<br>
</div>
<br>
<h1 id="functions">Functions</h1>
<p>
<b>Note.</b> If applicable, a function taking NaNs returns a NaN
unless otherwise specified.<br>
<pre><span id="VALdeg_of_rad"><span class="keyword">val</span> deg_of_rad</span> : <code class="type">float -> float</code></pre><div class="info">
<code class="code">deg_of_rad r</code> is <code class="code">r</code>
<a href="http://mathworld.wolfram.com/Radian.html">radians</a> in
<a href="http://mathworld.wolfram.com/Degree.html">degrees</a>.<br>
</div>
<pre><span id="VALrad_of_deg"><span class="keyword">val</span> rad_of_deg</span> : <code class="type">float -> float</code></pre><div class="info">
<code class="code">rad_of_deg d</code> is <code class="code">d</code>
<a href="http://mathworld.wolfram.com/Degree.html">degrees</a> in
<a href="http://mathworld.wolfram.com/Radian.html">radians</a>.<br>
</div>
<pre><span id="VALwrap_angle"><span class="keyword">val</span> wrap_angle</span> : <code class="type">float -> float</code></pre><div class="info">
<code class="code">wrap_angle r</code> is the angle <code class="code">r</code> in the interval [<code class="code">-pi;pi</code>[.<br>
</div>
<pre><span id="VALrandom"><span class="keyword">val</span> random</span> : <code class="type">?min:float -> len:float -> unit -> float</code></pre><div class="info">
<code class="code">random min len ()</code> is a random float in the interval
[<code class="code">min;min+len</code>] (<code class="code">min</code> defaults to 0.). Uses the standard
library's default <code class="code"><span class="constructor">Random</span></code> state for the generation.
<p>
<b>Warning.</b> The float generated by a given state may
change in future versions of the library.<br>
</div>
<pre><span id="VALsrandom"><span class="keyword">val</span> srandom</span> : <code class="type">Random.State.t -> ?min:float -> len:float -> unit -> float</code></pre><div class="info">
<code class="code">srandom state min len ()</code> is like <a href="Gg.Float.html#VALrandom"><code class="code"><span class="constructor">Gg</span>.<span class="constructor">Float</span>.random</code></a> but uses <code class="code">state</code>
for the generation.
<p>
<b>Warning.</b> The float generated by a given <code class="code">state</code> may
change in future versions of the library.<br>
</div>
<pre><span id="VALmix"><span class="keyword">val</span> mix</span> : <code class="type">float -> float -> float -> float</code></pre><div class="info">
<code class="code">mix x y t</code> is the linear interpolation <code class="code">x +. t *. (y -. x)</code>.<br>
</div>
<pre><span id="VALstep"><span class="keyword">val</span> step</span> : <code class="type">float -> float -> float</code></pre><div class="info">
<code class="code">step edge x</code> is <code class="code">0.</code> if <code class="code">x < edge</code> and <code class="code">1.</code> otherwise. The
result is undefined on NaNs.<br>
</div>
<pre><span id="VALsmooth_step"><span class="keyword">val</span> smooth_step</span> : <code class="type">float -> float -> float -> float</code></pre><div class="info">
<code class="code">smooth_step e0 e1 x</code> is <code class="code">0.</code> if <code class="code">x <= e0</code>, <code class="code">1.</code> if <code class="code">x >= e1</code>
and cubic hermite interpolation between 0. and 1. otherwise. The
result is undefined on NaNs.<br>
</div>
<pre><span id="VALfmax"><span class="keyword">val</span> fmax</span> : <code class="type">float -> float -> float</code></pre><div class="info">
<code class="code">fmax x y</code> is <code class="code">y</code> if <code class="code">x < y</code> and <code class="code">x</code> otherwise. If <code class="code">x</code> or <code class="code">y</code> is
NaN returns the other argument. If both are NaNs returns NaN.<br>
</div>
<pre><span id="VALfmin"><span class="keyword">val</span> fmin</span> : <code class="type">float -> float -> float</code></pre><div class="info">
<code class="code">fmin x y</code> is <code class="code">x</code> if <code class="code">x < y</code> and <code class="code">y</code> otherwise. If <code class="code">x</code> or <code class="code">y</code> is
NaN returns the other argument. If both are NaNs returns NaN.<br>
</div>
<pre><span id="VALclamp"><span class="keyword">val</span> clamp</span> : <code class="type">min:float -> max:float -> float -> float</code></pre><div class="info">
<code class="code">clamp min max x</code> is <code class="code">min</code> if <code class="code">x < min</code>, <code class="code">max</code> if <code class="code">x > max</code> and
<code class="code">x</code> otherwise. The result is undefined on NaNs and if <code class="code">min >
max</code>.<br>
</div>
<pre><span id="VALremap"><span class="keyword">val</span> remap</span> : <code class="type">x0:float -> x1:float -> y0:float -> y1:float -> float -> float</code></pre><div class="info">
<code class="code">remap x0 x1 y0 y1 v</code> applies to <code class="code">v</code> the
<a href="http://mathworld.wolfram.com/AffineTransformation.html">affine
transform</a> that maps <code class="code">x0</code> to <code class="code">y0</code> and <code class="code">x1</code> to <code class="code">y1</code>. If the
transform is undefined (<code class="code">x0 = x1</code> and <code class="code">y0 <> y1</code>) the function
returns <code class="code">y0</code> for any <code class="code">v</code>.<br>
</div>
<pre><span id="VALround"><span class="keyword">val</span> round</span> : <code class="type">float -> float</code></pre><div class="info">
<code class="code">round x</code> is the integer nearest to <code class="code">x</code>. Ties are rounded
towards positive infinity. If <code class="code">x</code> is an infinity, returns <code class="code">x</code>.
<p>
<b>Note.</b> If the absolute magnitude of <code class="code">x</code> is an integer strictly
greater than <a href="Gg.Float.html#VALmax_frac_float"><code class="code"><span class="constructor">Gg</span>.<span class="constructor">Float</span>.max_frac_float</code></a>, <code class="code">round x = x</code> may be <code class="code"><span class="keyword">false</span></code>.<br>
</div>
<pre><span id="VALint_of_round"><span class="keyword">val</span> int_of_round</span> : <code class="type">float -> int</code></pre><div class="info">
<code class="code">int_of_round x</code> is <code class="code">truncate (round v)</code>. The result is
undefined on NaNs and infinities.<br>
</div>
<pre><span id="VALround_dfrac"><span class="keyword">val</span> round_dfrac</span> : <code class="type">int -> float -> float</code></pre><div class="info">
<code class="code">round_dfrac d x</code> rounds <code class="code">x</code> to the <code class="code">d</code>th <em>decimal</em> fractional
digit. Ties are rounded towards positive infinity. If <code class="code">x</code> is an
infinity, returns <code class="code">x</code>. The result is only defined for <code class="code">0 <= d <=
16</code>.<br>
</div>
<pre><span id="VALround_dsig"><span class="keyword">val</span> round_dsig</span> : <code class="type">int -> float -> float</code></pre><div class="info">
<code class="code">round_dsig d x</code> rounds the normalized <em>decimal</em> significand
of <code class="code">x</code> to the <code class="code">d</code>th decimal fractional digit. Ties are rounded
towards positive infinity. The result is NaN on infinities. The
result only defined for <code class="code">0 <= d <= 16</code>.
<p>
<b>Warning.</b> The current implementation overflows on large <code class="code">x</code>
and <code class="code">d</code>.<br>
</div>
<pre><span id="VALround_zero"><span class="keyword">val</span> round_zero</span> : <code class="type">eps:float -> float -> float</code></pre><div class="info">
<code class="code">round_zero eps x</code> is <code class="code">0.</code> if <code class="code">abs_float x < eps</code> and <code class="code">x</code> otherwise.
The result is undefined if <code class="code">eps</code> is NaN.<br>
</div>
<pre><span id="VALchop"><span class="keyword">val</span> chop</span> : <code class="type">eps:float -> float -> float</code></pre><div class="info">
<code class="code">chop eps x</code> is <code class="code">round x</code> if <code class="code">abs_float (x -. round x) < eps</code> and <code class="code">x</code>
otherwise. The result is undefined if <code class="code">eps</code> is NaN.<br>
</div>
<pre><span id="VALsign"><span class="keyword">val</span> sign</span> : <code class="type">float -> float</code></pre><div class="info">
<code class="code">sign x</code> is <code class="code">1.</code> if <code class="code">x > 0.</code>, <code class="code">0.</code> if <code class="code">x = 0.</code>, <code class="code">-1.</code> if <code class="code">x < 0.</code><br>
</div>
<pre><span id="VALsign_bit"><span class="keyword">val</span> sign_bit</span> : <code class="type">float -> bool</code></pre><div class="info">
<code class="code">sign_bit x</code> is <code class="code"><span class="keyword">true</span></code> iff the sign bit is set in <code class="code">x</code>.<br>
</div>
<pre><span id="VALsucc"><span class="keyword">val</span> succ</span> : <code class="type">float -> float</code></pre><div class="info">
<code class="code">succ x</code> is the floating point value just after <code class="code">x</code> towards positive
infinity. Returns in particular :
<ul>
<li>NaN on NaNs.</li>
<li><code class="code">infinity</code> on <code class="code">infinity</code>.</li>
<li><code class="code">-max_float</code> on <code class="code">neg_infinity</code>.</li>
<li><code class="code">min_sub_float</code> on <code class="code">0.</code> <b>or</b> <code class="code">-0.</code>.</li>
</ul>
<br>
</div>
<pre><span id="VALpred"><span class="keyword">val</span> pred</span> : <code class="type">float -> float</code></pre><div class="info">
<code class="code">pred x</code> is <code class="code">-. succ (-.x)</code>, i.e. the floating point value before
<code class="code">x</code> towards negative infinity.<br>
</div>
<pre><span id="VALnan"><span class="keyword">val</span> nan</span> : <code class="type">int -> float</code></pre><div class="info">
<code class="code">nan payload</code> is a NaN whose 51 lower significand bits are
defined by the 51 lower (or less, as <code class="code">int</code> allows) bits of
<code class="code">payload</code>.<br>
</div>
<pre><span id="VALnan_payload"><span class="keyword">val</span> nan_payload</span> : <code class="type">float -> int</code></pre><div class="info">
<code class="code">nan_payload x</code> is the 51 lower significand bits (or less, as
<code class="code">int</code> allows) of the NaN <code class="code">x</code>.<br>
<b>Raises</b> <code>Invalid_argument</code> if <code class="code">x</code> is not a NaN.<br>
</div>
<br>
<h1 id="comparisons">Predicates and comparisons</h1><br>
<pre><span id="VALis_zero"><span class="keyword">val</span> is_zero</span> : <code class="type">eps:float -> float -> bool</code></pre><div class="info">
<code class="code">is_zero eps x</code> is <code class="code"><span class="keyword">true</span></code> if <code class="code">abs_float x < eps</code>
and <code class="code"><span class="keyword">false</span></code> otherwise. The result is undefined if <code class="code">eps</code> is NaN.<br>
</div>
<pre><span id="VALis_nan"><span class="keyword">val</span> is_nan</span> : <code class="type">float -> bool</code></pre><div class="info">
<code class="code">is_nan x</code> is <code class="code"><span class="keyword">true</span></code> iff <code class="code">x</code> is a NaN.<br>
</div>
<pre><span id="VALis_inf"><span class="keyword">val</span> is_inf</span> : <code class="type">float -> bool</code></pre><div class="info">
<code class="code">is_inf x</code> is <code class="code"><span class="keyword">true</span></code> iff <code class="code">x</code> is <code class="code">infinity</code> or <code class="code">neg_infinity</code>.<br>
</div>
<pre><span id="VALis_int"><span class="keyword">val</span> is_int</span> : <code class="type">float -> bool</code></pre><div class="info">
<code class="code">is_int x</code> is <code class="code"><span class="keyword">true</span></code> iff <code class="code">x</code> is an integer.<br>
</div>
<pre><span id="VALequal"><span class="keyword">val</span> equal</span> : <code class="type">float -> float -> bool</code></pre><div class="info">
<code class="code">equal x y</code> is <code class="code">x = y</code>.<br>
</div>
<pre><span id="VALequal_tol"><span class="keyword">val</span> equal_tol</span> : <code class="type">eps:float -> float -> float -> bool</code></pre><div class="info">
<code class="code">equal_tol eps x y</code> is <code class="code"><span class="keyword">true</span></code> iff |<code class="code">x - y</code>| <= <code class="code">eps</code> * max
(1,|<code class="code">x</code>|,|<code class="code">y</code>|). On special values the function behaves like
<code class="code">compare x y = 0</code>. The condition turns into an absolute tolerance
test for small magnitudes and a relative tolerance test for
large magnitudes.<br>
</div>
<pre><span id="VALcompare"><span class="keyword">val</span> compare</span> : <code class="type">float -> float -> int</code></pre><div class="info">
<code class="code">compare x y</code> is <code class="code"><span class="constructor">Pervasives</span>.compare x y</code>.<br>
</div>
<pre><span id="VALcompare_tol"><span class="keyword">val</span> compare_tol</span> : <code class="type">eps:float -> float -> float -> int</code></pre><div class="info">
<code class="code">compare_tol ~eps x y</code> is <code class="code">0</code> iff <code class="code">equal_tol ~eps x y</code> is <code class="code"><span class="keyword">true</span></code>
and <code class="code"><span class="constructor">Pervasives</span>.compare x y</code> otherwise.<br>
</div>
<br>
<h1 id="printers">Printers</h1><br>
<pre><span id="VALto_string"><span class="keyword">val</span> to_string</span> : <code class="type">float -> string</code></pre><div class="info">
<code class="code">to_string x</code> is a lossless textual representation of <code class="code">x</code>.
<ul>
<li>Normals are represented by <code class="code"><span class="string">"[-]0x1.<f>p<e>"</span></code> where
<code class="code"><f></code> is the significand bits in hexadecimal and <code class="code"><e></code> the
unbiased exponent in decimal.</li>
<li>Subnormals are represented by <code class="code"><span class="string">"[-]0x0.<f>p-1022"</span></code> where
<code class="code"><f></code> is the significand bits in hexadecimal.</li>
<li>NaNs are represented by <code class="code"><span class="string">"[-]nan(0x<p>)"</span></code> where <code class="code"><p></code> is the payload
in hexadecimal.</li>
<li>Infinities and zeroes are represented by <code class="code"><span class="string">"[-]inf"</span></code> and <code class="code"><span class="string">"[-]0."</span></code>.</li>
</ul>
<p>
This format should be compatible with recent implementations of
<a href="http://www.opengroup.org/onlinepubs/000095399/functions/strtod.html">
strtod</a> and hence with <code class="code">float_of_string</code> (but negative NaNs seem to
be problematic to get back) .<br>
</div>
<pre><span id="VALpp"><span class="keyword">val</span> pp</span> : <code class="type">Format.formatter -> float -> unit</code></pre><div class="info">
<code class="code">pp ppf x</code> prints <code class="code">x</code> on <code class="code">ppf</code> according to the lossless
representation of <a href="Gg.Float.html#VALto_string"><code class="code"><span class="constructor">Gg</span>.<span class="constructor">Float</span>.to_string</code></a>.<br>
</div>
<br>
<h1 id="floatrecall">Quick recall on OCaml's <code class="code">float</code>s</h1>
<p>
An OCaml <code class="code">float</code> is an
<a href="http://ieeexplore.ieee.org/servlet/opac?punumber=4610933">IEEE-754</a>
64 bit double precision binary floating point number. The 64 bits
are laid out as follows :
<pre class="verbatim">+----------------+-----------------------+-------------------------+
| sign s (1 bit) | exponent e (11 bits) | significand t (52 bits) |
+----------------+-----------------------+-------------------------+
63|62 52|51 0|</pre>
<p>
The value represented depends on s, e and t :
<pre class="verbatim">sign exponent significand value represented meaning
-------------------------------------------------------------------------
s 0 0 -1^s * 0 zero
s 0 t <> 0 -1^s * 0.t * 2^-1022 subnormal
s 0 < e < 2047 f -1^s * 1.t * 2^(e - 1023) normal
s 2047 0 -1^s * infinity infinity
s 2047 t <> 0 NaN not a number</pre>
<p>
There are two zeros, a positive and a negative one but both are
deemed equal by <code class="code">=</code> and <code class="code"><span class="constructor">Pervasives</span>.compare</code>. A NaN is never equal
(=) to <em>itself</em> or to another NaN however <code class="code"><span class="constructor">Pervasives</span>.compare</code>
asserts any NaN to be equal to itself and to any other NaN.
<p>
The bit layout of a <code class="code">float</code> can be converted to an <code class="code">int64</code> and
back using <code class="code"><span class="constructor">Int64</span>.bits_of_float</code> and <code class="code"><span class="constructor">Int64</span>.float_of_bits</code>.
<p>
The bit 51 of a NaN is used to distinguish between quiet (bit set)
and signaling NaNs (bit cleared); the remaining 51 lower bits of
the significand are the NaN's <em>payload</em> which can be used to
store diagnostic information. These features don't seem to used in
OCaml.
<p>
The significand of a floating point number is made of 53 binary
digits (don't forget the implicit digit), this corresponds to
log<sub class="subscript">10</sub>(2<sup class="superscript">53</sup>) ~ 16 <em>decimal</em> digits.
<p>
Only <code class="code">float</code> values in the interval ]<code class="code">-2</code><sup class="superscript">52</sup>;2<sup class="superscript">52</sup>[ may have
a fractional part. <a href="Gg.Float.html#VALmax_frac_float"><code class="code"><span class="constructor">Gg</span>.<span class="constructor">Float</span>.max_frac_float</code></a> is the greatest
positive <code class="code">float</code> with a fractional part.
<p>
Any integer value in the interval [<code class="code">-2</code><sup class="superscript">53</sup>;2<sup class="superscript">53</sup>] can be
represented exactly by a <code class="code">float</code> value. <em>Integer</em> arithmetic
performed in this interval is exact. <a href="Gg.Float.html#VALmax_int_arith"><code class="code"><span class="constructor">Gg</span>.<span class="constructor">Float</span>.max_int_arith</code></a> is
2<sup class="superscript">53</sup>.<br>
</body></html>
distrib
>
Mageia
>
7
>
armv7hl
>
media
>
core-release
>
by-pkgid
>
406ffd9ed660e1cacde537b99733f77d
>
files
>
21
