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 )

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

  1. If value is present, then
    1. Let prim be ? ToNumeric(value).
    2. If Type(prim) is 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 )

When Number.isFinite is called with one argument number, the following steps are taken:

  1. If Type(number) is not Number, return false.
  2. If number is NaN, +∞𝔽, or -∞𝔽, return false.
  3. Otherwise, return true.

21.1.2.3 Number.isInteger ( number )

When Number.isInteger is called with one argument number, the following steps are taken:

  1. Return ! IsIntegralNumber(number).

21.1.2.4 Number.isNaN ( number )

When Number.isNaN is called with one argument number, the following steps are taken:

  1. If Type(number) is not 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 )

When Number.isSafeInteger is called with one argument number, the following steps are taken:

  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

The value of Number.MAX_SAFE_INTEGER is the largest integral Number n such that (n) and (n) + 1 are both exactly representable as a Number value.

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

The value of Number.MIN_SAFE_INTEGER is the smallest integral Number n such that (n) and (n) - 1 are both exactly representable as a Number value.

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 value of the Number.parseFloat data property is the same built-in function object that is the initial value of the "parseFloat" property of the global object defined in 19.2.4.

21.1.2.13 Number.parseInt ( string, radix )

The value of the Number.parseInt data property is the same built-in function object that is the initial value of the "parseInt" property of the global object defined in 19.2.5.

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 abstract operation thisNumberValue takes argument value. It performs the following steps when called:

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

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 )

Return 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, include 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). Specifically, perform the following steps:

  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).
  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 10fn < 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 f be integers such that f ≥ 0, 10fn < 10f + 1, 𝔽(n × 10e - f) is 𝔽(x), and f is as small as possible. Note that the decimal representation of n has f + 1 digits, n is not divisible by 10, and the least significant digit of n is not necessarily uniquely determined by these criteria.
    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, 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, 10fn < 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

toFixed 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.

The following steps are performed:

  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).
  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 the String "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 kf, 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 the Number.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 Number 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.1.3.5 Number.prototype.toPrecision ( precision )

Return 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, call ToString instead. Specifically, perform the following steps:

  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).
  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 - 1n < 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 ep, 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 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 ? thisNumberValue(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.1.20.

The toString function 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 the toString method is 1𝔽.

21.1.3.7 Number.prototype.valueOf ( )

  1. Return ? thisNumberValue(this value).

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.