From ba3d9b4f5a99260fa03ac4ada5fb50f989886bd9 Mon Sep 17 00:00:00 2001 From: Richard Gibson Date: Mon, 30 Sep 2024 17:15:47 -0400 Subject: [PATCH 1/3] Editorial: Recommend "remapping" for dates exceeding era year bounds Fixes #2865 --- polyfill/lib/calendar.mjs | 3 --- spec/calendar.html | 7 +++++++ 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/polyfill/lib/calendar.mjs b/polyfill/lib/calendar.mjs index 0b5eeeca7..6b0fe9d56 100644 --- a/polyfill/lib/calendar.mjs +++ b/polyfill/lib/calendar.mjs @@ -1461,9 +1461,6 @@ const makeHelperGregorian = (id, originalEras) => { ({ code, names = [] }) => code === era || ES.Call(ArrayPrototypeIncludes, names, [era]) ]); if (!matchingEra) throw new RangeErrorCtor(`Era ${era} (ISO year ${eraYear}) was not matched by any era`); - if (eraYear < 1 && matchingEra.reverseOf) { - throw new RangeErrorCtor(`Years in ${era} era must be positive, not ${year}`); - } if (matchingEra.reverseOf) { year = matchingEra.anchorEpoch.year - eraYear; } else { diff --git a/spec/calendar.html b/spec/calendar.html index d8553c504..b7ee66cc2 100644 --- a/spec/calendar.html +++ b/spec/calendar.html @@ -1348,6 +1348,13 @@

In some cases, verifying the internal consistency of fields requires accessing the data from other fields, such checking _fields_.[[MonthCode]] *"M06"* against _fields_.[[Month]] 7 in the Hebrew calendar (which are consistent if and only if _fields_ identifies a year that includes leap month Adar I). + +

When the fields of _fields_ are inconsistent with respect to a non-~unset~ _fields_.[[Era]], it is recommended that _fields_.[[Era]] and _fields_.[[EraYear]] be updated to resolve the inconsistency by appropriate interpretation of out-of-bounds values (rather than throwing a *RangeError*), which is particularly useful for consistent interpretation of dates in calendars with regnal eras.

+
    +
  • In the Gregorian calendar, a non-positive [[EraYear]] should be replaced with a positive [[EraYear]] corresponding with extension of the era into its complement and [[Era]] should be updating accordingly (such that Common Era [[EraYear]] 0 is updated to Before Common Era [[EraYear]] 1, Before Common Era [[EraYear]] -1 is updated to Common Era [[EraYear]] 2, etc.).
    • +
  • In the Japanese calendar, when _fields_.[[Era]] is not ~unset~ and the date represented by _fields_ is not within the bounds of that era, _fields_.[[Era]] should be updated to the appropriate containing era for that date (for example, because the transition from Heisei era [[EraYear]] 31 to Reiwa era [[EraYear]] 1 took place on May 1 of [[Year]] 2019, Heisei era [[EraYear]] 32 should be updated to Reiwa era [[EraYear]] 2, Reiwa era [[EraYear]] 1 [[Month]] 1 should be updated to Heisei era [[EraYear]] 31 [[Month 1]], etc.).
    • +
+ When _type_ is ~month-day~ and _fields_.[[Month]] is not ~unset~, it is recommended that all built-in calendars other than the ISO 8601 calendar require a disambiguating year (e.g., either _fields_.[[Year]] or _fields_.[[Era]] and _fields_.[[EraYear]]), regardless of whether or not _fields_.[[MonthCode]] is also ~unset~. The ISO 8601 calendar allows _fields_.[[Year]] to be ~unset~ in this case because it is a special default calendar that is permanently stable for automated processing. From 5d87b9fb8e6e3bb33d8922305531927d96a54924 Mon Sep 17 00:00:00 2001 From: Richard Gibson Date: Mon, 30 Sep 2024 17:17:11 -0400 Subject: [PATCH 2/3] Docs: Mention "remapping" for dates exceeding era year Ref #2865 --- docs/plaindate.md | 4 ++-- docs/plaindatetime.md | 4 ++-- docs/plainyearmonth.md | 4 ++-- docs/zoneddatetime.md | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/plaindate.md b/docs/plaindate.md index 6185dba01..09854b97c 100644 --- a/docs/plaindate.md +++ b/docs/plaindate.md @@ -81,8 +81,8 @@ If the string isn't valid according to ISO 8601, then a `RangeError` will be thr The `overflow` option works as follows, if `item` is an object: -- In `constrain` mode (the default), any out-of-range values are clamped to the nearest in-range value. -- In `reject` mode, the presence of out-of-range values will cause the function to throw a `RangeError`. +- In `constrain` mode (the default), any out-of-range values are clamped to the nearest in-range value (after assuming extension of eras over arbitrary years to substitute `era` and `eraYear` with appropriate values for the `item`). +- In `reject` mode, the presence of out-of-range values (after assuming extension of eras over arbitrary years to substitute `era` and `eraYear` with appropriate values for the `item`) will cause the function to throw a `RangeError`. The `overflow` option is ignored if `item` is a string. diff --git a/docs/plaindatetime.md b/docs/plaindatetime.md index d3f4b180e..24b9ba4fa 100644 --- a/docs/plaindatetime.md +++ b/docs/plaindatetime.md @@ -112,8 +112,8 @@ If the string isn't valid according to ISO 8601, then a `RangeError` will be thr The `overflow` option works as follows, if `item` is an object: -- In `constrain` mode (the default), any out-of-range values are clamped to the nearest in-range value. -- In `reject` mode, the presence of out-of-range values will cause the function to throw a `RangeError`. +- In `constrain` mode (the default), any out-of-range values are clamped to the nearest in-range value (after assuming extension of eras over arbitrary years to substitute `era` and `eraYear` with appropriate values for the `item`). +- In `reject` mode, the presence of out-of-range values (after assuming extension of eras over arbitrary years to substitute `era` and `eraYear` with appropriate values for the `item`) will cause the function to throw a `RangeError`. The `overflow` option is ignored if `item` is a string. diff --git a/docs/plainyearmonth.md b/docs/plainyearmonth.md index 493005e86..521f26e39 100644 --- a/docs/plainyearmonth.md +++ b/docs/plainyearmonth.md @@ -83,8 +83,8 @@ A `RangeError` will also be thrown for strings that contain a `Z` in place of a The `overflow` option works as follows, if `item` is an object: -- In `constrain` mode (the default), any out-of-range values are clamped to the nearest in-range value. -- In `reject` mode, the presence of out-of-range values will cause the function to throw a `RangeError`. +- In `constrain` mode (the default), any out-of-range values are clamped to the nearest in-range value (after assuming extension of eras over arbitrary years to substitute `era` and `eraYear` with appropriate values for the `item`). +- In `reject` mode, the presence of out-of-range values (after assuming extension of eras over arbitrary years to substitute `era` and `eraYear` with appropriate values for the `item`) will cause the function to throw a `RangeError`. The `overflow` option is ignored if `item` is a string. diff --git a/docs/zoneddatetime.md b/docs/zoneddatetime.md index 8f98a8892..166109814 100644 --- a/docs/zoneddatetime.md +++ b/docs/zoneddatetime.md @@ -175,8 +175,8 @@ Instead of using `Temporal.ZonedDateTime` with an offset time zone, it may be ea The `overflow` option works as follows, if `item` is an object: -- In `'constrain'` mode (the default), any out-of-range values are clamped to the nearest in-range value. -- In `'reject'` mode, the presence of out-of-range values will cause the function to throw a `RangeError`. +- In `'constrain'` mode (the default), any out-of-range values are clamped to the nearest in-range value (after assuming extension of eras over arbitrary years to substitute `era` and `eraYear` with appropriate values for the `item`). +- In `'reject'` mode, the presence of out-of-range values (after assuming extension of eras over arbitrary years to substitute `era` and `eraYear` with appropriate values for the `item`) will cause the function to throw a `RangeError`. The `overflow` option is ignored if `item` is a string. From 0740c3b08a60dd67772869c00fcbe6b7a641e1c8 Mon Sep 17 00:00:00 2001 From: Richard Gibson Date: Wed, 2 Oct 2024 00:32:46 -0400 Subject: [PATCH 3/3] Editorial: Fix typo Co-authored-by: Philip Chimento --- spec/calendar.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/calendar.html b/spec/calendar.html index b7ee66cc2..d7b88c9e6 100644 --- a/spec/calendar.html +++ b/spec/calendar.html @@ -1352,7 +1352,7 @@

When the fields of _fields_ are inconsistent with respect to a non-~unset~ _fields_.[[Era]], it is recommended that _fields_.[[Era]] and _fields_.[[EraYear]] be updated to resolve the inconsistency by appropriate interpretation of out-of-bounds values (rather than throwing a *RangeError*), which is particularly useful for consistent interpretation of dates in calendars with regnal eras.

  • In the Gregorian calendar, a non-positive [[EraYear]] should be replaced with a positive [[EraYear]] corresponding with extension of the era into its complement and [[Era]] should be updating accordingly (such that Common Era [[EraYear]] 0 is updated to Before Common Era [[EraYear]] 1, Before Common Era [[EraYear]] -1 is updated to Common Era [[EraYear]] 2, etc.).
    • -
  • In the Japanese calendar, when _fields_.[[Era]] is not ~unset~ and the date represented by _fields_ is not within the bounds of that era, _fields_.[[Era]] should be updated to the appropriate containing era for that date (for example, because the transition from Heisei era [[EraYear]] 31 to Reiwa era [[EraYear]] 1 took place on May 1 of [[Year]] 2019, Heisei era [[EraYear]] 32 should be updated to Reiwa era [[EraYear]] 2, Reiwa era [[EraYear]] 1 [[Month]] 1 should be updated to Heisei era [[EraYear]] 31 [[Month 1]], etc.).
    • +
  • In the Japanese calendar, when _fields_.[[Era]] is not ~unset~ and the date represented by _fields_ is not within the bounds of that era, _fields_.[[Era]] should be updated to the appropriate containing era for that date (for example, because the transition from Heisei era [[EraYear]] 31 to Reiwa era [[EraYear]] 1 took place on May 1 of [[Year]] 2019, Heisei era [[EraYear]] 32 should be updated to Reiwa era [[EraYear]] 2, Reiwa era [[EraYear]] 1 [[Month]] 1 should be updated to Heisei era [[EraYear]] 31 [[Month]] 1, etc.).