Stage 1 Draft / July 11, 2022

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::abs(x) Math.abs(x) Math.abs ( x ) T
T::exponentiate(x) Math.sign(x) Math.sign ( x ) T
T::sign(x) Math.sign(x) Math.sign ( x ) T
T::sqrt(x) Math.sqrt(x) Math.sqrt ( x ) T

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::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.1.3 Number::sqrt ( x )

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

  1. If x is NaN, x is +0𝔽, x is -0𝔽, or x is +∞𝔽, return x.
  2. If x < +0𝔽, return NaN.
  3. Return an implementation-approximated value that represents the result of the square root of ℝ(x).

1.1.1.1.4 The BigInt Type

1.1.1.1.4.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.1.4.2 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ℤ.

1.1.1.1.4.3 BigInt::sqrt ( x )

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

  1. If x < 0ℤ, throw a RangeError exception.
  2. Let root be the result of the square root of ℝ(x).
  3. Return the BigInt value that represents root rounded towards 0 to the next integer value.

1.2 Numbers and Dates

1.2.1 The Math Object

1.2.1.1 Function Properties of the Math Object

Editor's Note

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

1.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).

1.2.1.1.2 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𝔽.

1.2.1.1.3 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𝔽.

1.2.1.1.4 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).

1.2.1.1.5 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).

1.2.1.1.6 Math.sqrt ( x )

Returns the square root of x.

When the Math.sqrt 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𝔽, n is -0𝔽, or n is +∞𝔽, return n.
  3. If n < +0𝔽, return NaN.
  4. Return an implementation-approximated value representing the result of the square root of ℝ(n).
  1. Let n be ? ToNumeric(x).
  2. Let T be Type(n).
  3. Return ! T::sqrt(n).