Skip to content

Commit

Permalink
Editorial: Synchronise Intl updates with latest ECMA-402
Browse files Browse the repository at this point in the history
General changes:
- Synchronise with latest ECMA-402 draft, including changes from tc39/ecma402#901.
- Change `CreateDateTimeFormat` to always store the hour-cycle in
  `dateTimeFormat.[[HourCycle]]`, so later formatting operations can select the
  correct pattern string. Update `Intl.DateTimeFormat.prototype.resolvedOptions`
  to only output "hourCycle" and "hour12" when `[[DateTimeFormat]]` actually
  has an `[[hour]]` field. This is needed to match the existing behaviour.
- Change `Value Format Records` to prefer upper-case fields and replace
  `[[pattern]]` and `[[rangePatterns]]` with `[[Format]]` which holds a
  `DateTime Format Record`.
- Correctly specify `CreateTemporalDateTime` as infallible in
  `HandleDateTimeTemporal{Date,MonthDay,Time}`. `CreateTemporalDateTime` in
  `HandleDateTimeTemporalYearMonth` is fallible, because the ISO reference day
  can make it an out-of-range date-time value.
- Remove unreachable case for a `null` format record in
  `HandleDateTimeTemporal{DateTime,Instant}`.
- Correct value conversion in `HandleDateTimeOthers`, because `ℤ` can't be applied
  on a Number value.
- Update `Temporal.ZonedDateTime.prototype.toLocaleString` to accept offset
  time zones, now that upstream ECMA-402 supports offset time zones.
- Add standalone "month" as a required format to the `[[formats]]` list. This change
  is needed to correctly process `Temporal.PlainYearMonth` and `Temporal.PlainMonthDay`,
  because right now only "year+month" and "month+day" are required formats. When the
  user requests a standalone "month", `BasicFormatMatcher` will compute the same
  penalty for "year+month" and "month+day", so both formats have the same preference.
  This will then result in either incorrectly using "year+month" with
  `Temporal.PlainMonthDay` or using "month+day" with `Temporal.PlainYearMonth`.
  This incorrect case can't apply when standalone "month" is a required format.
- It's not possible to request that all options are supported in a standalone
  context, because for example "year" with "en-u-ca-islamic" will currently also
  add "era" to the output string in implementations.

Notes:
- `FormatDateTimePattern` is now an infallible operation, but adding "ins" / "del"
  marker tags doesn't seem to work in structured types definitions.

---

Updated date-time format selection:

Case 1: `dateStyle` or `timeStyle` is present.

When one of the style options is present, then the previous condition

> If bestFormat does not have any fields that are in Supported Fields, [...]

is equivalent to testing which of `dateStyle` or `timeStyle` is `undefined`,
because for example when `dateStyle` isn't `undefined`, then "year", "month",
and "day" are guaranteed to be present. That also means only a single call to
`DateTimeStyleFormat` is needed to compute the correct format for all types.

Case 2: `dateStyle` or `timeStyle` are both absent.

Add the new abstract operation `GetDateTimeFormat` which implements the same
formatting options processing which is currently inlined in `CreateDateTimeFormat`.

The logic is now as follows:
- If at least one option from `requiredOptions` is present, then use the user inputs.
- Otherwise use the default options from the `defaultOptions` list.
- `requiredOptions` and `defaultOptions` have different entries based on the
  `required` and `defaults` arguments.
- The `inherit` parameter selects which user options in addition to the members
  of `requiredOptions` are copied over:
  - When `inherit=all`, then all user inputs are copied over, even if they are
    unexpected in the context given by `required` and `defaults`. This is needed
    for backwards compatibility with the current ECMA-402 spec. For example
    `new Date().toLocaleTimeString("en", {era: "long"})` currently returns
    `"Anno Domini, 7:46:53 AM"` in all engines, which means the "era" option is
    used even though the formatting context is a local-time string.
  - When `inherit=relevant`, only relevant additional options are copied over. These
    are options which are relevant, but can't be elements of `requiredOptions`:
    - "era" can't occur in a standalone context, there it's not a member of the
      `requiredOptions` list.
    - "hourCycle" is needed for the pattern selection, see tc39/ecma402#571.
  - The `inherit=relevant` case only applies to `Temporal.PlainX` types to ignore
    unsupported options. For example
    `new Intl.DateTimeFormat("en", {day: "numeric"}).format(new Temporal.PlainTime())`
    should return the string `"12:00:00 AM"` and don't display any "day" parts.
  - `Temporal.Instant` and `Temporal.ZonedDateTime` support all date-time options,
    so no additional filtering is needed for them.
- In addition to "era", the "timeZoneName" option also can't occur in a standalone
  context, therefore it's also not an element of the `requiredOptions` list.

The default options processing in GetDateTimeFormat matches the previous
Temporal draft, but it's not clear at this point if this implements previous
concensus, because it means the unsupported format case can only apply when
`dateStyle` or `timeStyle` are used. IOW `new Intl.DateTimeFormat("en", {day: "numeric"})`
works with all `Temporal` types, including `Temporal.PlainTime`, whereas
`new Intl.DateTimeFormat("en", {dateStyle: "short"})` throws when used with
`Temporal.PlainTime`.
  • Loading branch information
anba committed Jun 24, 2024
1 parent 2a8b26f commit 763acd2
Showing 1 changed file with 327 additions and 313 deletions.
Loading

0 comments on commit 763acd2

Please sign in to comment.