Consider narrower error type between try_new_from_codes and try_from_fields

[sffc]

issue: these new variants are only returned by from-fields, not by constructors on Date (which is what this type is for). please lets not have catch-all errors again

Originally posted by @robertbastian in #6910 (comment)

[sffc]

Also consider making an error module as suggested by @Manishearth in #7012 (comment)

[sffc]

ok so in terms of new APIs in 2.1, it is only Date::try_from_fields that needs to have a new error type. We'll need to answer this question for Date::try_add in 2.2, unless we somehow find time to graduate those APIs in 2.1, which I don't think will happen.

Sadly Date::try_new_from_codes returns a type called DateError; ideally it would have been named DateFromCodesError. Maybe in 3.0 (or in 3.0 we can just delete that function).

Here is DateError:

pub enum DateError {
    Range {
        /// The field that is out of range, such as "year"
        field: &'static str,
        /// The actual value
        value: i32,
        /// The minimum value (inclusive). This might not be tight.
        min: i32,
        /// The maximum value (inclusive). This might not be tight.
        max: i32,
    },
    UnknownEra,
    UnknownMonthCode(MonthCode),
    InconsistentYear,
    InconsistentMonth,
    NotEnoughFields,
}

The last three variants are the new ones reachable from Date::try_from_fields rather than Date::try_new_from_codes.

There are two things I could do:

1. Make pub enum DateFromFieldsError with a variant DateError plus the other three new ones.
2. Make pub enum DateFromFieldsError with all six variants.

In both cases, I'll revert DateError back to 2.0 state.

Thoughts @robertbastian ?

[sffc]

I'm leaning toward expanding all six variants, because I think we may eventually want to get rid of DateError, and because I think I want to make Range into its own struct DateRangeError.

Maybe I want to split UnknownMonthCode, too, since it is used in a lot of different situations.

So then we get:

pub enum DateFromFieldsError {
    Range(DateRangeError),
    UnknownEra,

    /// MonthCode syntax is invalid
    InvalidMonthCode(MonthCode),
    /// MonthCode doesn't exist in the calendar
    UnknownMonthCodeInCalendar(MonthCode),
    /// MonthCode doesn't exist in the specific year
    UnknownMonthCodeInYear(MonthCode),

    InconsistentYear,
    InconsistentMonth,
    NotEnoughFields,
}

Ideally we wouldn't need InvalidMonthCode because ideally MonthCode would check its syntax on construction, but for some reason MonthCode has a public TinyStr field, which means this error case is reachable in pretty much all of our APIs that take a MonthCode. Hmm, should I change DateFields to take a &str instead of MonthCode?

[Manishearth]

and because I think I want to make Range into its own struct DateRangeError.

Already the case: https://unicode-org.github.io/icu4x/rustdoc/icu/calendar/struct.RangeError.html

But we can't wrap it withotu it being a breaking change. File-and-forget 3.0 issue, I say.

Maybe I want to split UnknownMonthCode, too, since it is used in a lot of different situations.

I would love to differentiate between "you gave me a crap month code", "you gave me a month code that does not work for this calendar" and "you gave me a month code that does not work for this date". Mostly between the second two, but differentiating between Mabc and M05L may be useful.

Hmm, should I change DateFields to take a &str instead of MonthCode?

I think to some extent the choice of MonthCode having a public field was since the month code format may extend in the future. PErhaps that was a wrong call.

I think we should still take a MonthCode, it's fine if we validate it in-code.

[robertbastian]

It should be an error with 6 variants, I'd like our errors to be as flat as possible. I'd also want the range variant to be the same as in DateError, not wrapping a RangeError, as that's another level a caller would have to navigate.

Hmm, should I change DateFields to take a &str instead of MonthCode?

I think that makes sense, we also accept eras as &str. TinyAsciiStrs are convenient for return values, because then there's no life time, but for function parameters they are just annoying to construct.

[robertbastian]

Using &str also makes FFI more aligned, as there we already return UnknownMonthCode if the &str fails to parse into a MonthCode; whereas in Rust the client has to handle that separately.

[Manishearth]

Hmmm, that argument is compelling.

I dislike having lifetimes on input structs but it's ... fine.

[sffc]

We already have a lifetime on it for the era code.

[Manishearth]

oh, then i'm convinced