is the initial value of the "Number" property of the global object.
creates and initializes a new Number object when called as a constructor.
performs a type conversion when called as a function rather than as a constructor.
may be used as the value of an extends clause of a class definition. Subclass constructors that intend to inherit the specified Number behaviour must include a super call to the Number constructor to create and initialize the subclass instance with a [[NumberData]] internal slot.
21.1.1.1 Number ( value )
This function performs the following steps when called:
The value of Number.EPSILON is the Number value for the magnitude of the difference between 1 and the smallest value greater than 1 that is representable as a Number value, which is approximately 2.2204460492503130808472633361816 ร 10-16.
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.
21.1.2.2 Number.isFinite ( number )
This function performs the following steps when called:
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.
Due to rounding behaviour necessitated by precision limitations of IEEE 754-2019, the Number value for every integer greater than Number.MAX_SAFE_INTEGER is shared with at least one other integer. Such large-magnitude integers are therefore not safe, and are not guaranteed to be exactly representable as Number values or even to be distinguishable from each other. For example, both 9007199254740992 and 9007199254740993 evaluate to the Number value 9007199254740992๐ฝ.
The value of Number.MAX_SAFE_INTEGER is 9007199254740991๐ฝ (๐ฝ(253 - 1)).
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.
21.1.2.7 Number.MAX_VALUE
The value of Number.MAX_VALUE is the largest positive finite value of the Number type, which is approximately 1.7976931348623157 ร 10308.
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.
21.1.2.8 Number.MIN_SAFE_INTEGER
Note
Due to rounding behaviour necessitated by precision limitations of IEEE 754-2019, the Number value for every integer less than Number.MIN_SAFE_INTEGER is shared with at least one other integer. Such large-magnitude integers are therefore not safe, and are not guaranteed to be exactly representable as Number values or even to be distinguishable from each other. For example, both -9007199254740992 and -9007199254740993 evaluate to the Number value -9007199254740992๐ฝ.
The value of Number.MIN_SAFE_INTEGER is -9007199254740991๐ฝ (๐ฝ(-(253 - 1))).
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.
21.1.2.9 Number.MIN_VALUE
The value of Number.MIN_VALUE is the smallest positive value of the Number type, which is approximately 5 ร 10-324.
In the IEEE 754-2019 double precision binary representation, the smallest possible value is a denormalized number. If an implementation does not support denormalized values, the value of Number.MIN_VALUE must be the smallest non-zero positive value that can actually be represented by the implementation.
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.
21.1.2.10 Number.NaN
The value of Number.NaN is NaN.
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.
21.1.2.11 Number.NEGATIVE_INFINITY
The value of Number.NEGATIVE_INFINITY is -โ๐ฝ.
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.
21.1.2.12 Number.parseFloat ( string )
The initial value of the "parseFloat" property is %parseFloat%.
21.1.2.13 Number.parseInt ( string, radix )
The initial value of the "parseInt" property is %parseInt%.
21.1.2.14 Number.POSITIVE_INFINITY
The value of Number.POSITIVE_INFINITY is +โ๐ฝ.
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.
Unless explicitly stated otherwise, the methods of the Number prototype object defined below are not generic and the this value passed to them must be either a Number value or an object that has a [[NumberData]] internal slot that has been initialized to a Number value.
The phrase โthis Number valueโ within the specification of a method refers to the result returned by calling the abstract operation ThisNumberValue with the this value of the method invocation passed as the argument.
21.1.3.1 Number.prototype.constructor
The initial value of Number.prototype.constructor is %Number%.
This method returns a String containing this Number value represented in decimal exponential notation with one digit before the significand's decimal point and fractionDigits digits after the significand's decimal point. If fractionDigits is undefined, it includes as many significand digits as necessary to uniquely specify the Number (just like in ToString except that in this case the Number is always output in exponential notation).
Let m be the String value consisting of f + 1 occurrences of the code unit 0x0030 (DIGIT ZERO).
Let e be 0.
Else,
If fractionDigits is not undefined, then
Let e and n be integers such that 10f โค n < 10f + 1 and for which n ร 10e - f - x is as close to zero as possible. If there are two such sets of e and n, pick the e and n for which n ร 10e - f is larger.
Else,
Let e, n, and ff be integers such that ff โฅ 0, 10ff โค n < 10ff + 1, ๐ฝ(n ร 10e - ff) is ๐ฝ(x), and ff is as small as possible. Note that the decimal representation of n has ff + 1 digits, n is not divisible by 10, and the least significant digit of n is not necessarily uniquely determined by these criteria.
Set f to ff.
Let m be the String value consisting of the digits of the decimal representation of n (in order, with no leading zeroes).
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:
Let e, n, and f be integers such that f โฅ 0, 10f โค n < 10f + 1, ๐ฝ(n ร 10e - f) is ๐ฝ(x), and f is as small as possible. If there are multiple possibilities for n, choose the value of n for which ๐ฝ(n ร 10e - f) is closest in value to ๐ฝ(x). If there are two such possible values of n, choose the one that is even.
This method returns a String containing this Number value represented in decimal fixed-point notation with fractionDigits digits after the decimal point. If fractionDigits is undefined, 0 is assumed.
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.
If n = 0, let m be "0". Otherwise, let m be the String value consisting of the digits of the decimal representation of n (in order, with no leading zeroes).
If f โ 0, then
Let k be the length of m.
If k โค f, then
Let z be the String value consisting of f + 1 - k occurrences of the code unit 0x0030 (DIGIT ZERO).
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".
An ECMAScript implementation that includes the ECMA-402 Internationalization API must implement this method as specified in the ECMA-402 specification. If an ECMAScript implementation does not include the ECMA-402 API the following specification of this method is used:
This method produces a String value that represents this Number value formatted according to the conventions of the host environment's current locale. This method is implementation-defined, and it is permissible, but not encouraged, for it to return the same thing as toString.
The meanings of the optional parameters to this method are defined in the ECMA-402 specification; implementations that do not include ECMA-402 support must not use those parameter positions for anything else.
This method returns a String containing this Number value represented either in decimal exponential notation with one digit before the significand's decimal point and precision - 1 digits after the significand's decimal point or in decimal fixed notation with precision significant digits. If precision is undefined, it calls ToString instead.
Let m be the String value consisting of p occurrences of the code unit 0x0030 (DIGIT ZERO).
Let e be 0.
Else,
Let e and n be integers such that 10p - 1 โค n < 10p and for which n ร 10e - p + 1 - x is as close to zero as possible. If there are two such sets of e and n, pick the e and n for which n ร 10e - p + 1 is larger.
Let m be the String value consisting of the digits of the decimal representation of n (in order, with no leading zeroes).
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.
Else,
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.
The optional radix should be an integral Number value in the inclusive interval from 2๐ฝ to 36๐ฝ. If radix is undefined then 10๐ฝ is used as the value of radix.
This method performs the following steps when called:
This method is not generic; it throws a TypeError exception if its this value is not a Number or a Number object. Therefore, it cannot be transferred to other kinds of objects for use as a method.
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.
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 )
This function performs the following steps when called:
If NewTarget is not undefined, throw a TypeError exception.
The abstract operation NumberToBigInt takes argument number (a Number) and returns either a normal completion containing a BigInt or a throw completion. It performs the following steps when called:
If number is not an integral Number, throw a RangeError 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%.
An ECMAScript implementation that includes the ECMA-402 Internationalization API must implement this method as specified in the ECMA-402 specification. If an ECMAScript implementation does not include the ECMA-402 API the following specification of this method is used:
This method produces a String value that represents this BigInt value formatted according to the conventions of the host environment's current locale. This method is implementation-defined, and it is permissible, but not encouraged, for it to return the same thing as toString.
The meanings of the optional parameters to this method are defined in the ECMA-402 specification; implementations that do not include ECMA-402 support must not use those parameter positions for anything else.
21.2.3.3 BigInt.prototype.toString ( [ radix ] )
Note
The optional radix should be an integral Number value in the inclusive interval from 2๐ฝ to 36๐ฝ. If radix is undefined then 10๐ฝ is used as the value of radix.
This method performs the following steps when called:
This method 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.
The initial value of the @@toStringTag property is the String value "BigInt".
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.
21.2.4 Properties of BigInt Instances
BigInt instances are ordinary objects that inherit properties from the BigInt prototype object. BigInt instances also have a [[BigIntData]] internal slot. The [[BigIntData]] internal slot is the BigInt value represented by this BigInt object.
21.3 The Math Object
The Math object:
is %Math%.
is the initial value of the "Math" property of the global 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 forxโ 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 fore, 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 )
This function returns the absolute value of x; the result has the same magnitude as x but has positive sign.
This function returns the inverse tangent of x. The result is expressed in radians and is in the inclusive interval from ๐ฝ(-ฯ / 2) to ๐ฝ(ฯ / 2).
This function 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 is in the inclusive interval from -ฯ to +ฯ.
This function 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.
If n is either +0๐ฝ or -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 )
This function returns the cosine of x. The argument is expressed in radians.
This function 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.
If n is one of NaN, +0๐ฝ, -0๐ฝ, or +โ๐ฝ, return n.
If n is -โ๐ฝ, return -1๐ฝ.
Return an implementation-approximated Number value representing the result of subtracting 1 from the exponential function of โ(n).
21.3.2.16 Math.floor ( x )
This function 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.
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 )
This function performs the following steps when called:
If number is +0๐ฝ and highest is -0๐ฝ, set highest to +0๐ฝ.
If number > highest, set highest to number.
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 this function is 2๐ฝ.
21.3.2.25 Math.min ( ...args )
Given zero or more arguments, this function calls ToNumber on each of the arguments and returns the smallest of the resulting values.
If number is -0๐ฝ and lowest is +0๐ฝ, set lowest to -0๐ฝ.
If number < lowest, set lowest to number.
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 this function is 2๐ฝ.
21.3.2.26 Math.pow ( base, exponent )
This function performs the following steps when called:
This function 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.
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 )
This function 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.
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 x 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 )
This function returns the sign of x, indicating whether x is positive, negative, or zero.
If n is not finite or n is either +0๐ฝ or -0๐ฝ, return n.
If n < 1๐ฝ and n > +0๐ฝ, return +0๐ฝ.
If n < -0๐ฝ and n > -1๐ฝ, return -0๐ฝ.
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 finiteintegral 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 86,400,000 ร d for some integerd) 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 (t - s) 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
In the proleptic Gregorian calendar, leap years are precisely those which are both divisible by 4 and either divisible by 400 or not divisible by 100.
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 Time-related Constants
These constants are referenced by algorithms in the following sections.
The abstract operation Day takes argument t (a finitetime value) and returns an integral Number. It returns the day number of the day in which t falls. It performs the following steps when called:
The abstract operation TimeWithinDay takes argument t (a finitetime value) and returns an integral Number in the interval from +0๐ฝ (inclusive) to msPerDay (exclusive). It returns the number of milliseconds since the start of the day in which t falls. It performs the following steps when called:
The abstract operation DaysInYear takes argument y (an integral Number) and returns 365๐ฝ or 366๐ฝ. It returns the number of days in year y. Leap years have 366 days; all other years have 365. It performs the following steps when called:
The abstract operation DayFromYear takes argument y (an integral Number) and returns an integral Number. It returns the day number of the first day of year y. It performs the following steps when called:
NOTE: In the following steps, numYears1, numYears4, numYears100, and numYears400 represent the number of years divisible by 1, 4, 100, and 400, respectively, that occur between the epoch and the start of year y. The number is negative if y is before the epoch.
The abstract operation TimeFromYear takes argument y (an integral Number) and returns a time value. It returns the time value of the start of year y. It performs the following steps when called:
The abstract operation YearFromTime takes argument t (a finitetime value) and returns an integral Number. It returns the year in which t falls. It performs the following steps when called:
The abstract operation DayWithinYear takes argument t (a finitetime value) and returns an integral Number in the inclusive interval from +0๐ฝ to 365๐ฝ. It performs the following steps when called:
The abstract operation InLeapYear takes argument t (a finitetime value) and returns +0๐ฝ or 1๐ฝ. It returns 1๐ฝ if t is within a leap year and +0๐ฝ otherwise. It performs the following steps when called:
The abstract operation MonthFromTime takes argument t (a finitetime value) and returns an integral Number in the inclusive interval from +0๐ฝ to 11๐ฝ. It returns a Number identifying the month in which t falls. 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. It performs the following steps when called:
The abstract operation DateFromTime takes argument t (a finitetime value) and returns an integral Number in the inclusive interval from 1๐ฝ to 31๐ฝ. It returns the day of the month in which t falls. It performs the following steps when called:
The abstract operation WeekDay takes argument t (a finitetime value) and returns an integral Number in the inclusive interval from +0๐ฝ to 6๐ฝ. It returns a Number identifying the day of the week in which t falls. 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. It performs the following steps when called:
The abstract operation HourFromTime takes argument t (a finitetime value) and returns an integral Number in the inclusive interval from +0๐ฝ to 23๐ฝ. It returns the hour of the day in which t falls. It performs the following steps when called:
The abstract operation MinFromTime takes argument t (a finitetime value) and returns an integral Number in the inclusive interval from +0๐ฝ to 59๐ฝ. It returns the minute of the hour in which t falls. It performs the following steps when called:
The abstract operation SecFromTime takes argument t (a finitetime value) and returns an integral Number in the inclusive interval from +0๐ฝ to 59๐ฝ. It returns the second of the minute in which t falls. It performs the following steps when called:
The abstract operation msFromTime takes argument t (a finitetime value) and returns an integral Number in the inclusive interval from +0๐ฝ to 999๐ฝ. It returns the millisecond of the second in which t falls. It performs the following steps when called:
Time zones in ECMAScript are represented by time zone identifiers, which are Strings composed entirely of code units in the inclusive interval from 0x0000 to 0x007F.
Time zones supported by an ECMAScript implementation may be available named time zones, represented by the [[Identifier]] field of the Time Zone Identifier Records returned by AvailableNamedTimeZoneIdentifiers, or offset time zones, represented by Strings for which IsTimeZoneOffsetString returns true.
A primary time zone identifier is the preferred identifier for an available named time zone.
A non-primary time zone identifier is an identifier for an available named time zone that is not a primary time zone identifier.
An available named time zone identifier is either a primary time zone identifier or a non-primary time zone identifier.
Each available named time zone identifier is associated with exactly one available named time zone.
Each available named time zone is associated with exactly one primary time zone identifier and zero or more non-primary time zone identifiers.
ECMAScript implementations must support an available named time zone with the identifier "UTC", which must be the primary time zone identifier for the UTC time zone.
In addition, implementations may support any number of other available named time zones.
Implementations that follow the requirements for time zones as described in the ECMA-402 Internationalization API specification are called time zone aware.
Time zone aware implementations must support available named time zones corresponding to the Zone and Link names of the IANA Time Zone Database, and only such names.
In time zone aware implementations, a primary time zone identifier is a Zone name, and a non-primary time zone identifier is a Link name, respectively, in the IANA Time Zone Database except as specifically overridden by AvailableNamedTimeZoneIdentifiers as specified in the ECMA-402 specification.
Implementations that do not support the entire IANA Time Zone Database are still recommended to use IANA Time Zone Database names as identifiers to represent time zones.
When the input represents a local time occurring more than once because of a negative time zone transition (e.g. when daylight saving time ends or the time zone offset is decreased due to a time zone rule change), the returned List will have more than one element and will be sorted by ascending numerical value.
When the input represents a local time skipped because of a positive time zone transition (e.g. when daylight saving time begins or the time zone offset is increased due to a time zone rule change), the returned List will be empty.
Otherwise, the returned List will have one element.
The default implementation of GetNamedTimeZoneEpochNanoseconds, to be used for ECMAScript implementations that do not include local political rules for any time zones, performs the following steps when called:
1:30 AM on 5 November 2017 in America/New_York is repeated twice, so GetNamedTimeZoneEpochNanoseconds("America/New_York", 2017, 11, 5, 1, 30, 0, 0, 0, 0) would return a List of length 2 in which the first element represents 05:30 UTC (corresponding with 01:30 US Eastern Daylight Time at UTC offset -04:00) and the second element represents 06:30 UTC (corresponding with 01:30 US Eastern Standard Time at UTC offset -05:00).
2:30 AM on 12 March 2017 in America/New_York does not exist, so GetNamedTimeZoneEpochNanoseconds("America/New_York", 2017, 3, 12, 2, 30, 0, 0, 0, 0) would return an empty List.
The implementation-defined abstract operation GetNamedTimeZoneOffsetNanoseconds takes arguments timeZoneIdentifier (a String) and epochNanoseconds (a BigInt) and returns an integer.
The returned integer represents the offset from UTC of the named time zone identified by timeZoneIdentifier, at the instant corresponding with epochNanoseconds relative to the epoch, both in nanoseconds.
The default implementation of GetNamedTimeZoneOffsetNanoseconds, to be used for ECMAScript implementations that do not include local political rules for any time zones, performs the following steps when called:
Time zone aware implementations, including all implementations that implement the ECMA-402 Internationalization API, must implement the AvailableNamedTimeZoneIdentifiers abstract operation as specified in the ECMA-402 specification.
For implementations that are not time zone aware, AvailableNamedTimeZoneIdentifiers performs the following steps when called:
If the implementation does not include local political rules for any time zones, then
The implementation-defined abstract operation SystemTimeZoneIdentifier takes no arguments and returns a String.
It returns a String representing the host environment's current time zone, which is either a String representing a UTC offset for which IsTimeZoneOffsetString returns true, or a primary time zone identifier.
It performs the following steps when called:
If the implementation only supports the UTC time zone, return "UTC".
To ensure the level of functionality that implementations commonly provide in the methods of the Date object, it is recommended that SystemTimeZoneIdentifier return an IANA time zone name corresponding to the host environment's time zone setting, if such a thing exists.
GetNamedTimeZoneEpochNanoseconds and GetNamedTimeZoneOffsetNanoseconds must reflect the local political rules for standard time and daylight saving time in that time zone, if such rules exist.
For example, if the host environment is a browser on a system where the user has chosen US Eastern Time as their time zone, SystemTimeZoneIdentifier returns "America/New_York".
21.4.1.25 LocalTime ( t )
The abstract operation LocalTime takes argument t (a finitetime value) and returns an integral Number.
It converts t from UTC to local time.
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.
It performs the following steps when called:
Two different input time valuestUTC 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.26 UTC ( t )
The abstract operation UTC takes argument t (a Number) and returns a time value.
It converts t from local time to a UTC time value.
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.
It performs the following steps when called:
NOTE: The following steps ensure that when t 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 transition (e.g. when the daylight saving time starts or the time zone offset is increased due to a time zone rule change), t is interpreted using the time zone offset before the transition.
If possibleInstants is not empty, then
Let disambiguatedInstant be possibleInstants[0].
Else,
NOTE: t represents a local time skipped at a positive time zone transition (e.g. due to daylight saving time starting or a time zone rule change increasing the UTC offset).
Input t is nominally a time value but may be any Number value.
The algorithm must not limit t to the time value range, so that inputs corresponding with a boundary of the time value range can be supported regardless of local UTC offset.
For example, the maximum time value is 8.64 ร 1015, corresponding with "+275760-09-13T00:00:00Z".
In an environment where the local time zone offset is ahead of UTC by 1 hour at that instant, it is represented by the larger input of 8.64 ร 1015 + 3.6 ร 106, corresponding with "+275760-09-13T01:00:00+01:00".
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.
In UTC(TimeClip(MakeDate(MakeDay(2017, 10, 5), MakeTime(1, 30, 0, 0)))), the value of offsetMs 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).
In UTC(TimeClip(MakeDate(MakeDay(2017, 2, 12), MakeTime(2, 30, 0, 0)))), the value of offsetMs is -5 ร msPerHour.
Note 2
UTC(LocalTime(tUTC)) is not necessarily always equal to tUTC. Correspondingly, LocalTime(UTC(tlocal)) is not necessarily always equal to tlocal.
21.4.1.27 MakeTime ( hour, min, sec, ms )
The abstract operation MakeTime takes arguments hour (a Number), min (a Number), sec (a Number), and ms (a Number) and returns a Number. It calculates a number of milliseconds. It performs the following steps when called:
The arithmetic in MakeTime is floating-point arithmetic, which is not associative, so the operations must be performed in the correct order.
21.4.1.28 MakeDay ( year, month, date )
The abstract operation MakeDay takes arguments year (a Number), month (a Number), and date (a Number) and returns a Number. It calculates a number of days. It performs the following steps when called:
If year is not finite, month is not finite, or date is not finite, return NaN.
The abstract operation MakeDate takes arguments day (a Number) and time (a Number) and returns a Number. It calculates a number of milliseconds. It performs the following steps when called:
If day is not finite or time is not finite, return NaN.
The abstract operation MakeFullYear takes argument year (a Number) and returns an integral Number or NaN. It returns the full year associated with the integer part of year, interpreting any value in the inclusive interval from 0 to 99 as a count of years since the start of 1900. For alignment with the proleptic Gregorian calendar, "full year" is defined as the signed count of complete years since the start of year 0 (1 B.C.). It performs the following steps when called:
The abstract operation TimeClip takes argument time (a Number) and returns a Number. It calculates a number of milliseconds. It performs the following steps when called:
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 as either "+" or "-" followed by a time expression HH:mm (a subset of the time zone offset string format for 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.32.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 must be prefixed with a + sign. The representation of the year 0 as -000000 is invalid. 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.1.33 Time Zone Offset String Format
ECMAScript defines a string interchange format for UTC offsets, derived from ISO 8601.
The format is described by the following grammar.
The usage of Unicode code points in this grammar is listed in Table 61.
The abstract operation IsTimeZoneOffsetString takes argument offsetString (a String) and returns a Boolean. The return value indicates whether offsetString conforms to the grammar given by UTCOffset. It performs the following steps when called:
The abstract operation ParseTimeZoneOffsetString takes argument offsetString (a String) and returns an integer. The return value is the UTC offset, as a number of nanoseconds, that corresponds to the String offsetString. It performs the following steps when called:
If parsedSign is the single code point U+002D (HYPHEN-MINUS) or U+2212 (MINUS SIGN), then
Let sign be -1.
Else,
Let sign be 1.
NOTE: Applications of StringToNumber below do not lose precision, since each of the parsed values is guaranteed to be a sufficiently short string of decimal digits.
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.
21.4.2.1 Date ( ...values )
This function performs the following steps when called:
If NewTarget is undefined, then
Let now be the time value (UTC) identifying the current time.
This function returns the time value designating the UTC date and time of the occurrence of the call to it.
21.4.3.2 Date.parse ( string )
This function applies the ToString operator to its argument. If ToString results in an abrupt completion the Completion Record is immediately returned. Otherwise, this function 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.32), 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 this function 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:
is not required to produce the same Number value as the preceding three expressions and, in general, the value produced by this function is implementation-defined when given any String value that does not conform to the Date Time String Format (21.4.1.32) and that could not be produced in that implementation by the toString or toUTCString method.
This 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.
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.
21.4.4.1 Date.prototype.constructor
The initial value of Date.prototype.constructor is %Date%.
21.4.4.2 Date.prototype.getDate ( )
This method performs the following steps when called:
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 ] ] ] )
This method performs the following steps when called:
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 )
This method performs the following steps when called:
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 ] )
This method performs the following steps when called:
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 ] ] ] )
This method performs the following steps when called:
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 )
This method performs the following steps when called:
If sec is not present, this method 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 return by getUTCMilliseconds().
21.4.4.33 Date.prototype.setUTCMonth ( month [ , date ] )
This method performs the following steps when called:
If tv corresponds with a year that cannot be represented in the Date Time String Format, throw a RangeError exception.
Return a String representation of tv in the Date Time String 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 method provides a String representation of a Date for use by JSON.stringify (25.5.2).
This method 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.
An ECMAScript implementation that includes the ECMA-402 Internationalization API must implement this method as specified in the ECMA-402 specification. If an ECMAScript implementation does not include the ECMA-402 API the following specification of this method is used:
This method 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.
An ECMAScript implementation that includes the ECMA-402 Internationalization API must implement this method as specified in the ECMA-402 specification. If an ECMAScript implementation does not include the ECMA-402 API the following specification of this method is used:
This method 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.
An ECMAScript implementation that includes the ECMA-402 Internationalization API must implement this method as specified in the ECMA-402 specification. If an ECMAScript implementation does not include the ECMA-402 API the following specification of this method is used:
This method 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 ( )
This method performs the following steps when called:
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
This method 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) and returns a String. It performs the following steps when called:
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 62: Names of days of the week
Number
Name
+0๐ฝ
"Sun"
1๐ฝ
"Mon"
2๐ฝ
"Tue"
3๐ฝ
"Wed"
4๐ฝ
"Thu"
5๐ฝ
"Fri"
6๐ฝ
"Sat"
Table 63: 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 (an integral Number) and returns a String. It performs the following steps when called:
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).
Return the string-concatenation of offsetSign, offsetHour, offsetMin, and tzName.
21.4.4.41.4 ToDateString ( tv )
The abstract operation ToDateString takes argument tv (an integral Number or NaN) and returns a String. It performs the following steps when called:
This method returns a String value representing the instant in time corresponding to the this 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.
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 ( )
This method performs the following steps when called:
21.4.4.45 Date.prototype [ @@toPrimitive ] ( hint )
This method 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".
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.
The value of the "name" property of this method is "[Symbol.toPrimitive]".
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.