\input texinfo @iftex@afourpaper@headings double@end iftex @titlepage@afourpaper@sp 7@center @titlefont{Javascript Bignum Extensions}@sp 3@center Version 2020-01-11@sp 3@center Author: Fabrice Bellard@end titlepage @setfilename jsbignum.info@settitle Javascript Bignum Extensions @contents @chapter Introduction The Bignum extensions add the following features to the Javascriptlanguage while being 100% backward compatible: @itemize @item Operator overloading with a dispatch logic inspired from the proposal available at @url{https://github.com/tc39/proposal-operator-overloading/}. @item Arbitrarily large floating point numbers (@code{BigFloat}) in base 2 using the IEEE 754 semantics. @item Arbitrarily large floating point numbers (@code{BigDecimal}) in base 10 based on the proposal available at@url{https://github.com/littledan/proposal-bigdecimal}. @item @code{math} 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{%}) is defined as the Euclidianremainder. @code{^} is an alias to the power operator(@code{**}). @code{^^} is used as the exclusive or operator. @end itemize The extensions are independent from each other except the @code{math}mode which relies on BigFloat and operator overloading. @chapter Operator overloading Operator overloading is inspired from the proposal available at@url{https://github.com/tc39/proposal-operator-overloading/}. Itimplements the same dispatch logic but finds the operator sets bylooking at the @code{Symbol.operatorSet} property in the objects. Thechanges were done in order to simplify the implementation. More precisely, the following modifications were made: @itemize @item @code{with operators from} is not supported. Operator overloading is always enabled. @item The dispatch is not based on a static @code{[[OperatorSet]]} field in all instances. Instead, a dynamic lookup of the @code{Symbol.operatorSet} property is done. This property is typically added in the prototype of each object. @item @code{Operators.create(...dictionaries)} is used to create a new OperatorSet object. The @code{Operators} function is supported as an helper to be closer to the TC39 proposal. @item @code{[]} cannot be overloaded. @item In math mode, the BigInt division and power operators can be overloaded with @code{Operators.updateBigIntOperators(dictionary)}. @end itemize @chapter BigInt extensions A few properties are added to the BigInt object: @table @code @item tdiv(a, b)Return @math{trunc(a/b)}. @code{b = 0} raises a RangeErrorexception. @item fdiv(a, b)Return @math{\lfloor a/b \rfloor}. @code{b = 0} raises a RangeErrorexception. @item cdiv(a, b)Return @math{\lceil a/b \rceil}. @code{b = 0} raises a RangeErrorexception. @item ediv(a, b)Return @math{sgn(b) \lfloor a/{|b|} \rfloor} (Euclidiandivision). @code{b = 0} raises a RangeError exception. @item tdivrem(a, b)@item fdivrem(a, b)@item cdivrem(a, b)@item edivrem(a, b)Return an array of two elements. The first element is the quotient,the second is the remainder. The same rounding is done as thecorresponding division operation. @item sqrt(a)Return @math{\lfloor \sqrt(a) \rfloor}. A RangeError exception israised if @math{a < 0}. @item sqrtrem(a)Return an array of two elements. The first element is @math{\lfloor\sqrt{a} \rfloor}. The second element is @math{a-\lfloor \sqrt{a}\rfloor^2}. A RangeError exception is raised if @math{a < 0}. @item floorLog2(a)Return -1 if @math{a \leq 0} otherwise return @math{\lfloor \log2(a) \rfloor}. @item ctz(a)Return the number of trailing zeros in the two's complement binary representation of a. Return -1 if @math{a=0}. @end table @chapter BigFloat @section Introduction This extension adds the @code{BigFloat} primitive type. The@code{BigFloat} type represents floating point numbers in base 2with the IEEE 754 semantics. A floatingpoint number is represented as a sign, mantissa and exponent. Thespecial values @code{NaN}, @code{+/-Infinity}, @code{+0} and @code{-0}are supported. The mantissa and exponent can have any bit length withan implementation specific minimum and maximum. @section Floating point rounding Each floating point operation operates with infinite precision andthen rounds the result according to the specified floating pointenvironment (@code{BigFloatEnv} object). The status flags of theenvironment are also set according to the result of the operation. If no floating point environment is provided, the global floatingpoint environment is used. The rounding mode of the global floating point environment is always@code{RNDN} (``round to nearest with ties to even'')@footnote{Therationale is that the rounding mode changes must always beexplicit.}. The status flags of the global environment cannot beread@footnote{The rationale is to avoid side effects for the built-inoperators.}. The precision of the global environment is@code{BigFloatEnv.prec}. The number of exponent bits of the globalenvironment is @code{BigFloatEnv.expBits}. The global environmentsubnormal flag is set to @code{true}. For example, @code{prec = 53} and @code{ expBits = 11} exactly givethe same precision as the IEEE 754 64 bit floating point format. Thedefault precision is @code{prec = 113} and @code{ expBits = 15} (IEEE754 128 bit floating point format). The global floating point environment can only be modified temporarilywhen calling a function (see @code{BigFloatEnv.setPrec}). Hence afunction can change the global floating point environment for itscallees but not for its caller. @section Operators The builtin operators are extended so that a BigFloat is returned ifat least one operand is a BigFloat. The computations are always donewith infinite precision and rounded according to the global floatingpoint environment. @code{typeof} applied on a @code{BigFloat} returns @code{bigfloat}. BigFloat can be compared with all the other numeric types and theresult follows the expected mathematical relations. However, since BigFloat and Number are different types they are neverequal when using the strict comparison operators (e.g. @code{0.0 ===0.0l} is false). @section BigFloat literals BigFloat literals are floating point numbers with a trailing @code{l}suffix. BigFloat literals have an infinite precision. They are roundedaccording to the global floating point environment when they areevaluated.@footnote{Base 10 floating point literals cannot usually beexactly represented as base 2 floating point number. In order toensure that the literal is represented accurately with the currentprecision, it must be evaluated at runtime.} @section Builtin Object changes @subsection @code{BigFloat} function The @code{BigFloat} function cannot be invoked as a constructor. Wheninvoked as a function: the parameter is converted to a primitivetype. If the result is a numeric type, it is converted to BigFloatwithout rounding. If the result is a string, it is converted toBigFloat using the precision of the global floating point environment. @code{BigFloat} properties: @table @code @item LN2@item PIGetter. Return the value of the corresponding mathematical constantrounded to nearest, ties to even with the current globalprecision. The constant values are cached for small precisions. @item MIN_VALUE@item MAX_VALUE@item EPSILONGetter. Return the minimum, maximum and epsilon @code{BigFloat} values(same definition as the corresponding @code{Number} constants). @item fpRound(a[, e])Round the floating point number @code{a} according to the floatingpoint environment @code{e} or the global environment if @code{e} isundefined. @item parseFloat(a[, radix[, e]])Parse the string @code{a} as a floating point number in radix@code{radix}. The radix is 0 (default) or from 2 to 36. The radix 0means radix 10 unless there is a hexadecimal or binary prefix. Theresult is rounded according to the floating point environment @code{e}or the global environment if @code{e} is undefined. @item isFinite(a)Return true if @code{a} is a finite bigfloat. @item isNaN(a)Return true if @code{a} is a NaN bigfloat. @item add(a, b[, e])@item sub(a, b[, e])@item mul(a, b[, e])@item div(a, b[, e])Perform the specified floating point operation and round the floatingpoint number @code{a} according to the floating point environment@code{e} or the global environment if @code{e} is undefined. If@code{e} is specified, the floating point status flags are updated. @item floor(x)@item ceil(x)@item round(x)@item trunc(x)Round to an integer. No additional rounding is performed. @item abs(x)Return the absolute value of x. No additional rounding is performed. @item fmod(x, y[, e])@item remainder(x, y[, e])Floating point remainder. The quotient is truncated to zero (fmod) orto the nearest integer with ties to even (remainder). @code{e} is anoptional floating point environment. @item sqrt(x[, e])Square root. Return a rounded floating point number. @code{e} is anoptional floating point environment. @item sin(x[, e])@item cos(x[, e])@item tan(x[, e])@item asin(x[, e])@item acos(x[, e])@item atan(x[, e])@item atan2(x, y[, e])@item exp(x[, e])@item log(x[, e])@item pow(x, y[, e])Transcendental operations. Return a rounded floating pointnumber. @code{e} is an optional floating point environment. @end table @subsection @code{BigFloat.prototype} The following properties are modified: @table @code@item valueOf()Return the bigfloat primitive value corresponding to @code{this}. @item toString(radix) For floating point numbers: @itemize@itemIf the radix is a power of two, the conversion is done with infiniteprecision.@itemOtherwise, the number is rounded to nearest with ties to even usingthe global precision. It is then converted to string using the minimumnumber of digits so that its conversion back to a floating point usingthe global precision and round to nearest gives the same number.  @end itemize The exponent letter is @code{e} for base 10, @code{p} for bases 2, 8,16 with a binary exponent and @code{@@} for the other bases. @item toPrecision(p, rnd_mode = BigFloatEnv.RNDNA, radix = 10)@item toFixed(p, rnd_mode = BigFloatEnv.RNDNA, radix = 10)@item toExponential(p, rnd_mode = BigFloatEnv.RNDNA, radix = 10)Same semantics as the corresponding @code{Number} functions withBigFloats. There is no limit on the accepted precision @code{p}. Therounding mode and radix can be optionally specified. The radix must bebetween 2 and 36. @end table @subsection @code{BigFloatEnv} constructor The @code{BigFloatEnv([p, [,rndMode]]} constructor cannot be invoked as afunction. The floating point environment contains: @itemize@item the mantissa precision in bits @item the exponent size in bits assuming an IEEE 754 representation; @item the subnormal flag (if true, subnormal floating point numbers canbe generated by the floating point operations). @item the rounding mode @item 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()} or with the various status flag setters. @end itemize @code{new BigFloatEnv([p, [,rndMode]]} creates a new floating pointenvironment. The status flags are reset. If no parameter is given theprecision, exponent bits and subnormal flags are copied from theglobal floating point environment. Otherwise, the precision is set to@code{p}, the number of exponent bits is set to @code{expBitsMax} and thesubnormal flags is set to @code{false}. If @code{rndMode} is@code{undefined}, the rounding mode is set to @code{RNDN}. @code{BigFloatEnv} properties: @table @code @item precGetter. Return the precision in bits of the global floating pointenvironment. The initial value is @code{113}. @item expBitsGetter. Return the exponent size in bits of the global floating pointenvironment assuming an IEEE 754 representation. The initial value is@code{15}. @item setPrec(f, p[, e])Set the precision of the global floating point environment to @code{p}and the exponent size to @code{e} then call the function@code{f}. Then the Float precision and exponent size are reset totheir precious value and the return value of @code{f} is returned (oran exception is raised if @code{f} raised an exception). If @code{e}is @code{undefined} it is set to @code{BigFloatEnv.expBitsMax}. @item precMinRead-only integer. Return the minimum allowed precision. Must be at least 2. @item precMaxRead-only integer. Return the maximum allowed precision. Must be at least 113. @item expBitsMinRead-only integer. Return the minimum allowed exponent size inbits. Must be at least 3. @item expBitsMaxRead-only integer. Return the maximum allowed exponent size inbits. Must be at least 15. @item RNDNRead-only integer. Round to nearest, with ties to even rounding mode. @item RNDZRead-only integer. Round to zero rounding mode. @item RNDDRead-only integer. Round to -Infinity rounding mode. @item RNDURead-only integer. Round to +Infinity rounding mode. @item RNDNARead-only integer. Round to nearest, with ties away from zero rounding mode. @item RNDARead-only integer. Round away from zero rounding mode. @item RNDF@footnote{Could be removed in case a deterministic behavior for floating point operations is required.}Read-only integer. Faithful rounding mode. The result isnon-deterministically rounded to -Infinity or +Infinity. This roundingmode usually gives a faster and deterministic running time for thefloating point operations. @end table @code{BigFloatEnv.prototype} properties: @table @code @item precGetter and setter (Integer). Return or set the precision in bits. @item expBitsGetter and setter (Integer). Return or set the exponent size in bitsassuming an IEEE 754 representation. @item rndModeGetter and setter (Integer). Return or set the rounding mode. @item subnormalGetter and setter (Boolean). subnormal flag. It is false when@code{expBits = expBitsMax}. @item clearStatus()Clear the status flags. @item invalidOperation@item divideByZero@item overflow@item underflow@item inexactGetter and setter (Boolean). Status flags. @end table @chapter BigDecimal This extension adds the @code{BigDecimal} primitive type. The@code{BigDecimal} type represents floating point numbers in base10. It is inspired from the proposal available at@url{https://github.com/littledan/proposal-bigdecimal}. The @code{BigDecimal} floating point numbers are always normalized andfinite. There is no concept of @code{-0}, @code{Infinity} or@code{NaN}. By default, all the computations are done with infiniteprecision. @section Operators The following builtin operators support BigDecimal: @table @code @item +@item -@item *Both operands must be BigDecimal. The result is computed with infiniteprecision.@item %Both operands must be BigDecimal. The result is computed with infiniteprecision. A range error is throws in case of division by zero. @item /Both operands must be BigDecimal. A range error is throws in case ofdivision by zero or if the result cannot be represented with infiniteprecision (use @code{BigDecimal.div} to specify the rounding). @item **Both operands must be BigDecimal. The exponent must be a positiveinteger. The result is computed with infinite precision. @item ===When one of the operand is a BigDecimal, return true if both operandsare a BigDecimal and if they are equal. @item ==@item !=@item <=@item >=@item <@item > Numerical comparison. When one of the operand is not a BigDecimal, it isconverted to BigDecimal by using ToString(). Hence comparisons betweenNumber and BigDecimal do not use the exact mathematical value of theNumber value. @end table @section BigDecimal literals BigDecimal literals are decimal floating point numbers with a trailing@code{m} suffix. @section Builtin Object changes @subsection The @code{BigDecimal} function. It returns @code{0m} if no parameter is provided. Otherwise the firstparameter is converted to a bigdecimal by using ToString(). HenceNumber values are not converted to their exact numerical value asBigDecimal. @subsection Properties of the @code{BigDecimal} object @table @code @item add(a, b[, e])@item sub(a, b[, e])

Lines 1–500 of 589. Load more