Skip to content

Commit

Permalink
Editorial: Better relate ECMAScript time values to POSIX and UTC (#1325)
Browse files Browse the repository at this point in the history
 - Be more precise about UTC alignment discontinuities
 - Define time values as linear sums rather than pure counts
 - Make the distinction between finite and NaN time values more explicit
 - Clarify that every time value is a Number
 - Explicitly describe the relationship between time values and leap seconds
 - Confine time value interpretation to the same day as its referent
 - Improve grammar
  • Loading branch information
gibson042 authored and ljharb committed Oct 4, 2019
1 parent 1e00ac2 commit a91a674
Showing 1 changed file with 5 additions and 6 deletions.
11 changes: 5 additions & 6 deletions spec.html
Original file line number Diff line number Diff line change
Expand Up @@ -27999,14 +27999,13 @@ <h1>Overview of Date Objects and Definitions of Abstract Operations</h1>

<emu-clause id="sec-time-values-and-time-range">
<h1>Time Values and Time Range</h1>
<p>A Date object contains a Number representing an instant in time with millisecond precision. Such a Number is called a <dfn>time value</dfn>. A time value may also be *NaN*, indicating that the Date object does not represent a specific instant in time.</p>
<p>Time is measured in ECMAScript as milliseconds since midnight at the beginning of 01 January, 1970 UTC. Time in ECMAScript does not observe leap seconds; they are ignored. Time calculations assume each and every day contains exactly <emu-eqn>60 &times; 60 &times; 24 &times; 1000 = 86,400,000</emu-eqn> milliseconds, to align with the POSIX specification of each and every day containing exactly 86,400 seconds.</p>
<p>A Number can exactly represent all integers from -9,007,199,254,740,992 to 9,007,199,254,740,992 (<emu-xref href="#sec-number.min_safe_integer"></emu-xref> and <emu-xref href="#sec-number.max_safe_integer"></emu-xref>). A time value supports a slightly smaller range of exactly -100,000,000 days to 100,000,000 days measured relative to midnight at the beginning of 01 January, 1970 UTC. This yields an exact supported time value range of -8,640,000,000,000,000 to 8,640,000,000,000,000 milliseconds relative to midnight at the beginning of 01 January, 1970 UTC.</p>
<p>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 01 January, 1970 UTC, and an accounting of every day as comprising exactly 86,400 seconds (each of which is 1000 milliseconds long).</p>
<p>An ECMAScript <dfn>time value</dfn> is a Number, either a finite integer representing an instant in time to millisecond precision or *NaN* representing no specific instant. A time value that is a multiple of <emu-eqn>24 &times; 60 &times; 60 &times; 1000 = 86,400,000</emu-eqn> (i.e., is equal to 86,400,000 &times; _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 _t_ &minus; _s_ milliseconds.</p>
<p>Time values do not account for UTC leap seconds&mdash;there are no time values representing instants within positive leap seconds, but 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, discontinuities only at leap second boundaries, and zero difference outside of leap seconds.</p>
<p>A Number can exactly represent all integers from -9,007,199,254,740,992 to 9,007,199,254,740,992 (<emu-xref href="#sec-number.min_safe_integer"></emu-xref> and <emu-xref href="#sec-number.max_safe_integer"></emu-xref>). 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 01 January, 1970 UTC.</p>
<p>The exact moment of midnight at the beginning of 01 January, 1970 UTC is represented by the time value *+0*.</p>
<emu-note>
<p>The 400 year cycle of the Gregorian calendar contains 97 leap years. This yields an average of 365.2425 days per year, or an average of 31,556,952,000 milliseconds per year under the Gregorian calendar. ECMAScript applies a proleptic Gregorian calendar for all time computations.</p>
<p>As specified by this section, the maximum year range a Number can represent exactly with millisecond precision is approximately -285,426 to 285,426 years relative to midnight at the beginning of 01 January, 1970 UTC.</p>
<p>As specified by this section, the maximum year range a time value can represent is approximately -273,790 to 273,790 years relative to midnight at the beginning of 01 January, 1970 UTC.</p>
<p>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.</p>
</emu-note>
</emu-clause>

Expand Down

0 comments on commit a91a674

Please sign in to comment.