21.2 BigInt Objects

21.2.1 The BigInt Constructor

The BigInt constructor:

  • is %BigInt%.
  • is the initial value of the "BigInt" property of the global object.
  • performs a type conversion when called as a function rather than as a constructor.
  • is not intended to be used with the new operator or to be subclassed. It may be used as the value of an extends clause of a class definition but a super call to the BigInt constructor will cause an exception.

21.2.1.1 BigInt ( value )

When BigInt is called with argument value, the following steps are taken:

  1. If NewTarget is not undefined, throw a TypeError exception.
  2. Let prim be ? ToPrimitive(value, number).
  3. If Type(prim) is Number, return ? NumberToBigInt(prim).
  4. Otherwise, return ? ToBigInt(value).

21.2.1.1.1 NumberToBigInt ( number )

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

  1. If IsIntegralNumber(number) is false, throw a RangeError exception.
  2. Return the BigInt value that represents (number).

21.2.2 Properties of the BigInt Constructor

The value of the [[Prototype]] internal slot of the BigInt constructor is %Function.prototype%.

The BigInt constructor has the following properties:

21.2.2.1 BigInt.asIntN ( bits, bigint )

When the BigInt.asIntN function is called with two arguments bits and bigint, the following steps are taken:

  1. Set bits to ? ToIndex(bits).
  2. Set bigint to ? ToBigInt(bigint).
  3. Let mod be (bigint) modulo 2bits.
  4. If mod ≥ 2bits - 1, return (mod - 2bits); otherwise, return (mod).

21.2.2.2 BigInt.asUintN ( bits, bigint )

When the BigInt.asUintN function is called with two arguments bits and bigint, the following steps are taken:

  1. Set bits to ? ToIndex(bits).
  2. Set bigint to ? ToBigInt(bigint).
  3. Return the BigInt value that represents (bigint) modulo 2bits.

21.2.2.3 BigInt.prototype

The initial value of BigInt.prototype is the BigInt prototype object.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

21.2.3 Properties of the BigInt Prototype Object

The BigInt prototype object:

  • is %BigInt.prototype%.
  • is an ordinary object.
  • is not a BigInt object; it does not have a [[BigIntData]] internal slot.
  • has a [[Prototype]] internal slot whose value is %Object.prototype%.

The abstract operation thisBigIntValue takes argument value. It performs the following steps when called:

  1. If Type(value) is BigInt, return value.
  2. If Type(value) is Object and value has a [[BigIntData]] internal slot, then
    1. Assert: Type(value.[[BigIntData]]) is BigInt.
    2. Return value.[[BigIntData]].
  3. Throw a TypeError exception.

The phrase “this BigInt value” within the specification of a method refers to the result returned by calling the abstract operation thisBigIntValue with the this value of the method invocation passed as the argument.

21.2.3.1 BigInt.prototype.constructor

The initial value of BigInt.prototype.constructor is %BigInt%.

21.2.3.2 BigInt.prototype.toLocaleString ( [ reserved1 [ , reserved2 ] ] )

An ECMAScript implementation that includes the ECMA-402 Internationalization API must implement the BigInt.prototype.toLocaleString method as specified in the ECMA-402 specification. If an ECMAScript implementation does not include the ECMA-402 API the following specification of the toLocaleString method is used.

Produces a String value that represents this BigInt value formatted according to the conventions of the host environment's current locale. This function is implementation-defined, and it is permissible, but not encouraged, for it to return the same thing as toString.

The meanings of the optional parameters to this method are defined in the ECMA-402 specification; implementations that do not include ECMA-402 support must not use those parameter positions for anything else.

21.2.3.3 BigInt.prototype.toString ( [ radix ] )

Note

The optional radix should be an integral Number value in the inclusive range 2𝔽 to 36𝔽. If radix is undefined then 10𝔽 is used as the value of radix.

The following steps are performed:

  1. Let x be ? thisBigIntValue(this value).
  2. If radix is undefined, let radixMV be 10.
  3. Else, let radixMV be ? ToIntegerOrInfinity(radix).
  4. If radixMV < 2 or radixMV > 36, throw a RangeError exception.
  5. If radixMV = 10, return ! ToString(x).
  6. Return the String representation of this Number value using the radix specified by radixMV. Letters a-z are used for digits with values 10 through 35. The precise algorithm is implementation-defined, however the algorithm should be a generalization of that specified in 6.1.6.2.23.

The toString function is not generic; it throws a TypeError exception if its this value is not a BigInt or a BigInt object. Therefore, it cannot be transferred to other kinds of objects for use as a method.

21.2.3.4 BigInt.prototype.valueOf ( )

  1. Return ? thisBigIntValue(this value).

21.2.3.5 BigInt.prototype [ @@toStringTag ]

The initial value of the @@toStringTag property is the String value "BigInt".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.