Editorial: Convert operations with numeric arguments to structured he…

…aders There were a few remaining abstract operations that operate on numeric types, that didn't have those types spelled out either via structured headers or via assertions. This converts those operations to use structured headers. That also allows ecmarkup to point out places where a ! notation was used superfluously. This revealed that the return type of RoundTemporalInstant wasn't correct: it should have been a BigInt, since it returns a number of epoch nanoseconds. Closes: #1413
tc39 · Jan 10, 2023 · c60af4b · c60af4b
1 parent 4664de5
commit c60af4b
Show file tree

Hide file tree

Showing 3 changed files with 51 additions and 27 deletions.
diff --git a/spec/duration.html b/spec/duration.html
@@ -1530,7 +1530,7 @@ <h1>
         1. Let _intermediateNs_ be ? AddZonedDateTime(_relativeTo_.[[Nanoseconds]], _timeZone_, _calendar_, _y1_, _mon1_, _w1_, _d1_, _h1_, _min1_, _s1_, _ms1_, _mus1_, _ns1_).
         1. Let _endNs_ be ? AddZonedDateTime(_intermediateNs_, _timeZone_, _calendar_, _y2_, _mon2_, _w2_, _d2_, _h2_, _min2_, _s2_, _ms2_, _mus2_, _ns2_).
         1. If _largestUnit_ is not one of *"year"*, *"month"*, *"week"*, or *"day"*, then
-          1. Let _result_ be ! DifferenceInstant(_relativeTo_.[[Nanoseconds]], _endNs_, 1, *"nanosecond"*, _largestUnit_, *"halfExpand"*).
+          1. Let _result_ be DifferenceInstant(_relativeTo_.[[Nanoseconds]], _endNs_, 1, *"nanosecond"*, _largestUnit_, *"halfExpand"*).
           1. Return ! CreateDurationRecord(0, 0, 0, 0, _result_.[[Hours]], _result_.[[Minutes]], _result_.[[Seconds]], _result_.[[Milliseconds]], _result_.[[Microseconds]], _result_.[[Nanoseconds]]).
         1. Return ? DifferenceZonedDateTime(_relativeTo_.[[Nanoseconds]], _endNs_, _timeZone_, _calendar_, _largestUnit_, OrdinaryObjectCreate(*null*)).
       </emu-alg>
@@ -1803,7 +1803,7 @@ <h1>
         1. Let _dayLengthNs_ be ℝ(_dayEnd_ - _dayStart_).
         1. If (_timeRemainderNs_ - _dayLengthNs_) &times; _direction_ &lt; 0, then
           1. Return ! CreateDurationRecord(_years_, _months_, _weeks_, _days_, _hours_, _minutes_, _seconds_, _milliseconds_, _microseconds_, _nanoseconds_).
-        1. Set _timeRemainderNs_ to ! RoundTemporalInstant(ℤ(_timeRemainderNs_ - _dayLengthNs_), _increment_, _unit_, _roundingMode_).
+        1. Set _timeRemainderNs_ to ℝ(RoundTemporalInstant(ℤ(_timeRemainderNs_ - _dayLengthNs_), _increment_, _unit_, _roundingMode_)).
         1. Let _adjustedDateDuration_ be ? AddDuration(_years_, _months_, _weeks_, _days_, 0, 0, 0, 0, 0, 0, 0, 0, 0, _direction_, 0, 0, 0, 0, 0, 0, _relativeTo_).
         1. Let _adjustedTimeDuration_ be ? <emu-meta suppress-effects="user-code">BalanceDuration(0, 0, 0, 0, 0, 0, _timeRemainderNs_, *"hour"*)</emu-meta>.
         1. Return ! CreateDurationRecord(_adjustedDateDuration_.[[Years]], _adjustedDateDuration_.[[Months]], _adjustedDateDuration_.[[Weeks]], _adjustedDateDuration_.[[Days]], _adjustedTimeDuration_.[[Hours]], _adjustedTimeDuration_.[[Minutes]], _adjustedTimeDuration_.[[Seconds]], _adjustedTimeDuration_.[[Milliseconds]], _adjustedTimeDuration_.[[Microseconds]], _adjustedTimeDuration_.[[Nanoseconds]]).

diff --git a/spec/instant.html b/spec/instant.html
@@ -122,7 +122,7 @@ <h1>Temporal.Instant.compare ( _one_, _two_ )</h1>
       <emu-alg>
         1. Set _one_ to ? ToTemporalInstant(_one_).
         1. Set _two_ to ? ToTemporalInstant(_two_).
-        1. Return 𝔽(! CompareEpochNanoseconds(_one_.[[Nanoseconds]], _two_.[[Nanoseconds]])).
+        1. Return 𝔽(CompareEpochNanoseconds(_one_.[[Nanoseconds]], _two_.[[Nanoseconds]])).
       </emu-alg>
     </emu-clause>
   </emu-clause>
@@ -293,7 +293,7 @@ <h1>Temporal.Instant.prototype.round ( _roundTo_ )</h1>
           1. Assert: _smallestUnit_ is *"nanosecond"*.
           1. Let _maximum_ be nsPerDay.
         1. Perform ? ValidateTemporalRoundingIncrement(_roundingIncrement_, _maximum_, *true*).
-        1. Let _roundedNs_ be ! RoundTemporalInstant(_instant_.[[Nanoseconds]], _roundingIncrement_, _smallestUnit_, _roundingMode_).
+        1. Let _roundedNs_ be RoundTemporalInstant(_instant_.[[Nanoseconds]], _roundingIncrement_, _smallestUnit_, _roundingMode_).
         1. Return ! CreateTemporalInstant(_roundedNs_).
       </emu-alg>
     </emu-clause>
@@ -330,7 +330,7 @@ <h1>Temporal.Instant.prototype.toString ( [ _options_ ] )</h1>
         1. If _timeZone_ is not *undefined*, then
           1. Set _timeZone_ to ? ToTemporalTimeZone(_timeZone_).
         1. Let _precision_ be ToSecondsStringPrecisionRecord(_smallestUnit_, _digits_).
-        1. Let _roundedNs_ be ! RoundTemporalInstant(_instant_.[[Nanoseconds]], _precision_.[[Increment]], _precision_.[[Unit]], _roundingMode_).
+        1. Let _roundedNs_ be RoundTemporalInstant(_instant_.[[Nanoseconds]], _precision_.[[Increment]], _precision_.[[Unit]], _roundingMode_).
         1. Let _roundedInstant_ be ! CreateTemporalInstant(_roundedNs_).
         1. Return ? TemporalInstantToString(_roundedInstant_, _timeZone_, _precision_.[[Precision]]).
       </emu-alg>
@@ -534,8 +534,17 @@ <h1>ParseTemporalInstant ( _isoString_ )</h1>
       </emu-alg>
     </emu-clause>
 
-    <emu-clause id="sec-temporal-compareepochnanoseconds" aoid="CompareEpochNanoseconds">
-      <h1>CompareEpochNanoseconds ( _epochNanosecondsOne_, _epochNanosecondsTwo_ )</h1>
+    <emu-clause id="sec-temporal-compareepochnanoseconds" type="abstract operation">
+      <h1>
+        CompareEpochNanoseconds (
+          _epochNanosecondsOne_: a BigInt,
+          _epochNanosecondsTwo_: a BigInt,
+        ): either -1, 0, or 1
+      </h1>
+      <dl class="header">
+        <dt>description</dt>
+        <dd></dd>
+      </dl>
       <emu-alg>
         1. If _epochNanosecondsOne_ &gt; _epochNanosecondsTwo_, return 1.
         1. If _epochNanosecondsOne_ &lt; _epochNanosecondsTwo_, return -1.
@@ -571,28 +580,43 @@ <h1>
       </emu-alg>
     </emu-clause>
 
-    <emu-clause id="sec-temporal-differenceinstant" aoid="DifferenceInstant">
-      <h1>DifferenceInstant ( _ns1_, _ns2_, _roundingIncrement_, _smallestUnit_, _largestUnit_, _roundingMode_ )</h1>
-      <p>
-        The abstract operation DifferenceInstant computes the difference between two exact times expressed in nanoseconds since the Unix epoch, and rounds the result according to the given parameters.
-      </p>
+    <emu-clause id="sec-temporal-differenceinstant" type="abstract operation">
+      <h1>
+        DifferenceInstant (
+          _ns1_: a BigInt,
+          _ns2_: a BigInt,
+          _roundingIncrement_: a positive integer,
+          _smallestUnit_: a String,
+          _largestUnit_: a String,
+          _roundingMode_: a String,
+        ): a Time Duration Record
+      </h1>
+      <dl class="header">
+        <dt>description</dt>
+        <dd>It computes the difference between two exact times _ns1_ and _ns2_ expressed in nanoseconds since the epoch, and rounds the result according to the parameters _roundingIncrement_, _smallestUnit_, _largestUnit_, and _roundingMode_.</dd>
+      </dl>
       <emu-alg>
-        1. Assert: Type(_ns1_) is BigInt.
-        1. Assert: Type(_ns2_) is BigInt.
-        1. Assert: The following step cannot fail due to overflow in the Number domain because abs(_ns2_ - _ns1_) &le; 2 &times; nsMaxInstant.
-        1. Let _roundResult_ be ! RoundDuration(0, 0, 0, 0, 0, 0, 0, 0, 0, _ns2_ - _ns1_, _roundingIncrement_, _smallestUnit_, _roundingMode_).[[DurationRecord]].
+        1. Assert: The following step cannot fail due to overflow in the Number domain because abs(ℝ(_ns2_) - ℝ(_ns1_)) &le; 2 &times; nsMaxInstant.
+        1. Let _roundResult_ be ! RoundDuration(0, 0, 0, 0, 0, 0, 0, 0, 0, ℝ(_ns2_) - ℝ(_ns1_), _roundingIncrement_, _smallestUnit_, _roundingMode_).[[DurationRecord]].
         1. Assert: _roundResult_.[[Days]] is 0.
         1. Return ! BalanceDuration(0, _roundResult_.[[Hours]], _roundResult_.[[Minutes]], _roundResult_.[[Seconds]], _roundResult_.[[Milliseconds]], _roundResult_.[[Microseconds]], _roundResult_.[[Nanoseconds]], _largestUnit_).
       </emu-alg>
     </emu-clause>
 
-    <emu-clause id="sec-temporal-roundtemporalinstant" aoid="RoundTemporalInstant">
-      <h1>RoundTemporalInstant ( _ns_, _increment_, _unit_, _roundingMode_ )</h1>
-      <p>
-        The abstract operation RoundTemporalInstant rounds a number of nanoseconds since the Unix epoch to the given rounding increment.
-      </p>
+    <emu-clause id="sec-temporal-roundtemporalinstant" type="abstract operation">
+      <h1>
+        RoundTemporalInstant (
+          _ns_: a BigInt,
+          _increment_: a positive integer,
+          _unit_: a String,
+          _roundingMode_: a String,
+        ): a BigInt
+      </h1>
+      <dl class="header">
+        <dt>description</dt>
+        <dd>It rounds a number of nanoseconds _ns_ since the epoch to the given rounding increment.</dd>
+      </dl>
       <emu-alg>
-        1. Assert: Type(_ns_) is BigInt.
         1. If _unit_ is *"hour"*, then
           1. Let _incrementNs_ be _increment_ &times; 3.6 &times; 10<sup>12</sup>.
         1. Else if _unit_ is *"minute"*, then
@@ -606,7 +630,7 @@ <h1>RoundTemporalInstant ( _ns_, _increment_, _unit_, _roundingMode_ )</h1>
         1. Else,
           1. Assert: _unit_ is *"nanosecond"*.
           1. Let _incrementNs_ be _increment_.
-        1. Return RoundNumberToIncrementAsIfPositive(ℝ(_ns_), _incrementNs_, _roundingMode_).
+        1. Return ℤ(RoundNumberToIncrementAsIfPositive(ℝ(_ns_), _incrementNs_, _roundingMode_)).
       </emu-alg>
     </emu-clause>
 
@@ -646,7 +670,7 @@ <h1>
         1. If _operation_ is ~since~, let _sign_ be -1. Otherwise, let _sign_ be 1.
         1. Set _other_ to ? ToTemporalInstant(_other_).
         1. Let _settings_ be ? GetDifferenceSettings(_operation_, _options_, ~time~, &laquo; &raquo;, *"nanosecond"*, *"second"*).
-        1. Let _result_ be ! DifferenceInstant(_instant_.[[Nanoseconds]], _other_.[[Nanoseconds]], _settings_.[[RoundingIncrement]], _settings_.[[SmallestUnit]], _settings_.[[LargestUnit]], _settings_.[[RoundingMode]]).
+        1. Let _result_ be DifferenceInstant(_instant_.[[Nanoseconds]], _other_.[[Nanoseconds]], _settings_.[[RoundingIncrement]], _settings_.[[SmallestUnit]], _settings_.[[LargestUnit]], _settings_.[[RoundingMode]]).
         1. Return ! CreateTemporalDuration(0, 0, 0, 0, _sign_ &times; _result_.[[Hours]], _sign_ &times; _result_.[[Minutes]], _sign_ &times; _result_.[[Seconds]], _sign_ &times; _result_.[[Milliseconds]], _sign_ &times; _result_.[[Microseconds]], _sign_ &times; _result_.[[Nanoseconds]]).
       </emu-alg>
     </emu-clause>

diff --git a/spec/zoneddatetime.html b/spec/zoneddatetime.html
@@ -78,7 +78,7 @@ <h1>Temporal.ZonedDateTime.compare ( _one_, _two_ )</h1>
       <emu-alg>
         1. Set _one_ to ? ToTemporalZonedDateTime(_one_).
         1. Set _two_ to ? ToTemporalZonedDateTime(_two_).
-        1. Return 𝔽(! CompareEpochNanoseconds(_one_.[[Nanoseconds]], _two_.[[Nanoseconds]])).
+        1. Return 𝔽(CompareEpochNanoseconds(_one_.[[Nanoseconds]], _two_.[[Nanoseconds]])).
       </emu-alg>
     </emu-clause>
   </emu-clause>
@@ -1217,7 +1217,7 @@ <h1>
         1. If _increment_ is not present, set _increment_ to 1.
         1. If _unit_ is not present, set _unit_ to *"nanosecond"*.
         1. If _roundingMode_ is not present, set _roundingMode_ to *"trunc"*.
-        1. Let _ns_ be ! RoundTemporalInstant(_zonedDateTime_.[[Nanoseconds]], _increment_, _unit_, _roundingMode_).
+        1. Let _ns_ be RoundTemporalInstant(_zonedDateTime_.[[Nanoseconds]], _increment_, _unit_, _roundingMode_).
         1. Let _timeZone_ be _zonedDateTime_.[[TimeZone]].
         1. Let _instant_ be ! CreateTemporalInstant(_ns_).
         1. Let _isoCalendar_ be ! GetISO8601Calendar().
@@ -1398,7 +1398,7 @@ <h1>
           1. Throw a *RangeError* exception.
         1. Let _settings_ be ? GetDifferenceSettings(_operation_, _options_, ~datetime~, &laquo; &raquo;, *"nanosecond"*, *"hour"*).
         1. If _settings_.[[LargestUnit]] is not one of *"year"*, *"month"*, *"week"*, or *"day"*, then
-          1. Let _result_ be ! DifferenceInstant(_zonedDateTime_.[[Nanoseconds]], _other_.[[Nanoseconds]], _settings_.[[RoundingIncrement]], _settings_.[[SmallestUnit]], _settings_.[[LargestUnit]], _settings_.[[RoundingMode]]).
+          1. Let _result_ be DifferenceInstant(_zonedDateTime_.[[Nanoseconds]], _other_.[[Nanoseconds]], _settings_.[[RoundingIncrement]], _settings_.[[SmallestUnit]], _settings_.[[LargestUnit]], _settings_.[[RoundingMode]]).
           1. Return ! CreateTemporalDuration(0, 0, 0, 0, _sign_ &times; _result_.[[Hours]], _sign_ &times; _result_.[[Minutes]], _sign_ &times; _result_.[[Seconds]], _sign_ &times; _result_.[[Milliseconds]], _sign_ &times; _result_.[[Microseconds]], _sign_ &times; _result_.[[Nanoseconds]]).
         1. If ? TimeZoneEquals(_zonedDateTime_.[[TimeZone]], _other_.[[TimeZone]]) is *false*, then
           1. Throw a *RangeError* exception.