Stage 2.7 review feedback: Provide guidance on calculating a reference year for MonthDay when not provided.

[Manishearth]

This effectively covers filling in CalendarMonthDayToISOReferenceDate.

This is the type of tricky calendar-specific thing that the spec should try and have some clarity on.

Ideally we can specify a default year for each calendar but we may not be able to pick a solution like that.

[Manishearth]

I think there are broadly, four types of selections of a reference year:

1. A single default reference year that is chosen based on simplicity.
   1. Just pick the year that overlaps with 1972.
   2. Year 1 in the default epoch.
2. A single default reference year that is chosen based on supporting most dates, the way 1972 is for ISO.
   1. It can be chosen on maximal month and day support: This would mean a leap year for all of the solar calendars, and a Shlemah leap year for Hebrew. There is no clear answer for chinese/dangi/islamic, where no year supports all months and month lengths.
   2. It can be chosen on minimal month but maximal day support. This would mean a leap year for all solar calendars, a Shlemah non-leap year for Hebrew, a non-leap year for Chinese, and some year for Islamic. Once again there is no clear choice for chinese/dangi/islamic, where you cannot get a year with all "full sized months" or all "short months".
3. A reference year calculated based on finding a year which supports the provided month/day combo. This can get tricky; not every calendar will be uniform here. In particular, finding things like "A chinese M05L with 30 days" might not even be possible. We know that chinese M12L/M11L/M0L are not really going to exist without extending the math beyond its accurate range, so this gets pretty messy to specify.
   1. The year can be chosen to support, narrowly, the given month/day combo
   2. The year can be chosen to support the maximal number of days possible in that month, even if the day requested was just "1".
4. Hybrid between (2ii) and (3ii): We do not support non-leap months in MonthDay.from()/with() without a reference year, however we will select a year in which the given month has a maximum number of days.

We should, ideally, provide concrete year numbers as much as possible. For solutions 1 and 2 we just can provide a table of default years. For 3 and 4, we provide a single year for all solar calendars, and the Hebrew calendar., using some heuristic like the first year after 1970 with this property For Chinese, Dangi, and Islamic can provide the same heuristic, and provide tentative month->year mappings based on that (by picking an implementation). Chinese/Dangi/Islamic with some statement of variability based on implementation.

[Manishearth]

Some principles to work off of for this decision. These principles may conflict with each other when it comes to selecting a solution.

Generally an API that causes errors in one implementation but not another isn't great. As such, when it comes to stuff dependent on the specific calendar implementation; it's better to take a hard line and error where possible. This makes solutions that e.g. disallow leap months here entirely somewhat appealing.

Being able to talk about "month 05L , day 30" in the Chinese calendar is useful, and is somewhat in the spirit of use of this API.

If we require the user to calculate a reference year for the complex cases, the user has to write nontrivial, expensive for loops querying the calendar API. This is not great and it seems like it should be our responsibility.

We should try to do something that will be uniform across browsers.

As an implementor, it is nice to have direct answers from the spec rather than a research problem. Implementors are likely to be using calendar libraries, not implementing them.

[sffc]

Here's one approach. We can start with this algorithm:

const START = Temporal.PlainDate.from("1970-01-01").withCalendar("hebrew");
const allowedYears = [];
for (days=0; days<10000; days++) {
    let d = START.add({ days });
    let found = false;
    for (let year of allowedYears) {
        try { d.with({ year }, { overflow: "reject" }); found = true } catch {}
    }
    if (!found) allowedYears.push(d.year);
}
console.log(allowedYears);

Running with the Temporal polyfill, here are the years I get for a selection of calendars with this code:

Calendar	allowedYears
gregory	1970, 1972
hebrew	5730, 5731, 5732
coptic	1686, 1687
islamic-civil	1389, 1390
buddhist	2513, 2515
chinese	1969, 1970, 1971, 1973, 1974, 1976, 1979, 1984, 1987, 1993

(Notes: I was surprised that islamic-civil needed only 2 years. If I ran more days than this, I expect to get more hits in Chinese.)

Once we get that list, then we could run through it again and eliminate any years that are fully subsumed by some other year in the list. This is how we would get [1972] from [1970, 1972].

This roughly aligns with what the champions were thinking when they picked 1972 for ISO-8601.

[Manishearth]

@sffc I'm a bit confused as to the point of that algorithm: that algorithm appears to be trying to construct a year that fully subsumes all before it; but for chinese/islamic/dangi there is never going to be such a year since even ignoring month codes you cannot have a year with all months being "long"

Could you describe the algorithm in words? I might be missing something.

I think "first year after 1970 that can represent all representable dates" is sufficient for non-chinese/islamic/dangi, and for those three we can do "first year after 1970 that can represent the given month and a maximum number of days".

[Manishearth]

One other wrinkle: Chinese is complicated here.

My understanding is that winter leap months are rare, M01L may not be possible, as well as M02L. M11L and M12L appear to be possible in the ICU4X implementation, but I'm not 100% sure if that's actually correct.

They may only be possible in the far future, too.

[Manishearth]

I'm going to do some more research into Chinese (and why ICU4X seems to think M11L is okay)

[Manishearth]

Aha, found it.

Many Chinese astronomers claim that there can be no leap month after the 12th or 1st month ([52]). This is true in the sense that it has not happened since the last calendar reform in 1645, and that it will not happen in the 21st century.

(...math...)

Based on my computations, I believe that in 2262 there will be a leap month after the 1st month, and that in 3358 there will be a leap month after the 12th. Given the difficulty in making accurate astronomical predictions more than 100 years ahead, these computations must obviously be taken with a grain of salt. I also believe that there was an error in the computations for 1651, and I believe there should have been a leap month after the 1st month that year. Instead the leap month was added after the 2nd month.

From Aslaksen

I agree with Aslaksen that these should be taken with a grain with salt; so I'd be inclined to error on M01L and M12L without a reference year here (since any number we produce would be likely inaccurate).

Idk what this means for dangi.

[sffc]

I tried expressing it in words, but it was a big piece of spaghetti and expressing it in code is more clear.

My first post was almost complete except that I did write the last step in words: "eliminate any years that are fully subsumed by some other year in the list."

Here is code for the part I elided:

subsumedYears = [];
for (let year of allowedYears) {
    yearcheck: for (let otherYear of allowedYears) {
        if (year === otherYear) { continue };
        let d = Temporal.PlainDate.from({ calendar, year, month: 1, day: 1 });
        while (d.year === year) {
            try { d.with({ year: otherYear }, { overflow: "reject" }) } catch { continue yearcheck };
            d = d.add({ days: 1 });
        }
        subsumedYears.push(year);
    }
}
console.log(subsumedYears);

And then allowedYears - subsumedYears is the set of years to use.

Running these two together, I get:

Calendar	allowedYears	subsumedYears	Resolved Years
Gregory	1970, 1972	1970	1972
Hebrew	5730, 5731, 5732	5731	5730, 5732
Coptic	1686, 1687	1686	1687
islamic-civil	1389, 1390	1389	1390
Chinese	1969, 1970, 1971, 1973, 1974, 1976, 1979, 1984, 1987, 1993	empty set	1969, 1970, 1971, 1973, 1974, 1976, 1979, 1984, 1987, 1993

[sffc]

My best attempt to state the algorithm in prose:

• For every possible date in the calendar:
  • Pick the first year with a date in or after ISO 1970 that contains the date.
  • Collect the unique results into allowedYears.
• Then, trim any years from allowedYears that are fully subsumed by another year in the list.
  • (Postulate: a year can only be subsumed by a year later in the list.)

This in effect means that calendars with a single unique leap day pick the first leap year starting in or after 1970. So, my algorithm for picking years is of interest primary to calendars that need multiple years to cover all possible dates (those with leap months or irregular leap days).

[Manishearth]

I still don't understand, at a high level, what the point is. Is the goal to get a reduced set of reference years for the calendars where there is more than one by collapsing together years? What is the benefit of doing that vs just having one year choice per month code per calendar? Is the subsuming part actually gaining us anything?

Rephrasing my "in words" question: at a philosophical level, what is the algorithm attempting to produce?

Generally I'm not a fan of "the algorithm stated in words is spaghetti" for spec stuff.

Currently I have a proposed heuristic that is rather simple in words: For calendars where it is possible, the reference year is the year where all month days are possible. Otherwise, the reference year for a given month is the first year after 1970 in which that month code has the maximum number of days for that month code.

I think the heuristic you have proposed instead is: The reference year for a (month, day) is the first year after 1970 which contains it and contains the maximum number of other month day combinations. Which resolves to the same heuristic as you have noted for non-chinese/islamic, but seems to be slightly different for others in a way I do not really think is useful, but it has more complexity as a heuristic.

(I guess part of my problem with this algorithm is that allowedYears is not actually a useful concept; you need a mapping from month code to year as a result of this algorithm)

[sffc]

The advantage is that my algorithm does not (directly) deal with month codes. It deals with days. To pick a reference year, pick the first year in the output list that contains the desired day. That's the part where my algorithm is simple.

Your algorithm, IIUC, involves adding a mapping of "month code to year" into the spec. If we are okay doing this, then I agree that your algorithm is easier to understand.

[Manishearth]

Oh, okay. I thought you were proposing a different heuristic.

It's not 100% equivalent: the subsuming logic means that it is possible for a (month, day) combo to map to something other than the first year that month is possible.

This problem is solved by only running the subsuming logic for the calendars where a single answer is possible (true for everything except chinese, dangi, islamic-umalqura, and islamic-rgsa).

I do not think as a specification we need to include a fully-pinned-down algorithm: I think we include a heuristic, and for the majority of the calendars REQUIRE a single year we have calculated based on that heuristic. For the four calendars I mentioned, we REQUIRE a valid year or a RangeError (for the Chinese M01L/M12L case), we RECOMMEND following the heuristic as written above, and we OPTIONAL have a list of years we have computed with our implementation.

This means we do not need to fully specify an algorithm. In general I am in favor of specifications fully specifying an algorithm, but this is a situation where skew between calendar implementations will already lead to incompatabilities: a fully specified algorithm will not get us much.

[Manishearth]

The advantage is that my algorithm does not (directly) deal with month codes. It deals with days. To pick a reference year, pick the first year in the output list that contains the desired day. That's the part where my algorithm is simple.

Aha! That's a useful property. Not convinced it's better, but I see the merits now.

Your algorithm, IIUC, involves adding a mapping of "month code to year" into the spec. If we are okay doing this, then I agree that your algorithm is easier to understand.

With my implementor hat on, I think that is the easiest thing to implement.

I don't think it is efficient to ask implementors to run potentially upwards of 20 calendar constructions to find the matching reference year.