add "error kind" predicates on `jiff::Error`

[jessekrubin]

As discussed here adding some minimal sort of error kind api would be quite nice... that said, I imagine it could be a much larger job than I expect it to be.

preface: for anyone reading this, I have been working on creating jiff-python bindings for some time now, and have gone to pretty great lengths to avoid panics and always raise some sort of python error (bc at the end of the day my project is a python library).

In an ideal world, an error kind api would allow me to easily determine if I should throw:

• OverflowError
• TypeError (eg: you give a rounding/difference method an invalid unit)

[BurntSushi]

I'm overall in favor of something like this. There may be some challenges. At first glance, one can see that a jiff::Error does have a few concrete variants internally, including a range error:

jiff/src/error.rs

Lines 80 to 85 in 962edee

	/// An error that occurs when a number is not within its allowed range.
	///
	/// This can occur directly as a result of a number provided by the caller
	/// of a public API, or as a result of an operation on a number that
	/// results in it being out of range.
	Range(RangeError),

But it doesn't have anything corresponding to what you call a "type" error. Probably "is type error" doesn't really make sense in the context of Jiff because that would imply the program doesn't compile in the context of Rust source code. So the "is type error" thing here is really a Python-ism. I think what I'd need here is an understanding of the things that you want to classify as a "type error." Maybe Jiff should call them "invalid configuration" or "invalid parameter" or something along those lines.

Jiff doesn't currently have an "invalid parameter" kind internally, so that would need to be added.

There are a few more challenges.

First is that Jiff errors can be arbitrarily composed internally. In fact, they form a chain, like an anyhow::Error:

jiff/src/error.rs

Lines 64 to 65 in 962edee

	#[cfg(feature = "alloc")]
	cause: Option<Error>,

So this means a single jiff::Error could actually be both a range error and an invalid parameter error. I don't think that actually happens, but it's in theory a possible combination.

The other challenge here is whether we want a set of predicates for which at least one returns true for every possible error. I think this would be an enormous effort and somewhat contrary to my approach to error handling here. I'd recommend reading #8 for more context there.

[jessekrubin]

Detecting overflows/range-errors is the primary QOL thing for me personally.

Jiff doesn't currently have an "invalid parameter" kind internally, so that would need to be added.

Really in my experience the only place I would be using a TypeError would be with the invalid configs for round/difference/compare. That said, it's not such huge problem to use ValueError in most places I would use a TypeError -- most of the time when I throw/raise a TypeError it is on my side where I am attempting to coerce/extract compatible types (eg allowing someone to subtract a Span/SignedDuration/datetime.timedelta from a Zoned -- which lead me to create the Spanish struct a pun I am quite proud of)

Edit: A place where a type-error/configuration error could be super helpful would be in my adaptation of the .with builders which I have renamed to .replace (as with is a python keyword)