Add full support for `r` datetime symbol #7327

robertbastian · 2025-12-18T15:27:23Z

Currently we only support the r symbol for cyclic calendars, however nothing in the LDML says that it is only usable with cyclic calendars. This adds support for all other calendars.

Manishearth · 2025-12-18T18:20:50Z

components/calendar/src/types.rs

+    ///
+    /// Lunar calendars, like [`Hijri`](crate::cal::Hijri), drift quickly through the Gregorian year, so related Gregorian
+    /// years are frequently repeated.
+    pub fn related_gregorian(self) -> i32 {


given that it's allowed to be negative (no eras), this should be ISO year, yes? or gregorian extended year.

I agree that hte "ISO calendar" isn't the most consistent concept, but "ISO year" is much more well defined

CLDR calls it "related Gregorian" year

ISO is a format, Gregorian is a calendar. I will die on this hill

If that's what CLDR calls it fair enough.

Gregorian does not have signed years.

It has extended years; you could call it related_extended_gregorian but I don't think anyone wants that.

Plus, we already call it related_iso for cyclic years. You're the king of consistency.

I'm happy to deprecate any mentions of related_iso

ISO is a format

ISO-8601 defines a calendar system, not just a format.

it defines a string format for the proleptic Gregorian calendar

sffc

It's in CLDR, but it seems to have footguns. We shouldn't add new things that have known footguns.

sffc · 2025-12-18T22:02:02Z

components/calendar/src/types.rs

        }
    }

+    /// The Gregorian year in which this year started.


Observation: This produces surprising results for calendars with new years in the second half of the year, like Hebrew, Ethiopian, Coptic. It also means that multiple Hijri years will have the same related ISO year.

this is how CLDR defines this https://www.unicode.org/reports/tr35/tr35-dates.html#Contents:~:text=this%20corresponds%20to%20the%20extended%20Gregorian%20year%20in%20which%20the%20calendar%E2%80%99s%20year%20begins

Yeah, and I consider it a footgun. It is there because of Chinese, and it has a definition for other calendars, but that doesn't mean it should be used by those other calendars.

For Hebrew, I did some research with help from Gemini and found that there are a number of sources that use the later of the two years since it has more overlap (5786 <-> 2026, not 2025). For example:

https://web.library.yale.edu/cataloging/hebraica/about-hebrew-calendar

However, most sources write it as "2025-2026"

https://www.judaicaplace.com/jewish-year-calendar-5786-2025-2026-spiralbound/767278911413/

So in that sense, maybe r should print 2025-2026.

do you want to take that up with CLDR? this PR moves towards parity with ICU and implements the spec

It's long been a principle that we don't implement spec that we know is garbage.

Sometimes we accidentally implement spec that we didn't know was garbage and it's almost always been a pain point.

Question: is there data in CLDR that is impacted by this? As in, are there Hebrew formatting patterns that use this? (I can go searching, but I suspect that answer to already be known). That impacts how much our choices matter here. If there is no such data we can start by documenting this as "The related ISO year, this is currently the ISO year in which this calendar year started, but we may tweak this definition later" and then pursue proper resolution in CLDR.

Also, what I see here is that if the spec is garbage, it's not necessarily garbage in a "simple" way, it's garbage in an architecturally-relevant way that we may not be able to quickly work around. A good design here would probably allow the symbols {r}, {r +1}, and {r - 1}, so Chinese calendars could use {r} and Hebrew calendars could use {r - 1} - {r} (or whatever, as needed). The needs of Chinese and Hebrew are different here.

I'm in favor of bopping this to CLDR, landing the code as-is with documentation saying that it may change.

Overall I would prefer to not delay proper Chinese formatting based on open questions about Hebrew formatting.

Overall I would prefer to not delay proper Chinese formatting based on open questions about Hebrew formatting.

Hm? r already works for Chinese and anything that returns cyclic years.

I'm not aware of any data that uses r except in cyclic calendars.

Oh, I misunderstood, I thought we still had hacks for chinese formatting.

In that case I think we can wait on CLDR.

I am still also in favor of landing this with less committal docs, though.

The actual behavior change is in components/datetime/src/format/datetime.rs. Previously it checked for cyclic year before trying to load the related year. This PR adds the ability to load the related year from other calendars by adding things to the traits.

I probably have comments on the trait structure, too, but I don't agree with the PR on principle so I haven't spent time thinking too much abut them.

components/calendar/src/cal/julian.rs

components/calendar/src/cal/indian.rs

sffc

We've been consistent about Gregorian meaning the calendar with eras and nonzero year numbers. Let's not muck it up

robertbastian · 2025-12-18T22:15:38Z

It's in CLDR, but it seems to have footguns. We shouldn't add new things that have known footguns.

what's the footgun?

We've been consistent about Gregorian meaning the calendar with eras and nonzero year numbers. Let's not muck it up

related_gregorian_extended_year then. We've also generally tried to be consistent with CLDR.

sffc · 2025-12-18T22:24:14Z

It's in CLDR, but it seems to have footguns. We shouldn't add new things that have known footguns.

what's the footgun?

That there isn't a 1-to-1 mapping.

We've been consistent about Gregorian meaning the calendar with eras and nonzero year numbers. Let's not muck it up

related_gregorian_extended_year then. We've also generally tried to be consistent with CLDR.

I prefer related_iso but won't veto related_gregorian_extended_year.

Temporal uses ISO for this. It's literally encoded into the API: Temporal.Now.plainDateISO()

robertbastian · 2025-12-18T22:50:49Z

That there isn't a 1-to-1 mapping.

The r symbol can be used to add additional context to a non-gregorian date. Yes you can format dd-MM-rr, but that's not a footgun, because you don't do that accidentally.

robertbastian · 2025-12-19T14:12:06Z

Temporal uses ISO for this. It's literally encoded into the API: Temporal.Now.plainDateISO()

I consider ECMA's and Temporal's distinction between ISO and Gregorian a major flaw. I'd also like to point out that Temporal.PlainDate.year returns the extended/arithmetic year (even for Gregorian), and .eraYear returns the era year, so by Temporal logic this shouldn't be the extended Gregorian year, just the Gregorian year.

sffc · 2025-12-19T19:21:41Z

There were lengthy discussions in Temporal where we arrived at these designs, weighing lots and lots of tradeoffs. I could write it up but I have better things to spend my time on today.

Manishearth · 2025-12-19T19:56:05Z

I don't really care about the name here. Self-consistency is a good motivator. I'd like to avoid deprecating things further just for naming reasons.

robertbastian

There were lengthy discussions in Temporal where we arrived at these designs, weighing lots and lots of tradeoffs.

I'm not arguing against Temporal's decision, I'm arguing that we should follow it.

robertbastian · 2026-01-06T14:42:19Z

components/calendar/src/types.rs

        }
    }

+    /// The Gregorian year in which this year started.


this is how CLDR defines this https://www.unicode.org/reports/tr35/tr35-dates.html#Contents:~:text=this%20corresponds%20to%20the%20extended%20Gregorian%20year%20in%20which%20the%20calendar%E2%80%99s%20year%20begins

sffc · 2026-01-06T22:16:35Z

components/calendar/src/types.rs

        }
    }

+    /// The Gregorian year in which this year started.


Yeah, and I consider it a footgun. It is there because of Chinese, and it has a definition for other calendars, but that doesn't mean it should be used by those other calendars.

For Hebrew, I did some research with help from Gemini and found that there are a number of sources that use the later of the two years since it has more overlap (5786 <-> 2026, not 2025). For example:

https://web.library.yale.edu/cataloging/hebraica/about-hebrew-calendar

However, most sources write it as "2025-2026"

https://www.judaicaplace.com/jewish-year-calendar-5786-2025-2026-spiralbound/767278911413/

So in that sense, maybe r should print 2025-2026.

Manishearth

Fine architecturally.

On the ISO vs Gregorian debate I find myself slightly in favor of ISO naming (as it is currently in the PR): CLDR nomenclature compatability is a compelling argument, but I also find "ISO year" to be a good shorthand for "Gregorian extended year"

The year overlap direction question is probably something that can be figured out in a CLDR context.

components/calendar/src/cal/persian.rs

components/datetime/src/provider/fields/symbols.rs

sffc

I don't see a path for this PR until we work with CLDR on improving the spec

robertbastian requested review from Manishearth, sffc and zbraniecki as code owners December 18, 2025 15:27

related gregorian

e6b97e4

robertbastian force-pushed the related branch from c0cea90 to e6b97e4 Compare December 18, 2025 15:43

robertbastian requested a review from a team as a code owner December 18, 2025 15:43

Manishearth reviewed Dec 18, 2025

View reviewed changes

sffc reviewed Dec 18, 2025

View reviewed changes

sffc requested changes Dec 18, 2025

View reviewed changes

fix

a384e1e

Merge remote-tracking branch 'upstream/main' into related

ccfb1d9

robertbastian commented Jan 6, 2026

View reviewed changes

robertbastian requested review from Manishearth and sffc January 6, 2026 15:00

related_iso

3dfa73e

robertbastian force-pushed the related branch from eddf739 to 3dfa73e Compare January 6, 2026 15:02

sffc requested changes Jan 6, 2026

View reviewed changes

robertbastian requested a review from sffc January 6, 2026 22:59

Manishearth approved these changes Jan 6, 2026

View reviewed changes

components/calendar/src/cal/persian.rs Show resolved Hide resolved

components/datetime/src/provider/fields/symbols.rs Show resolved Hide resolved

sffc requested changes Jan 7, 2026

View reviewed changes

Add full support for r datetime symbol #7327

Are you sure you want to change the base?

Add full support for r datetime symbol #7327

Uh oh!

Conversation

robertbastian commented Dec 18, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sffc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sffc Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

sffc left a comment

Choose a reason for hiding this comment

Uh oh!

robertbastian commented Dec 18, 2025

Uh oh!

sffc commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

robertbastian commented Dec 18, 2025

Uh oh!

robertbastian commented Dec 19, 2025

Uh oh!

sffc commented Dec 19, 2025

Uh oh!

Manishearth commented Dec 19, 2025

Uh oh!

robertbastian left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sffc Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Manishearth left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

sffc left a comment

Add full support for `r` datetime symbol #7327

Add full support for `r` datetime symbol #7327

sffc Jan 6, 2026 •

edited

Loading

sffc commented Dec 18, 2025 •

edited

Loading

sffc Jan 6, 2026 •

edited

Loading

Manishearth left a comment •

edited

Loading