1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
|
---
title: Math.fround()
slug: Web/JavaScript/Reference/Global_Objects/Math/fround
tags:
- JavaScript
- Math
- Referencia
- metodo
translation_of: Web/JavaScript/Reference/Global_Objects/Math/fround
original_slug: Web/JavaScript/Referencia/Objetos_globales/Math/fround
---
<div>{{JSRef}}</div>
<p class="seoSummary">The <strong><code>Math.fround()</code></strong> function returns the nearest <a class="external" href="https://en.wikipedia.org/wiki/Single-precision_floating-point_format" title="link to the wikipedia page on single-precision floating-point format">32-bit single precision</a> float representation of a {{jsxref("Number")}}.</p>
<div>{{EmbedInteractiveExample("pages/js/math-fround.html")}}</div>
<h2 id="Syntax">Syntax</h2>
<pre class="syntaxbox">var <em>singleFloat</em> = Math.fround(<em>doubleFloat</em>);</pre>
<h3 id="Parameters">Parameters</h3>
<dl>
<dt><code>doubleFloat</code></dt>
<dd>A {{jsxref("Number")}}. If the parameter is of a different type, it will get converted to a number or to {{jsxref("NaN")}} if it cannot be converted.</dd>
</dl>
<h3 id="Return_value">Return value</h3>
<p>The nearest <a class="external" href="https://en.wikipedia.org/wiki/Single-precision_floating-point_format" title="link to the wikipedia page on single-precision floating-point format">32-bit single precision</a> float representation of the given number.</p>
<h2 id="Description">Description</h2>
<p>JavaScript uses 64-bit double floating-point numbers internally, which offer a very high precision. However, sometimes you may be working with 32-bit floating-point numbers, for example if you are reading values from a {{jsxref("Float32Array")}}. This can create confusion: Checking a 64-bit float and a 32-bit float for equality may fail even though the numbers are seemingly identical.</p>
<p>To solve this, <code>Math.fround()</code> can be used to cast the 64-bit float to a 32-bit float. Internally, JavaScript continues to treat the number as a 64-bit float, it just performs a "round to even" on the 23rd bit of the mantissa, and sets all following mantissa bits to <code>0</code>. If the number is outside the range of a 32-bit float, <code>{{jsxref("Infinity")}}</code> or <code>-Infinity</code> is returned.</p>
<p>Because <code>fround()</code> is a static method of <code>Math</code>, you always use it as <code>Math.fround()</code>, rather than as a method of a <code>Math</code> object you created (<code>Math</code> is not a constructor).</p>
<h2 id="Examples">Examples</h2>
<h3 id="Using_Math.fround()">Using <code>Math.fround()</code></h3>
<p>The number 1.5 can be precisely represented in the binary numeral system, and is identical in 32-bit and 64-bit:</p>
<pre class="brush: js">Math.fround(1.5); // 1.5
Math.fround(1.5) === 1.5; // true
</pre>
<p>However, the number 1.337 cannot be precisely represented in the binary numeral system, so it differs in 32-bit and 64-bit:</p>
<pre class="brush: js">Math.fround(1.337); // 1.3370000123977661
Math.fround(1.337) === 1.337; // false
</pre>
<p><math><semantics><msup><mn>2</mn><mn>150</mn></msup><annotation encoding="TeX">2^150</annotation></semantics></math> is too big for a 32-bit float, so <code>Infinity</code> is returned:</p>
<pre class="brush: js">2 ** 150; // 1.42724769270596e+45
Math.fround(2 ** 150); // Infinity
</pre>
<p>If the parameter cannot be converted to a number, or it is <a href="https://en.wikipedia.org/wiki/NaN" title="NaN on Wikipedia">not-a-number</a> (<code>NaN</code>), <code>Math.fround()</code> will return <code>NaN</code>:</p>
<pre class="brush: js">Math.fround('abc'); // NaN
Math.fround(NaN); // NaN
</pre>
<h2 id="Polyfill">Polyfill</h2>
<p>This can be emulated with the following function, if {{jsxref("Float32Array")}} are supported:</p>
<pre class="brush: js">Math.fround = Math.fround || (function (array) {
return function(x) {
return array[0] = x, array[0];
};
})(new Float32Array(1));
</pre>
<p>Supporting older browsers is slower, but also possible:</p>
<pre class="brush: js">if (!Math.fround) Math.fround = function(arg) {
arg = Number(arg);
// Return early for ±0 and NaN.
if (!arg) return arg;
var sign = arg < 0 ? -1 : 1;
if (sign < 0) arg = -arg;
// Compute the exponent (8 bits, signed).
var exp = Math.floor(Math.log(arg) / Math.LN2);
var powexp = Math.pow(2, Math.max(-126, Math.min(exp, 127)));
// Handle subnormals: leading digit is zero if exponent bits are all zero.
var leading = exp < -127 ? 0 : 1;
// Compute 23 bits of mantissa, inverted to round toward zero.
var mantissa = Math.round((leading - arg / powexp) * 0x800000);
if (mantissa <= -0x800000) return sign * Infinity;
return sign * powexp * (leading - mantissa / 0x800000);
};</pre>
<h2 id="Faster_Alternative_Polyfill_(Work_In_Progress)">Faster Alternative Polyfill (Work In Progress)</h2>
<p>The below polyfill is much faster and uses double-precision rounding errors to emulate the rounding errors caused by floating point narrowing. Although the polyfill higher on the page is good for comprehension, all of the complex Math function that it uses make it terrible slow. Although this polyfill is much faster, it is off by a bit in about 1 out of 2048 of the tests due to the tendency to round upwards like <code>Math.ceil</code> instead of like <code>Math.round</code> in the division of the subnormal-handling section of the code. Because single precision floating points have 23 bits of precision, the mean error deviation from the correct value is roughly <code>2**-28</code> or 0.0000000058%. This deviation from the correct value should be insignifigant in most circumstances, however please edit this polyfill if you have some tweaks to increase correctness without bloating the code size too much. NaN is not optimized for because it is most likely (almost certain) that you will not be calling <code>Math.fround</code> with NaN exclusively in a tight loop. Moreover, an additional check just for NaN instead of letting NaN naturally arise would induce a performance penalty for this function in older browsers when not called with NaN. Thus, the code below handles NaN correctly, but inefficiently for good reason.</p>
<pre class="brush: js">const Math_round = Math.round;
if (!Math.fround) Math.fround = function(x) {
if (x > 3.402823669209385e+38) return Infinity; // maximum float is 2**128
if (x < -3.402823669209385e+38) return -Infinity; // minimum is -2**128
if (-1.1754943508222875e-38 < x && x < 1.1754943508222875e-38) {
if (-1.401298464324817e-45 < x && x < 1.401298464324817e-45) return 0;
// else, it is a subnormal
var mul = Math_round(x/1.4012984643e-45)*1e-323;
return mul * 1.418129833677085e+278;
}
var hi = x * 9007199254740992; // 9007199254740992 is 2**53 which is the maximum of double precision
var exp = (x + hi) - hi; // adding this number chops off all lower bits, rounding the number.
exp /= 16777216; // 8388608 = 2**23 * 2, so preserve 23 bits in x because there are 23 bits in a float
// The "* 2" compensates for the addition shifting up the bits unwantedly
return Math_round(x / exp) * exp;
}
</pre>
<p>Below is code used to test for deviations from the correct value. The code below is meant for testing the merit of the function, not for polyfilling older browsers (as evidenced by the fact that the native Math.fround function is used).</p>
<pre class="brush: js">requestIdleCallback(function(){"use strict";
const Math_fround = Math.fround;
const Math_round = Math.round;
function my_fround(x) {
if (x > 3.402823669209385e+38) return Infinity; // maximum float is 2**128
if (x < -3.402823669209385e+38) return -Infinity; // minimum is -2**128
if (-1.1754943508222875e-38 < x && x < 1.1754943508222875e-38) {
if (-1.401298464324817e-45 < x && x < 1.401298464324817e-45) return 0;
// else, it is a subnormal
var mul = Math_round(x/1.4012984643e-45)*1e-323;
return mul * 1.418129833677085e+278;
}
var hi = x * 9007199254740992; // 9007199254740992 is 2**53 which is the maximum of double precision
var exp = (x + hi) - hi; // adding this number chops off all lower bits, rounding the number.
exp /= 16777216; // 8388608 = 2**23 * 2, so preserve 23 bits in x because there are 23 bits in a float
// The "* 2" compensates for the addition shifting up the bits unwantedly
return Math_round(x / exp) * exp;
}
const doublesArray = new Float64Array(8192);
const int32s = new Uint32Array(doublesArray.buffer);
const crypto = window.crypto;
var hasWarned = false, warnings=0;
for (var i=0; i<4; i=i+1|0) {
crypto.getRandomValues(int32s);
for (var k=0; k<8192; k=k+1|0) {
const myValue = my_fround(doublesArray[k]);
const froundVal = Math_fround(doublesArray[k]);
// quicker version of Object.is because of no function call overhead:
if (myValue === myValue ? myValue !== froundVal : froundVal === froundVal) {
if (!hasWarned) console.error(doublesArray[k]); // only show the first incorrect number
hasWarned = true;
warnings = warnings + 1|0;
}
}
}
console[warnings > 0 ? "warn" : "log"]( "Total number of mishandled floats: " + warnings );
});</pre>
<h2 id="Specifications">Specifications</h2>
<table class="standard-table">
<tbody>
<tr>
<th scope="col">Specification</th>
<th scope="col">Status</th>
<th scope="col">Comment</th>
</tr>
<tr>
<td>{{SpecName('ES6', '#sec-math.fround', 'Math.fround')}}</td>
<td>{{Spec2('ES6')}}</td>
<td>Initial definition.</td>
</tr>
<tr>
<td>{{SpecName('ESDraft', '#sec-math.fround', 'Math.fround')}}</td>
<td>{{Spec2('ESDraft')}}</td>
<td></td>
</tr>
</tbody>
</table>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<p>{{Compat("javascript.builtins.Math.fround")}}</p>
<h2 id="See_also">See also</h2>
<ul>
<li>{{jsxref("Math.round()")}}</li>
</ul>
|
