From 78e0b17655161efc03c3fd721fb09beca685903f Mon Sep 17 00:00:00 2001 From: Philip Chimento Date: Thu, 25 Aug 2022 11:55:01 -0700 Subject: [PATCH] Normative: Add timeZoneName: "critical" option to ZonedDateTime.toString() This adds a new recognized value "critical" to the timeZoneName option of ZonedDateTime.prototype.toString(). timeZoneName: "critical" behaves like timeZoneName: "always", but it also outputs a "!" flag in the time zone annotation. This flag is never used by Temporal, but could be consumed by other programs. See: #1450 --- docs/zoneddatetime.md | 5 +++-- polyfill/lib/ecmascript.mjs | 7 +++++-- spec/abstractops.html | 2 +- spec/zoneddatetime.html | 5 +++-- 4 files changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/zoneddatetime.md b/docs/zoneddatetime.md index 5744c02499..04ee8f89ab 100644 --- a/docs/zoneddatetime.md +++ b/docs/zoneddatetime.md @@ -1245,7 +1245,7 @@ zdt1.equals(zdt1); // => true Valid values are `'auto'` and `'never'`. The default is `'auto'`. - `timeZoneName` (string): Whether to show the time zone name annotation in the return value. - Valid values are `'auto'` and `'never'`. + Valid values are `'auto'`, `'never'`, and `'critical'`. The default is `'auto'`. - `calendarName` (string): Whether to show the calendar annotation in the return value. Valid values are `'auto'`, `'always'`, `'never'`, and `'critical'`. @@ -1284,8 +1284,9 @@ For more information on the calendar annotation, see [ISO string extensions](./s Likewise, passing `'never'` to the `timeZoneName` or `offset` options controls whether the time zone offset (`+01:00`) or name annotation (`[Europe/Paris]`) are shown. If the time zone offset is shown, it is always shown rounded to the nearest minute. +The `timeZoneName` option can additionally be `'critical'` which will add an additional `!` to the annotation, similar to `calendarName`. -The string format output by this method can be parsed by [`java.time.ZonedDateTime`](https://docs.oracle.com/javase/8/docs/api/java/time/ZonedDateTime.html) as long as the calendar annotation is not output. +The string format output by this method can be parsed by [`java.time.ZonedDateTime`](https://docs.oracle.com/javase/8/docs/api/java/time/ZonedDateTime.html) as long as the calendar annotation is not output and `'critical'` is not used. For more information on `Temporal`'s extensions to the ISO 8601 / RFC 3339 string format and the progress towards becoming a published standard, see [String Parsing, Serialization, and Formatting](./strings.md). Example usage: diff --git a/polyfill/lib/ecmascript.mjs b/polyfill/lib/ecmascript.mjs index eba28fac11..216f591b40 100644 --- a/polyfill/lib/ecmascript.mjs +++ b/polyfill/lib/ecmascript.mjs @@ -722,7 +722,7 @@ export const ES = ObjectAssign({}, ES2020, { return ES.GetOption(options, 'calendarName', ['auto', 'always', 'never', 'critical'], 'auto'); }, ToShowTimeZoneNameOption: (options) => { - return ES.GetOption(options, 'timeZoneName', ['auto', 'never'], 'auto'); + return ES.GetOption(options, 'timeZoneName', ['auto', 'never', 'critical'], 'auto'); }, ToShowOffsetOption: (options) => { return ES.GetOption(options, 'offset', ['auto', 'never'], 'auto'); @@ -2146,7 +2146,10 @@ export const ES = ObjectAssign({}, ES2020, { const offsetNs = ES.GetOffsetNanosecondsFor(tz, instant); result += ES.FormatISOTimeZoneOffsetString(offsetNs); } - if (showTimeZone !== 'never') result += `[${tz}]`; + if (showTimeZone !== 'never') { + const flag = showTimeZone === 'critical' ? '!' : ''; + result += `[${flag}${tz}]`; + } result += ES.MaybeFormatCalendarAnnotation(GetSlot(zdt, CALENDAR), showCalendar); return result; }, diff --git a/spec/abstractops.html b/spec/abstractops.html index 938ecbce5f..7a60bdd4bb 100644 --- a/spec/abstractops.html +++ b/spec/abstractops.html @@ -162,7 +162,7 @@

ToShowTimeZoneNameOption ( _normalizedOptions_ )

It is different from the `timeZone` property passed to `Temporal.ZonedDateTime.from()` and from the `timeZone` property in the options passed to `Temporal.Instant.prototype.toString()`. - 1. Return ? GetOption(_normalizedOptions_, *"timeZoneName"*, *"string"*, « *"auto"*, *"never"* », *"auto"*). + 1. Return ? GetOption(_normalizedOptions_, *"timeZoneName"*, *"string"*, « *"auto"*, *"never"*, *"critical"* », *"auto"*). diff --git a/spec/zoneddatetime.html b/spec/zoneddatetime.html index b3fa2fd0e3..c149b653c8 100644 --- a/spec/zoneddatetime.html +++ b/spec/zoneddatetime.html @@ -1163,7 +1163,7 @@

_zonedDateTime_: a Temporal.ZonedDateTime, _precision_: one of *"auto"*, *"minute"*, or an integer between 0 and 9 inclusive, _showCalendar_: one of *"auto"*, *"always"*, *"never"*, or *"critical"*, - _showTimeZone_: one of *"auto"* or *"never"*, + _showTimeZone_: one of *"auto"*, *"never"*, or *"critical"*, _showOffset_: one of *"auto"* or *"never"*, optional _increment_: an integer, optional _unit_: one of *"minute"*, *"second"*, *"millisecond"*, *"microsecond"*, or *"nanosecond"*, @@ -1195,7 +1195,8 @@

1. Let _timeZoneString_ be the empty String. 1. Else, 1. Let _timeZoneID_ be ? ToString(_timeZone_). - 1. Let _timeZoneString_ be the string-concatenation of the code unit 0x005B (LEFT SQUARE BRACKET), _timeZoneID_, and the code unit 0x005D (RIGHT SQUARE BRACKET). + 1. If _showTimeZone_ is *"critical"*, let _flag_ be *"!"*; else let _flag_ be the empty String. + 1. Let _timeZoneString_ be the string-concatenation of the code unit 0x005B (LEFT SQUARE BRACKET), _flag_, _timeZoneID_, and the code unit 0x005D (RIGHT SQUARE BRACKET). 1. Let _calendarString_ be ? MaybeFormatCalendarAnnotation(_zonedDateTime_.[[Calendar]], _showCalendar_). 1. Return the string-concatenation of _dateTimeString_, _offsetString_, _timeZoneString_, and _calendarString_.