Skip to content

Commit

Permalink
Editorial: Return types for AOs that return date-time records
Browse files Browse the repository at this point in the history 
Introduces structured headers with return types for several PlainDateTime
abstract operations. This will make it easier to see what types are
changing when we introduce normalized time duration records.
  • Loading branch information
@ptomato
ptomato committed Aug 10, 2023
1 parent d93c8e4 commit 14154e9
Show file tree
Hide file tree
Showing 3 changed files with 125 additions and 22 deletions.
143 changes: 123 additions & 20 deletions spec/plaindatetime.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -530,7 +530,7 @@ <h1>Temporal.PlainDateTime.prototype.round ( _roundTo_ )</h1>
1. Assert: _maximum_ is not *undefined*.
1. Let _inclusive_ be *false*.
1. Perform ? ValidateTemporalRoundingIncrement(_roundingIncrement_, _maximum_, _inclusive_).
1. Let _result_ be ! RoundISODateTime(_dateTime_.[[ISOYear]], _dateTime_.[[ISOMonth]], _dateTime_.[[ISODay]], _dateTime_.[[ISOHour]], _dateTime_.[[ISOMinute]], _dateTime_.[[ISOSecond]], _dateTime_.[[ISOMillisecond]], _dateTime_.[[ISOMicrosecond]], _dateTime_.[[ISONanosecond]], _roundingIncrement_, _smallestUnit_, _roundingMode_).
1. Let _result_ be RoundISODateTime(_dateTime_.[[ISOYear]], _dateTime_.[[ISOMonth]], _dateTime_.[[ISODay]], _dateTime_.[[ISOHour]], _dateTime_.[[ISOMinute]], _dateTime_.[[ISOSecond]], _dateTime_.[[ISOMillisecond]], _dateTime_.[[ISOMicrosecond]], _dateTime_.[[ISONanosecond]], _roundingIncrement_, _smallestUnit_, _roundingMode_).
1. Return ? CreateTemporalDateTime(_result_.[[Year]], _result_.[[Month]], _result_.[[Day]], _result_.[[Hour]], _result_.[[Minute]], _result_.[[Second]], _result_.[[Millisecond]], _result_.[[Microsecond]], _result_.[[Nanosecond]], _dateTime_.[[Calendar]]).
</emu-alg>
</emu-clause>
Expand Down Expand Up @@ -566,7 +566,7 @@ <h1>Temporal.PlainDateTime.prototype.toString ( [ _options_ ] )</h1>
1. Let _smallestUnit_ be ? GetTemporalUnit(_options_, *"smallestUnit"*, ~time~, *undefined*).
1. If _smallestUnit_ is *"hour"*, throw a *RangeError* exception.
1. Let _precision_ be ToSecondsStringPrecisionRecord(_smallestUnit_, _digits_).
1. Let _result_ be ! RoundISODateTime(_dateTime_.[[ISOYear]], _dateTime_.[[ISOMonth]], _dateTime_.[[ISODay]], _dateTime_.[[ISOHour]], _dateTime_.[[ISOMinute]], _dateTime_.[[ISOSecond]], _dateTime_.[[ISOMillisecond]], _dateTime_.[[ISOMicrosecond]], _dateTime_.[[ISONanosecond]], _precision_.[[Increment]], _precision_.[[Unit]], _roundingMode_).
1. Let _result_ be RoundISODateTime(_dateTime_.[[ISOYear]], _dateTime_.[[ISOMonth]], _dateTime_.[[ISODay]], _dateTime_.[[ISOHour]], _dateTime_.[[ISOMinute]], _dateTime_.[[ISOSecond]], _dateTime_.[[ISOMillisecond]], _dateTime_.[[ISOMicrosecond]], _dateTime_.[[ISONanosecond]], _precision_.[[Increment]], _precision_.[[Unit]], _roundingMode_).
1. Return ? TemporalDateTimeToString(_result_.[[Year]], _result_.[[Month]], _result_.[[Day]], _result_.[[Hour]], _result_.[[Minute]], _result_.[[Second]], _result_.[[Millisecond]], _result_.[[Microsecond]], _result_.[[Nanosecond]], _dateTime_.[[Calendar]], _precision_.[[Precision]], _showCalendar_).
</emu-alg>
</emu-clause>
Expand Down Expand Up @@ -833,6 +833,78 @@ <h1>Properties of Temporal.PlainDateTime Instances</h1>
<emu-clause id="sec-temporal-plaindatetime-abstract-ops">
<h1>Abstract operations</h1>

<emu-clause id="sec-temporal-iso-date-time-records">
<h1>ISO Date-Time Records</h1>
<p>
An <dfn variants="ISO Date-Time Records">ISO Date-Time Record</dfn> is a Record value used to represent a valid calendar date in the ISO 8601 calendar together with a clock time.
For any ISO Date-Time Record _r_, IsValidISODate(_r_.[[Year]], _r_.[[Month]], _r_.[[Day]]) must return *true*, and IsValidTime(_r_.[[Hour]], _r_.[[Minute]], _r_.[[Second]], _r_.[[Millisecond]], _r_.[[Microsecond]], _r_.[[Nanosecond]]) must return *true*.
It is not necessary for ISODateTimeWithinLimits(_r_.[[Year]], _r_.[[Month]], _r_.[[Day]], _r_.[[Hour]], _r_.[[Minute]], _r_.[[Second]], _r_.[[Millisecond]], _r_.[[Microsecond]], _r_.[[Nanosecond]]) to return *true*.
</p>
<p>
ISO Date-Time Records have the fields listed in <emu-xref href="#table-temporal-iso-date-time-record-fields"></emu-xref>.
</p>
<emu-table id="table-temporal-iso-date-time-record-fields" caption="ISO Date-Time Record Fields">
<table class="real-table">
<tr>
<th>Field Name</th>
<th>Value</th>
<th>Meaning</th>
</tr>
<tr>
<td>[[Year]]</td>
<td>an integer</td>
<td>
The year in the ISO 8601 calendar.
</td>
</tr>
<tr>
<td>[[Month]]</td>
<td>an integer between 1 and 12, inclusive</td>
<td>
The number of the month in the ISO 8601 calendar.
</td>
</tr>
<tr>
<td>[[Day]]</td>
<td>an integer between 1 and 31, inclusive</td>
<td>
The number of the day of the month in the ISO 8601 calendar.
</td>
</tr>
<tr>
<td>[[Hour]]</td>
<td>an integer in the inclusive range 0 to 23</td>
<td>The number of the hour.</td>
</tr>
<tr>
<td>[[Minute]]</td>
<td>an integer in the inclusive range 0 to 59</td>
<td>The number of the minute.</td>
</tr>
<tr>
<td>[[Second]]</td>
<td>an integer in the inclusive range 0 to 59</td>
<td>The number of the second.</td>
</tr>
<tr>
<td>[[Millisecond]]</td>
<td>an integer in the inclusive range 0 to 999</td>
<td>The number of the millisecond.</td>
</tr>
<tr>
<td>[[Microsecond]]</td>
<td>an integer in the inclusive range 0 to 999</td>
<td>The number of the microsecond.</td>
</tr>
<tr>
<td>[[Nanosecond]]</td>
<td>an integer in the inclusive range 0 to 999</td>
<td>The number of the nanosecond.</td>
</tr>
</table>
</emu-table>
</emu-clause>

<emu-clause id="sec-temporal-isodatetimewithinlimits" type="abstract operation">
<h1>
ISODateTimeWithinLimits (
Expand Down Expand Up @@ -928,10 +1000,25 @@ <h1>ToTemporalDateTime ( _item_ [ , _options_ ] )</h1>
</emu-alg>
</emu-clause>

<emu-clause id="sec-temporal-balanceisodatetime" aoid="BalanceISODateTime">
<h1>BalanceISODateTime ( _year_, _month_, _day_, _hour_, _minute_, _second_, _millisecond_, _microsecond_, _nanosecond_ )</h1>
<emu-clause id="sec-temporal-balanceisodatetime" type="abstract operation">
<h1>
BalanceISODateTime (
_year_: an integer,
_month_: an integer,
_day_: an integer,
_hour_: an integer,
_minute_: an integer,
_second_: an integer,
_millisecond_: an integer,
_microsecond_: an integer,
_nanosecond_: an integer,
): an ISO Date-Time Record
</h1>
<dl class="header">
<dt>description</dt>
<dd></dd>
</dl>
<emu-alg>
1. Assert: _year_, _month_, _day_, _hour_, _minute_, _second_, _millisecond_, _microsecond_, and _nanosecond_ are integers.
1. Let _balancedTime_ be BalanceTime(_hour_, _minute_, _second_, _millisecond_, _microsecond_, _nanosecond_).
1. Let _balancedDate_ be BalanceISODate(_year_, _month_, _day_ + _balancedTime_.[[Days]]).
1. Return the Record {
Expand Down Expand Up @@ -1018,14 +1105,14 @@ <h1>CompareISODateTime ( _y1_, _mon1_, _d1_, _h1_, _min1_, _s1_, _ms1_, _mus1_,
<h1>
AddDateTime (
_year_: an integer,
_month_: an integer,
_day_: an integer,
_hour_: an integer,
_minute_: an integer,
_second_: an integer,
_millisecond_: an integer,
_microsecond_: an integer,
_nanosecond_: an integer,
_month_: an integer in the inclusive interval from 1 to 12,
_day_: an integer in the inclusive interval from 1 to 31,
_hour_: an integer in the inclusive interval from 0 to 23,
_minute_: an integer in the inclusive interval from 0 to 59,
_second_: an integer in the inclusive interval from 0 to 59,
_millisecond_: an integer in the inclusive interval from 0 to 999,
_microsecond_: an integer in the inclusive interval from 0 to 999,
_nanosecond_: an integer in the inclusive interval from 0 to 999,
_calendar_: an Object,
_years_: an integer,
_months_: an integer,
Expand All @@ -1038,7 +1125,7 @@ <h1>
_microseconds_: an integer,
_nanoseconds_: an integer,
_options_: an Object or *undefined*,
)
): either a normal completion containing an ISO Date-Time Record, or a throw completion
</h1>
<dl class="header">
<dt>description</dt>
Expand Down Expand Up @@ -1066,13 +1153,29 @@ <h1>
</emu-alg>
</emu-clause>

<emu-clause id="sec-temporal-roundisodatetime" aoid="RoundISODateTime">
<h1>RoundISODateTime ( _year_, _month_, _day_, _hour_, _minute_, _second_, _millisecond_, _microsecond_, _nanosecond_, _increment_, _unit_, _roundingMode_ [ , _dayLength_ ] )</h1>
<p>
The abstract operation RoundISODateTime rounds the time part of a combined date and time, carrying over any excess into the date part.
</p>
<emu-clause id="sec-temporal-roundisodatetime" type="abstract operation">
<h1>
RoundISODateTime (
_year_: an integer,
_month_: an integer in the inclusive interval from 1 to 12,
_day_: an integer in the inclusive interval from 1 to 31,
_hour_: an integer in the inclusive interval from 0 to 23,
_minute_: an integer in the inclusive interval from 0 to 59,
_second_: an integer in the inclusive interval from 0 to 59,
_millisecond_: an integer in the inclusive interval from 0 to 999,
_microsecond_: an integer in the inclusive interval from 0 to 999,
_nanosecond_: an integer in the inclusive interval from 0 to 999,
_increment_: an integer,
_unit_: *"day"*, *"hour"*, *"minute"*, *"second"*, *"millisecond"*, *"microsecond"*, or *"nanosecond"*,
_roundingMode_: *"ceil"*, *"floor"*, *"expand"*, *"trunc"*, *"halfCeil"*, *"halfFloor"*, *"halfExpand"*, *"halfTrunc"*, or *"halfEven"*,
optional _dayLength_: an integer,
): an ISO Date-Time Record
</h1>
<dl class="header">
<dt>description</dt>
<dd>It rounds the time part of a combined date and time, carrying over any excess into the date part.</dd>
</dl>
<emu-alg>
1. Assert: _year_, _month_, _day_, _hour_, _minute_, _second_, _millisecond_, _microsecond_, and _nanosecond_ are integers.
1. Assert: ISODateTimeWithinLimits(_year_, _month_, _day_, _hour_, _minute_, _second_, _millisecond_, _microsecond_, _nanosecond_) is *true*.
1. If _dayLength_ is not present, set _dayLength_ to nsPerDay.
1. Let _roundedTime_ be RoundTime(_hour_, _minute_, _second_, _millisecond_, _microsecond_, _nanosecond_, _increment_, _unit_, _roundingMode_, _dayLength_).
Expand Down
2 changes: 1 addition & 1 deletion spec/timezone.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -692,7 +692,7 @@ <h1>
<emu-alg>
1. Let _offsetNanoseconds_ be ? GetOffsetNanosecondsFor(_timeZone_, _instant_).
1. Let _result_ be ! GetISOPartsFromEpoch(ℝ(_instant_.[[Nanoseconds]])).
1. Set _result_ to ! BalanceISODateTime(_result_.[[Year]], _result_.[[Month]], _result_.[[Day]], _result_.[[Hour]], _result_.[[Minute]], _result_.[[Second]], _result_.[[Millisecond]], _result_.[[Microsecond]], _result_.[[Nanosecond]] + _offsetNanoseconds_).
1. Set _result_ to BalanceISODateTime(_result_.[[Year]], _result_.[[Month]], _result_.[[Day]], _result_.[[Hour]], _result_.[[Minute]], _result_.[[Second]], _result_.[[Millisecond]], _result_.[[Microsecond]], _result_.[[Nanosecond]] + _offsetNanoseconds_).
1. Return ? CreateTemporalDateTime(_result_.[[Year]], _result_.[[Month]], _result_.[[Day]], _result_.[[Hour]], _result_.[[Minute]], _result_.[[Second]], _result_.[[Millisecond]], _result_.[[Microsecond]], _result_.[[Nanosecond]], _calendar_).
</emu-alg>
</emu-clause>
Expand Down
2 changes: 1 addition & 1 deletion spec/zoneddatetime.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -759,7 +759,7 @@ <h1>Temporal.ZonedDateTime.prototype.round ( _roundTo_ )</h1>
1. Let _dayLengthNs_ be ℝ(_endNs_ - _startNs_).
1. If _dayLengthNs_ &le; 0, then
1. Throw a *RangeError* exception.
1. Let _roundResult_ be ! RoundISODateTime(_temporalDateTime_.[[ISOYear]], _temporalDateTime_.[[ISOMonth]], _temporalDateTime_.[[ISODay]], _temporalDateTime_.[[ISOHour]], _temporalDateTime_.[[ISOMinute]], _temporalDateTime_.[[ISOSecond]], _temporalDateTime_.[[ISOMillisecond]], _temporalDateTime_.[[ISOMicrosecond]], _temporalDateTime_.[[ISONanosecond]], _roundingIncrement_, _smallestUnit_, _roundingMode_, _dayLengthNs_).
1. Let _roundResult_ be RoundISODateTime(_temporalDateTime_.[[ISOYear]], _temporalDateTime_.[[ISOMonth]], _temporalDateTime_.[[ISODay]], _temporalDateTime_.[[ISOHour]], _temporalDateTime_.[[ISOMinute]], _temporalDateTime_.[[ISOSecond]], _temporalDateTime_.[[ISOMillisecond]], _temporalDateTime_.[[ISOMicrosecond]], _temporalDateTime_.[[ISONanosecond]], _roundingIncrement_, _smallestUnit_, _roundingMode_, _dayLengthNs_).
1. Let _offsetNanoseconds_ be ? GetOffsetNanosecondsFor(_timeZone_, _instant_).
1. Let _epochNanoseconds_ be ? InterpretISODateTimeOffset(_roundResult_.[[Year]], _roundResult_.[[Month]], _roundResult_.[[Day]], _roundResult_.[[Hour]], _roundResult_.[[Minute]], _roundResult_.[[Second]], _roundResult_.[[Millisecond]], _roundResult_.[[Microsecond]], _roundResult_.[[Nanosecond]], ~option~, _offsetNanoseconds_, _timeZone_, *"compatible"*, *"prefer"*, ~match exactly~).
1. Return ! CreateTemporalZonedDateTime(_epochNanoseconds_, _timeZone_, _calendar_).
Expand Down

0 comments on commit 14154e9

Please sign in to comment.