1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ --> 4<head> 5<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 6<title>Javascript Bignum Extensions</title> 7 8<meta name="description" content="Javascript Bignum Extensions"> 9<meta name="keywords" content="Javascript Bignum Extensions"> 10<meta name="resource-type" content="document"> 11<meta name="distribution" content="global"> 12<meta name="Generator" content="makeinfo"> 13<link href="#SEC_Contents" rel="contents" title="Table of Contents"> 14<style type="text/css"> 15<!-- 16a.summary-letter {text-decoration: none} 17blockquote.indentedblock {margin-right: 0em} 18blockquote.smallindentedblock {margin-right: 0em; font-size: smaller} 19blockquote.smallquotation {font-size: smaller} 20div.display {margin-left: 3.2em} 21div.example {margin-left: 3.2em} 22div.lisp {margin-left: 3.2em} 23div.smalldisplay {margin-left: 3.2em} 24div.smallexample {margin-left: 3.2em} 25div.smalllisp {margin-left: 3.2em} 26kbd {font-style: oblique} 27pre.display {font-family: inherit} 28pre.format {font-family: inherit} 29pre.menu-comment {font-family: serif} 30pre.menu-preformatted {font-family: serif} 31pre.smalldisplay {font-family: inherit; font-size: smaller} 32pre.smallexample {font-size: smaller} 33pre.smallformat {font-family: inherit; font-size: smaller} 34pre.smalllisp {font-size: smaller} 35span.nolinebreak {white-space: nowrap} 36span.roman {font-family: initial; font-weight: normal} 37span.sansserif {font-family: sans-serif; font-weight: normal} 38ul.no-bullet {list-style: none} 39--> 40</style> 41<meta name="viewport" content="width=device-width, initial-scale=1.0"> 42 43 44</head> 45 46<body lang="en"> 47<h1 class="settitle" align="center">Javascript Bignum Extensions</h1> 48 49<a name="SEC_Contents"></a> 50<h2 class="contents-heading">Table of Contents</h2> 51 52<div class="contents"> 53<ul class="no-bullet"> 54<li><a name="toc-Introduction" href="#Introduction">1 Introduction</a></li> 55<li><a name="toc-Operator-overloading" href="#Operator-overloading">2 Operator overloading</a> 56<ul class="no-bullet"> 57 <li><a name="toc-Introduction-1" href="#Introduction-1">2.1 Introduction</a></li> 58 <li><a name="toc-Builtin-Object-changes" href="#Builtin-Object-changes">2.2 Builtin Object changes</a> 59 <ul class="no-bullet"> 60 <li><a name="toc-Symbol-constructor" href="#Symbol-constructor">2.2.1 <code>Symbol</code> constructor</a></li> 61 </ul></li> 62</ul></li> 63<li><a name="toc-The-BigInt-Mode" href="#The-BigInt-Mode">3 The BigInt Mode</a> 64<ul class="no-bullet"> 65 <li><a name="toc-Introduction-2" href="#Introduction-2">3.1 Introduction</a></li> 66 <li><a name="toc-Changes-that-introduce-incompatibilities-with-Javascript" href="#Changes-that-introduce-incompatibilities-with-Javascript">3.2 Changes that introduce incompatibilities with Javascript</a> 67 <ul class="no-bullet"> 68 <li><a name="toc-Standard-mode" href="#Standard-mode">3.2.1 Standard mode</a></li> 69 <li><a name="toc-Bigint-mode" href="#Bigint-mode">3.2.2 Bigint mode</a></li> 70 </ul></li> 71 <li><a name="toc-Operators" href="#Operators">3.3 Operators</a> 72 <ul class="no-bullet"> 73 <li><a name="toc-Arithmetic-operators" href="#Arithmetic-operators">3.3.1 Arithmetic operators</a></li> 74 <li><a name="toc-Logical-operators" href="#Logical-operators">3.3.2 Logical operators</a></li> 75 <li><a name="toc-Relational-operators" href="#Relational-operators">3.3.3 Relational operators</a></li> 76 </ul></li> 77 <li><a name="toc-Number-literals" href="#Number-literals">3.4 Number literals</a></li> 78 <li><a name="toc-Builtin-Object-changes-1" href="#Builtin-Object-changes-1">3.5 Builtin Object changes</a> 79 <ul class="no-bullet"> 80 <li><a name="toc-BigInt-function" href="#BigInt-function">3.5.1 <code>BigInt</code> function</a></li> 81 <li><a name="toc-BigInt_002eprototype" href="#BigInt_002eprototype">3.5.2 <code>BigInt.prototype</code></a></li> 82 <li><a name="toc-Number-constructor" href="#Number-constructor">3.5.3 <code>Number</code> constructor</a></li> 83 <li><a name="toc-Number_002eprototype" href="#Number_002eprototype">3.5.4 <code>Number.prototype</code></a></li> 84 <li><a name="toc-Math-object" href="#Math-object">3.5.5 <code>Math</code> object</a></li> 85 </ul></li> 86</ul></li> 87<li><a name="toc-Arbitrarily-large-floating-point-numbers" href="#Arbitrarily-large-floating-point-numbers">4 Arbitrarily large floating point numbers</a> 88<ul class="no-bullet"> 89 <li><a name="toc-Introduction-3" href="#Introduction-3">4.1 Introduction</a></li> 90 <li><a name="toc-Floating-point-rounding" href="#Floating-point-rounding">4.2 Floating point rounding</a></li> 91 <li><a name="toc-Operators-1" href="#Operators-1">4.3 Operators</a></li> 92 <li><a name="toc-BigFloat-literals" href="#BigFloat-literals">4.4 BigFloat literals</a></li> 93 <li><a name="toc-Builtin-Object-changes-2" href="#Builtin-Object-changes-2">4.5 Builtin Object changes</a> 94 <ul class="no-bullet"> 95 <li><a name="toc-BigFloat-function" href="#BigFloat-function">4.5.1 <code>BigFloat</code> function</a></li> 96 <li><a name="toc-BigFloat_002eprototype" href="#BigFloat_002eprototype">4.5.2 <code>BigFloat.prototype</code></a></li> 97 <li><a name="toc-BigFloatEnv-constructor" href="#BigFloatEnv-constructor">4.5.3 <code>BigFloatEnv</code> constructor</a></li> 98 <li><a name="toc-Math-object-1" href="#Math-object-1">4.5.4 <code>Math</code> object</a></li> 99 </ul></li> 100</ul></li> 101<li><a name="toc-Math-mode" href="#Math-mode">5 Math mode</a> 102<ul class="no-bullet"> 103 <li><a name="toc-Introduction-4" href="#Introduction-4">5.1 Introduction</a></li> 104 <li><a name="toc-Builtin-Object-changes-3" href="#Builtin-Object-changes-3">5.2 Builtin Object changes</a> 105 <ul class="no-bullet"> 106 <li><a name="toc-Symbol-constructor-1" href="#Symbol-constructor-1">5.2.1 <code>Symbol</code> constructor</a></li> 107 </ul></li> 108 <li><a name="toc-Remaining-issues" href="#Remaining-issues">5.3 Remaining issues</a></li> 109</ul></li> 110 111</ul> 112</div> 113 114 115<a name="Introduction"></a> 116<h2 class="chapter">1 Introduction</h2> 117 118<p>The Bignum extensions add the following features to the Javascript 119language while being 100% backward compatible: 120</p> 121<ul> 122<li> Overloading of the standard operators 123to support new types such as complex numbers, fractions or matrixes. 124 125</li><li> Bigint mode where arbitrarily large integers are available by default (no <code>n</code> suffix is necessary as in the TC39 BigInt proposal<a name="DOCF1" href="#FOOT1"><sup>1</sup></a>). 126 127</li><li> Arbitrarily large floating point numbers (<code>BigFloat</code>) in base 2 using the IEEE 754 semantics. 128 129</li><li> Optional <code>math</code> mode which modifies the semantics of the division, modulo and power operator. The division and power operator return a fraction with integer operands and the modulo operator is defined as the Euclidian remainder. 130 131</li></ul> 132 133<p>The extensions are independent from each other except the <code>math</code> 134mode which relies on the bigint mode and the operator overloading. 135</p> 136<a name="Operator-overloading"></a> 137<h2 class="chapter">2 Operator overloading</h2> 138 139<a name="Introduction-1"></a> 140<h3 class="section">2.1 Introduction</h3> 141 142<p>If the operands of an operator have at least one object type, a custom 143operator method is searched before doing the legacy Javascript 144<code>ToNumber</code> conversion. 145</p> 146<p>For unary operators, the custom function is looked up in the object 147and has the following name: 148</p> 149<dl compact="compact"> 150<dt><code>unary +</code></dt> 151<dd><p><code>Symbol.operatorPlus</code> 152</p> 153</dd> 154<dt><code>unary -</code></dt> 155<dd><p><code>Symbol.operatorNeg</code> 156</p> 157</dd> 158<dt><code>++</code></dt> 159<dd><p><code>Symbol.operatorInc</code> 160</p> 161</dd> 162<dt><code>--</code></dt> 163<dd><p><code>Symbol.operatorDec</code> 164</p> 165</dd> 166<dt><code>~</code></dt> 167<dd><p><code>Symbol.operatorNot</code> 168</p> 169</dd> 170</dl> 171 172<p>For binary operators: 173</p> 174<ul> 175<li> If both operands have the same constructor function, then the operator 176is looked up in the constructor. 177 178</li><li> Otherwise, the property <code>Symbol.operatorOrder</code> is looked up in both 179constructors and converted to <code>Int32</code>. The operator is then 180looked in the constructor with the larger <code>Symbol.operatorOrder</code> 181value. A <code>TypeError</code> is raised if both constructors have the same 182<code>Symbol.operatorOrder</code> value. 183 184</li></ul> 185 186<p>The operator is looked up with the following name: 187</p> 188<dl compact="compact"> 189<dt><code>+</code></dt> 190<dd><p><code>Symbol.operatorAdd</code> 191</p> 192</dd> 193<dt><code>-</code></dt> 194<dd><p><code>Symbol.operatorSub</code> 195</p> 196</dd> 197<dt><code>*</code></dt> 198<dd><p><code>Symbol.operatorMul</code> 199</p> 200</dd> 201<dt><code>/</code></dt> 202<dd><p><code>Symbol.operatorDiv</code> 203</p> 204</dd> 205<dt><code>%</code></dt> 206<dd><p><code>Symbol.operatorMod</code> 207</p> 208</dd> 209<dt><code>% (math mode)</code></dt> 210<dd><p><code>Symbol.operatorMathMod</code> 211</p> 212</dd> 213<dt><code>**</code></dt> 214<dd><p><code>Symbol.operatorPow</code> 215</p> 216</dd> 217<dt><code>|</code></dt> 218<dd><p><code>Symbol.operatorOr</code> 219</p> 220</dd> 221<dt><code>^</code></dt> 222<dd><p><code>Symbol.operatorXor</code> 223</p> 224</dd> 225<dt><code>&</code></dt> 226<dd><p><code>Symbol.operatorAnd</code> 227</p> 228</dd> 229<dt><code><<</code></dt> 230<dd><p><code>Symbol.operatorShl</code> 231</p> 232</dd> 233<dt><code>>></code></dt> 234<dd><p><code>Symbol.operatorShr</code> 235</p> 236</dd> 237<dt><code><</code></dt> 238<dd><p><code>Symbol.operatorCmpLT</code> 239</p> 240</dd> 241<dt><code>></code></dt> 242<dd><p><code>Symbol.operatorCmpLT</code>, operands swapped 243</p> 244</dd> 245<dt><code><=</code></dt> 246<dd><p><code>Symbol.operatorCmpLE</code> 247</p> 248</dd> 249<dt><code>>=</code></dt> 250<dd><p><code>Symbol.operatorCmpLE</code>, operands swapped 251</p> 252</dd> 253<dt><code>==, !=</code></dt> 254<dd><p><code>Symbol.operatorCmpEQ</code> 255</p> 256</dd> 257</dl> 258 259<p>The return value of <code>Symbol.operatorCmpLT</code>, <code>Symbol.operatorCmpLE</code> and 260<code>Symbol.operatorCmpEQ</code> is converted to <code>Boolean</code>. 261</p> 262<a name="Builtin-Object-changes"></a> 263<h3 class="section">2.2 Builtin Object changes</h3> 264 265<a name="Symbol-constructor"></a> 266<h4 class="subsection">2.2.1 <code>Symbol</code> constructor</h4> 267 268<p>The following global symbols are added for the operator overloading: 269</p><dl compact="compact"> 270<dt><code>operatorOrder</code></dt> 271<dt><code>operatorAdd</code></dt> 272<dt><code>operatorSub</code></dt> 273<dt><code>operatorMul</code></dt> 274<dt><code>operatorDiv</code></dt> 275<dt><code>operatorMod</code></dt> 276<dt><code>operatorPow</code></dt> 277<dt><code>operatorShl</code></dt> 278<dt><code>operatorShr</code></dt> 279<dt><code>operatorAnd</code></dt> 280<dt><code>operatorOr</code></dt> 281<dt><code>operatorXor</code></dt> 282<dt><code>operatorCmpLT</code></dt> 283<dt><code>operatorCmpLE</code></dt> 284<dt><code>operatorCmpEQ</code></dt> 285<dt><code>operatorPlus</code></dt> 286<dt><code>operatorNeg</code></dt> 287<dt><code>operatorNot</code></dt> 288<dt><code>operatorInc</code></dt> 289<dt><code>operatorDec</code></dt> 290</dl> 291 292 293<a name="The-BigInt-Mode"></a> 294<h2 class="chapter">3 The BigInt Mode</h2> 295 296<a name="Introduction-2"></a> 297<h3 class="section">3.1 Introduction</h3> 298 299<p>The bigint mode is enabled with the <code>"use bigint"</code> directive. It 300propagates the same way as the strict mode. In bigint mode, all 301integers are considered as <code>bigint</code> (arbitrarily large integer, 302similar to the TC39 BigInt 303proposal<a name="DOCF2" href="#FOOT2"><sup>2</sup></a>) 304instead of <code>number</code> (floating point number). In order to be able 305to exchange data between standard and bigint modes, numbers are 306internally represented as 3 different types: 307</p> 308<ul> 309<li> Small integer (SmallInt): 32 bit integer<a name="DOCF3" href="#FOOT3"><sup>3</sup></a>. 310 311</li><li> Big integer (BigInt): arbitrarily large integer. 312 313</li><li> Floating point number (Float). 314 315</li></ul> 316 317<p>In standard mode, the semantics of each operation is modified so that 318when it returns a <code>number</code>, it is either of SmallInt or 319Float. But the difference between SmallInt and Float is not observable 320in standard mode. 321</p> 322<p>In bigint mode, each operation behaves differently whether its 323operands are integer or float. The difference between SmallInt and 324BigInt is not observable (i.e. they are both integers). 325</p> 326<p>The following table summarizes the observable types: 327</p> 328<table> 329<thead><tr><th width="30%">Internal type</th><th width="30%">Observable type<br> (standard mode)</th><th width="30%">Observable type<br> (bigint mode)</th></tr></thead> 330<tr><td width="30%">SmallInt</td><td width="30%">number</td><td width="30%">bigint</td></tr> 331<tr><td width="30%">BigInt</td><td width="30%">bigint</td><td width="30%">bigint</td></tr> 332<tr><td width="30%">Float</td><td width="30%">number</td><td width="30%">number</td></tr> 333</table> 334 335<a name="Changes-that-introduce-incompatibilities-with-Javascript"></a> 336<h3 class="section">3.2 Changes that introduce incompatibilities with Javascript</h3> 337 338<a name="Standard-mode"></a> 339<h4 class="subsection">3.2.1 Standard mode</h4> 340 341<p>There is no incompatibility with Javascript. 342</p> 343<a name="Bigint-mode"></a> 344<h4 class="subsection">3.2.2 Bigint mode</h4> 345 346<p>The following changes are visible: 347</p> 348<ul> 349<li> Integer and Float are different types. Constants are typed. For example: <code>typeof 1.0 === "number"</code> and <code>typeof 1 === "bigint"</code>. Another consequence is that <code>1.0 === 1</code> is false. 350 351</li><li> The range of integers is unlimited. In standard mode: <code>2**53 + 1 === 2**53</code>. This is no longer true with the bignum extensions. 352 353</li><li> Binary bitwise operators do not truncate to 32 bits i.e. <code>0x800000000 | 1 === 0x800000001</code> while it gives <code>1</code> in standard mode. 354 355</li><li> Bitwise shift operators do not truncate to 32 bits and do not mask the shift count with <code>0x1f</code> i.e. <code>1 << 32 === 4294967296</code> while it gives <code>1</code> in standard mode. However, the <code>>>></code> operator (unsigned right shift) which is useless with bignums keeps its standard mode behavior<a name="DOCF4" href="#FOOT4"><sup>4</sup></a>. 356 357</li><li> Operators with integer operands never return the minus zero floating point value as result. Hence <code>Object.is(0, -0) === true</code>. Use <code>-0.0</code> to create a minus zero floating point value. 358 359</li><li> The <code>ToPrimitive</code> abstract operation is called with the <code>"integer"</code> preferred type when an integer is required (e.g. for bitwise binary or shift operations). 360 361</li><li> The prototype of integers is no longer <code>Number.prototype</code>. Instead<br> <code>Object.getPrototypeOf(1) === BigInt.prototype</code>. The prototype of floats remains Number.prototype. 362 363</li><li> If the TC39 BigInt proposal is supported, there is no observable difference between integers and <code>bigint</code>s. 364 365</li></ul> 366 367<a name="Operators"></a> 368<h3 class="section">3.3 Operators</h3> 369 370<a name="Arithmetic-operators"></a> 371<h4 class="subsection">3.3.1 Arithmetic operators</h4> 372 373<p>The operands are converted to number values as in normal 374Javascript. Then the general case is that an Integer is returned if 375both operands are Integer. Otherwise, a float is returned. 376</p> 377<p>The <code>+</code> operator also accepts strings as input and behaves like 378standard Javascript in this case. 379</p> 380<p>The binary operator <code>%</code> returns the truncated remainder of the 381division. When the result is an Integer type, a dividend of zero yields a 382RangeError exception. 383</p> 384<p>The binary operator <code>%</code> in math mode returns the Euclidian 385remainder of the division i.e. it is always positive. 386</p> 387<p>The binary operator <code>/</code> returns a float. 388</p> 389<p>The binary operator <code>/</code> in math mode returns a float if one of 390the operands is float. Otherwise, <code>BigInt[Symbol.operatorDiv]</code> is 391invoked. 392</p> 393<p>The returned type of <code>a ** b</code> is Float if <em>a</em> or <em>b</em> 394are Float. If <em>a</em> and <em>b</em> are integers: 395</p><ul> 396<li> <em>b < 0</em> returns a Float in bigint mode. In math mode, <code>BigInt[Symbol.operatorPow]</code> is invoked. 397 398</li><li> <em>b >= 0</em> returns an integer. 399</li></ul> 400 401<p>The unary <code>-</code> and unary <code>+</code> return the same type as their 402operand. They performs no floating point rounding when the result is a 403float. 404</p> 405<p>The unary operators <code>++</code> and <code>--</code> return the same type as 406their operand. 407</p> 408<p>In standard mode: 409</p> 410<p>If the operator returns an Integer and that the result fits a 411SmallInt, it is converted to SmallInt. Otherwise, the Integer is 412converted to a Float. 413</p> 414<p>In bigint mode: 415</p> 416<p>If the operator returns an Integer and that the result fits a 417SmallInt, it is converted to SmallInt. Otherwise it is a BigInt. 418</p> 419<a name="Logical-operators"></a> 420<h4 class="subsection">3.3.2 Logical operators</h4> 421 422<p>In standard mode: 423</p> 424<p>The operands have their standard behavior. If the result fits a 425SmallInt it is converted to a SmallInt. Otherwise it is a Float. 426</p> 427<p>In bigint mode: 428</p> 429<p>The operands are converted to integer values. The floating point 430values are converted to integer by rounding them to zero. 431</p> 432<p>The logical operators are defined assuming the integers are 433represented in two complement notation. 434</p> 435<p>For <code><<</code> and <code><<</code>, the shift can be positive or negative. So 436<code>a << b</code> is defined as <em>\lfloor a/2^{-b} \rfloor</em> and 437<code>a >> b</code> is defined as <em>\lfloor a/2^{b} \rfloor</em>. 438</p> 439<p>The operator <code>>>></code> is supported for backward compatibility and 440behaves the same way as Javascript i.e. implicit conversion to <code>Uint32</code>. 441</p> 442<p>If the result fits a SmallInt it is converted to a SmallInt. Otherwise 443it is a BigInt. 444</p> 445<a name="Relational-operators"></a> 446<h4 class="subsection">3.3.3 Relational operators</h4> 447 448<p>The relational operators <, <=, >, >=, ==, != work as expected with 449integers and floating point numbers (e.g. <code>1.0 == 1</code> is true). 450</p> 451<p>The strict equality operators === and !== have the usual Javascript 452semantics. In particular, different types never equal, so <code>1.0 453=== 1</code> is false. 454</p> 455<a name="Number-literals"></a> 456<h3 class="section">3.4 Number literals</h3> 457 458<p>Number literals in bigint mode have a slightly different behavior than 459in standard Javascript: 460</p> 461<ol> 462<li> A number literal without a decimal point or an exponent is considered 463as an Integer. Otherwise it is a Float. 464 465</li><li> Hexadecimal, octal or binary floating point literals are accepted with 466a decimal point or an exponent. The exponent is specified with the 467<code>p</code> letter assuming a base 2. The same convention is used by 468C99. Example: <code>0x1p3</code> is the same as <code>8.0</code>. 469 470</li></ol> 471 472<a name="Builtin-Object-changes-1"></a> 473<h3 class="section">3.5 Builtin Object changes</h3> 474 475<a name="BigInt-function"></a> 476<h4 class="subsection">3.5.1 <code>BigInt</code> function</h4> 477 478<p>The <code>BigInt</code> function cannot be invoked as a constructor. When 479invoked as a function, it converts its first parameter to an 480integer. When a floating point number is given as parameter, it is 481truncated to an integer with infinite precision. 482</p> 483<p><code>BigInt</code> properties: 484</p> 485<dl compact="compact"> 486<dt><code>asIntN(bits, a)</code></dt> 487<dd><p>Set <em>b=a \pmod{2^{bits}}</em>. Return <em>b</em> if <em>b < 2^{bits-1}</em> 488otherwise <em>b-2^{bits}</em>. 489</p> 490</dd> 491<dt><code>asUintN(bits, a)</code></dt> 492<dd><p>Return <em>a \pmod{2^{bits}}</em>. 493</p> 494</dd> 495<dt><code>tdiv(a, b)</code></dt> 496<dd><p>Return <em>trunc(a/b)</em>. <code>b = 0</code> raises a RangeError 497exception. 498</p> 499</dd> 500<dt><code>fdiv(a, b)</code></dt> 501<dd><p>Return <em>\lfloor a/b \rfloor</em>. <code>b = 0</code> raises a RangeError 502exception. 503</p> 504</dd> 505<dt><code>cdiv(a, b)</code></dt> 506<dd><p>Return <em>\lceil a/b \rceil</em>. <code>b = 0</code> raises a RangeError 507exception. 508</p> 509</dd> 510<dt><code>ediv(a, b)</code></dt> 511<dd><p>Return <em>sgn(b) \lfloor a/{|b|} \rfloor</em> (Euclidian 512division). <code>b = 0</code> raises a RangeError exception. 513</p> 514</dd> 515<dt><code>tdivrem(a, b)</code></dt> 516<dt><code>fdivrem(a, b)</code></dt> 517<dt><code>cdivrem(a, b)</code></dt> 518<dt><code>edivrem(a, b)</code></dt> 519<dd><p>Return an array of two elements. The first element is the quotient, 520the second is the remainder. The same rounding is done as the 521corresponding division operation. 522</p> 523</dd> 524<dt><code>sqrt(a)</code></dt> 525<dd><p>Return <em>\lfloor \sqrt(a) \rfloor</em>. A RangeError exception is 526raised if <em>a < 0</em>. 527</p> 528</dd> 529<dt><code>sqrtrem(a)</code></dt> 530<dd><p>Return an array of two elements. The first element is <em>\lfloor 531\sqrt{a} \rfloor</em>. The second element is <em>a-\lfloor \sqrt{a} 532\rfloor^2</em>. A RangeError exception is raised if <em>a < 0</em>. 533</p> 534</dd> 535<dt><code>floorLog2(a)</code></dt> 536<dd><p>Return -1 if <em>a \leq 0</em> otherwise return <em>\lfloor \log2(a) \rfloor</em>. 537</p> 538</dd> 539<dt><code>ctz(a)</code></dt> 540<dd><p>Return the number of trailing zeros in the two’s complement binary representation of a. Return -1 if <em>a=0</em>. 541</p> 542</dd> 543</dl> 544 545<a name="BigInt_002eprototype"></a> 546<h4 class="subsection">3.5.2 <code>BigInt.prototype</code></h4> 547 548<p>It is a normal object. 549</p> 550<a name="Number-constructor"></a> 551<h4 class="subsection">3.5.3 <code>Number</code> constructor</h4> 552 553<p>The number constructor returns its argument rounded to a Float using 554the global floating point environement. In bigint mode, the Number 555constructor returns a Float. In standard mode, it returns a SmallInt 556if the value fits it, otherwise a Float. 557</p> 558<a name="Number_002eprototype"></a> 559<h4 class="subsection">3.5.4 <code>Number.prototype</code></h4> 560 561<p>The following properties are modified: 562</p> 563<dl compact="compact"> 564<dt><code>toString(radix)</code></dt> 565<dd> 566<p>In bigint mode, integers are converted to the specified radix with 567infinite precision. 568</p> 569</dd> 570<dt><code>toPrecision(p)</code></dt> 571<dt><code>toFixed(p)</code></dt> 572<dt><code>toExponential(p)</code></dt> 573<dd> 574<p>In bigint mode, integers are accepted and converted to string with 575infinite precision. 576</p> 577</dd> 578<dt><code>parseInt(string, radix)</code></dt> 579<dd> 580<p>In bigint mode, an integer is returned and the conversion is done with 581infinite precision. 582</p> 583</dd> 584</dl> 585 586<a name="Math-object"></a> 587<h4 class="subsection">3.5.5 <code>Math</code> object</h4> 588 589<p>The following properties are modified: 590</p> 591<dl compact="compact"> 592<dt><code>abs(x)</code></dt> 593<dd><p>Absolute value. Return an integer if <code>x</code> is an Integer. Otherwise 594return a Float. No rounding is performed. 595</p> 596</dd> 597<dt><code>min(a, b)</code></dt> 598<dt><code>max(a, b)</code></dt> 599<dd><p>No rounding is performed. The returned type is the same one as the 600minimum (resp. maximum) value. 601</p> 602</dd> 603</dl> 604 605<a name="Arbitrarily-large-floating-point-numbers"></a> 606<h2 class="chapter">4 Arbitrarily large floating point numbers</h2> 607 608<a name="Introduction-3"></a> 609<h3 class="section">4.1 Introduction</h3> 610 611<p>This extension adds the <code>BigFloat</code> primitive type. The 612<code>BigFloat</code> type represents floating point numbers are in base 2 613with the IEEE 754 semantics. A floating 614point number is represented as a sign, mantissa and exponent. The 615special values <code>NaN</code>, <code>+/-Infinity</code>, <code>+0</code> and <code>-0</code> 616are supported. The mantissa and exponent can have any bit length with 617an implementation specific minimum and maximum. 618</p> 619<a name="Floating-point-rounding"></a> 620<h3 class="section">4.2 Floating point rounding</h3> 621 622<p>Each floating point operation operates with infinite precision and 623then rounds the result according to the specified floating point 624environment (<code>BigFloatEnv</code> object). The status flags of the 625environment are also set according to the result of the operation. 626</p> 627<p>If no floating point environment is provided, the global floating 628point environment is used. 629</p> 630<p>The rounding mode of the global floating point environment is always 631<code>RNDN</code> (“round to nearest with ties to even”)<a name="DOCF5" href="#FOOT5"><sup>5</sup></a>. The status flags of the global environment cannot be 632read<a name="DOCF6" href="#FOOT6"><sup>6</sup></a>. The precision of the global environment is 633<code>BigFloatEnv.prec</code>. The number of exponent bits of the global 634environment is <code>BigFloatEnv.expBits</code>. If <code>BigFloatEnv.expBits</code> is 635strictly smaller than the maximum allowed number of exponent bits 636(<code>BigFloatEnv.expBitsMax</code>), then the global environment subnormal 637flag is set to <code>true</code>. Otherwise it is set to <code>false</code>; 638</p> 639<p>For example, <code>prec = 53</code> and <code> expBits = 11</code> give exactly 640the same precision as the IEEE 754 64 bit floating point type. It is 641the default floating point precision. 642</p> 643<p>The global floating point environment can only be modified temporarily 644when calling a function (see <code>BigFloatEnv.setPrec</code>). Hence a 645function can change the global floating point environment for its 646callees but not for its caller. 647</p> 648<a name="Operators-1"></a> 649<h3 class="section">4.3 Operators</h3> 650 651<p>The builtin operators are extended so that a BigFloat is returned if 652at least one operand is a BigFloat. The computations are always done 653with infinite precision and rounded according to the global floating 654point environment. 655</p> 656<p><code>typeof</code> applied on a <code>BigFloat</code> returns <code>bigfloat</code>. 657</p> 658<p>BigFloat can be compared with all the other numeric types and the 659result follows the expected mathematical relations. 660</p> 661<p>However, since BigFloat and Number are different types they are never 662equal when using the strict comparison operators (e.g. <code>0.0 === 6630.0l</code> is false). 664</p> 665<a name="BigFloat-literals"></a> 666<h3 class="section">4.4 BigFloat literals</h3> 667 668<p>BigFloat literals are floating point numbers with a trailing <code>l</code> 669suffix. BigFloat literals have an infinite precision. They are rounded 670according to the global floating point environment when they are 671evaluated.<a name="DOCF7" href="#FOOT7"><sup>7</sup></a> 672</p> 673<a name="Builtin-Object-changes-2"></a> 674<h3 class="section">4.5 Builtin Object changes</h3> 675 676<a name="BigFloat-function"></a> 677<h4 class="subsection">4.5.1 <code>BigFloat</code> function</h4> 678 679<p>The <code>BigFloat</code> function cannot be invoked as a constructor. When 680invoked as a function: the parameter is converted to a primitive 681type. If the result is a numeric type, it is converted to BigFloat 682without rounding. If the result is a string, it is converted to 683BigFloat using the precision of the global floating point environment. 684</p> 685<p><code>BigFloat</code> properties: 686</p> 687<dl compact="compact"> 688<dt><code>LN2</code></dt> 689<dt><code>PI</code></dt> 690<dd><p>Getter. Return the value of the corresponding mathematical constant 691rounded to nearest, ties to even with the current global 692precision. The constant values are cached for small precisions. 693</p> 694</dd> 695<dt><code>MIN_VALUE</code></dt> 696<dt><code>MAX_VALUE</code></dt> 697<dt><code>EPSILON</code></dt> 698<dd><p>Getter. Return the minimum, maximum and epsilon <code>BigFloat</code> values 699(same definition as the corresponding <code>Number</code> constants). 700</p> 701</dd> 702<dt><code>fpRound(a[, e])</code></dt> 703<dd><p>Round the floating point number <code>a</code> according to the floating 704point environment <code>e</code> or the global environment if <code>e</code> is 705undefined. 706</p> 707</dd> 708<dt><code>parseFloat(a[, radix[, e]])</code></dt> 709<dd><p>Parse the string <code>a</code> as a floating point number in radix 710<code>radix</code>. The radix is 0 (default) or from 2 to 36. The radix 0 711means radix 10 unless there is a hexadecimal or binary prefix. The 712result is rounded according to the floating point environment <code>e</code> 713or the global environment if <code>e</code> is undefined. 714</p> 715</dd> 716<dt><code>add(a, b[, e])</code></dt> 717<dt><code>sub(a, b[, e])</code></dt> 718<dt><code>mul(a, b[, e])</code></dt> 719<dt><code>div(a, b[, e])</code></dt> 720<dd><p>Perform the specified floating point operation and round the floating 721point number <code>a</code> according to the floating point environment 722<code>e</code> or the global environment if <code>e</code> is undefined. If 723<code>e</code> is specified, the floating point status flags are updated. 724</p> 725</dd> 726<dt><code>floor(x[, e])</code></dt> 727<dt><code>ceil(x[, e])</code></dt> 728<dt><code>round(x[, e])</code></dt> 729<dt><code>trunc(x[, e])</code></dt> 730<dd><p>Round to integer. A rounded <code>BigFloat</code> is returned. <code>e</code> is an 731optional floating point environment. 732</p> 733</dd> 734<dt><code>fmod(x, y[, e])</code></dt> 735<dt><code>remainder(x, y[, e])</code></dt> 736<dd><p>Floating point remainder. The quotient is truncated to zero (fmod) or 737to the nearest integer with ties to even (remainder). <code>e</code> is an 738optional floating point environment. 739</p> 740</dd> 741<dt><code>sqrt(x[, e])</code></dt> 742<dd><p>Square root. Return a rounded floating point number. <code>e</code> is an 743optional floating point environment. 744</p> 745</dd> 746<dt><code>sin(x[, e])</code></dt> 747<dt><code>cos(x[, e])</code></dt> 748<dt><code>tan(x[, e])</code></dt> 749<dt><code>asin(x[, e])</code></dt> 750<dt><code>acos(x[, e])</code></dt> 751<dt><code>atan(x[, e])</code></dt> 752<dt><code>atan2(x, y[, e])</code></dt> 753<dt><code>exp(x[, e])</code></dt> 754<dt><code>log(x[, e])</code></dt> 755<dt><code>pow(x, y[, e])</code></dt> 756<dd><p>Transcendental operations. Return a rounded floating point 757number. <code>e</code> is an optional floating point environment. 758</p> 759</dd> 760</dl> 761 762<a name="BigFloat_002eprototype"></a> 763<h4 class="subsection">4.5.2 <code>BigFloat.prototype</code></h4> 764 765<p>The following properties are modified: 766</p> 767<dl compact="compact"> 768<dt><code>toString(radix)</code></dt> 769<dd> 770<p>For floating point numbers: 771</p> 772<ul> 773<li> If the radix is a power of two, the conversion is done with infinite 774precision. 775</li><li> Otherwise, the number is rounded to nearest with ties to even using 776the global precision. It is then converted to string using the minimum 777number of digits so that its conversion back to a floating point using 778the global precision and round to nearest gives the same number. 779 780</li></ul> 781 782</dd> 783<dt><code>toPrecision(p[, rnd_mode])</code></dt> 784<dt><code>toFixed(p[, rnd_mode])</code></dt> 785<dt><code>toExponential(p[, rnd_mode])</code></dt> 786<dd><p>Same semantics as the corresponding <code>Number</code> functions with 787BigFloats. There is no limit on the accepted precision <code>p</code>. The 788rounding mode can be optionally specified. It is set by default to 789<code>BigFloatEnv.RNDNA</code>. 790</p> 791</dd> 792</dl> 793 794<a name="BigFloatEnv-constructor"></a> 795<h4 class="subsection">4.5.3 <code>BigFloatEnv</code> constructor</h4> 796 797<p>The <code>BigFloatEnv([p, [,rndMode]]</code> constructor cannot be invoked as a 798function. The floating point environment contains: 799</p> 800<ul> 801<li> the mantissa precision in bits 802 803</li><li> the exponent size in bits assuming an IEEE 754 representation; 804 805</li><li> the subnormal flag (if true, subnormal floating point numbers can 806be generated by the floating point operations). 807 808</li><li> the rounding mode 809 810</li><li> the floating point status. The status flags can only be set by the floating point operations. They can be reset with <code>BigFloatEnv.prototype.clearStatus()</code> or with the various status flag setters. 811 812</li></ul> 813 814<p><code>new BigFloatEnv([p, [,rndMode]]</code> creates a new floating point 815environment. The status flags are reset. If no parameter is given the 816precision, exponent bits and subnormal flags are copied from the 817global floating point environment. Otherwise, the precision is set to 818<code>p</code>, the number of exponent bits is set to <code>expBitsMax</code> and the 819subnormal flags is set to <code>false</code>. If <code>rndMode</code> is 820<code>undefined</code>, the rounding mode is set to <code>RNDN</code>. 821</p> 822<p><code>BigFloatEnv</code> properties: 823</p> 824<dl compact="compact"> 825<dt><code>prec</code></dt> 826<dd><p>Getter. Return the precision in bits of the global floating point 827environment. The initial value is <code>53</code>. 828</p> 829</dd> 830<dt><code>expBits</code></dt> 831<dd><p>Getter. Return the exponent size in bits of the global floating point 832environment assuming an IEEE 754 representation. If <code>expBits < 833expBitsMax</code>, then subnormal numbers are supported. The initial value 834is <code>11</code>. 835</p> 836</dd> 837<dt><code>setPrec(f, p[, e])</code></dt> 838<dd><p>Set the precision of the global floating point environment to <code>p</code> 839and the exponent size to <code>e</code> then call the function 840<code>f</code>. Then the Float precision and exponent size are reset to 841their precious value and the return value of <code>f</code> is returned (or 842an exception is raised if <code>f</code> raised an exception). If <code>e</code> 843is <code>undefined</code> it is set to <code>BigFloatEnv.expBitsMax</code>. <code>p</code> 844must be >= 53 and <code>e</code> must be >= 11 so that the global precision 845is at least equivalent to the IEEE 754 64 bit doubles. 846</p> 847</dd> 848<dt><code>precMin</code></dt> 849<dd><p>Read-only integer. Return the minimum allowed precision. Must be at least 2. 850</p> 851</dd> 852<dt><code>precMax</code></dt> 853<dd><p>Read-only integer. Return the maximum allowed precision. Must be at least 53. 854</p> 855</dd> 856<dt><code>expBitsMin</code></dt> 857<dd><p>Read-only integer. Return the minimum allowed exponent size in 858bits. Must be at least 3. 859</p> 860</dd> 861<dt><code>expBitsMax</code></dt> 862<dd><p>Read-only integer. Return the maximum allowed exponent size in 863bits. Must be at least 11. 864</p> 865</dd> 866<dt><code>RNDN</code></dt> 867<dd><p>Read-only integer. Round to nearest, with ties to even rounding mode. 868</p> 869</dd> 870<dt><code>RNDZ</code></dt> 871<dd><p>Read-only integer. Round to zero rounding mode. 872</p> 873</dd> 874<dt><code>RNDD</code></dt> 875<dd><p>Read-only integer. Round to -Infinity rounding mode. 876</p> 877</dd> 878<dt><code>RNDU</code></dt> 879<dd><p>Read-only integer. Round to +Infinity rounding mode. 880</p> 881</dd> 882<dt><code>RNDNA</code></dt> 883<dd><p>Read-only integer. Round to nearest, with ties away from zero rounding mode. 884</p> 885</dd> 886<dt><code>RNDNU</code></dt> 887<dd><p>Read-only integer. Round to nearest, with ties to +Infinity rounding mode. 888</p> 889</dd> 890<dt><code>RNDF<a name="DOCF8" href="#FOOT8"><sup>8</sup></a></code></dt> 891<dd><p>Read-only integer. Faithful rounding mode. The result is 892non-deterministicly rounded to -Infinity or +Infinity. This rounding 893mode usually gives a faster and deterministic running time for the 894floating point operations. 895</p> 896</dd> 897</dl> 898 899<p><code>BigFloatEnv.prototype</code> properties: 900</p> 901<dl compact="compact"> 902<dt><code>prec</code></dt> 903<dd><p>Getter and setter (Integer). Return or set the precision in bits. 904</p> 905</dd> 906<dt><code>expBits</code></dt> 907<dd><p>Getter and setter (Integer). Return or set the exponent size in bits 908assuming an IEEE 754 representation. 909</p> 910</dd> 911<dt><code>rndMode</code></dt> 912<dd><p>Getter and setter (Integer). Return or set the rounding mode. 913</p> 914</dd> 915<dt><code>subnormal</code></dt> 916<dd><p>Getter and setter (Boolean). subnormal flag. It is false when 917<code>expBits = expBitsMax</code>. 918</p> 919</dd> 920<dt><code>clearStatus()</code></dt> 921<dd><p>Clear the status flags. 922</p> 923</dd> 924<dt><code>invalidOperation</code></dt> 925<dt><code>divideByZero</code></dt> 926<dt><code>overflow</code></dt> 927<dt><code>underflow</code></dt> 928<dt><code>inexact</code></dt> 929<dd><p>Getter and setter (Boolean). Status flags. 930</p> 931</dd> 932</dl> 933 934<a name="Math-object-1"></a> 935<h4 class="subsection">4.5.4 <code>Math</code> object</h4> 936 937<p>The following properties are modified: 938</p> 939<dl compact="compact"> 940<dt><code>abs(x)</code></dt> 941<dd><p>Absolute value. If <code>x</code> is a BigFloat, its absolute value is 942returned as a BigFloat. No rounding is performed. 943</p> 944</dd> 945<dt><code>min(a, b)</code></dt> 946<dt><code>max(a, b)</code></dt> 947<dd><p>The returned type is the same one as the minimum (resp. maximum) 948value, so <code>BigFloat</code> values are accepted. When a <code>BigFloat</code> 949is returned, no rounding is performed. 950</p> 951</dd> 952</dl> 953 954<a name="Math-mode"></a> 955<h2 class="chapter">5 Math mode</h2> 956 957<a name="Introduction-4"></a> 958<h3 class="section">5.1 Introduction</h3> 959 960<p>A new <em>math mode</em> is enabled with the <code>"use math"</code> 961directive. <code>"use bigint"</code> is implied in math mode. With this 962mode, writing mathematical expressions is more intuitive, exact 963results (e.g. fractions) can be computed for all operators and floating 964point literals have the <code>BigFloat</code> type by default. 965</p> 966<p>It propagates the same way as the <em>strict mode</em>. In 967this mode: 968</p> 969<ul> 970<li> The <code>^</code> operator is a similar to the power operator (<code>**</code>). 971 972</li><li> The power operator (both <code>^</code> and <code>**</code>) grammar is modified so that <code>-2^2</code> is allowed and yields <code>-4</code>. 973 974</li><li> The logical xor operator is still available with the <code>^^</code> operator. 975 976</li><li> The division operator invokes <code>BigInt[Symbol.operatorDiv]</code> in case both operands are integers. 977 978</li><li> The power operator invokes <code>BigInt[Symbol.operatorPow]</code> in case both operands are integers and the exponent is strictly negative. 979 980</li><li> The modulo operator returns the Euclidian remainder (always positive) instead of the truncated remainder. 981 982</li><li> Floating point literals are <code>BigFloat</code> by default (i.e. a <code>l</code> suffix is implied). 983 984</li></ul> 985 986<a name="Builtin-Object-changes-3"></a> 987<h3 class="section">5.2 Builtin Object changes</h3> 988 989<a name="Symbol-constructor-1"></a> 990<h4 class="subsection">5.2.1 <code>Symbol</code> constructor</h4> 991 992<p>The following global symbol is added for the operator overloading: 993</p><dl compact="compact"> 994<dt><code>operatorMathMod</code></dt> 995</dl> 996 997<a name="Remaining-issues"></a> 998<h3 class="section">5.3 Remaining issues</h3> 999 1000<ol> 1001<li> A new floating point literal suffix could be added for <code>Number</code> literals. 1002 1003</li></ol> 1004 1005<div class="footnote"> 1006<hr> 1007<h4 class="footnotes-heading">Footnotes</h4> 1008 1009<h3><a name="FOOT1" href="#DOCF1">(1)</a></h3> 1010<p><a href="https://tc39.github.io/proposal-bigint/">https://tc39.github.io/proposal-bigint/</a></p> 1011<h3><a name="FOOT2" href="#DOCF2">(2)</a></h3> 1012<p><a href="https://tc39.github.io/proposal-bigint/">https://tc39.github.io/proposal-bigint/</a></p> 1013<h3><a name="FOOT3" href="#DOCF3">(3)</a></h3> 1014<p>Could be extended to 53 bits without changing the principle.</p> 1015<h3><a name="FOOT4" href="#DOCF4">(4)</a></h3> 1016<p>The unsigned right right operator could be removed in bigint mode.</p> 1017<h3><a name="FOOT5" href="#DOCF5">(5)</a></h3> 1018<p>The 1019rationale is that the rounding mode changes must always be 1020explicit.</p> 1021<h3><a name="FOOT6" href="#DOCF6">(6)</a></h3> 1022<p>The rationale is to avoid side effects for the built-in 1023operators.</p> 1024<h3><a name="FOOT7" href="#DOCF7">(7)</a></h3> 1025<p>Base 10 floating point literals cannot usually be 1026exactly represented as base 2 floating point number. In order to 1027ensure that the literal is represented accurately with the current 1028precision, it must be evaluated at runtime.</p> 1029<h3><a name="FOOT8" href="#DOCF8">(8)</a></h3> 1030<p>Could be removed in case a deterministic behvior for floating point operations is required.</p> 1031</div> 1032<hr> 1033 1034 1035 1036</body> 1037</html> 1038