Use more specific calendar-dependent operations in Until, Add, and ToISO

[sffc]

Fixes #55. More steps toward #57.

This PR is based on #66, and it also depends on #68 and tc39/proposal-temporal#3138.

I rewrote NonISODateAdd, NonISODateUntil, and NonISOCalendarDateToISO to more precisely specify their algorithms. They are still ultimately calendar-dependent, but the calendar-dependent parts are boiled down to more bite-sized abstract operations:

• CalendarDateArithmeticalToISO
• CalendarDaysInMonth
• CalendarMonthsInYear
• YearContainsMonthCode

[Manishearth]

Partial review up til NonISODateSurpasses

[Manishearth]

nit: I think you can say something like a String which is a valid month code

[sffc]

I was considering introducing a type for it. I say "valid month code" in the description. Happy for editorial advice from @ptomato or others.

[ryzokuken]

I agree we should narrow down the possible set of month codes (which we already have) and define that (essentially mark the existing definition) as the term "month code" or "month code type" akin to "calendar type" that we utilize from upstream Temporal. I don't think it's a bad idea to place this definition in the Temporal spec since it can be utilized in the upstream AO https://tc39.es/proposal-temporal/#sec-temporal-tomonthcode.

[sffc]

Would you like me to add the definitions in this PR or can I do it in another PR? I'd also like to define terms like "arithmetical month"

[Manishearth]

observation/praise: this will work for calendars that have multiple leap months in a year, like a hindu lunisolar calendar (especially a purnimanta calendar, where you are required to model fortnights as months since otherwise your leap months get "split" in half)

Implementors will likely optimize this to not need a for loop and instead query something like "does this year have a leap month and if so which month is it" which is potentially a useful other way of writing this spec text to avoid the loop. It falls within the type of thing that is possible to leave to implementors without confusion, though.

[sffc]

To make it support Hindu (although Hindu is not yet in the spec), should I start _number_ at 0 in order to catch M00L?

[sffc]

I considered "does this year have a leap month and if so which month is it" but that is a more confusing calendar-dependent behavior, whereas "does year contain this particular month code" is more clear. I expect implementations to implement it as they see fit so long as the behaviors match.

[Manishearth]

I would not spend too much time thinking about the nitty gritty specifics of Hindu until we have a concrete proposal on the table since there are multiple ways to model ir. I don't think it needs an M00L, but it might. The fact that Hindu days can be "merged" is probably going to be the biggest problem.

[gibson042]

To make it support Hindu (although Hindu is not yet in the spec), should I start _number_ at 0 in order to catch M00L?

Yes, I think the algorithm should be able to handle M00L. Ignoring that possibility just creates future liability. And likewise for hard-coding 12 rather than something more clear like HighestMonthNumberForCalendarYear(calendar, year).

[sffc]

I resolved the month 0 / month 13 issue by adding an assertion in 6abbe6e

Was there anything else actionable from this thread?

[Manishearth]

interesting choice; any particular reason behind it?

Not that I dislike it, but I would have thought keeping M06 as M06 would be clearer since Adar II is supposed to be the "regular" Adar

[sffc]

#70

[gibson042]

Please explain the intent of these steps with a "NOTE: The following steps…".

[sffc]

I deleted this AO in 6abbe6e and replaced it with a table reference

[Manishearth]

praise: well written.

suggestion: I suppose this could be refactored into BalanceNonISOYearMonth and BalanceNonISODate to avoid the duplication of the resolvedMonth balancing. But I don't know if that's better.

[sffc]

Thanks. I want to highlight that this logic is novel to Intl Era Month Code; the equivalent ISO operation in Temporal does month balancing with divrem and then goes to Epoch Days for weeks and days.

I think I prefer keeping it in one AO because it is easier to see how month and day balancing interact.

[sffc]

I changed around the AOs in 6abbe6e

[Manishearth]

LGTM

[Manishearth]

thought: I find this naming a bit confusing. In the original spec, "Regulate" is about applying overflow options, but here it's really doing a type of addition operation.

[sffc]

Yeah; my mental model was "regulate" means "if overflow, constrain the least significant unit" and "balance" means "if overflow, roll over the smallest unit into higher units". This AO does the regulating behavior, so that's how I named it. I'm happy to explore other naming options, or refactor exactly what role the AO serves.

[ryzokuken]

ConstrainNonISOYearMonth sounds good as well but yeah don't mind Regulate either since it's consistent with upstream

[sffc]

I replaced RegulateNonISOYearMonth with ConstrainMonthCodeToArithmeticalMonth in 6abbe6e

[Manishearth]

thought related to previous: My immediate response to this was "shouldn't the result of CalendarISOToDate already be regulated" before I remembered that RegulateNonISOYearMonth also does some year addition.

[sffc]

I acknowledge that this was confusing, and it should be fixed in 6abbe6e

[Manishearth]

issue: this doesn't clamp, but the previous one does. Is that a discrepancy we are okay with?

This means Surpasses(calendar, sign = 1, baseDate, isoDate2, years, months, weeks = 0, days = 0) could be true whilst Surpasses(calendar, sign = 1, baseDate, isoDate2, years, months, weels = 0, days = 1) could be false if, say, the other numbers were something like "add 1 month to to January 31st" since with days = 1 it will get normalized to Feb 28 + 1 (assume non leap year) but with days = 0 it'll get normalized to Feb 32.

[sffc]

This matches the behavior in tc39/proposal-temporal#3138.

The AO has one call site, Until, which wants a true return value for things like "march 31 + 1 month ?< april 30", since the Temporal Addition Algorithm only regulates to the end of the month immediately before adding weeks and days.

I could have written this AO with an extra argument, regulationBehavior or something, or even as a completely different AO, but I realized that checking weeks == 0 and days == 0 was equivalent.

[Manishearth]

Hmm, okay. I don't fully understand the Until argument but I see there is a reason. Perhaps worth including a note.

[sffc]

Is this thread resolved?

[Manishearth]

Yes!

[Manishearth]

Very minor points overall. Looks good!

Implementing this efficiently may be tricky but that's fine; at least now we have more concrete guidance for behavior

[Manishearth]

observation: so we don't end up doing anything about the overflow with months, only with day

question: is there a reason we should try to be more consistent? is there a reason we should not?

[sffc]

Feel free to weigh in on #56. I took the position that overflow should be applied consistently for overflowed days only, and not have an extra error case in lunisolar.

[Manishearth]

Okay, that makes sense, because day is a final thing whereas months is still incomplete.

Might be worth having a note here to that effect.

[Manishearth]

Wait, hold on, but the day here is partial as well; we have not yet finished adding.

But I guess that's somewhat the behavior you ask for with REJECT.

[Manishearth]

praise: I appreciate the simplicity of this AO

[sffc]

A bit more commentary on my choices of AOs:

1. RegulateNonISOYearMonth ( calendar, arithmeticalYear, monthCode, years )
   • This is a key calendar-dependent operation that adds years but not months. This is where we resolve common/leap month constraining issues in Chinese, Dangi, and Hebrew.
2. BalanceNonISODate ( calendar, year, month, day )
   • This AO works the same across all calendars. There are zero special cases. It depends only on CalendarDaysInMonth and CalendarMonthsInYear.
3. NonISODateSurpasses ( calendar, sign, baseDate, isoDate2, years, months, weeks, days )
   • This is my generalization of Editorial: Move regulating and balancing logic into ISODateSurpasses proposal-temporal#3138 to non-ISO. I tweaked the dependent AOs slightly. The ISO version combines the first few steps into a BalanceISOYearMonth, but that is a fundamentally different operation because it can be implemented with a DivRem. For non-ISO, I wanted to emphasize that there are multiple steps: first you add years, then you convert month codes to arithmetical months, then you continue with the rest of the balancing. This order of operations is crucial for the interoperability of calendar arithmetic.
4. NonISODateAdd and NonISODateUntil
   • My goal is to refactor these AOs back into main Temporal so that they depend on the same low-level operations. I have a start in Editorial: Rewrite CalendarDateUntil to be simpler and more general proposal-temporal#3136.

[sffc]

To put Add and Until's algorithm in words:

1. Add years
2. Constrain to a valid year/month
3. Add and balance months
4. Constrain to a valid year/month/day
5. Add and balance weeks and days

The key difference with non-ISO is step 2. ISO doesn't need to constrain to a valid year/month because all months are valid in all years.

This also feeds into #56. Is it more consistent or less consistent for non-ISO to reject when constraining year/month? I took the position that non-ISO is better off rejecting on step 4 only. I think it's a valid position that it should reject on both steps 2 and 4. However, maybe there should be a third option in the enum to allow for either behavior.

[gibson042]

An integer result is always positive, right?

Suggested change

	): an integer or ~invalid~
	): a positive integer or ~invalid~

[sffc]

Done in 3dacca7

[gibson042]

This kind of implicit assumption that all possible exceptions have been enumerated makes me uncomfortable. I'd like an assertion about what calendar must be if it is not "chinese", "dangi", or "hebrew", or better yet, representation of the underlying concept:

Suggested change

	1. If _calendar_ is not *"chinese"*, *"dangi"*, or *"hebrew"*, then
	1. Return _monthCodeParts_.[[Number]].
	1. Let _monthsBefore_ be 0.
	1. If CalendarHasLeapMonths(_calendar_) is *false*, then
	1. Return _monthCodeParts_.[[Number]].
	1. Let _monthsBefore_ be 0.

[sffc]

In 6abbe6e, I am checking for leap months by the presence of a new column in #table-additional-month-codes.

[gibson042]

Shouldn't this have a named operation?

Suggested change

	1. If _calendar_ contains CreateMonthCode(_number_, _isLeap_) in _year_, according to a calendar-dependent algorithm, then
	1. If IsValidYearMonthCodeForCalendar(_calendar_, _year_, CreateMonthCode(_number_, _isLeap_)) is *true*, then

[sffc]

Yes, except the AO that we're currently inside is also how I would implement IsValidYearMonthCodeForCalendar... in fact this AO was called that in an earlier draft before I made it start returning an integer. I only need the sub-AO in order to determine if it is a valid leap month.

[gibson042]

I'm more comfortable with the sub-AO than this kind of handwavy algorithm step. Or alternatively, with just making the entirety of MonthCodeToArithmeticalMonth calendar-dependent rather than trivially wrapping a calendar-dependent core.

[sffc]

I made a standalone AO YearContainsMonthCode in 6abbe6e.

[gibson042]

To make it support Hindu (although Hindu is not yet in the spec), should I start _number_ at 0 in order to catch M00L?

Yes, I think the algorithm should be able to handle M00L. Ignoring that possibility just creates future liability. And likewise for hard-coding 12 rather than something more clear like HighestMonthNumberForCalendarYear(calendar, year).

[gibson042]

Suggested change

	1. If _monthCodeParts_.[[Number]] is _number_ and _monthCodeParts.[[IsLeap]] is _isLeap_, then
	1. If _monthCodeParts_.[[Number]] is _number_ and _monthCodeParts_.[[IsLeap]] is _isLeap_, then

[sffc]

I changed it to check for month code string equality instead, in 6abbe6e.

[gibson042]

Please explain the intent of these steps with a "NOTE: The following steps…".

[gibson042]

Suggested change

	1. Let _month_ be MonthCodeToArithmeticalMonth(_calendar_, _monthCode_, _y2_).
	1. Assert: _month_ is not ~invalid~.
	1. Else,
	1. Let _month_ be ParseMonthCode(_monthCode_).[[Number]].
	1. Return the Record { [[Year]]: _y2_, [[Month]]: _month_ }.
	1. Let _arithmeticalMonth_ be MonthCodeToArithmeticalMonth(_calendar_, _monthCode_, _y2_).
	1. Assert: _arithmeticalMonth_ is not ~invalid~.
	1. Else,
	1. Let _arithmeticalMonth_ be ParseMonthCode(_monthCode_).[[Number]].
	1. Return the Record { [[Year]]: _y2_, [[Month]]: _arithmeticalMonth_ }.

[sffc]

This code was deleted in 6abbe6e

[gibson042]

Suggested change

	_month_: an integer,
	_day_: an integer,
	): a Record with fields [[Year]] (an integer), [[Month]] (an integer), and [[Day]] (an integer)
	</h1>
	<dl class="header">
	<dt>description</dt>
	<dd>
	It interprets the given _year_ and potentially out-of-range _month_ and _day_ as arithmetical values in the given _calendar_ and returns in-range values by overflowing out-of-range _month_ or _day_ values into the next-highest unit.
	This date may be outside the range given by ISODateTimeWithinLimits.
	</dd>
	</dl>
	<p>It performs the following steps when called:</p>
	<emu-alg>
	1. Let _resolvedYear_ be _year_.
	1. Let _resolvedMonth_ be _month_.
	_arithmeticalMonth_: an integer,
	_day_: an integer,
	): a Record with fields [[Year]] (an integer), [[Month]] (an integer), and [[Day]] (an integer)
	</h1>
	<dl class="header">
	<dt>description</dt>
	<dd>
	It interprets the given _year_ and potentially out-of-range _arithmeticalMonth_ and _day_ as arithmetical values in the given _calendar_ and returns in-range values by overflowing out-of-range _arithmeticalMonth_ or _day_ values into the next-highest unit.
	This date may be outside the range given by ISODateTimeWithinLimits.
	</dd>
	</dl>
	<p>It performs the following steps when called:</p>
	<emu-alg>
	1. Let _resolvedYear_ be _year_.
	1. Let _resolvedArithmeticalMonth_ be _arithmeticalMonth_.

and so on.

[sffc]

In this particular function, I don't think the verbosity of repeating "arithmetical" a dozen times lends clarity. This AO is very much defined as working on arithmetical values only.

However, I did change the argument name in f54148f.

[gibson042]

I don't like the asymmetry of baseDate vs. isoDate2. What about fromIsoDate and toIsoDate?

[sffc]

I had used isoDate2 to match the name in 262 but I will change this according to your suggestion here which I agree is better. f157b7a

[gibson042]

Suggested change

	1. Let _month_ be MonthCodeToArithmeticalMonth(_calendar_, _year_, _fields_.[[MonthCode]]).
	1. If _month_ is ~invalid~, throw a *RangeError* exception.
	1. Else,
	1. Let _month_ be RegulateNonISOYearMonth(_calendar_, _year_, _fields_.[[MonthCode]], 0).[[Month]].
	1. Else,
	1. Assert: _fields_.[[Month]] is not ~unset~.
	1. Let _month_ be _fields_.[[Month]].
	1. Let _day_ be _fields_.[[Day]].
	1. Assert: _day_ is not ~unset~.
	1. Let _daysInMonth_ be CalendarDaysInMonth(_calendar_, _year_, _month_).
	1. If _daysInMonth_ ≤ _day_, then
	1. If _overflow_ is ~reject~, throw a *RangeError* exception.
	1. Let _regulatedDay_ be _daysInMonth_.
	1. Else,
	1. Let _regulatedDay_ be _day_.
	1. Return ? CalendarDateArithmeticalToISO(_calendar_, _year_, _month_, _regulatedDay_).
	1. Let _arithmeticalMonth_ be MonthCodeToArithmeticalMonth(_calendar_, _year_, _fields_.[[MonthCode]]).
	1. If _arithmeticalMonth_ is ~invalid~, throw a *RangeError* exception.
	1. Else,
	1. Let _arithmeticalMonth_ be RegulateNonISOYearMonth(_calendar_, _year_, _fields_.[[MonthCode]], 0).[[Month]].
	1. Else,
	1. Assert: _fields_.[[Month]] is not ~unset~.
	1. Let _arithmeticalMonth_ be _fields_.[[Month]].
	1. Let _day_ be _fields_.[[Day]].
	1. Assert: _day_ is not ~unset~.
	1. Let _daysInMonth_ be CalendarDaysInMonth(_calendar_, _year_, _arithmeticalMonth_).
	1. If _daysInMonth_ ≤ _day_, then
	1. If _overflow_ is ~reject~, throw a *RangeError* exception.
	1. Let _regulatedDay_ be _daysInMonth_.
	1. Else,
	1. Let _regulatedDay_ be _day_.
	1. Return ? CalendarDateArithmeticalToISO(_calendar_, _year_, _arithmeticalMonth_, _regulatedDay_).

[sffc]

Resolved in f54148f

[ryzokuken]

I agree we should narrow down the possible set of month codes (which we already have) and define that (essentially mark the existing definition) as the term "month code" or "month code type" akin to "calendar type" that we utilize from upstream Temporal. I don't think it's a bad idea to place this definition in the Temporal spec since it can be utilized in the upstream AO https://tc39.es/proposal-temporal/#sec-temporal-tomonthcode.

[ryzokuken]

nit: we can move this elsewhere as the list or table of supported calendars with leap months to make it easier to reuse and maintain and refer to that "central" (not necessarily for now, just disjointed) definition here.

[sffc]

I like the idea of moving this to a table, and the same table can also be used in @gibson042's proposed AO CalendarHasLeapMonths.

[sffc]

Added it to #table-additional-month-codes in 6abbe6e

[ryzokuken]

ConstrainNonISOYearMonth sounds good as well but yeah don't mind Regulate either since it's consistent with upstream

[ryzokuken]

isoDate isn't defined here, replace with "a YearMonth corresponding to arithmeticYear and monthCode".

[sffc]

I deleted this AO in 6abbe6e

[sffc]

This PR was included in the Stage 2.7 presentation. This PR was approved as part of Stage 2.7 with the following understanding: "changes the spec text to transform some parts of the spec from prose to algorithmic spec steps"

[sffc]

I believe I have responded to all of the threads. PTAL. Thank you @Manishearth @gibson042 @ryzokuken!

[justingrant]

Minor suggestion: the adjective for "arithmetic" can be "arithmetical" but could also be "arithmetic", e.g. "arithmetic mean".

Brevity is important in spec text, so I'd suggest globally replacing "arithmetical" wtih just "arithmetic".

[justingrant]

Overall looks good. A few minor suggestions only.

[justingrant]

Is there a more descriptive name than number that could be appropriate here, specifcally that would distinguish this numnber from arithmetic month, common month, etc.? For example, for a month code like M06L, do we have a term for the "6" part of that code? If not, should we have a term for it?

At a minimum, maybe change this to _monthNumber_ if we don't want to use a separate term?

[justingrant]

Suggested change

	_isLeap_: a Boolean,
	_isLeapMonth_: a Boolean,

Might be good to distinguish from leap years vs. leap months. I know it's obvious to us, but for readers who are not familar wtih lunisolar calendars it might be clearer to emphasize that this is a leap month not a leap year.

[justingrant]

Is there a reason why we chose "calendar type" instead of "calendar identifier" to align with "time zone identifier" ?

[ptomato]

It was the term already in use in 402.

[justingrant]

Suggested change

	It interprets _year_ as arithmetical value in the given _calendar_ and returns the number of months in the corresponding year.
	It interprets _year_ as arithmetic year in the given _calendar_ and returns the number of months in the corresponding year.

"Arithmethical Value" sounds like it could be a floating point thing that could be confused wtih "mathematical value" in ECMA-262. Also, do we need the "-al" per my earlier comment?

[justingrant]

Suggested change

	It interprets the given _year_ and potentially out-of-range _arithmeticalMonth_ and _day_ as arithmetical values in the given _calendar_ and returns in-range values by overflowing out-of-range _arithmeticalMonth_ or _day_ values into the next-highest unit.
	It interprets the given _year_ and potentially out-of-range _arithmeticalMonth_ and/or _day_ as arithmetical values in the given _calendar_ and returns in-range values by overflowing out-of-range _arithmeticalMonth_ or _day_ values into the next-highest unit.

There's a minor ambiguity possible where it's unclear whether the _day_could also be out of range. Using and/or might clarify,.

[sffc]

Minor suggestion: the adjective for "arithmetic" can be "arithmetical" but could also be "arithmetic", e.g. "arithmetic mean".

Brevity is important in spec text, so I'd suggest globally replacing "arithmetical" wtih just "arithmetic".

I prefer using the explicitly-adjective "arithmetical", but I was actually thinking of using a term like "monotonic" to emphasize how they actually behave, in another PR. But since this spec currently uses "arithmetic", I can keep using that term to reduce the diff, if other people feel the difference warrants fixing.