21 Numbers and Dates

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.

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

21.3 The Math Object

The Math object:

  • is %Math%.
  • is the initial value of the "Math" property of the global object.
  • is an ordinary object.
  • has a [[Prototype]] internal slot whose value is %Object.prototype%.
  • is not a function object.
  • does not have a [[Construct]] internal method; it cannot be used as a constructor with the new operator.
  • does not have a [[Call]] internal method; it cannot be invoked as a function.
Note

In this specification, the phrase “the Number value for x” has a technical meaning defined in 6.1.6.1.

21.3.1 Value Properties of the Math Object

21.3.1.1 Math.E

The Number value for e, the base of the natural logarithms, which is approximately 2.7182818284590452354.

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

21.3.1.2 Math.LN10

The Number value for the natural logarithm of 10, which is approximately 2.302585092994046.

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

21.3.1.3 Math.LN2

The Number value for the natural logarithm of 2, which is approximately 0.6931471805599453.

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

21.3.1.4 Math.LOG10E

The Number value for the base-10 logarithm of e, the base of the natural logarithms; this value is approximately 0.4342944819032518.

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

Note

The value of Math.LOG10E is approximately the reciprocal of the value of Math.LN10.

21.3.1.5 Math.LOG2E

The Number value for the base-2 logarithm of e, the base of the natural logarithms; this value is approximately 1.4426950408889634.

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

Note

The value of Math.LOG2E is approximately the reciprocal of the value of Math.LN2.

21.3.1.6 Math.PI

The Number value for π, the ratio of the circumference of a circle to its diameter, which is approximately 3.1415926535897932.

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

21.3.1.7 Math.SQRT1_2

The Number value for the square root of ½, which is approximately 0.7071067811865476.

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

Note

The value of Math.SQRT1_2 is approximately the reciprocal of the value of Math.SQRT2.

21.3.1.8 Math.SQRT2

The Number value for the square root of 2, which is approximately 1.4142135623730951.

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

21.3.1.9 Math [ @@toStringTag ]

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

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

21.3.2 Function Properties of the Math Object

Note

The behaviour of the functions acos, acosh, asin, asinh, atan, atanh, atan2, cbrt, cos, cosh, exp, expm1, hypot, log, log1p, log2, log10, pow, random, sin, sinh, sqrt, tan, and tanh is not precisely specified here except to require specific results for certain argument values that represent boundary cases of interest. For other argument values, these functions are intended to compute approximations to the results of familiar mathematical functions, but some latitude is allowed in the choice of approximation algorithms. The general intent is that an implementer should be able to use the same mathematical library for ECMAScript on a given hardware platform that is available to C programmers on that platform.

Although the choice of algorithms is left to the implementation, it is recommended (but not specified by this standard) that implementations use the approximation algorithms for IEEE 754-2019 arithmetic contained in fdlibm, the freely distributable mathematical library from Sun Microsystems (http://www.netlib.org/fdlibm).

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

21.3.2.2 Math.acos ( x )

Returns the inverse cosine of x. The result is expressed in radians and ranges from +0𝔽 to 𝔽(π), inclusive.

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

  1. Let n be ? ToNumber(x).
  2. If n is NaN, n > 1𝔽, or n < -1𝔽, return NaN.
  3. If n is 1𝔽, return +0𝔽.
  4. Return an implementation-approximated value representing the result of the inverse cosine of (n).

21.3.2.3 Math.acosh ( x )

Returns the inverse hyperbolic cosine of x.

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

  1. Let n be ? ToNumber(x).
  2. If n is NaN or n is +∞𝔽, return n.
  3. If n is 1𝔽, return +0𝔽.
  4. If n < 1𝔽, return NaN.
  5. Return an implementation-approximated value representing the result of the inverse hyperbolic cosine of (n).

21.3.2.4 Math.asin ( x )

Returns the inverse sine of x. The result is expressed in radians and ranges from 𝔽(-π / 2) to 𝔽(π / 2), inclusive.

When the Math.asin 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 > 1𝔽 or n < -1𝔽, return NaN.
  4. Return an implementation-approximated value representing the result of the inverse sine of (n).

21.3.2.5 Math.asinh ( x )

Returns the inverse hyperbolic sine of x.

When the Math.asinh 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𝔽, n is +∞𝔽, or n is -∞𝔽, return n.
  3. Return an implementation-approximated value representing the result of the inverse hyperbolic sine of (n).

21.3.2.6 Math.atan ( x )

Returns the inverse tangent of x. The result is expressed in radians and ranges from 𝔽(-π / 2) to 𝔽(π / 2), inclusive.

When the Math.atan 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 is +∞𝔽, return an implementation-approximated value representing π / 2.
  4. If n is -∞𝔽, return an implementation-approximated value representing -π / 2.
  5. Return an implementation-approximated value representing the result of the inverse tangent of (n).

21.3.2.7 Math.atanh ( x )

Returns the inverse hyperbolic tangent of x.

When the Math.atanh 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 > 1𝔽 or n < -1𝔽, return NaN.
  4. If n is 1𝔽, return +∞𝔽.
  5. If n is -1𝔽, return -∞𝔽.
  6. Return an implementation-approximated value representing the result of the inverse hyperbolic tangent of (n).

21.3.2.8 Math.atan2 ( y, x )

Returns the inverse tangent of the quotient y / x of the arguments y and x, where the signs of y and x are used to determine the quadrant of the result. Note that it is intentional and traditional for the two-argument inverse tangent function that the argument named y be first and the argument named x be second. The result is expressed in radians and ranges from -π to +π, inclusive.

When the Math.atan2 method is called with arguments y and x, the following steps are taken:

  1. Let ny be ? ToNumber(y).
  2. Let nx be ? ToNumber(x).
  3. If ny is NaN or nx is NaN, return NaN.
  4. If ny is +∞𝔽, then
    1. If nx is +∞𝔽, return an implementation-approximated value representing π / 4.
    2. If nx is -∞𝔽, return an implementation-approximated value representing 3π / 4.
    3. Return an implementation-approximated value representing π / 2.
  5. If ny is -∞𝔽, then
    1. If nx is +∞𝔽, return an implementation-approximated value representing -π / 4.
    2. If nx is -∞𝔽, return an implementation-approximated value representing -3π / 4.
    3. Return an implementation-approximated value representing -π / 2.
  6. If ny is +0𝔽, then
    1. If nx > +0𝔽 or nx is +0𝔽, return +0𝔽.
    2. Return an implementation-approximated value representing π.
  7. If ny is -0𝔽, then
    1. If nx > +0𝔽 or nx is +0𝔽, return -0𝔽.
    2. Return an implementation-approximated value representing -π.
  8. Assert: ny is finite and is neither +0𝔽 nor -0𝔽.
  9. If ny > +0𝔽, then
    1. If nx is +∞𝔽, return +0𝔽.
    2. If nx is -∞𝔽, return an implementation-approximated value representing π.
    3. If nx is +0𝔽 or nx is -0𝔽, return an implementation-approximated value representing π / 2.
  10. If ny < +0𝔽, then
    1. If nx is +∞𝔽, return -0𝔽.
    2. If nx is -∞𝔽, return an implementation-approximated value representing -π.
    3. If nx is +0𝔽 or nx is -0𝔽, return an implementation-approximated value representing -π / 2.
  11. Assert: nx is finite and is neither +0𝔽 nor -0𝔽.
  12. Return an implementation-approximated value representing the result of the inverse tangent of the quotient (ny) / (nx).

21.3.2.9 Math.cbrt ( x )

Returns the cube root of x.

When the Math.cbrt 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𝔽, n is +∞𝔽, or n is -∞𝔽, return n.
  3. Return an implementation-approximated value representing the result of the cube root of (n).

21.3.2.10 Math.ceil ( x )

Returns the smallest (closest to -∞) integral Number value that is not less than x. If x is already an integral Number, the result is x.

When the Math.ceil 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𝔽, n is +∞𝔽, or n is -∞𝔽, return n.
  3. If n < +0𝔽 and n > -1𝔽, return -0𝔽.
  4. If n is an integral Number, return n.
  5. Return the smallest (closest to -∞) integral Number value that is not less than n.
Note

The value of Math.ceil(x) is the same as the value of -Math.floor(-x).

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

21.3.2.12 Math.cos ( x )

Returns the cosine of x. The argument is expressed in radians.

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

  1. Let n be ? ToNumber(x).
  2. If n is NaN, n is +∞𝔽, or n is -∞𝔽, return NaN.
  3. If n is +0𝔽 or n is -0𝔽, return 1𝔽.
  4. Return an implementation-approximated value representing the result of the cosine of (n).

21.3.2.13 Math.cosh ( x )

Returns the hyperbolic cosine of x.

When the Math.cosh 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 +∞𝔽 or n is -∞𝔽, return +∞𝔽.
  4. If n is +0𝔽 or n is -0𝔽, return 1𝔽.
  5. Return an implementation-approximated value representing the result of the hyperbolic cosine of (n).
Note

The value of Math.cosh(x) is the same as the value of (Math.exp(x) + Math.exp(-x)) / 2.

21.3.2.14 Math.exp ( x )

Returns the exponential function of x (e raised to the power of x, where e is the base of the natural logarithms).

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

  1. Let n be ? ToNumber(x).
  2. If n is NaN or n is +∞𝔽, return n.
  3. If n is +0𝔽 or n is -0𝔽, return 1𝔽.
  4. If n is -∞𝔽, return +0𝔽.
  5. Return an implementation-approximated value representing the result of the exponential function of (n).

21.3.2.15 Math.expm1 ( x )

Returns the result of subtracting 1 from the exponential function of x (e raised to the power of x, where e is the base of the natural logarithms). The result is computed in a way that is accurate even when the value of x is close to 0.

When the Math.expm1 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 is -∞𝔽, return -1𝔽.
  4. Return an implementation-approximated value representing the result of subtracting 1 from the exponential function of (n).

21.3.2.16 Math.floor ( x )

Returns the greatest (closest to +∞) integral Number value that is not greater than x. If x is already an integral Number, the result is x.

When the Math.floor 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𝔽, n is +∞𝔽, or n is -∞𝔽, return n.
  3. If n < 1𝔽 and n > +0𝔽, return +0𝔽.
  4. If n is an integral Number, return n.
  5. Return the greatest (closest to +∞) integral Number value that is not greater than n.
Note

The value of Math.floor(x) is the same as the value of -Math.ceil(-x).

21.3.2.17 Math.fround ( x )

When the Math.fround 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 one of +0𝔽, -0𝔽, +∞𝔽, or -∞𝔽, return n.
  4. Let n32 be the result of converting n to a value in IEEE 754-2019 binary32 format using roundTiesToEven mode.
  5. Let n64 be the result of converting n32 to a value in IEEE 754-2019 binary64 format.
  6. Return the ECMAScript Number value corresponding to n64.

21.3.2.18 Math.hypot ( ...args )

Returns the square root of the sum of squares of its arguments.

When the Math.hypot 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 ? ToNumber(arg).
    2. Append n to coerced.
  3. For each element number of coerced, do
    1. If number is +∞𝔽 or number is -∞𝔽, return +∞𝔽.
  4. Let onlyZero be true.
  5. For each element number of coerced, do
    1. If number is NaN, return NaN.
    2. If number is neither +0𝔽 nor -0𝔽, set onlyZero to false.
  6. If onlyZero is true, return +0𝔽.
  7. Return an implementation-approximated value representing the square root of the sum of squares of the mathematical values of the elements of coerced.

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

Note

Implementations should take care to avoid the loss of precision from overflows and underflows that are prone to occur in naive implementations when this function is called with two or more arguments.

21.3.2.19 Math.imul ( x, y )

When Math.imul is called with arguments x and y, the following steps are taken:

  1. Let a be (? ToUint32(x)).
  2. Let b be (? ToUint32(y)).
  3. Let product be (a × b) modulo 232.
  4. If product ≥ 231, return 𝔽(product - 232); otherwise return 𝔽(product).

21.3.2.20 Math.log ( x )

Returns the natural logarithm of x.

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

  1. Let n be ? ToNumber(x).
  2. If n is NaN or n is +∞𝔽, return n.
  3. If n is 1𝔽, return +0𝔽.
  4. If n is +0𝔽 or n is -0𝔽, return -∞𝔽.
  5. If n < +0𝔽, return NaN.
  6. Return an implementation-approximated value representing the result of the natural logarithm of (n).

21.3.2.21 Math.log1p ( x )

Returns the natural logarithm of 1 + x. The result is computed in a way that is accurate even when the value of x is close to zero.

When the Math.log1p 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 is -1𝔽, return -∞𝔽.
  4. If n < -1𝔽, return NaN.
  5. Return an implementation-approximated value representing the result of the natural logarithm of 1 + (n).

21.3.2.22 Math.log10 ( x )

Returns the base 10 logarithm of x.

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

  1. Let n be ? ToNumber(x).
  2. If n is NaN or n is +∞𝔽, return n.
  3. If n is 1𝔽, return +0𝔽.
  4. If n is +0𝔽 or n is -0𝔽, return -∞𝔽.
  5. If n < +0𝔽, return NaN.
  6. Return an implementation-approximated value representing the result of the base 10 logarithm of (n).

21.3.2.23 Math.log2 ( x )

Returns the base 2 logarithm of x.

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

  1. Let n be ? ToNumber(x).
  2. If n is NaN or n is +∞𝔽, return n.
  3. If n is 1𝔽, return +0𝔽.
  4. If n is +0𝔽 or n is -0𝔽, return -∞𝔽.
  5. If n < +0𝔽, return NaN.
  6. Return an implementation-approximated value representing the result of the base 2 logarithm of (n).

21.3.2.24 Math.max ( ...args )

Given zero or more arguments, calls ToNumber on each of the arguments and returns the largest of the resulting values.

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 ? ToNumber(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, 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𝔽.

21.3.2.25 Math.min ( ...args )

Given zero or more arguments, calls ToNumber on each of the arguments and returns the smallest of the resulting values.

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 ? ToNumber(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, 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𝔽.

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

21.3.2.27 Math.random ( )

Returns a Number value with positive sign, greater than or equal to +0𝔽 but strictly less than 1𝔽, chosen randomly or pseudo randomly with approximately uniform distribution over that range, using an implementation-defined algorithm or strategy. This function takes no arguments.

Each Math.random function created for distinct realms must produce a distinct sequence of values from successive calls.

21.3.2.28 Math.round ( x )

Returns the Number value that is closest to x and is integral. If two integral Numbers are equally close to x, then the result is the Number value that is closer to +∞. If x is already integral, the result is x.

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

  1. Let n be ? ToNumber(x).
  2. If n is NaN, +∞𝔽, -∞𝔽, or an integral Number, return n.
  3. If n < 0.5𝔽 and n > +0𝔽, return +0𝔽.
  4. If n < +0𝔽 and n-0.5𝔽, return -0𝔽.
  5. Return the integral Number closest to n, preferring the Number closer to +∞ in the case of a tie.
Note 1

Math.round(3.5) returns 4, but Math.round(-3.5) returns -3.

Note 2

The value of Math.round(x) is not always the same as the value of Math.floor(x + 0.5). When x is -0𝔽 or is less than +0𝔽 but greater than or equal to -0.5𝔽, Math.round(x) returns -0𝔽, but Math.floor(x + 0.5) returns +0𝔽. Math.round(x) may also differ from the value of Math.floor(x + 0.5)because of internal rounding when computing x + 0.5.

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

21.3.2.30 Math.sin ( x )

Returns the sine of x. The argument is expressed in radians.

When the Math.sin 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 is +∞𝔽 or n is -∞𝔽, return NaN.
  4. Return an implementation-approximated value representing the result of the sine of (n).

21.3.2.31 Math.sinh ( x )

Returns the hyperbolic sine of x.

When the Math.sinh 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𝔽, n is +∞𝔽, or n is -∞𝔽, return n.
  3. Return an implementation-approximated value representing the result of the hyperbolic sine of (n).
Note

The value of Math.sinh(x) is the same as the value of (Math.exp(x) - Math.exp(-x)) / 2.

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

21.3.2.33 Math.tan ( x )

Returns the tangent of x. The argument is expressed in radians.

When the Math.tan 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 is +∞𝔽, or n is -∞𝔽, return NaN.
  4. Return an implementation-approximated value representing the result of the tangent of (n).

21.3.2.34 Math.tanh ( x )

Returns the hyperbolic tangent of x.

When the Math.tanh 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 is +∞𝔽, return 1𝔽.
  4. If n is -∞𝔽, return -1𝔽.
  5. Return an implementation-approximated value representing the result of the hyperbolic tangent of (n).
Note

The value of Math.tanh(x) is the same as the value of (Math.exp(x) - Math.exp(-x)) / (Math.exp(x) + Math.exp(-x)).

21.3.2.35 Math.trunc ( x )

Returns the integral part of the number x, removing any fractional digits. If x is already integral, the result is x.

When the Math.trunc 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𝔽, n is +∞𝔽, or n is -∞𝔽, return n.
  3. If n < 1𝔽 and n > +0𝔽, return +0𝔽.
  4. If n < +0𝔽 and n > -1𝔽, return -0𝔽.
  5. Return the integral Number nearest n in the direction of +0𝔽.

21.4 Date Objects

21.4.1 Overview of Date Objects and Definitions of Abstract Operations

The following abstract operations operate on time values (defined in 21.4.1.1). Note that, in every case, if any argument to one of these functions is NaN, the result will be NaN.

21.4.1.1 Time Values and Time Range

Time measurement in ECMAScript is analogous to time measurement in POSIX, in particular sharing definition in terms of the proleptic Gregorian calendar, an epoch of midnight at the beginning of 1 January 1970 UTC, and an accounting of every day as comprising exactly 86,400 seconds (each of which is 1000 milliseconds long).

An ECMAScript time value is a Number, either a finite integral Number representing an instant in time to millisecond precision or NaN representing no specific instant. A time value that is a multiple of 24 × 60 × 60 × 1000 = 86,400,000 (i.e., is equal to 86,400,000 × d for some integer d) represents the instant at the start of the UTC day that follows the epoch by d whole UTC days (preceding the epoch for negative d). Every other finite time value t is defined relative to the greatest preceding time value s that is such a multiple, and represents the instant that occurs within the same UTC day as s but follows it by ts milliseconds.

Time values do not account for UTC leap seconds—there are no time values representing instants within positive leap seconds, and there are time values representing instants removed from the UTC timeline by negative leap seconds. However, the definition of time values nonetheless yields piecewise alignment with UTC, with discontinuities only at leap second boundaries and zero difference outside of leap seconds.

A Number can exactly represent all integers from -9,007,199,254,740,992 to 9,007,199,254,740,992 (21.1.2.8 and 21.1.2.6). A time value supports a slightly smaller range of -8,640,000,000,000,000 to 8,640,000,000,000,000 milliseconds. This yields a supported time value range of exactly -100,000,000 days to 100,000,000 days relative to midnight at the beginning of 1 January 1970 UTC.

The exact moment of midnight at the beginning of 1 January 1970 UTC is represented by the time value +0𝔽.

Note

The 400 year cycle of the proleptic Gregorian calendar contains 97 leap years. This yields an average of 365.2425 days per year, which is 31,556,952,000 milliseconds. Therefore, the maximum range a Number could represent exactly with millisecond precision is approximately -285,426 to 285,426 years relative to 1970. The smaller range supported by a time value as specified in this section is approximately -273,790 to 273,790 years relative to 1970.

21.4.1.2 Day Number and Time within Day

A given time value t belongs to day number

Day(t) = 𝔽(floor((t / msPerDay)))

where the number of milliseconds per day is

msPerDay = 86400000𝔽

The remainder is called the time within the day:

TimeWithinDay(t) = 𝔽((t) modulo (msPerDay))

21.4.1.3 Year Number

ECMAScript uses a proleptic Gregorian calendar to map a day number to a year number and to determine the month and date within that year. In this calendar, leap years are precisely those which are (divisible by 4) and ((not divisible by 100) or (divisible by 400)). The number of days in year number y is therefore defined by

DaysInYear(y)
= 365𝔽 if ((y) modulo 4) ≠ 0
= 366𝔽 if ((y) modulo 4) = 0 and ((y) modulo 100) ≠ 0
= 365𝔽 if ((y) modulo 100) = 0 and ((y) modulo 400) ≠ 0
= 366𝔽 if ((y) modulo 400) = 0

All non-leap years have 365 days with the usual number of days per month and leap years have an extra day in February. The day number of the first day of year y is given by:

DayFromYear(y) = 𝔽(365 × ((y) - 1970) + floor(((y) - 1969) / 4) - floor(((y) - 1901) / 100) + floor(((y) - 1601) / 400))

The time value of the start of a year is:

TimeFromYear(y) = msPerDay × DayFromYear(y)

A time value determines a year by:

YearFromTime(t) = the largest integral Number y (closest to +∞) such that TimeFromYear(y) ≤ t

The leap-year function is 1𝔽 for a time within a leap year and otherwise is +0𝔽:

InLeapYear(t)
= +0𝔽 if DaysInYear(YearFromTime(t)) = 365𝔽
= 1𝔽 if DaysInYear(YearFromTime(t)) = 366𝔽

21.4.1.4 Month Number

Months are identified by an integral Number in the range +0𝔽 to 11𝔽, inclusive. The mapping MonthFromTime(t) from a time value t to a month number is defined by:

MonthFromTime(t)
= +0𝔽 if +0𝔽DayWithinYear(t) < 31𝔽
= 1𝔽 if 31𝔽DayWithinYear(t) < 59𝔽 + InLeapYear(t)
= 2𝔽 if 59𝔽 + InLeapYear(t) ≤ DayWithinYear(t) < 90𝔽 + InLeapYear(t)
= 3𝔽 if 90𝔽 + InLeapYear(t) ≤ DayWithinYear(t) < 120𝔽 + InLeapYear(t)
= 4𝔽 if 120𝔽 + InLeapYear(t) ≤ DayWithinYear(t) < 151𝔽 + InLeapYear(t)
= 5𝔽 if 151𝔽 + InLeapYear(t) ≤ DayWithinYear(t) < 181𝔽 + InLeapYear(t)
= 6𝔽 if 181𝔽 + InLeapYear(t) ≤ DayWithinYear(t) < 212𝔽 + InLeapYear(t)
= 7𝔽 if 212𝔽 + InLeapYear(t) ≤ DayWithinYear(t) < 243𝔽 + InLeapYear(t)
= 8𝔽 if 243𝔽 + InLeapYear(t) ≤ DayWithinYear(t) < 273𝔽 + InLeapYear(t)
= 9𝔽 if 273𝔽 + InLeapYear(t) ≤ DayWithinYear(t) < 304𝔽 + InLeapYear(t)
= 10𝔽 if 304𝔽 + InLeapYear(t) ≤ DayWithinYear(t) < 334𝔽 + InLeapYear(t)
= 11𝔽 if 334𝔽 + InLeapYear(t) ≤ DayWithinYear(t) < 365𝔽 + InLeapYear(t)

where

DayWithinYear(t) = Day(t) - DayFromYear(YearFromTime(t))

A month value of +0𝔽 specifies January; 1𝔽 specifies February; 2𝔽 specifies March; 3𝔽 specifies April; 4𝔽 specifies May; 5𝔽 specifies June; 6𝔽 specifies July; 7𝔽 specifies August; 8𝔽 specifies September; 9𝔽 specifies October; 10𝔽 specifies November; and 11𝔽 specifies December. Note that MonthFromTime(+0𝔽) = +0𝔽, corresponding to Thursday, 1 January 1970.

21.4.1.5 Date Number

A date number is identified by an integral Number in the range 1𝔽 through 31𝔽, inclusive. The mapping DateFromTime(t) from a time value t to a date number is defined by:

DateFromTime(t)
= DayWithinYear(t) + 1𝔽 if MonthFromTime(t) = +0𝔽
= DayWithinYear(t) - 30𝔽 if MonthFromTime(t) = 1𝔽
= DayWithinYear(t) - 58𝔽 - InLeapYear(t) if MonthFromTime(t) = 2𝔽
= DayWithinYear(t) - 89𝔽 - InLeapYear(t) if MonthFromTime(t) = 3𝔽
= DayWithinYear(t) - 119𝔽 - InLeapYear(t) if MonthFromTime(t) = 4𝔽
= DayWithinYear(t) - 150𝔽 - InLeapYear(t) if MonthFromTime(t) = 5𝔽
= DayWithinYear(t) - 180𝔽 - InLeapYear(t) if MonthFromTime(t) = 6𝔽
= DayWithinYear(t) - 211𝔽 - InLeapYear(t) if MonthFromTime(t) = 7𝔽
= DayWithinYear(t) - 242𝔽 - InLeapYear(t) if MonthFromTime(t) = 8𝔽
= DayWithinYear(t) - 272𝔽 - InLeapYear(t) if MonthFromTime(t) = 9𝔽
= DayWithinYear(t) - 303𝔽 - InLeapYear(t) if MonthFromTime(t) = 10𝔽
= DayWithinYear(t) - 333𝔽 - InLeapYear(t) if MonthFromTime(t) = 11𝔽

21.4.1.6 Week Day

The weekday for a particular time value t is defined as

WeekDay(t) = 𝔽((Day(t) + 4𝔽) modulo 7)

A weekday value of +0𝔽 specifies Sunday; 1𝔽 specifies Monday; 2𝔽 specifies Tuesday; 3𝔽 specifies Wednesday; 4𝔽 specifies Thursday; 5𝔽 specifies Friday; and 6𝔽 specifies Saturday. Note that WeekDay(+0𝔽) = 4𝔽, corresponding to Thursday, 1 January 1970.

21.4.1.7 LocalTZA ( t, isUTC )

The implementation-defined abstract operation LocalTZA takes arguments t and isUTC. It returns an integral Number representing the local time zone adjustment, or offset, in milliseconds. The local political rules for standard time and daylight saving time in effect at t should be used to determine the result in the way specified in this section.

When isUTC is true, LocalTZA( tUTC, true ) should return the offset of the local time zone from UTC measured in milliseconds at time represented by time value tUTC. When the result is added to tUTC, it should yield the corresponding Number tlocal.

When isUTC is false, LocalTZA( tlocal, false ) should return the offset of the local time zone from UTC measured in milliseconds at local time represented by Number tlocal. When the result is subtracted from tlocal, it should yield the corresponding time value tUTC.

Input t is nominally a time value but may be any Number value. This can occur when isUTC is false and tlocal represents a time value that is already offset outside of the time value range at the range boundaries. The algorithm must not limit tlocal to the time value range, so that such inputs are supported.

When tlocal represents local time repeating multiple times at a negative time zone transition (e.g. when the daylight saving time ends or the time zone offset is decreased due to a time zone rule change) or skipped local time at a positive time zone transitions (e.g. when the daylight saving time starts or the time zone offset is increased due to a time zone rule change), tlocal must be interpreted using the time zone offset before the transition.

If an implementation does not support a conversion described above or if political rules for time t are not available within the implementation, the result must be +0𝔽.

Note

It is recommended that implementations use the time zone information of the IANA Time Zone Database https://www.iana.org/time-zones/.

1:30 AM on 5 November 2017 in America/New_York is repeated twice (fall backward), but it must be interpreted as 1:30 AM UTC-04 instead of 1:30 AM UTC-05. LocalTZA(TimeClip(MakeDate(MakeDay(2017, 10, 5), MakeTime(1, 30, 0, 0))), false) is -4 × msPerHour.

2:30 AM on 12 March 2017 in America/New_York does not exist, but it must be interpreted as 2:30 AM UTC-05 (equivalent to 3:30 AM UTC-04). LocalTZA(TimeClip(MakeDate(MakeDay(2017, 2, 12), MakeTime(2, 30, 0, 0))), false) is -5 × msPerHour.

Local time zone offset values may be positive or negative.

21.4.1.8 LocalTime ( t )

The abstract operation LocalTime takes argument t. It converts t from UTC to local time. It performs the following steps when called:

  1. Return t + LocalTZA(t, true).
Note

Two different input time values tUTC are converted to the same local time tlocal at a negative time zone transition when there are repeated times (e.g. the daylight saving time ends or the time zone adjustment is decreased.).

LocalTime(UTC(tlocal)) is not necessarily always equal to tlocal. Correspondingly, UTC(LocalTime(tUTC)) is not necessarily always equal to tUTC.

21.4.1.9 UTC ( t )

The abstract operation UTC takes argument t. It converts t from local time to UTC. It performs the following steps when called:

  1. Return t - LocalTZA(t, false).
Note

UTC(LocalTime(tUTC)) is not necessarily always equal to tUTC. Correspondingly, LocalTime(UTC(tlocal)) is not necessarily always equal to tlocal.

21.4.1.10 Hours, Minutes, Second, and Milliseconds

The following abstract operations are useful in decomposing time values:

HourFromTime(t) = 𝔽(floor((t / msPerHour)) modulo HoursPerDay)
MinFromTime(t) = 𝔽(floor((t / msPerMinute)) modulo MinutesPerHour)
msFromTime(t) = 𝔽((t) modulo msPerSecond)

where

HoursPerDay = 24
MinutesPerHour = 60
SecondsPerMinute = 60
msPerSecond = 1000𝔽
msPerMinute = 60000𝔽 = msPerSecond × 𝔽(SecondsPerMinute)
msPerHour = 3600000𝔽 = msPerMinute × 𝔽(MinutesPerHour)

21.4.1.11 MakeTime ( hour, min, sec, ms )

The abstract operation MakeTime takes arguments hour (a Number), min (a Number), sec (a Number), and ms (a Number). It calculates a number of milliseconds. It performs the following steps when called:

  1. If hour is not finite or min is not finite or sec is not finite or ms is not finite, return NaN.
  2. Let h be 𝔽(! ToIntegerOrInfinity(hour)).
  3. Let m be 𝔽(! ToIntegerOrInfinity(min)).
  4. Let s be 𝔽(! ToIntegerOrInfinity(sec)).
  5. Let milli be 𝔽(! ToIntegerOrInfinity(ms)).
  6. Let t be ((h * msPerHour + m * msPerMinute) + s * msPerSecond) + milli, performing the arithmetic according to IEEE 754-2019 rules (that is, as if using the ECMAScript operators * and +).
  7. Return t.

21.4.1.12 MakeDay ( year, month, date )

The abstract operation MakeDay takes arguments year (a Number), month (a Number), and date (a Number). It calculates a number of days. It performs the following steps when called:

  1. If year is not finite or month is not finite or date is not finite, return NaN.
  2. Let y be 𝔽(! ToIntegerOrInfinity(year)).
  3. Let m be 𝔽(! ToIntegerOrInfinity(month)).
  4. Let dt be 𝔽(! ToIntegerOrInfinity(date)).
  5. Let ym be y + 𝔽(floor((m) / 12)).
  6. If ym is not finite, return NaN.
  7. Let mn be 𝔽((m) modulo 12).
  8. Find a finite time value t such that YearFromTime(t) is ym and MonthFromTime(t) is mn and DateFromTime(t) is 1𝔽; but if this is not possible (because some argument is out of range), return NaN.
  9. Return Day(t) + dt - 1𝔽.

21.4.1.13 MakeDate ( day, time )

The abstract operation MakeDate takes arguments day (a Number) and time (a Number). It calculates a number of milliseconds. It performs the following steps when called:

  1. If day is not finite or time is not finite, return NaN.
  2. Let tv be day × msPerDay + time.
  3. If tv is not finite, return NaN.
  4. Return tv.

21.4.1.14 TimeClip ( time )

The abstract operation TimeClip takes argument time (a Number). It calculates a number of milliseconds. It performs the following steps when called:

  1. If time is not finite, return NaN.
  2. If abs((time)) > 8.64 × 1015, return NaN.
  3. Return 𝔽(! ToIntegerOrInfinity(time)).

21.4.1.15 Date Time String Format

ECMAScript defines a string interchange format for date-times based upon a simplification of the ISO 8601 calendar date extended format. The format is as follows: YYYY-MM-DDTHH:mm:ss.sssZ

Where the elements are as follows:

YYYY is the year in the proleptic Gregorian calendar as four decimal digits from 0000 to 9999, or as an expanded year of "+" or "-" followed by six decimal digits.
- "-" (hyphen) appears literally twice in the string.
MM is the month of the year as two decimal digits from 01 (January) to 12 (December).
DD is the day of the month as two decimal digits from 01 to 31.
T "T" appears literally in the string, to indicate the beginning of the time element.
HH is the number of complete hours that have passed since midnight as two decimal digits from 00 to 24.
: ":" (colon) appears literally twice in the string.
mm is the number of complete minutes since the start of the hour as two decimal digits from 00 to 59.
ss is the number of complete seconds since the start of the minute as two decimal digits from 00 to 59.
. "." (dot) appears literally in the string.
sss is the number of complete milliseconds since the start of the second as three decimal digits.
Z is the UTC offset representation specified as "Z" (for UTC with no offset) or an offset of either "+" or "-" followed by a time expression HH:mm (indicating local time ahead of or behind UTC, respectively)

This format includes date-only forms:

YYYY
YYYY-MM
YYYY-MM-DD
        

It also includes “date-time” forms that consist of one of the above date-only forms immediately followed by one of the following time forms with an optional UTC offset representation appended:

THH:mm
THH:mm:ss
THH:mm:ss.sss
        

A string containing out-of-bounds or nonconforming elements is not a valid instance of this format.

Note 1

As every day both starts and ends with midnight, the two notations 00:00 and 24:00 are available to distinguish the two midnights that can be associated with one date. This means that the following two notations refer to exactly the same point in time: 1995-02-04T24:00 and 1995-02-05T00:00. This interpretation of the latter form as "end of a calendar day" is consistent with ISO 8601, even though that specification reserves it for describing time intervals and does not permit it within representations of single points in time.

Note 2

There exists no international standard that specifies abbreviations for civil time zones like CET, EST, etc. and sometimes the same abbreviation is even used for two very different time zones. For this reason, both ISO 8601 and this format specify numeric representations of time zone offsets.

21.4.1.15.1 Expanded Years

Covering the full time value range of approximately 273,790 years forward or backward from 1 January 1970 (21.4.1.1) requires representing years before 0 or after 9999. ISO 8601 permits expansion of the year representation, but only by mutual agreement of the partners in information interchange. In the simplified ECMAScript format, such an expanded year representation shall have 6 digits and is always prefixed with a + or - sign. The year 0 is considered positive and hence prefixed with a + sign. Strings matching the Date Time String Format with expanded years representing instants in time outside the range of a time value are treated as unrecognizable by Date.parse and cause that function to return NaN without falling back to implementation-specific behaviour or heuristics.

Note

Examples of date-time values with expanded years:

-271821-04-20T00:00:00Z 271822 B.C.
-000001-01-01T00:00:00Z 2 B.C.
+000000-01-01T00:00:00Z 1 B.C.
+000001-01-01T00:00:00Z 1 A.D.
+001970-01-01T00:00:00Z 1970 A.D.
+002009-12-15T00:00:00Z 2009 A.D.
+275760-09-13T00:00:00Z 275760 A.D.

21.4.2 The Date Constructor

The Date constructor:

  • is %Date%.
  • is the initial value of the "Date" property of the global object.
  • creates and initializes a new Date when called as a constructor.
  • returns a String representing the current time (UTC) when called as a function rather than as a constructor.
  • is a function whose behaviour differs based upon the number and types of its arguments.
  • may be used as the value of an extends clause of a class definition. Subclass constructors that intend to inherit the specified Date behaviour must include a super call to the Date constructor to create and initialize the subclass instance with a [[DateValue]] internal slot.
  • has a "length" property whose value is 7𝔽.

21.4.2.1 Date ( ...values )

When the Date function is called, the following steps are taken:

  1. If NewTarget is undefined, then
    1. Let now be the time value (UTC) identifying the current time.
    2. Return ToDateString(now).
  2. Let numberOfArgs be the number of elements in values.
  3. If numberOfArgs = 0, then
    1. Let dv be the time value (UTC) identifying the current time.
  4. Else if numberOfArgs = 1, then
    1. Let value be values[0].
    2. If Type(value) is Object and value has a [[DateValue]] internal slot, then
      1. Let tv be ! thisTimeValue(value).
    3. Else,
      1. Let v be ? ToPrimitive(value).
      2. If Type(v) is String, then
        1. Assert: The next step never returns an abrupt completion because Type(v) is String.
        2. Let tv be the result of parsing v as a date, in exactly the same manner as for the parse method (21.4.3.2).
      3. Else,
        1. Let tv be ? ToNumber(v).
    4. Let dv be TimeClip(tv).
  5. Else,
    1. Assert: numberOfArgs ≥ 2.
    2. Let y be ? ToNumber(values[0]).
    3. Let m be ? ToNumber(values[1]).
    4. If numberOfArgs > 2, let dt be ? ToNumber(values[2]); else let dt be 1𝔽.
    5. If numberOfArgs > 3, let h be ? ToNumber(values[3]); else let h be +0𝔽.
    6. If numberOfArgs > 4, let min be ? ToNumber(values[4]); else let min be +0𝔽.
    7. If numberOfArgs > 5, let s be ? ToNumber(values[5]); else let s be +0𝔽.
    8. If numberOfArgs > 6, let milli be ? ToNumber(values[6]); else let milli be +0𝔽.
    9. If y is NaN, let yr be NaN.
    10. Else,
      1. Let yi be ! ToIntegerOrInfinity(y).
      2. If 0 ≤ yi ≤ 99, let yr be 1900𝔽 + 𝔽(yi); otherwise, let yr be y.
    11. Let finalDate be MakeDate(MakeDay(yr, m, dt), MakeTime(h, min, s, milli)).
    12. Let dv be TimeClip(UTC(finalDate)).
  6. Let O be ? OrdinaryCreateFromConstructor(NewTarget, "%Date.prototype%", « [[DateValue]] »).
  7. Set O.[[DateValue]] to dv.
  8. Return O.

21.4.3 Properties of the Date Constructor

The Date constructor:

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

21.4.3.1 Date.now ( )

The now function returns the time value designating the UTC date and time of the occurrence of the call to now.

21.4.3.2 Date.parse ( string )

The parse function applies the ToString operator to its argument. If ToString results in an abrupt completion the Completion Record is immediately returned. Otherwise, parse interprets the resulting String as a date and time; it returns a Number, the UTC time value corresponding to the date and time. The String may be interpreted as a local time, a UTC time, or a time in some other time zone, depending on the contents of the String. The function first attempts to parse the String according to the format described in Date Time String Format (21.4.1.15), including expanded years. If the String does not conform to that format the function may fall back to any implementation-specific heuristics or implementation-specific date formats. Strings that are unrecognizable or contain out-of-bounds format element values shall cause Date.parse to return NaN.

If the String conforms to the Date Time String Format, substitute values take the place of absent format elements. When the MM or DD elements are absent, "01" is used. When the HH, mm, or ss elements are absent, "00" is used. When the sss element is absent, "000" is used. When the UTC offset representation is absent, date-only forms are interpreted as a UTC time and date-time forms are interpreted as a local time.

If x is any Date whose milliseconds amount is zero within a particular implementation of ECMAScript, then all of the following expressions should produce the same numeric value in that implementation, if all the properties referenced have their initial values:

x.valueOf()
Date.parse(x.toString())
Date.parse(x.toUTCString())
Date.parse(x.toISOString())

However, the expression

Date.parse(x.toLocaleString())

is not required to produce the same Number value as the preceding three expressions and, in general, the value produced by Date.parse is implementation-defined when given any String value that does not conform to the Date Time String Format (21.4.1.15) and that could not be produced in that implementation by the toString or toUTCString method.

21.4.3.3 Date.prototype

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

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

21.4.3.4 Date.UTC ( year [ , month [ , date [ , hours [ , minutes [ , seconds [ , ms ] ] ] ] ] ] )

When the UTC function is called, the following steps are taken:

  1. Let y be ? ToNumber(year).
  2. If month is present, let m be ? ToNumber(month); else let m be +0𝔽.
  3. If date is present, let dt be ? ToNumber(date); else let dt be 1𝔽.
  4. If hours is present, let h be ? ToNumber(hours); else let h be +0𝔽.
  5. If minutes is present, let min be ? ToNumber(minutes); else let min be +0𝔽.
  6. If seconds is present, let s be ? ToNumber(seconds); else let s be +0𝔽.
  7. If ms is present, let milli be ? ToNumber(ms); else let milli be +0𝔽.
  8. If y is NaN, let yr be NaN.
  9. Else,
    1. Let yi be ! ToIntegerOrInfinity(y).
    2. If 0 ≤ yi ≤ 99, let yr be 1900𝔽 + 𝔽(yi); otherwise, let yr be y.
  10. Return TimeClip(MakeDate(MakeDay(yr, m, dt), MakeTime(h, min, s, milli))).

The "length" property of the UTC function is 7𝔽.

Note

The UTC function differs from the Date constructor in two ways: it returns a time value as a Number, rather than creating a Date, and it interprets the arguments in UTC rather than as local time.

21.4.4 Properties of the Date Prototype Object

The Date prototype object:

  • is %Date.prototype%.
  • is itself an ordinary object.
  • is not a Date instance and does not have a [[DateValue]] internal slot.
  • has a [[Prototype]] internal slot whose value is %Object.prototype%.

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

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

  1. If Type(value) is Object and value has a [[DateValue]] internal slot, then
    1. Return value.[[DateValue]].
  2. Throw a TypeError exception.

In following descriptions of functions that are properties of the Date prototype object, the phrase “this Date object” refers to the object that is the this value for the invocation of the function. If the Type of the this value is not Object, a TypeError exception is thrown. The phrase “this time value” within the specification of a method refers to the result returned by calling the abstract operation thisTimeValue with the this value of the method invocation passed as the argument.

21.4.4.1 Date.prototype.constructor

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

21.4.4.2 Date.prototype.getDate ( )

The following steps are performed:

  1. Let t be ? thisTimeValue(this value).
  2. If t is NaN, return NaN.
  3. Return DateFromTime(LocalTime(t)).

21.4.4.3 Date.prototype.getDay ( )

The following steps are performed:

  1. Let t be ? thisTimeValue(this value).
  2. If t is NaN, return NaN.
  3. Return WeekDay(LocalTime(t)).

21.4.4.4 Date.prototype.getFullYear ( )

The following steps are performed:

  1. Let t be ? thisTimeValue(this value).
  2. If t is NaN, return NaN.
  3. Return YearFromTime(LocalTime(t)).

21.4.4.5 Date.prototype.getHours ( )

The following steps are performed:

  1. Let t be ? thisTimeValue(this value).
  2. If t is NaN, return NaN.
  3. Return HourFromTime(LocalTime(t)).

21.4.4.6 Date.prototype.getMilliseconds ( )

The following steps are performed:

  1. Let t be ? thisTimeValue(this value).
  2. If t is NaN, return NaN.
  3. Return msFromTime(LocalTime(t)).

21.4.4.7 Date.prototype.getMinutes ( )

The following steps are performed:

  1. Let t be ? thisTimeValue(this value).
  2. If t is NaN, return NaN.
  3. Return MinFromTime(LocalTime(t)).

21.4.4.8 Date.prototype.getMonth ( )

The following steps are performed:

  1. Let t be ? thisTimeValue(this value).
  2. If t is NaN, return NaN.
  3. Return MonthFromTime(LocalTime(t)).

21.4.4.9 Date.prototype.getSeconds ( )

The following steps are performed:

  1. Let t be ? thisTimeValue(this value).
  2. If t is NaN, return NaN.
  3. Return SecFromTime(LocalTime(t)).

21.4.4.10 Date.prototype.getTime ( )

The following steps are performed:

  1. Return ? thisTimeValue(this value).

21.4.4.11 Date.prototype.getTimezoneOffset ( )

The following steps are performed:

  1. Let t be ? thisTimeValue(this value).
  2. If t is NaN, return NaN.
  3. Return (t - LocalTime(t)) / msPerMinute.

21.4.4.12 Date.prototype.getUTCDate ( )

The following steps are performed:

  1. Let t be ? thisTimeValue(this value).
  2. If t is NaN, return NaN.
  3. Return DateFromTime(t).

21.4.4.13 Date.prototype.getUTCDay ( )

The following steps are performed:

  1. Let t be ? thisTimeValue(this value).
  2. If t is NaN, return NaN.
  3. Return WeekDay(t).

21.4.4.14 Date.prototype.getUTCFullYear ( )

The following steps are performed:

  1. Let t be ? thisTimeValue(this value).
  2. If t is NaN, return NaN.
  3. Return YearFromTime(t).

21.4.4.15 Date.prototype.getUTCHours ( )

The following steps are performed:

  1. Let t be ? thisTimeValue(this value).
  2. If t is NaN, return NaN.
  3. Return HourFromTime(t).

21.4.4.16 Date.prototype.getUTCMilliseconds ( )

The following steps are performed:

  1. Let t be ? thisTimeValue(this value).
  2. If t is NaN, return NaN.
  3. Return msFromTime(t).

21.4.4.17 Date.prototype.getUTCMinutes ( )

The following steps are performed:

  1. Let t be ? thisTimeValue(this value).
  2. If t is NaN, return NaN.
  3. Return MinFromTime(t).

21.4.4.18 Date.prototype.getUTCMonth ( )

The following steps are performed:

  1. Let t be ? thisTimeValue(this value).
  2. If t is NaN, return NaN.
  3. Return MonthFromTime(t).

21.4.4.19 Date.prototype.getUTCSeconds ( )

The following steps are performed:

  1. Let t be ? thisTimeValue(this value).
  2. If t is NaN, return NaN.
  3. Return SecFromTime(t).

21.4.4.20 Date.prototype.setDate ( date )

The following steps are performed:

  1. Let t be LocalTime(? thisTimeValue(this value)).
  2. Let dt be ? ToNumber(date).
  3. Let newDate be MakeDate(MakeDay(YearFromTime(t), MonthFromTime(t), dt), TimeWithinDay(t)).
  4. Let u be TimeClip(UTC(newDate)).
  5. Set the [[DateValue]] internal slot of this Date object to u.
  6. Return u.

21.4.4.21 Date.prototype.setFullYear ( year [ , month [ , date ] ] )

The following steps are performed:

  1. Let t be ? thisTimeValue(this value).
  2. If t is NaN, set t to +0𝔽; otherwise, set t to LocalTime(t).
  3. Let y be ? ToNumber(year).
  4. If month is not present, let m be MonthFromTime(t); otherwise, let m be ? ToNumber(month).
  5. If date is not present, let dt be DateFromTime(t); otherwise, let dt be ? ToNumber(date).
  6. Let newDate be MakeDate(MakeDay(y, m, dt), TimeWithinDay(t)).
  7. Let u be TimeClip(UTC(newDate)).
  8. Set the [[DateValue]] internal slot of this Date object to u.
  9. Return u.

The "length" property of the setFullYear method is 3𝔽.

Note

If month is not present, this method behaves as if month was present with the value getMonth(). If date is not present, it behaves as if date was present with the value getDate().

21.4.4.22 Date.prototype.setHours ( hour [ , min [ , sec [ , ms ] ] ] )

The following steps are performed:

  1. Let t be LocalTime(? thisTimeValue(this value)).
  2. Let h be ? ToNumber(hour).
  3. If min is not present, let m be MinFromTime(t); otherwise, let m be ? ToNumber(min).
  4. If sec is not present, let s be SecFromTime(t); otherwise, let s be ? ToNumber(sec).
  5. If ms is not present, let milli be msFromTime(t); otherwise, let milli be ? ToNumber(ms).
  6. Let date be MakeDate(Day(t), MakeTime(h, m, s, milli)).
  7. Let u be TimeClip(UTC(date)).
  8. Set the [[DateValue]] internal slot of this Date object to u.
  9. Return u.

The "length" property of the setHours method is 4𝔽.

Note

If min is not present, this method behaves as if min was present with the value getMinutes(). If sec is not present, it behaves as if sec was present with the value getSeconds(). If ms is not present, it behaves as if ms was present with the value getMilliseconds().

21.4.4.23 Date.prototype.setMilliseconds ( ms )

The following steps are performed:

  1. Let t be LocalTime(? thisTimeValue(this value)).
  2. Set ms to ? ToNumber(ms).
  3. Let time be MakeTime(HourFromTime(t), MinFromTime(t), SecFromTime(t), ms).
  4. Let u be TimeClip(UTC(MakeDate(Day(t), time))).
  5. Set the [[DateValue]] internal slot of this Date object to u.
  6. Return u.

21.4.4.24 Date.prototype.setMinutes ( min [ , sec [ , ms ] ] )

The following steps are performed:

  1. Let t be LocalTime(? thisTimeValue(this value)).
  2. Let m be ? ToNumber(min).
  3. If sec is not present, let s be SecFromTime(t); otherwise, let s be ? ToNumber(sec).
  4. If ms is not present, let milli be msFromTime(t); otherwise, let milli be ? ToNumber(ms).
  5. Let date be MakeDate(Day(t), MakeTime(HourFromTime(t), m, s, milli)).
  6. Let u be TimeClip(UTC(date)).
  7. Set the [[DateValue]] internal slot of this Date object to u.
  8. Return u.

The "length" property of the setMinutes method is 3𝔽.

Note

If sec is not present, this method behaves as if sec was present with the value getSeconds(). If ms is not present, this behaves as if ms was present with the value getMilliseconds().

21.4.4.25 Date.prototype.setMonth ( month [ , date ] )

The following steps are performed:

  1. Let t be LocalTime(? thisTimeValue(this value)).
  2. Let m be ? ToNumber(month).
  3. If date is not present, let dt be DateFromTime(t); otherwise, let dt be ? ToNumber(date).
  4. Let newDate be MakeDate(MakeDay(YearFromTime(t), m, dt), TimeWithinDay(t)).
  5. Let u be TimeClip(UTC(newDate)).
  6. Set the [[DateValue]] internal slot of this Date object to u.
  7. Return u.

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

Note

If date is not present, this method behaves as if date was present with the value getDate().

21.4.4.26 Date.prototype.setSeconds ( sec [ , ms ] )

The following steps are performed:

  1. Let t be LocalTime(? thisTimeValue(this value)).
  2. Let s be ? ToNumber(sec).
  3. If ms is not present, let milli be msFromTime(t); otherwise, let milli be ? ToNumber(ms).
  4. Let date be MakeDate(Day(t), MakeTime(HourFromTime(t), MinFromTime(t), s, milli)).
  5. Let u be TimeClip(UTC(date)).
  6. Set the [[DateValue]] internal slot of this Date object to u.
  7. Return u.

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

Note

If ms is not present, this method behaves as if ms was present with the value getMilliseconds().

21.4.4.27 Date.prototype.setTime ( time )

The following steps are performed:

  1. Perform ? thisTimeValue(this value).
  2. Let t be ? ToNumber(time).
  3. Let v be TimeClip(t).
  4. Set the [[DateValue]] internal slot of this Date object to v.
  5. Return v.

21.4.4.28 Date.prototype.setUTCDate ( date )

The following steps are performed:

  1. Let t be ? thisTimeValue(this value).
  2. Let dt be ? ToNumber(date).
  3. Let newDate be MakeDate(MakeDay(YearFromTime(t), MonthFromTime(t), dt), TimeWithinDay(t)).
  4. Let v be TimeClip(newDate).
  5. Set the [[DateValue]] internal slot of this Date object to v.
  6. Return v.

21.4.4.29 Date.prototype.setUTCFullYear ( year [ , month [ , date ] ] )

The following steps are performed:

  1. Let t be ? thisTimeValue(this value).
  2. If t is NaN, set t to +0𝔽.
  3. Let y be ? ToNumber(year).
  4. If month is not present, let m be MonthFromTime(t); otherwise, let m be ? ToNumber(month).
  5. If date is not present, let dt be DateFromTime(t); otherwise, let dt be ? ToNumber(date).
  6. Let newDate be MakeDate(MakeDay(y, m, dt), TimeWithinDay(t)).
  7. Let v be TimeClip(newDate).
  8. Set the [[DateValue]] internal slot of this Date object to v.
  9. Return v.

The "length" property of the setUTCFullYear method is 3𝔽.

Note

If month is not present, this method behaves as if month was present with the value getUTCMonth(). If date is not present, it behaves as if date was present with the value getUTCDate().

21.4.4.30 Date.prototype.setUTCHours ( hour [ , min [ , sec [ , ms ] ] ] )

The following steps are performed:

  1. Let t be ? thisTimeValue(this value).
  2. Let h be ? ToNumber(hour).
  3. If min is not present, let m be MinFromTime(t); otherwise, let m be ? ToNumber(min).
  4. If sec is not present, let s be SecFromTime(t); otherwise, let s be ? ToNumber(sec).
  5. If ms is not present, let milli be msFromTime(t); otherwise, let milli be ? ToNumber(ms).
  6. Let newDate be MakeDate(Day(t), MakeTime(h, m, s, milli)).
  7. Let v be TimeClip(newDate).
  8. Set the [[DateValue]] internal slot of this Date object to v.
  9. Return v.

The "length" property of the setUTCHours method is 4𝔽.

Note

If min is not present, this method behaves as if min was present with the value getUTCMinutes(). If sec is not present, it behaves as if sec was present with the value getUTCSeconds(). If ms is not present, it behaves as if ms was present with the value getUTCMilliseconds().

21.4.4.31 Date.prototype.setUTCMilliseconds ( ms )

The following steps are performed:

  1. Let t be ? thisTimeValue(this value).
  2. Let milli be ? ToNumber(ms).
  3. Let time be MakeTime(HourFromTime(t), MinFromTime(t), SecFromTime(t), milli).
  4. Let v be TimeClip(MakeDate(Day(t), time)).
  5. Set the [[DateValue]] internal slot of this Date object to v.
  6. Return v.

21.4.4.32 Date.prototype.setUTCMinutes ( min [ , sec [ , ms ] ] )

The following steps are performed:

  1. Let t be ? thisTimeValue(this value).
  2. Let m be ? ToNumber(min).
  3. If sec is not present, let s be SecFromTime(t).
  4. Else,
    1. Let s be ? ToNumber(sec).
  5. If ms is not present, let milli be msFromTime(t).
  6. Else,
    1. Let milli be ? ToNumber(ms).
  7. Let date be MakeDate(Day(t), MakeTime(HourFromTime(t), m, s, milli)).
  8. Let v be TimeClip(date).
  9. Set the [[DateValue]] internal slot of this Date object to v.
  10. Return v.

The "length" property of the setUTCMinutes method is 3𝔽.

Note

If sec is not present, this method behaves as if sec was present with the value getUTCSeconds(). If ms is not present, it function behaves as if ms was present with the value return by getUTCMilliseconds().

21.4.4.33 Date.prototype.setUTCMonth ( month [ , date ] )

The following steps are performed:

  1. Let t be ? thisTimeValue(this value).
  2. Let m be ? ToNumber(month).
  3. If date is not present, let dt be DateFromTime(t).
  4. Else,
    1. Let dt be ? ToNumber(date).
  5. Let newDate be MakeDate(MakeDay(YearFromTime(t), m, dt), TimeWithinDay(t)).
  6. Let v be TimeClip(newDate).
  7. Set the [[DateValue]] internal slot of this Date object to v.
  8. Return v.

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

Note

If date is not present, this method behaves as if date was present with the value getUTCDate().

21.4.4.34 Date.prototype.setUTCSeconds ( sec [ , ms ] )

The following steps are performed:

  1. Let t be ? thisTimeValue(this value).
  2. Let s be ? ToNumber(sec).
  3. If ms is not present, let milli be msFromTime(t).
  4. Else,
    1. Let milli be ? ToNumber(ms).
  5. Let date be MakeDate(Day(t), MakeTime(HourFromTime(t), MinFromTime(t), s, milli)).
  6. Let v be TimeClip(date).
  7. Set the [[DateValue]] internal slot of this Date object to v.
  8. Return v.

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

Note

If ms is not present, this method behaves as if ms was present with the value getUTCMilliseconds().

21.4.4.35 Date.prototype.toDateString ( )

The following steps are performed:

  1. Let O be this Date object.
  2. Let tv be ? thisTimeValue(O).
  3. If tv is NaN, return "Invalid Date".
  4. Let t be LocalTime(tv).
  5. Return DateString(t).

21.4.4.36 Date.prototype.toISOString ( )

If this time value is not a finite Number or if it corresponds with a year that cannot be represented in the Date Time String Format, this function throws a RangeError exception. Otherwise, it returns a String representation of this time value in that format on the UTC time scale, including all format elements and the UTC offset representation "Z".

21.4.4.37 Date.prototype.toJSON ( key )

This function provides a String representation of a Date for use by JSON.stringify (25.5.2).

When the toJSON method is called with argument key, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Let tv be ? ToPrimitive(O, number).
  3. If Type(tv) is Number and tv is not finite, return null.
  4. Return ? Invoke(O, "toISOString").
Note 1

The argument is ignored.

Note 2

The toJSON function is intentionally generic; it does not require that its this value be a Date. Therefore, it can be transferred to other kinds of objects for use as a method. However, it does require that any such object have a toISOString method.

21.4.4.38 Date.prototype.toLocaleDateString ( [ reserved1 [ , reserved2 ] ] )

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

This function returns a String value. The contents of the String are implementation-defined, but are intended to represent the “date” portion of the Date in the current time zone in a convenient, human-readable form that corresponds to the conventions of the host environment's current locale.

The meaning 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.4.4.39 Date.prototype.toLocaleString ( [ reserved1 [ , reserved2 ] ] )

An ECMAScript implementation that includes the ECMA-402 Internationalization API must implement the Date.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.

This function returns a String value. The contents of the String are implementation-defined, but are intended to represent the Date in the current time zone in a convenient, human-readable form that corresponds to the conventions of the host environment's current locale.

The meaning 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.4.4.40 Date.prototype.toLocaleTimeString ( [ reserved1 [ , reserved2 ] ] )

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

This function returns a String value. The contents of the String are implementation-defined, but are intended to represent the “time” portion of the Date in the current time zone in a convenient, human-readable form that corresponds to the conventions of the host environment's current locale.

The meaning 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.4.4.41 Date.prototype.toString ( )

The following steps are performed:

  1. Let tv be ? thisTimeValue(this value).
  2. Return ToDateString(tv).
Note 1

For any Date d such that d.[[DateValue]] is evenly divisible by 1000, the result of Date.parse(d.toString()) = d.valueOf(). See 21.4.3.2.

Note 2

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

21.4.4.41.1 TimeString ( tv )

The abstract operation TimeString takes argument tv (a Number, but not NaN). It performs the following steps when called:

  1. Let hour be the String representation of HourFromTime(tv), formatted as a two-digit decimal number, padded to the left with the code unit 0x0030 (DIGIT ZERO) if necessary.
  2. Let minute be the String representation of MinFromTime(tv), formatted as a two-digit decimal number, padded to the left with the code unit 0x0030 (DIGIT ZERO) if necessary.
  3. Let second be the String representation of SecFromTime(tv), formatted as a two-digit decimal number, padded to the left with the code unit 0x0030 (DIGIT ZERO) if necessary.
  4. Return the string-concatenation of hour, ":", minute, ":", second, the code unit 0x0020 (SPACE), and "GMT".

21.4.4.41.2 DateString ( tv )

The abstract operation DateString takes argument tv (a Number, but not NaN). It performs the following steps when called:

  1. Let weekday be the Name of the entry in Table 65 with the Number WeekDay(tv).
  2. Let month be the Name of the entry in Table 66 with the Number MonthFromTime(tv).
  3. Let day be the String representation of DateFromTime(tv), formatted as a two-digit decimal number, padded to the left with the code unit 0x0030 (DIGIT ZERO) if necessary.
  4. Let yv be YearFromTime(tv).
  5. If yv+0𝔽, let yearSign be the empty String; otherwise, let yearSign be "-".
  6. Let year be the String representation of abs((yv)), formatted as a decimal number.
  7. Let paddedYear be ! StringPad(year, 4𝔽, "0", start).
  8. Return the string-concatenation of weekday, the code unit 0x0020 (SPACE), month, the code unit 0x0020 (SPACE), day, the code unit 0x0020 (SPACE), yearSign, and paddedYear.
Table 65: Names of days of the week
Number Name
+0𝔽 "Sun"
1𝔽 "Mon"
2𝔽 "Tue"
3𝔽 "Wed"
4𝔽 "Thu"
5𝔽 "Fri"
6𝔽 "Sat"
Table 66: Names of months of the year
Number Name
+0𝔽 "Jan"
1𝔽 "Feb"
2𝔽 "Mar"
3𝔽 "Apr"
4𝔽 "May"
5𝔽 "Jun"
6𝔽 "Jul"
7𝔽 "Aug"
8𝔽 "Sep"
9𝔽 "Oct"
10𝔽 "Nov"
11𝔽 "Dec"

21.4.4.41.3 TimeZoneString ( tv )

The abstract operation TimeZoneString takes argument tv (a Number, but not NaN). It performs the following steps when called:

  1. Let offset be LocalTZA(tv, true).
  2. If offset+0𝔽, then
    1. Let offsetSign be "+".
    2. Let absOffset be offset.
  3. Else,
    1. Let offsetSign be "-".
    2. Let absOffset be -offset.
  4. Let offsetMin be the String representation of MinFromTime(absOffset), formatted as a two-digit decimal number, padded to the left with the code unit 0x0030 (DIGIT ZERO) if necessary.
  5. Let offsetHour be the String representation of HourFromTime(absOffset), formatted as a two-digit decimal number, padded to the left with the code unit 0x0030 (DIGIT ZERO) if necessary.
  6. Let tzName be an implementation-defined string that is either the empty String or the string-concatenation of the code unit 0x0020 (SPACE), the code unit 0x0028 (LEFT PARENTHESIS), an implementation-defined timezone name, and the code unit 0x0029 (RIGHT PARENTHESIS).
  7. Return the string-concatenation of offsetSign, offsetHour, offsetMin, and tzName.

21.4.4.41.4 ToDateString ( tv )

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

  1. If tv is NaN, return "Invalid Date".
  2. Let t be LocalTime(tv).
  3. Return the string-concatenation of DateString(t), the code unit 0x0020 (SPACE), TimeString(t), and TimeZoneString(tv).

21.4.4.42 Date.prototype.toTimeString ( )

The following steps are performed:

  1. Let O be this Date object.
  2. Let tv be ? thisTimeValue(O).
  3. If tv is NaN, return "Invalid Date".
  4. Let t be LocalTime(tv).
  5. Return the string-concatenation of TimeString(t) and TimeZoneString(tv).

21.4.4.43 Date.prototype.toUTCString ( )

The toUTCString method returns a String value representing the instance in time corresponding to this time value. The format of the String is based upon "HTTP-date" from RFC 7231, generalized to support the full range of times supported by ECMAScript Dates. It performs the following steps when called:

  1. Let O be this Date object.
  2. Let tv be ? thisTimeValue(O).
  3. If tv is NaN, return "Invalid Date".
  4. Let weekday be the Name of the entry in Table 65 with the Number WeekDay(tv).
  5. Let month be the Name of the entry in Table 66 with the Number MonthFromTime(tv).
  6. Let day be the String representation of DateFromTime(tv), formatted as a two-digit decimal number, padded to the left with the code unit 0x0030 (DIGIT ZERO) if necessary.
  7. Let yv be YearFromTime(tv).
  8. If yv+0𝔽, let yearSign be the empty String; otherwise, let yearSign be "-".
  9. Let year be the String representation of abs((yv)), formatted as a decimal number.
  10. Let paddedYear be ! StringPad(year, 4𝔽, "0", start).
  11. Return the string-concatenation of weekday, ",", the code unit 0x0020 (SPACE), day, the code unit 0x0020 (SPACE), month, the code unit 0x0020 (SPACE), yearSign, paddedYear, the code unit 0x0020 (SPACE), and TimeString(tv).

21.4.4.44 Date.prototype.valueOf ( )

The following steps are performed:

  1. Return ? thisTimeValue(this value).

21.4.4.45 Date.prototype [ @@toPrimitive ] ( hint )

This function is called by ECMAScript language operators to convert a Date to a primitive value. The allowed values for hint are "default", "number", and "string". Dates are unique among built-in ECMAScript object in that they treat "default" as being equivalent to "string", All other built-in ECMAScript objects treat "default" as being equivalent to "number".

When the @@toPrimitive method is called with argument hint, the following steps are taken:

  1. Let O be the this value.
  2. If Type(O) is not Object, throw a TypeError exception.
  3. If hint is "string" or "default", then
    1. Let tryFirst be string.
  4. Else if hint is "number", then
    1. Let tryFirst be number.
  5. Else, throw a TypeError exception.
  6. Return ? OrdinaryToPrimitive(O, tryFirst).

The value of the "name" property of this function is "[Symbol.toPrimitive]".

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

21.4.5 Properties of Date Instances

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