ECMAScript® 2024 Language Specification

Draft ECMA-262 / February 15, 2024

21.1 Number Objects

21.1.1 The Number Constructor

The Number constructor:

  • is %Number%.
  • is the initial value of the "Number" property of the global object.
  • creates and initializes a new Number object when called as a constructor.
  • performs a type conversion when called as a function rather than as a constructor.
  • may be used as the value of an extends clause of a class definition. Subclass constructors that intend to inherit the specified Number behaviour must include a super call to the Number constructor to create and initialize the subclass instance with a [[NumberData]] internal slot.

21.1.1.1 Number ( value )

This function performs the following steps when called:

  1. If value is present, then
    1. Let prim be ? ToNumeric(value).
    2. If prim is a BigInt, let n be 𝔽(ℝ(prim)).
    3. Otherwise, let n be prim.
  2. Else,
    1. Let n be +0𝔽.
  3. If NewTarget is undefined, return n.
  4. Let O be ? OrdinaryCreateFromConstructor(NewTarget, "%Number.prototype%", « [[NumberData]] »).
  5. Set O.[[NumberData]] to n.
  6. Return O.

21.1.2 Properties of the Number Constructor

The Number constructor:

  • has a [[Prototype]] internal slot whose value is %Function.prototype%.
  • has the following properties:

21.1.2.1 Number.EPSILON

The value of Number.EPSILON is the Number value for the magnitude of the difference between 1 and the smallest value greater than 1 that is representable as a Number value, which is approximately 2.2204460492503130808472633361816 × 10-16.

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

21.1.2.2 Number.isFinite ( number )

This function performs the following steps when called:

  1. If number is not a Number, return false.
  2. If number is not finite, return false.
  3. Otherwise, return true.

21.1.2.3 Number.isInteger ( number )

This function performs the following steps when called:

  1. Return IsIntegralNumber(number).

21.1.2.4 Number.isNaN ( number )

This function performs the following steps when called:

  1. If number is not a Number, return false.
  2. If number is NaN, return true.
  3. Otherwise, return false.
 Note

This function differs from the global isNaN function (19.2.3) in that it does not convert its argument to a Number before determining whether it is NaN.

21.1.2.5 Number.isSafeInteger ( number )

Note

An integer n is a "safe integer" if and only if the Number value for n is not the Number value for any other integer.

This function performs the following steps when called:

  1. If IsIntegralNumber(number) is true, then
    1. If abs(ℝ(number)) ≤ 253 - 1, return true.
  2. Return false.

21.1.2.6 Number.MAX_SAFE_INTEGER

Note

Due to rounding behaviour necessitated by precision limitations of IEEE 754-2019, the Number value for every integer greater than Number.MAX_SAFE_INTEGER is shared with at least one other integer. Such large-magnitude integers are therefore not safe, and are not guaranteed to be exactly representable as Number values or even to be distinguishable from each other. For example, both 9007199254740992 and 9007199254740993 evaluate to the Number value 9007199254740992𝔽.

The value of Number.MAX_SAFE_INTEGER is 9007199254740991𝔽 (𝔽(253 - 1)).

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

21.1.2.7 Number.MAX_VALUE

The value of Number.MAX_VALUE is the largest positive finite value of the Number type, which is approximately 1.7976931348623157 × 10308.

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

21.1.2.8 Number.MIN_SAFE_INTEGER

Note

Due to rounding behaviour necessitated by precision limitations of IEEE 754-2019, the Number value for every integer less than Number.MIN_SAFE_INTEGER is shared with at least one other integer. Such large-magnitude integers are therefore not safe, and are not guaranteed to be exactly representable as Number values or even to be distinguishable from each other. For example, both -9007199254740992 and -9007199254740993 evaluate to the Number value -9007199254740992𝔽.

The value of Number.MIN_SAFE_INTEGER is -9007199254740991𝔽 (𝔽(-(253 - 1))).

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

21.1.2.9 Number.MIN_VALUE

The value of Number.MIN_VALUE is the smallest positive value of the Number type, which is approximately 5 × 10-324.

In the IEEE 754-2019 double precision binary representation, the smallest possible value is a denormalized number. If an implementation does not support denormalized values, the value of Number.MIN_VALUE must be the smallest non-zero positive value that can actually be represented by the implementation.

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

21.1.2.10 Number.NaN

The value of Number.NaN is NaN.

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

21.1.2.11 Number.NEGATIVE_INFINITY

The value of Number.NEGATIVE_INFINITY is -∞𝔽.

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

21.1.2.12 Number.parseFloat ( string )

The initial value of the "parseFloat" property is %parseFloat%.

21.1.2.13 Number.parseInt ( string, radix )

The initial value of the "parseInt" property is %parseInt%.

21.1.2.14 Number.POSITIVE_INFINITY

The value of Number.POSITIVE_INFINITY is +∞𝔽.

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

21.1.2.15 Number.prototype

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

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

21.1.3 Properties of the Number Prototype Object

The Number prototype object:

  • is %Number.prototype%.
  • is an ordinary object.
  • is itself a Number object; it has a [[NumberData]] internal slot with the value +0𝔽.
  • has a [[Prototype]] internal slot whose value is %Object.prototype%.

Unless explicitly stated otherwise, the methods of the Number prototype object defined below are not generic and the this value passed to them must be either a Number value or an object that has a [[NumberData]] internal slot that has been initialized to a Number value.

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

21.1.3.1 Number.prototype.constructor

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

21.1.3.2 Number.prototype.toExponential ( fractionDigits )

This method returns a String containing this Number value represented in decimal exponential notation with one digit before the significand's decimal point and fractionDigits digits after the significand's decimal point. If fractionDigits is undefined, it includes as many significand digits as necessary to uniquely specify the Number (just like in ToString except that in this case the Number is always output in exponential notation).

It performs the following steps when called:

  1. Let x be ? ThisNumberValue(this value).
  2. Let f be ? ToIntegerOrInfinity(fractionDigits).
  3. Assert: If fractionDigits is undefined, then f is 0.
  4. If x is not finite, return Number::toString(x, 10).
  5. If f < 0 or f > 100, throw a RangeError exception.
  6. Set x to ℝ(x).
  7. Let s be the empty String.
  8. If x < 0, then
    1. Set s to "-".
    2. Set x to -x.
  9. If x = 0, then
    1. Let m be the String value consisting of f + 1 occurrences of the code unit 0x0030 (DIGIT ZERO).
    2. Let e be 0.
  10. Else,
    1. If fractionDigits is not undefined, then
      1. Let e and n be integers such that 10f ≤ n < 10f + 1 and for which n × 10e - f - x is as close to zero as possible. If there are two such sets of e and n, pick the e and n for which n × 10e - f is larger.
    2. Else,
      1. Let e, n, and ff be integers such that ff ≥ 0, 10ff ≤ n < 10ff + 1, 𝔽(n × 10e - ff) is 𝔽(x), and ff is as small as possible. Note that the decimal representation of n has ff + 1 digits, n is not divisible by 10, and the least significant digit of n is not necessarily uniquely determined by these criteria.
      2. Set f to ff.
    3. Let m be the String value consisting of the digits of the decimal representation of n (in order, with no leading zeroes).
  11. If f ≠ 0, then
    1. Let a be the first code unit of m.
    2. Let b be the other f code units of m.
    3. Set m to the string-concatenation of a, ".", and b.
  12. If e = 0, then
    1. Let c be "+".
    2. Let d be "0".
  13. Else,
    1. If e > 0, then
      1. Let c be "+".
    2. Else,
      1. Assert: e < 0.
      2. Let c be "-".
      3. Set e to -e.
    3. Let d be the String value consisting of the digits of the decimal representation of e (in order, with no leading zeroes).
  14. Set m to the string-concatenation of m, "e", c, and d.
  15. Return the string-concatenation of s and m.
 Note

For implementations that provide more accurate conversions than required by the rules above, it is recommended that the following alternative version of step 10.b.i be used as a guideline:

  1. Let e, n, and f be integers such that f ≥ 0, 10f ≤ n < 10f + 1, 𝔽(n × 10e - f) is 𝔽(x), and f is as small as possible. If there are multiple possibilities for n, choose the value of n for which 𝔽(n × 10e - f) is closest in value to 𝔽(x). If there are two such possible values of n, choose the one that is even.

21.1.3.3 Number.prototype.toFixed ( fractionDigits )

Note 1

This method returns a String containing this Number value represented in decimal fixed-point notation with fractionDigits digits after the decimal point. If fractionDigits is undefined, 0 is assumed.

It performs the following steps when called:

  1. Let x be ? ThisNumberValue(this value).
  2. Let f be ? ToIntegerOrInfinity(fractionDigits).
  3. Assert: If fractionDigits is undefined, then f is 0.
  4. If f is not finite, throw a RangeError exception.
  5. If f < 0 or f > 100, throw a RangeError exception.
  6. If x is not finite, return Number::toString(x, 10).
  7. Set x to ℝ(x).
  8. Let s be the empty String.
  9. If x < 0, then
    1. Set s to "-".
    2. Set x to -x.
  10. If x ≥ 1021, then
    1. Let m be ! ToString(𝔽(x)).
  11. Else,
    1. Let n be an integer for which n / 10f - x is as close to zero as possible. If there are two such n, pick the larger n.
    2. If n = 0, let m be "0". Otherwise, let m be the String value consisting of the digits of the decimal representation of n (in order, with no leading zeroes).
    3. If f ≠ 0, then
      1. Let k be the length of m.
      2. If k ≤ f, then
        1. Let z be the String value consisting of f + 1 - k occurrences of the code unit 0x0030 (DIGIT ZERO).
        2. Set m to the string-concatenation of z and m.
        3. Set k to f + 1.
      3. Let a be the first k - f code units of m.
      4. Let b be the other f code units of m.
      5. Set m to the string-concatenation of a, ".", and b.
  12. Return the string-concatenation of s and m.
 Note 2

The output of toFixed may be more precise than toString for some values because toString only prints enough significant digits to distinguish the number from adjacent Number values. For example,

(1000000000000000128).toString() returns "1000000000000000100", while
(1000000000000000128).toFixed(0) returns "1000000000000000128".

21.1.3.4 Number.prototype.toLocaleString ( [ reserved1 [ , reserved2 ] ] )

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

This method produces a String value that represents this Number value formatted according to the conventions of the host environment's current locale. This method 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.1.3.5 Number.prototype.toPrecision ( precision )

This method returns a String containing this Number value represented either in decimal exponential notation with one digit before the significand's decimal point and precision - 1 digits after the significand's decimal point or in decimal fixed notation with precision significant digits. If precision is undefined, it calls ToString instead.

It performs the following steps when called:

  1. Let x be ? ThisNumberValue(this value).
  2. If precision is undefined, return ! ToString(x).
  3. Let p be ? ToIntegerOrInfinity(precision).
  4. If x is not finite, return Number::toString(x, 10).
  5. If p < 1 or p > 100, throw a RangeError exception.
  6. Set x to ℝ(x).
  7. Let s be the empty String.
  8. If x < 0, then
    1. Set s to the code unit 0x002D (HYPHEN-MINUS).
    2. Set x to -x.
  9. If x = 0, then
    1. Let m be the String value consisting of p occurrences of the code unit 0x0030 (DIGIT ZERO).
    2. Let e be 0.
  10. Else,
    1. Let e and n be integers such that 10p - 1 ≤ n < 10p and for which n × 10e - p + 1 - x is as close to zero as possible. If there are two such sets of e and n, pick the e and n for which n × 10e - p + 1 is larger.
    2. Let m be the String value consisting of the digits of the decimal representation of n (in order, with no leading zeroes).
    3. If e < -6 or e ≥ p, then
      1. Assert: e ≠ 0.
      2. If p ≠ 1, then
        1. Let a be the first code unit of m.
        2. Let b be the other p - 1 code units of m.
        3. Set m to the string-concatenation of a, ".", and b.
      3. If e > 0, then
        1. Let c be the code unit 0x002B (PLUS SIGN).
      4. Else,
        1. Assert: e < 0.
        2. Let c be the code unit 0x002D (HYPHEN-MINUS).
        3. Set e to -e.
      5. Let d be the String value consisting of the digits of the decimal representation of e (in order, with no leading zeroes).
      6. Return the string-concatenation of s, m, the code unit 0x0065 (LATIN SMALL LETTER E), c, and d.
  11. If e = p - 1, return the string-concatenation of s and m.
  12. If e ≥ 0, then
    1. Set m to the string-concatenation of the first e + 1 code units of m, the code unit 0x002E (FULL STOP), and the remaining p - (e + 1) code units of m.
  13. Else,
    1. Set m to the string-concatenation of the code unit 0x0030 (DIGIT ZERO), the code unit 0x002E (FULL STOP), -(e + 1) occurrences of the code unit 0x0030 (DIGIT ZERO), and the String m.
  14. Return the string-concatenation of s and m.

21.1.3.6 Number.prototype.toString ( [ radix ] )

Note

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

This method performs the following steps when called:

  1. Let x be ? ThisNumberValue(this value).
  2. If radix is undefined, let radixMV be 10.
  3. Else, let radixMV be ? ToIntegerOrInfinity(radix).
  4. If radixMV is not in the inclusive interval from 2 to 36, throw a RangeError exception.
  5. Return Number::toString(x, radixMV).

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

The "length" property of this method is 1𝔽.

21.1.3.7 Number.prototype.valueOf ( )

  1. Return ? ThisNumberValue(this value).

21.1.3.7.1 ThisNumberValue ( value )

The abstract operation ThisNumberValue takes argument value (an ECMAScript language value) and returns either a normal completion containing a Number or a throw completion. It performs the following steps when called:

  1. If value is a Number, return value.
  2. If value is an Object and value has a [[NumberData]] internal slot, then
    1. Let n be value.[[NumberData]].
    2. Assert: n is a Number.
    3. Return n.
  3. Throw a TypeError exception.

21.1.4 Properties of Number Instances

Number instances are ordinary objects that inherit properties from the Number prototype object. Number instances also have a [[NumberData]] internal slot. The [[NumberData]] internal slot is the Number value represented by this Number object.