Implement month and era codes

[sffc]

The syntax for month and era codes is being discussed in #355. I implemented a placeholder in #445. This ticket is to follow up and properly wire month codes throughout the data model and document them appropriately.

[sffc]

I will do this along with #257.

[sffc]

Blocked on #519

[sffc]

Blocked on #493

[Manishearth]

Reassigning to self since this is a part of #1115 and #1116

I plan to do the era code part for now, not month codes (not yet, anyway)

[Manishearth]

Split it out into a separate issue since month codes will likely best be paired with a calendar that needs them

#1312

[gregtatum]

I am unclear what this is exactly. @Manishearth @sffc would you mind clarifying and pointing to UTS 35 for this? It's marked with the C-datetime label, and we're triaging the DateTimeFormat component.

[Manishearth]

@gregtatum So that we can handle leap months/etc, we need to have a way of talking about months that's not just numbers. There's a design for a month coding scheme here.

We may ultimately choose to still use indices in the data, but use codes in the Calendar API.

It's largely a Calendar-side change, but DTF will need to be updated to be able to fetch month formatting info using codes.

[Manishearth]

This isn't a UTS 35 thing, UTS 35 has a month naming scheme that's somewhat inadequate: fine for data, but not for user-visible APIs.

[Manishearth]

I think the general plan will be to move over to using month codes as data indices. Month may also contain an ordinal month, but not necessarily.

[sffc]

@macchiati @pedberg-icu For calendars that insert months into the middle of the year, if a numeric-only month format is requested, is it acceptable to use the ordinal month number?

[sffc]

Axes of questions:

1. Should we be using month codes in data? (yes)
2. Should we return the ordinal month in the month object? (conclusion: yes)
3. When doing formatting, what should we do when we are requested to display a numeric month in a calendar that doesn't have the same number of months per year? (conclusion: ordinal month(
4. What do constructors look like? (conclusion: generic)

• @sffc - Ideally the constructor should take an enum YearInput (arithmetic or era+eraYear) and enum MonthInput (ordinal or monthCode)
• @Manishearth - We could have a generic constructor for Date, and we could optionally add additional constructors on a calendar-by-calendar basis. The generic constructor should return errors if the values are invalid.
• @sffc - Note that the constructor should resolve the ordinal month if necessary.
• @sffc - I think the answer to question 2 is yes
• @sffc - I see a few options for question 3

1. Use the ordinal month
2. Use the numeric portion of the month code
3. Add the mapping in the data payload
4. Error, and the data transformer ensures this case doesn't happen

• @Manishearth - 2 is weird, especially in Hebrew.
• @Manishearth - I think 1 is fine. It's basically GIGO, and CLDR doesn't currently have such data, at least for Hebrew, and we can check that they don't add that data in the future.
• @sffc - For option 4, it's not a case that developers really know how to handle. But we have some precedent for this, like with fractional second digits. But, I'm also happy with 1, since this is an edge case and I favor simpler solutions to edge cases.
• @Manishearth - Most calendars do 1 anyway. If we did 4, we'd need to add an extra code path.

Conclusion: Yes on 2, option 1 on 3, and generic constructor on 4.

[Manishearth]

I've filed #2066 for leap month things and will be referencing it in code wehre leap months need to be handled, because I'm wary of writing code that can't be tested.