Stage 1 Draft / September 17, 2021

ES BigInt Math (2021)

Introduction

This is the formal specification for a proposed extension of the Math JavaScript global object with BigInt operations. It modifies the original ECMAScript specification with several new or revised clauses. See the proposal's explainer for the proposal's background, motivation, and usage examples.

1 ECMAScript Data Types and Values

1.1 ECMAScript Language Types

1.1.1 Numeric Types

Editor's Note

This section augments the original Numeric Types clause.

ECMAScript has two built-in numeric types: Number and BigInt. In this specification, every numeric type T contains a multiplicative identity value denoted T::unit. The specification types also have the following abstract operations, likewise denoted T::op for a given operation with specification name op. All argument types are T. The "Result" column shows the return type, along with an indication if it is possible for some invocations of the operation to return an abrupt completion.

Table 1: Numeric Type Operations
Invocation Synopsis Example source Invoked by the Evaluation semantics of ... Result
T::bitwiseOR(x, y) x | y Binary Bitwise Operators T
T::abs(x) Math.abs(x) Math.abs ( x ) T
T::clz32(x) Math.clz32(x) Math.clz32 ( x ) T
T::sign(x) Math.sign(x) Math.sign ( x ) T
T::toString(x) String(x) Many expressions and built-in functions, via ToString ( argument ) String

1.1.1.1 The Number Type

1.1.1.1.1 Number::abs ( x )

The abstract operation Number::abs takes argument x (a Number). It performs the following steps when called:

  1. If x is NaN, return NaN.
  2. If x is -0𝔽, return +0𝔽.
  3. If x is -∞𝔽, return +∞𝔽.
  4. If x < +0𝔽, return -x.
  5. Return x.

1.1.1.1.2 Number::clz32 ( x )

The abstract operation Number::clz32 takes argument x (a Number). It performs the following steps when called:

  1. Let n32 be ? ToUint32(x).
  2. Let p be the number of leading zero bits in the unsigned 32-bit binary representation of n32.
  3. Return 𝔽(p).
 Note

If n is +0𝔽 or n is -0𝔽, this method returns 32𝔽. If the most significant bit of the 32-bit binary encoding of n is 1, this method returns +0𝔽.

1.1.1.1.3 Number::sign ( x )

The abstract operation Number::sign takes argument x (a Number). It performs the following steps when called:

  1. Let n be ? ToNumber(x).
  2. If n is NaN, n is +0𝔽, or n is -0𝔽, return n.
  3. If n < +0𝔽, return -1𝔽.
  4. Return 1𝔽.

1.1.1.2 The BigInt Type

1.1.1.2.1 BigInt::abs ( x )

The abstract operation BigInt::abs takes argument x (a BigInt). It performs the following steps when called:

  1. Return the BigInt value that represents abs(ℝ(x)).

1.1.1.2.2 BigInt::clz32 ( x )

The abstract operation BigInt::clz32 takes argument x (a BigInt). It performs the following steps when called:

  1. Let int be the mathematical value whose sign is the sign of x and whose magnitude is abs(ℝ(x)).
  2. Let int32bit be int modulo 232.
  3. Return ℤ(int32bit).

1.1.1.2.3 BigInt::sign ( x )

The abstract operation BigInt::sign takes argument x (a BigInt). It performs the following steps when called:

  1. If x is 0ℤ, return x.
  2. If x < 0ℤ, return -1ℤ.
  3. Return 1ℤ.

2 Numbers and Dates

2.1 The Math Object

2.1.1 Function Properties of the Math Object

Editor's Note

This section augments the original Function Properties of the Math Object clause.

2.1.1.1 Math.abs ( x )

Returns the absolute value of x; the result has the same magnitude as x but has positive sign.

When the Math.abs method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN, return NaN.
  3. If n is -0𝔽, return +0𝔽.
  4. If n is -∞𝔽, return +∞𝔽.
  5. If n < +0𝔽, return -n.
  6. Return n.
  1. Let n be ? ToNumeric(x).
  2. Let T be Type(n).
  3. Return ! T::abs(n).

2.1.1.2 Math.clz32 ( x )

When the Math.clz32 method is called with argument x, the following steps are taken:

  1. Let n be ? ToUint32(x).
  2. Let p be the number of leading zero bits in the unsigned 32-bit binary representation of n.
  3. Return 𝔽(p).
 Note

If n is +0𝔽 or n is -0𝔽, this method returns 32𝔽. If the most significant bit of the 32-bit binary encoding of n is 1, this method returns +0𝔽.
  1. Let n be ? ToNumeric(value).
  2. Let T be Type(n).
  3. Return ! T::clz32(n).

2.1.1.3 Math.max ( ...args )

Given zero or more arguments, calls ToNumberToNumeric on each of the arguments and returns the largest of the resulting values. When multiple arguments share the same mathematical value, then the latest argument is returned.

When the Math.max method is called with zero or more arguments which form the rest parameter ...args, the following steps are taken:

  1. Let coerced be a new empty List.
  2. For each element arg of args, do
    1. Let n be ? ToNumberToNumeric(arg).
    2. Append n to coerced.
  3. Let highest be -∞𝔽.
  4. For each element number of coerced, do
    1. If number is NaN, return NaN.
    2. If number is +0𝔽 and highest is -0𝔽, set highest to +0𝔽.
    3. If number > highestℝ(number) ≥ ℝ(highest), set highest to number.
  5. Return highest.
 Note

The comparison of values to determine the largest value is done using the IsLessThan algorithm except that +0𝔽 is considered to be larger than -0𝔽.

The "length" property of the max method is 2𝔽.

2.1.1.4 Math.min ( ...args )

Given zero or more arguments, calls ToNumberToNumeric on each of the arguments and returns the smallest of the resulting values. When multiple arguments share the same mathematical value, then the earliest argument is returned.

When the Math.min method is called with zero or more arguments which form the rest parameter ...args, the following steps are taken:

  1. Let coerced be a new empty List.
  2. For each element arg of args, do
    1. Let n be ? ToNumberToNumeric(arg).
    2. Append n to coerced.
  3. Let lowest be +∞𝔽.
  4. For each element number of coerced, do
    1. If number is NaN, return NaN.
    2. If number is -0𝔽 and lowest is +0𝔽, set lowest to -0𝔽.
    3. If number < lowestℝ(number) < ℝ(lowest), set lowest to number.
  5. Return lowest.
 Note

The comparison of values to determine the largest value is done using the IsLessThan algorithm except that +0𝔽 is considered to be larger than -0𝔽.

The "length" property of the min method is 2𝔽.

2.1.1.5 Math.pow ( base, exponent )

When the Math.pow method is called with arguments base and exponent, the following steps are taken:

  1. Set base to ? ToNumber(base).
  2. Set exponent to ? ToNumber(exponent).
  3. Return ! Number::exponentiate(base, exponent).
  1. Set base to ? ToNumeric(base).
  2. Set exponent to ? ToNumeric(exponent).
  3. If Type(base) is different from Type(exponent), throw a **TypeError** exception.
  4. Let T be Type(base).
  5. Return ! T::exponentiate(base, exponent).

2.1.1.6 Math.sign ( x )

Returns the sign of x, indicating whether x is positive, negative, or zero.

When the Math.sign method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN, n is +0𝔽, or n is -0𝔽, return n.
  3. If n < +0𝔽, return -1𝔽.
  4. Return 1𝔽.
  1. Let n be ? ToNumeric(x).
  2. Let T be Type(n).
  3. Return ! T::sign(n).

A Copyright & Software License

Copyright Notice

© 2021 J. S. Choi, Ecma International

Software License

All Software contained in this document ("Software") is protected by copyright and is being made available under the "BSD License", included below. This Software may be subject to third party rights (rights from parties other than Ecma International), including patent rights, and no licenses under such third party rights are granted under this license even if the third party concerned is a member of Ecma International. SEE THE ECMA CODE OF CONDUCT IN PATENT MATTERS AVAILABLE AT https://ecma-international.org/memento/codeofconduct.htm FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the name of the authors nor Ecma International may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE ECMA INTERNATIONAL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ECMA INTERNATIONAL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.