734 lines
30 KiB
HTML
734 lines
30 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<!-- Created by GNU Texinfo 6.1, http://www.gnu.org/software/texinfo/ -->
|
|
<head>
|
|
<title>Javascript Bignum Extensions</title>
|
|
|
|
<meta name="description" content="Javascript Bignum Extensions">
|
|
<meta name="keywords" content="Javascript Bignum Extensions">
|
|
<meta name="resource-type" content="document">
|
|
<meta name="distribution" content="global">
|
|
<meta name="Generator" content="makeinfo">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<link href="#SEC_Contents" rel="contents" title="Table of Contents">
|
|
<style type="text/css">
|
|
<!--
|
|
a.summary-letter {text-decoration: none}
|
|
blockquote.indentedblock {margin-right: 0em}
|
|
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
|
|
blockquote.smallquotation {font-size: smaller}
|
|
div.display {margin-left: 3.2em}
|
|
div.example {margin-left: 3.2em}
|
|
div.lisp {margin-left: 3.2em}
|
|
div.smalldisplay {margin-left: 3.2em}
|
|
div.smallexample {margin-left: 3.2em}
|
|
div.smalllisp {margin-left: 3.2em}
|
|
kbd {font-style: oblique}
|
|
pre.display {font-family: inherit}
|
|
pre.format {font-family: inherit}
|
|
pre.menu-comment {font-family: serif}
|
|
pre.menu-preformatted {font-family: serif}
|
|
pre.smalldisplay {font-family: inherit; font-size: smaller}
|
|
pre.smallexample {font-size: smaller}
|
|
pre.smallformat {font-family: inherit; font-size: smaller}
|
|
pre.smalllisp {font-size: smaller}
|
|
span.nolinebreak {white-space: nowrap}
|
|
span.roman {font-family: initial; font-weight: normal}
|
|
span.sansserif {font-family: sans-serif; font-weight: normal}
|
|
ul.no-bullet {list-style: none}
|
|
-->
|
|
</style>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
|
|
|
|
</head>
|
|
|
|
<body lang="en">
|
|
<h1 class="settitle" align="center">Javascript Bignum Extensions</h1>
|
|
|
|
<a name="SEC_Contents"></a>
|
|
<h2 class="contents-heading">Table of Contents</h2>
|
|
|
|
<div class="contents">
|
|
<ul class="no-bullet">
|
|
<li><a name="toc-Introduction" href="#Introduction">1 Introduction</a></li>
|
|
<li><a name="toc-Operator-overloading" href="#Operator-overloading">2 Operator overloading</a></li>
|
|
<li><a name="toc-BigInt-extensions" href="#BigInt-extensions">3 BigInt extensions</a></li>
|
|
<li><a name="toc-BigFloat" href="#BigFloat">4 BigFloat</a>
|
|
<ul class="no-bullet">
|
|
<li><a name="toc-Introduction-1" href="#Introduction-1">4.1 Introduction</a></li>
|
|
<li><a name="toc-Floating-point-rounding" href="#Floating-point-rounding">4.2 Floating point rounding</a></li>
|
|
<li><a name="toc-Operators" href="#Operators">4.3 Operators</a></li>
|
|
<li><a name="toc-BigFloat-literals" href="#BigFloat-literals">4.4 BigFloat literals</a></li>
|
|
<li><a name="toc-Builtin-Object-changes" href="#Builtin-Object-changes">4.5 Builtin Object changes</a>
|
|
<ul class="no-bullet">
|
|
<li><a name="toc-BigFloat-function" href="#BigFloat-function">4.5.1 <code>BigFloat</code> function</a></li>
|
|
<li><a name="toc-BigFloat_002eprototype" href="#BigFloat_002eprototype">4.5.2 <code>BigFloat.prototype</code></a></li>
|
|
<li><a name="toc-BigFloatEnv-constructor" href="#BigFloatEnv-constructor">4.5.3 <code>BigFloatEnv</code> constructor</a></li>
|
|
</ul></li>
|
|
</ul></li>
|
|
<li><a name="toc-BigDecimal" href="#BigDecimal">5 BigDecimal</a>
|
|
<ul class="no-bullet">
|
|
<li><a name="toc-Operators-1" href="#Operators-1">5.1 Operators</a></li>
|
|
<li><a name="toc-BigDecimal-literals" href="#BigDecimal-literals">5.2 BigDecimal literals</a></li>
|
|
<li><a name="toc-Builtin-Object-changes-1" href="#Builtin-Object-changes-1">5.3 Builtin Object changes</a>
|
|
<ul class="no-bullet">
|
|
<li><a name="toc-The-BigDecimal-function_002e" href="#The-BigDecimal-function_002e">5.3.1 The <code>BigDecimal</code> function.</a></li>
|
|
<li><a name="toc-Properties-of-the-BigDecimal-object" href="#Properties-of-the-BigDecimal-object">5.3.2 Properties of the <code>BigDecimal</code> object</a></li>
|
|
<li><a name="toc-Properties-of-the-BigDecimal_002eprototype-object" href="#Properties-of-the-BigDecimal_002eprototype-object">5.3.3 Properties of the <code>BigDecimal.prototype</code> object</a></li>
|
|
</ul></li>
|
|
</ul></li>
|
|
<li><a name="toc-Math-mode" href="#Math-mode">6 Math mode</a></li>
|
|
|
|
</ul>
|
|
</div>
|
|
|
|
|
|
<a name="Introduction"></a>
|
|
<h2 class="chapter">1 Introduction</h2>
|
|
|
|
<p>The Bignum extensions add the following features to the Javascript
|
|
language while being 100% backward compatible:
|
|
</p>
|
|
<ul>
|
|
<li> Operator overloading with a dispatch logic inspired from the proposal available at <a href="https://github.com/tc39/proposal-operator-overloading/">https://github.com/tc39/proposal-operator-overloading/</a>.
|
|
|
|
</li><li> Arbitrarily large floating point numbers (<code>BigFloat</code>) in base 2 using the IEEE 754 semantics.
|
|
|
|
</li><li> Arbitrarily large floating point numbers (<code>BigDecimal</code>) in base 10 based on the proposal available at
|
|
<a href="https://github.com/littledan/proposal-bigdecimal">https://github.com/littledan/proposal-bigdecimal</a>.
|
|
|
|
</li><li> <code>math</code> mode: arbitrarily large integers and floating point numbers are available by default. The integer division and power can be overloaded for example to return a fraction. The modulo operator (<code>%</code>) is defined as the Euclidian
|
|
remainder. <code>^</code> is an alias to the power operator
|
|
(<code>**</code>). <code>^^</code> is used as the exclusive or operator.
|
|
|
|
</li></ul>
|
|
|
|
<p>The extensions are independent from each other except the <code>math</code>
|
|
mode which relies on BigFloat and operator overloading.
|
|
</p>
|
|
<a name="Operator-overloading"></a>
|
|
<h2 class="chapter">2 Operator overloading</h2>
|
|
|
|
<p>Operator overloading is inspired from the proposal available at
|
|
<a href="https://github.com/tc39/proposal-operator-overloading/">https://github.com/tc39/proposal-operator-overloading/</a>. It
|
|
implements the same dispatch logic but finds the operator sets by
|
|
looking at the <code>Symbol.operatorSet</code> property in the objects. The
|
|
changes were done in order to simplify the implementation.
|
|
</p>
|
|
<p>More precisely, the following modifications were made:
|
|
</p>
|
|
<ul>
|
|
<li> <code>with operators from</code> is not supported. Operator overloading is always enabled.
|
|
|
|
</li><li> The dispatch is not based on a static <code>[[OperatorSet]]</code> field in all instances. Instead, a dynamic lookup of the <code>Symbol.operatorSet</code> property is done. This property is typically added in the prototype of each object.
|
|
|
|
</li><li> <code>Operators.create(...dictionaries)</code> is used to create a new OperatorSet object. The <code>Operators</code> function is supported as an helper to be closer to the TC39 proposal.
|
|
|
|
</li><li> <code>[]</code> cannot be overloaded.
|
|
|
|
</li><li> In math mode, the BigInt division and power operators can be overloaded with <code>Operators.updateBigIntOperators(dictionary)</code>.
|
|
|
|
</li></ul>
|
|
|
|
<a name="BigInt-extensions"></a>
|
|
<h2 class="chapter">3 BigInt extensions</h2>
|
|
|
|
<p>A few properties are added to the BigInt object:
|
|
</p>
|
|
<dl compact="compact">
|
|
<dt><code>tdiv(a, b)</code></dt>
|
|
<dd><p>Return <em>trunc(a/b)</em>. <code>b = 0</code> raises a RangeError
|
|
exception.
|
|
</p>
|
|
</dd>
|
|
<dt><code>fdiv(a, b)</code></dt>
|
|
<dd><p>Return <em>\lfloor a/b \rfloor</em>. <code>b = 0</code> raises a RangeError
|
|
exception.
|
|
</p>
|
|
</dd>
|
|
<dt><code>cdiv(a, b)</code></dt>
|
|
<dd><p>Return <em>\lceil a/b \rceil</em>. <code>b = 0</code> raises a RangeError
|
|
exception.
|
|
</p>
|
|
</dd>
|
|
<dt><code>ediv(a, b)</code></dt>
|
|
<dd><p>Return <em>sgn(b) \lfloor a/{|b|} \rfloor</em> (Euclidian
|
|
division). <code>b = 0</code> raises a RangeError exception.
|
|
</p>
|
|
</dd>
|
|
<dt><code>tdivrem(a, b)</code></dt>
|
|
<dt><code>fdivrem(a, b)</code></dt>
|
|
<dt><code>cdivrem(a, b)</code></dt>
|
|
<dt><code>edivrem(a, b)</code></dt>
|
|
<dd><p>Return an array of two elements. The first element is the quotient,
|
|
the second is the remainder. The same rounding is done as the
|
|
corresponding division operation.
|
|
</p>
|
|
</dd>
|
|
<dt><code>sqrt(a)</code></dt>
|
|
<dd><p>Return <em>\lfloor \sqrt(a) \rfloor</em>. A RangeError exception is
|
|
raised if <em>a < 0</em>.
|
|
</p>
|
|
</dd>
|
|
<dt><code>sqrtrem(a)</code></dt>
|
|
<dd><p>Return an array of two elements. The first element is <em>\lfloor
|
|
\sqrt{a} \rfloor</em>. The second element is <em>a-\lfloor \sqrt{a}
|
|
\rfloor^2</em>. A RangeError exception is raised if <em>a < 0</em>.
|
|
</p>
|
|
</dd>
|
|
<dt><code>floorLog2(a)</code></dt>
|
|
<dd><p>Return -1 if <em>a \leq 0</em> otherwise return <em>\lfloor \log2(a) \rfloor</em>.
|
|
</p>
|
|
</dd>
|
|
<dt><code>ctz(a)</code></dt>
|
|
<dd><p>Return the number of trailing zeros in the two’s complement binary representation of a. Return -1 if <em>a=0</em>.
|
|
</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<a name="BigFloat"></a>
|
|
<h2 class="chapter">4 BigFloat</h2>
|
|
|
|
<a name="Introduction-1"></a>
|
|
<h3 class="section">4.1 Introduction</h3>
|
|
|
|
<p>This extension adds the <code>BigFloat</code> primitive type. The
|
|
<code>BigFloat</code> type represents floating point numbers in base 2
|
|
with the IEEE 754 semantics. A floating
|
|
point number is represented as a sign, mantissa and exponent. The
|
|
special values <code>NaN</code>, <code>+/-Infinity</code>, <code>+0</code> and <code>-0</code>
|
|
are supported. The mantissa and exponent can have any bit length with
|
|
an implementation specific minimum and maximum.
|
|
</p>
|
|
<a name="Floating-point-rounding"></a>
|
|
<h3 class="section">4.2 Floating point rounding</h3>
|
|
|
|
<p>Each floating point operation operates with infinite precision and
|
|
then rounds the result according to the specified floating point
|
|
environment (<code>BigFloatEnv</code> object). The status flags of the
|
|
environment are also set according to the result of the operation.
|
|
</p>
|
|
<p>If no floating point environment is provided, the global floating
|
|
point environment is used.
|
|
</p>
|
|
<p>The rounding mode of the global floating point environment is always
|
|
<code>RNDN</code> (“round to nearest with ties to even”)<a name="DOCF1" href="#FOOT1"><sup>1</sup></a>. The status flags of the global environment cannot be
|
|
read<a name="DOCF2" href="#FOOT2"><sup>2</sup></a>. The precision of the global environment is
|
|
<code>BigFloatEnv.prec</code>. The number of exponent bits of the global
|
|
environment is <code>BigFloatEnv.expBits</code>. The global environment
|
|
subnormal flag is set to <code>true</code>.
|
|
</p>
|
|
<p>For example, <code>prec = 53</code> and <code> expBits = 11</code> exactly give
|
|
the same precision as the IEEE 754 64 bit floating point format. The
|
|
default precision is <code>prec = 113</code> and <code> expBits = 15</code> (IEEE
|
|
754 128 bit floating point format).
|
|
</p>
|
|
<p>The global floating point environment can only be modified temporarily
|
|
when calling a function (see <code>BigFloatEnv.setPrec</code>). Hence a
|
|
function can change the global floating point environment for its
|
|
callees but not for its caller.
|
|
</p>
|
|
<a name="Operators"></a>
|
|
<h3 class="section">4.3 Operators</h3>
|
|
|
|
<p>The builtin operators are extended so that a BigFloat is returned if
|
|
at least one operand is a BigFloat. The computations are always done
|
|
with infinite precision and rounded according to the global floating
|
|
point environment.
|
|
</p>
|
|
<p><code>typeof</code> applied on a <code>BigFloat</code> returns <code>bigfloat</code>.
|
|
</p>
|
|
<p>BigFloat can be compared with all the other numeric types and the
|
|
result follows the expected mathematical relations.
|
|
</p>
|
|
<p>However, since BigFloat and Number are different types they are never
|
|
equal when using the strict comparison operators (e.g. <code>0.0 ===
|
|
0.0l</code> is false).
|
|
</p>
|
|
<a name="BigFloat-literals"></a>
|
|
<h3 class="section">4.4 BigFloat literals</h3>
|
|
|
|
<p>BigFloat literals are floating point numbers with a trailing <code>l</code>
|
|
suffix. BigFloat literals have an infinite precision. They are rounded
|
|
according to the global floating point environment when they are
|
|
evaluated.<a name="DOCF3" href="#FOOT3"><sup>3</sup></a>
|
|
</p>
|
|
<a name="Builtin-Object-changes"></a>
|
|
<h3 class="section">4.5 Builtin Object changes</h3>
|
|
|
|
<a name="BigFloat-function"></a>
|
|
<h4 class="subsection">4.5.1 <code>BigFloat</code> function</h4>
|
|
|
|
<p>The <code>BigFloat</code> function cannot be invoked as a constructor. When
|
|
invoked as a function: the parameter is converted to a primitive
|
|
type. If the result is a numeric type, it is converted to BigFloat
|
|
without rounding. If the result is a string, it is converted to
|
|
BigFloat using the precision of the global floating point environment.
|
|
</p>
|
|
<p><code>BigFloat</code> properties:
|
|
</p>
|
|
<dl compact="compact">
|
|
<dt><code>LN2</code></dt>
|
|
<dt><code>PI</code></dt>
|
|
<dd><p>Getter. Return the value of the corresponding mathematical constant
|
|
rounded to nearest, ties to even with the current global
|
|
precision. The constant values are cached for small precisions.
|
|
</p>
|
|
</dd>
|
|
<dt><code>MIN_VALUE</code></dt>
|
|
<dt><code>MAX_VALUE</code></dt>
|
|
<dt><code>EPSILON</code></dt>
|
|
<dd><p>Getter. Return the minimum, maximum and epsilon <code>BigFloat</code> values
|
|
(same definition as the corresponding <code>Number</code> constants).
|
|
</p>
|
|
</dd>
|
|
<dt><code>fpRound(a[, e])</code></dt>
|
|
<dd><p>Round the floating point number <code>a</code> according to the floating
|
|
point environment <code>e</code> or the global environment if <code>e</code> is
|
|
undefined.
|
|
</p>
|
|
</dd>
|
|
<dt><code>parseFloat(a[, radix[, e]])</code></dt>
|
|
<dd><p>Parse the string <code>a</code> as a floating point number in radix
|
|
<code>radix</code>. The radix is 0 (default) or from 2 to 36. The radix 0
|
|
means radix 10 unless there is a hexadecimal or binary prefix. The
|
|
result is rounded according to the floating point environment <code>e</code>
|
|
or the global environment if <code>e</code> is undefined.
|
|
</p>
|
|
</dd>
|
|
<dt><code>isFinite(a)</code></dt>
|
|
<dd><p>Return true if <code>a</code> is a finite bigfloat.
|
|
</p>
|
|
</dd>
|
|
<dt><code>isNaN(a)</code></dt>
|
|
<dd><p>Return true if <code>a</code> is a NaN bigfloat.
|
|
</p>
|
|
</dd>
|
|
<dt><code>add(a, b[, e])</code></dt>
|
|
<dt><code>sub(a, b[, e])</code></dt>
|
|
<dt><code>mul(a, b[, e])</code></dt>
|
|
<dt><code>div(a, b[, e])</code></dt>
|
|
<dd><p>Perform the specified floating point operation and round the floating
|
|
point number <code>a</code> according to the floating point environment
|
|
<code>e</code> or the global environment if <code>e</code> is undefined. If
|
|
<code>e</code> is specified, the floating point status flags are updated.
|
|
</p>
|
|
</dd>
|
|
<dt><code>floor(x)</code></dt>
|
|
<dt><code>ceil(x)</code></dt>
|
|
<dt><code>round(x)</code></dt>
|
|
<dt><code>trunc(x)</code></dt>
|
|
<dd><p>Round to an integer. No additional rounding is performed.
|
|
</p>
|
|
</dd>
|
|
<dt><code>abs(x)</code></dt>
|
|
<dd><p>Return the absolute value of x. No additional rounding is performed.
|
|
</p>
|
|
</dd>
|
|
<dt><code>fmod(x, y[, e])</code></dt>
|
|
<dt><code>remainder(x, y[, e])</code></dt>
|
|
<dd><p>Floating point remainder. The quotient is truncated to zero (fmod) or
|
|
to the nearest integer with ties to even (remainder). <code>e</code> is an
|
|
optional floating point environment.
|
|
</p>
|
|
</dd>
|
|
<dt><code>sqrt(x[, e])</code></dt>
|
|
<dd><p>Square root. Return a rounded floating point number. <code>e</code> is an
|
|
optional floating point environment.
|
|
</p>
|
|
</dd>
|
|
<dt><code>sin(x[, e])</code></dt>
|
|
<dt><code>cos(x[, e])</code></dt>
|
|
<dt><code>tan(x[, e])</code></dt>
|
|
<dt><code>asin(x[, e])</code></dt>
|
|
<dt><code>acos(x[, e])</code></dt>
|
|
<dt><code>atan(x[, e])</code></dt>
|
|
<dt><code>atan2(x, y[, e])</code></dt>
|
|
<dt><code>exp(x[, e])</code></dt>
|
|
<dt><code>log(x[, e])</code></dt>
|
|
<dt><code>pow(x, y[, e])</code></dt>
|
|
<dd><p>Transcendental operations. Return a rounded floating point
|
|
number. <code>e</code> is an optional floating point environment.
|
|
</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<a name="BigFloat_002eprototype"></a>
|
|
<h4 class="subsection">4.5.2 <code>BigFloat.prototype</code></h4>
|
|
|
|
<p>The following properties are modified:
|
|
</p>
|
|
<dl compact="compact">
|
|
<dt><code>valueOf()</code></dt>
|
|
<dd><p>Return the bigfloat primitive value corresponding to <code>this</code>.
|
|
</p>
|
|
</dd>
|
|
<dt><code>toString(radix)</code></dt>
|
|
<dd>
|
|
<p>For floating point numbers:
|
|
</p>
|
|
<ul>
|
|
<li> If the radix is a power of two, the conversion is done with infinite
|
|
precision.
|
|
</li><li> Otherwise, the number is rounded to nearest with ties to even using
|
|
the global precision. It is then converted to string using the minimum
|
|
number of digits so that its conversion back to a floating point using
|
|
the global precision and round to nearest gives the same number.
|
|
|
|
</li></ul>
|
|
|
|
<p>The exponent letter is <code>e</code> for base 10, <code>p</code> for bases 2, 8,
|
|
16 with a binary exponent and <code>@</code> for the other bases.
|
|
</p>
|
|
</dd>
|
|
<dt><code>toPrecision(p, rnd_mode = BigFloatEnv.RNDNA, radix = 10)</code></dt>
|
|
<dt><code>toFixed(p, rnd_mode = BigFloatEnv.RNDNA, radix = 10)</code></dt>
|
|
<dt><code>toExponential(p, rnd_mode = BigFloatEnv.RNDNA, radix = 10)</code></dt>
|
|
<dd><p>Same semantics as the corresponding <code>Number</code> functions with
|
|
BigFloats. There is no limit on the accepted precision <code>p</code>. The
|
|
rounding mode and radix can be optionally specified. The radix must be
|
|
between 2 and 36.
|
|
</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<a name="BigFloatEnv-constructor"></a>
|
|
<h4 class="subsection">4.5.3 <code>BigFloatEnv</code> constructor</h4>
|
|
|
|
<p>The <code>BigFloatEnv([p, [,rndMode]]</code> constructor cannot be invoked as a
|
|
function. The floating point environment contains:
|
|
</p>
|
|
<ul>
|
|
<li> the mantissa precision in bits
|
|
|
|
</li><li> the exponent size in bits assuming an IEEE 754 representation;
|
|
|
|
</li><li> the subnormal flag (if true, subnormal floating point numbers can
|
|
be generated by the floating point operations).
|
|
|
|
</li><li> the rounding mode
|
|
|
|
</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.
|
|
|
|
</li></ul>
|
|
|
|
<p><code>new BigFloatEnv([p, [,rndMode]]</code> creates a new floating point
|
|
environment. The status flags are reset. If no parameter is given the
|
|
precision, exponent bits and subnormal flags are copied from the
|
|
global floating point environment. Otherwise, the precision is set to
|
|
<code>p</code>, the number of exponent bits is set to <code>expBitsMax</code> and the
|
|
subnormal flags is set to <code>false</code>. If <code>rndMode</code> is
|
|
<code>undefined</code>, the rounding mode is set to <code>RNDN</code>.
|
|
</p>
|
|
<p><code>BigFloatEnv</code> properties:
|
|
</p>
|
|
<dl compact="compact">
|
|
<dt><code>prec</code></dt>
|
|
<dd><p>Getter. Return the precision in bits of the global floating point
|
|
environment. The initial value is <code>113</code>.
|
|
</p>
|
|
</dd>
|
|
<dt><code>expBits</code></dt>
|
|
<dd><p>Getter. Return the exponent size in bits of the global floating point
|
|
environment assuming an IEEE 754 representation. The initial value is
|
|
<code>15</code>.
|
|
</p>
|
|
</dd>
|
|
<dt><code>setPrec(f, p[, e])</code></dt>
|
|
<dd><p>Set the precision of the global floating point environment to <code>p</code>
|
|
and the exponent size to <code>e</code> then call the function
|
|
<code>f</code>. Then the Float precision and exponent size are reset to
|
|
their precious value and the return value of <code>f</code> is returned (or
|
|
an exception is raised if <code>f</code> raised an exception). If <code>e</code>
|
|
is <code>undefined</code> it is set to <code>BigFloatEnv.expBitsMax</code>.
|
|
</p>
|
|
</dd>
|
|
<dt><code>precMin</code></dt>
|
|
<dd><p>Read-only integer. Return the minimum allowed precision. Must be at least 2.
|
|
</p>
|
|
</dd>
|
|
<dt><code>precMax</code></dt>
|
|
<dd><p>Read-only integer. Return the maximum allowed precision. Must be at least 113.
|
|
</p>
|
|
</dd>
|
|
<dt><code>expBitsMin</code></dt>
|
|
<dd><p>Read-only integer. Return the minimum allowed exponent size in
|
|
bits. Must be at least 3.
|
|
</p>
|
|
</dd>
|
|
<dt><code>expBitsMax</code></dt>
|
|
<dd><p>Read-only integer. Return the maximum allowed exponent size in
|
|
bits. Must be at least 15.
|
|
</p>
|
|
</dd>
|
|
<dt><code>RNDN</code></dt>
|
|
<dd><p>Read-only integer. Round to nearest, with ties to even rounding mode.
|
|
</p>
|
|
</dd>
|
|
<dt><code>RNDZ</code></dt>
|
|
<dd><p>Read-only integer. Round to zero rounding mode.
|
|
</p>
|
|
</dd>
|
|
<dt><code>RNDD</code></dt>
|
|
<dd><p>Read-only integer. Round to -Infinity rounding mode.
|
|
</p>
|
|
</dd>
|
|
<dt><code>RNDU</code></dt>
|
|
<dd><p>Read-only integer. Round to +Infinity rounding mode.
|
|
</p>
|
|
</dd>
|
|
<dt><code>RNDNA</code></dt>
|
|
<dd><p>Read-only integer. Round to nearest, with ties away from zero rounding mode.
|
|
</p>
|
|
</dd>
|
|
<dt><code>RNDA</code></dt>
|
|
<dd><p>Read-only integer. Round away from zero rounding mode.
|
|
</p>
|
|
</dd>
|
|
<dt><code>RNDF<a name="DOCF4" href="#FOOT4"><sup>4</sup></a></code></dt>
|
|
<dd><p>Read-only integer. Faithful rounding mode. The result is
|
|
non-deterministically rounded to -Infinity or +Infinity. This rounding
|
|
mode usually gives a faster and deterministic running time for the
|
|
floating point operations.
|
|
</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p><code>BigFloatEnv.prototype</code> properties:
|
|
</p>
|
|
<dl compact="compact">
|
|
<dt><code>prec</code></dt>
|
|
<dd><p>Getter and setter (Integer). Return or set the precision in bits.
|
|
</p>
|
|
</dd>
|
|
<dt><code>expBits</code></dt>
|
|
<dd><p>Getter and setter (Integer). Return or set the exponent size in bits
|
|
assuming an IEEE 754 representation.
|
|
</p>
|
|
</dd>
|
|
<dt><code>rndMode</code></dt>
|
|
<dd><p>Getter and setter (Integer). Return or set the rounding mode.
|
|
</p>
|
|
</dd>
|
|
<dt><code>subnormal</code></dt>
|
|
<dd><p>Getter and setter (Boolean). subnormal flag. It is false when
|
|
<code>expBits = expBitsMax</code>.
|
|
</p>
|
|
</dd>
|
|
<dt><code>clearStatus()</code></dt>
|
|
<dd><p>Clear the status flags.
|
|
</p>
|
|
</dd>
|
|
<dt><code>invalidOperation</code></dt>
|
|
<dt><code>divideByZero</code></dt>
|
|
<dt><code>overflow</code></dt>
|
|
<dt><code>underflow</code></dt>
|
|
<dt><code>inexact</code></dt>
|
|
<dd><p>Getter and setter (Boolean). Status flags.
|
|
</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<a name="BigDecimal"></a>
|
|
<h2 class="chapter">5 BigDecimal</h2>
|
|
|
|
<p>This extension adds the <code>BigDecimal</code> primitive type. The
|
|
<code>BigDecimal</code> type represents floating point numbers in base
|
|
10. It is inspired from the proposal available at
|
|
<a href="https://github.com/littledan/proposal-bigdecimal">https://github.com/littledan/proposal-bigdecimal</a>.
|
|
</p>
|
|
<p>The <code>BigDecimal</code> floating point numbers are always normalized and
|
|
finite. There is no concept of <code>-0</code>, <code>Infinity</code> or
|
|
<code>NaN</code>. By default, all the computations are done with infinite
|
|
precision.
|
|
</p>
|
|
<a name="Operators-1"></a>
|
|
<h3 class="section">5.1 Operators</h3>
|
|
|
|
<p>The following builtin operators support BigDecimal:
|
|
</p>
|
|
<dl compact="compact">
|
|
<dt><code>+</code></dt>
|
|
<dt><code>-</code></dt>
|
|
<dt><code>*</code></dt>
|
|
<dd><p>Both operands must be BigDecimal. The result is computed with infinite
|
|
precision.
|
|
</p></dd>
|
|
<dt><code>%</code></dt>
|
|
<dd><p>Both operands must be BigDecimal. The result is computed with infinite
|
|
precision. A range error is throws in case of division by zero.
|
|
</p>
|
|
</dd>
|
|
<dt><code>/</code></dt>
|
|
<dd><p>Both operands must be BigDecimal. A range error is throws in case of
|
|
division by zero or if the result cannot be represented with infinite
|
|
precision (use <code>BigDecimal.div</code> to specify the rounding).
|
|
</p>
|
|
</dd>
|
|
<dt><code>**</code></dt>
|
|
<dd><p>Both operands must be BigDecimal. The exponent must be a positive
|
|
integer. The result is computed with infinite precision.
|
|
</p>
|
|
</dd>
|
|
<dt><code>===</code></dt>
|
|
<dd><p>When one of the operand is a BigDecimal, return true if both operands
|
|
are a BigDecimal and if they are equal.
|
|
</p>
|
|
</dd>
|
|
<dt><code>==</code></dt>
|
|
<dt><code>!=</code></dt>
|
|
<dt><code><=</code></dt>
|
|
<dt><code>>=</code></dt>
|
|
<dt><code><</code></dt>
|
|
<dt><code>></code></dt>
|
|
<dd>
|
|
<p>Numerical comparison. When one of the operand is not a BigDecimal, it is
|
|
converted to BigDecimal by using ToString(). Hence comparisons between
|
|
Number and BigDecimal do not use the exact mathematical value of the
|
|
Number value.
|
|
</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<a name="BigDecimal-literals"></a>
|
|
<h3 class="section">5.2 BigDecimal literals</h3>
|
|
|
|
<p>BigDecimal literals are decimal floating point numbers with a trailing
|
|
<code>m</code> suffix.
|
|
</p>
|
|
<a name="Builtin-Object-changes-1"></a>
|
|
<h3 class="section">5.3 Builtin Object changes</h3>
|
|
|
|
<a name="The-BigDecimal-function_002e"></a>
|
|
<h4 class="subsection">5.3.1 The <code>BigDecimal</code> function.</h4>
|
|
|
|
<p>It returns <code>0m</code> if no parameter is provided. Otherwise the first
|
|
parameter is converted to a bigdecimal by using ToString(). Hence
|
|
Number values are not converted to their exact numerical value as
|
|
BigDecimal.
|
|
</p>
|
|
<a name="Properties-of-the-BigDecimal-object"></a>
|
|
<h4 class="subsection">5.3.2 Properties of the <code>BigDecimal</code> object</h4>
|
|
|
|
<dl compact="compact">
|
|
<dt><code>add(a, b[, e])</code></dt>
|
|
<dt><code>sub(a, b[, e])</code></dt>
|
|
<dt><code>mul(a, b[, e])</code></dt>
|
|
<dt><code>div(a, b[, e])</code></dt>
|
|
<dt><code>mod(a, b[, e])</code></dt>
|
|
<dt><code>sqrt(a, e)</code></dt>
|
|
<dt><code>round(a, e)</code></dt>
|
|
<dd><p>Perform the specified floating point operation and round the floating
|
|
point result according to the rounding object <code>e</code>. If the
|
|
rounding object is not present, the operation is executed with
|
|
infinite precision.
|
|
</p>
|
|
<p>For <code>div</code>, a <code>RangeError</code> exception is thrown in case of
|
|
division by zero or if the result cannot be represented with infinite
|
|
precision if no rounding object is present.
|
|
</p>
|
|
<p>For <code>sqrt</code>, a range error is thrown if <code>a</code> is less than
|
|
zero.
|
|
</p>
|
|
<p>The rounding object must contain the following properties:
|
|
<code>roundingMode</code> is a string specifying the rounding mode
|
|
(<code>"floor"</code>, <code>"ceiling"</code>, <code>"down"</code>, <code>"up"</code>,
|
|
<code>"half-even"</code>, <code>"half-up"</code>). Either
|
|
<code>maximumSignificantDigits</code> or <code>maximumFractionDigits</code> must
|
|
be present to specify respectively the number of significant digits
|
|
(must be >= 1) or the number of digits after the decimal point (must
|
|
be >= 0).
|
|
</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<a name="Properties-of-the-BigDecimal_002eprototype-object"></a>
|
|
<h4 class="subsection">5.3.3 Properties of the <code>BigDecimal.prototype</code> object</h4>
|
|
|
|
<dl compact="compact">
|
|
<dt><code>valueOf()</code></dt>
|
|
<dd><p>Return the bigdecimal primitive value corresponding to <code>this</code>.
|
|
</p>
|
|
</dd>
|
|
<dt><code>toString()</code></dt>
|
|
<dd><p>Convert <code>this</code> to a string with infinite precision in base 10.
|
|
</p>
|
|
</dd>
|
|
<dt><code>toPrecision(p, rnd_mode = "half-up")</code></dt>
|
|
<dt><code>toFixed(p, rnd_mode = "half-up")</code></dt>
|
|
<dt><code>toExponential(p, rnd_mode = "half-up")</code></dt>
|
|
<dd><p>Convert the BigDecimal <code>this</code> to string with the specified
|
|
precision <code>p</code>. There is no limit on the accepted precision
|
|
<code>p</code>. The rounding mode can be optionally
|
|
specified. <code>toPrecision</code> outputs either in decimal fixed notation
|
|
or in decimal exponential notation with a <code>p</code> digits of
|
|
precision. <code>toExponential</code> outputs in decimal exponential
|
|
notation with <code>p</code> digits after the decimal point. <code>toFixed</code>
|
|
outputs in decimal notation with <code>p</code> digits after the decimal
|
|
point.
|
|
</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<a name="Math-mode"></a>
|
|
<h2 class="chapter">6 Math mode</h2>
|
|
|
|
<p>A new <em>math mode</em> is enabled with the <code>"use math"</code>
|
|
directive. It propagates the same way as the <em>strict mode</em>. It is
|
|
designed so that arbitrarily large integers and floating point numbers
|
|
are available by default. In order to minimize the number of changes
|
|
in the Javascript semantics, integers are represented either as Number
|
|
or BigInt depending on their magnitude. Floating point numbers are
|
|
always represented as BigFloat.
|
|
</p>
|
|
<p>The following changes are made to the Javascript semantics:
|
|
</p>
|
|
<ul>
|
|
<li> Floating point literals (i.e. number with a decimal point or an exponent) are <code>BigFloat</code> by default (i.e. a <code>l</code> suffix is implied). Hence <code>typeof 1.0 === "bigfloat"</code>.
|
|
|
|
</li><li> Integer literals (i.e. numbers without a decimal point or an exponent) with or without the <code>n</code> suffix are <code>BigInt</code> if their value cannot be represented as a safe integer. A safe integer is defined as a integer whose absolute value is smaller or equal to <code>2**53-1</code>. Hence <code>typeof 1 === "number "</code>, <code>typeof 1n === "number"</code> but <code>typeof 9007199254740992 === "bigint" </code>.
|
|
|
|
</li><li> All the bigint builtin operators and functions are modified so that their result is returned as a Number if it is a safe integer. Otherwise the result stays a BigInt.
|
|
|
|
</li><li> The builtin operators are modified so that they return an exact result (which can be a BigInt) if their operands are safe integers. Operands between Number and BigInt are accepted provided the Number operand is a safe integer. The integer power with a negative exponent returns a BigFloat as result. The integer division returns a BigFloat as result.
|
|
|
|
</li><li> The <code>^</code> operator is an alias to the power operator (<code>**</code>).
|
|
|
|
</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>.
|
|
|
|
</li><li> The logical xor operator is still available with the <code>^^</code> operator.
|
|
|
|
</li><li> The modulo operator (<code>%</code>) returns the Euclidian remainder (always positive) instead of the truncated remainder.
|
|
|
|
</li><li> The integer division operator can be overloaded with <code>Operators.updateBigIntOperators(dictionary)</code>.
|
|
|
|
</li><li> The integer power operator with a non zero negative exponent can be overloaded with <code>Operators.updateBigIntOperators(dictionary)</code>.
|
|
|
|
</li></ul>
|
|
|
|
<div class="footnote">
|
|
<hr>
|
|
<h4 class="footnotes-heading">Footnotes</h4>
|
|
|
|
<h3><a name="FOOT1" href="#DOCF1">(1)</a></h3>
|
|
<p>The
|
|
rationale is that the rounding mode changes must always be
|
|
explicit.</p>
|
|
<h3><a name="FOOT2" href="#DOCF2">(2)</a></h3>
|
|
<p>The rationale is to avoid side effects for the built-in
|
|
operators.</p>
|
|
<h3><a name="FOOT3" href="#DOCF3">(3)</a></h3>
|
|
<p>Base 10 floating point literals cannot usually be
|
|
exactly represented as base 2 floating point number. In order to
|
|
ensure that the literal is represented accurately with the current
|
|
precision, it must be evaluated at runtime.</p>
|
|
<h3><a name="FOOT4" href="#DOCF4">(4)</a></h3>
|
|
<p>Could be removed in case a deterministic behavior for floating point operations is required.</p>
|
|
</div>
|
|
<hr>
|
|
|
|
|
|
|
|
</body>
|
|
</html>
|