Skip to content

Create option timezone as Proposed REQUIRED option #950

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Nov 20, 2024
Merged

Create option timezone as Proposed REQUIRED option #950

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
d386fa9
Create option `timezone` as Proposed REQUIRED option
aphillips Nov 19, 2024
3b03e17
Update spec/registry.md
aphillips Nov 19, 2024
ad3e2c9
Update spec/registry.md
aphillips Nov 19, 2024
63270de
Address comments about ABNF etc.
aphillips Nov 19, 2024
a532a56
Merge branch 'main' into aphillips-timezone
aphillips Nov 19, 2024
5bb9d1f
Address "proposed"
aphillips Nov 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 22 additions & 3 deletions spec/registry.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1103,6 +1103,10 @@ override values set by the current locale,
or provided by the _formatting context_ (such as the default time zone),
or embedded in an implementation-defined date/time _operand_ value.

> [!NOTE]
> These _options_ do not have default values because they are only to be used
> as overrides for locale-and-value dependent implementation-defined defaults.

The following _option_ and its values are REQUIRED to be available on
the functions `:datetime` and `:time`:

Expand All @@ -1118,7 +1122,22 @@ the functions `:datetime`, `:date`, and `:time`.
- `numberingSystem`
- valid [Unicode Number System Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html#UnicodeNumberSystemIdentifier)

The following _option_ and its values are **Proposed** for
inclusion in the next release of this specification but have not yet been
finalized.
If accepted, implementations could be REQUIRED to make this _option_
available in the functions `:datetime`, `:date`, and `:time`.
Comment on lines +1125 to +1129
Copy link
Collaborator

@eemeli eemeli Nov 20, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With this clarification, I'm fine with merging the currently proposed text as it does not impose any restrictions or requirements on implementations, effectively kicking the can down the road.


- `timeZone`
- A valid time zone identifier
(see [TZDB](https://www.iana.org/time-zones)
and [LDML](https://www.unicode.org/reports/tr35/tr35-dates.html#Time_Zone_Names)
for information on identifiers)
Comment on lines +1132 to +1135
Copy link
Collaborator

@eemeli eemeli Nov 19, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like this. It's sufficiently vague to be revisable later into something more explicit, while being sufficiently specific to be unlikely to lead to abuse.

- `local`
- `UTC`
Copy link
Collaborator

@eemeli eemeli Nov 19, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think UTC needs to be called out specifically, as it's included in the LDML definition.

Suggested change
- `UTC`

Copy link
Member Author

@aphillips aphillips Nov 20, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I call it out for the reason JS calls it out: technically it is not a valid value and is added by exception. UTC is also special, in that it is generally the pivot for other zones as well as the zone that applies to most canonical incremental time values (Date objects in many languages and platforms is in terms of millis or nanos from the UNIX epoch in UTC).

By listing it here, we require that all implementations accept that specific literal. All of the other literals are up to the implementation and its capabilities.


> [!NOTE]
> These _options_ do not have default values because they are only to be used
> as overrides for locale-and-value dependent implementation-defined defaults.

> The value `local` permits a _message_ to convert a date/time value
> into a [floating](https://www.w3.org/TR/timezone/#floating) time value
> (sometimes called a _plain_ or _local_ time value) by removing
> the association with a specific time zone.
Comment on lines +1140 to +1143
Copy link
Collaborator

@eemeli eemeli Nov 19, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find this very confusing. From the name, my presumption would be that "local" means the formatter's local system time, but that's a time with an explicit timezone, while this note is indicating that it ought to mean a datetime not associated with any timezone.

With something like a literal date as operand, I presume that these would give the same results, but if the operand is an implementation-defined datetime with a timezone different from the local system time, it's not at all clear what date might get formatted.

I would find it very useful to have an example provided for a use case where timeZone=local would be required to get desirable behaviour, as opposed to just leaving out the option entirely.

Also, just for clarity, are there any use cases for floating datetimes that include anything more precise than a day being formatted?

Copy link
Member Author

@aphillips aphillips Nov 19, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't care for the name local, but both HTML and Java Temporal use it. JS Temporal elected an (equally bad, from my perspective) name plain for this concept. It does not mean the local system time zone. It is a very different thing. I gritted my teeth to write local here, because I wanted to choose the term most likely to be familiar to average developers. If it were just me, I'd write float or maybe none.

With something like a literal date as operand, I presume that these would give the same results, but if the operand is an implementation-defined datetime with a timezone different from the local system time, it's not at all clear what date might get formatted.

Literals are tricky too. They get parsed into internal date/time objects. If the literal includes an offset or zone ID, then the internal type will be attached to the timeline and have an offset or zone.

"Classical" time values (Date in JS, Date in Java, Instant in Java Temporal) are common representations internally. These representations lose their attachment to a specific wall time. So {|2024-11-19T00:00:00.000+10:00| :datetime} is actually 2024-11-18T14:00.000Z. This then formats to some time zone (in my case, America/Los_Angeles) with yet another set of digits.

The point of timeZone=local is to remove the offset/zone ID. Then the digits you see are the digits you get, regardless of where you run the formatter. In the example case, 2 PM on November 18th. It also explicitly gives instructions to the formatter not to attach the value to the timeline.

Also, just for clarity, are there any use cases for floating datetimes that include anything more precise than a day being formatted?

Yes, all the time. Airline schedules, for example, show departure/arrival times in the local time of the airport in question. You compute the time and then float it so the digits stay the same. Of if you have a value that you want to stick to a specific time zone, it's easier to float the value than to send the time zone down the wire:

Your package will be delivered on {$delivery :date} by {$delivery :time}

If you send 2024-11-19T22:00:00-08:00[America/Los_Angeles] down the wire, the receiver might be a JSON library that returns a Date--an incremental time that displays as (perhaps) 2024-11-20T08:00:00+02:00[Europe/Helsinki], which is not the desired result if one wants to see what time to tell the housekeeper to check for the package if I'm visiting you.

If instead I just send 2024-11-19T22:00:00 down the wire, the result might still be unfloated and display something weird (like the time zone name).