Should fallible methods on `jiff::SignedDuration` return their own error types?

[BurntSushi]

The only such methods currently are SignedDuration::try_from_secs_f64 and its 32-bit counter-part. Currently, these return the god jiff::Error type. But in std, the corresponding methods return a specific TryFromFloatSecsError.

I think I chose the jiff::Error because it avoided defining a new error type and these methods seemed a little niche to me.

But I do somewhat expect that std::time::Duration will eventually get other fallible constructors, and they're either going to return an Option or a Result with their own specific error. So it might be good to decide on this for Jiff 1.0. I suppose the conservative route is to return a new and specific error type. But this does add API noise.

[tisonkun]

Noticed that jiff has unalignment between try_from_secs_f32 (-> Result<SignedDuration, Error>) and try_from_hours (-> Option).

If the only reason such constructors can fail is argument overflow, we can safely use an Option because the None variant is mapped to the single reason.

And typically, users do not care about the reason but read it as "conversion failed - throw or swallow".

The design of std looks a bit over-designed. The only thing I can imagine it helps is that when impl TryFrom<f64> for Duration and consider the input f64 as seconds, the TryFrom trait requires an Error type. But that looks unreasonable.

[BurntSushi]

Noticed that jiff has unalignment between try_from_secs_f32 (-> Result<SignedDuration, Error>) and try_from_hours (-> Option).

Yes, this was unintentional: #462

It's possible that this unalignment will end up being the right choice. I wasn't sure. But I prematurely published the APIs.

If the only reason such constructors can fail is argument overflow, we can safely use an Option because the None variant is mapped to the single reason.

That's true of things like try_from_hours, but try_from_secs_f32 can also fail when the number isn't finite.

Now whether that's deserving of an error type or not, I'm not sure. Looking at the stabilization issue for Duration::try_from_secs_{f32,f64}, the error type isn't discussed much. It's mentioned briefly in the initial PR adding the constructors, but there wasn't otherwise much discussion.

With that said, Jiff has plenty of routines where the only failure mode is overflow, but Jiff still returns errors. This is an intentional departure from Chrono's API which is mostly Option-based. My thinking here is that explicit errors are better for Jiff because:

1. Many of them derive from user input, and so if Jiff returns an error, callers can bubble that up to their users as-is. With Option<T>, callers have to form their own error messages.
2. Jiff has many different error categories. Making APIs return Option<T> means that failure can only ever happen one way. If another error category is added to an operation besides overflow, then we're stuck.

If SignedDuration were in the domain of Jiff, then I would return an error type here. And I would probably change other things about the API too. But the tension is with std. I specifically want the type to be a drop-in signed replacement for std::time::Duration.

[BurntSushi]

I'm not going to make any changes here. The try_from_hours routines will keep returning an Option so that they can remain const. Moreover, this is consistent with the checked arithmetic APIs, which are also const and return an Option.

I'm also just going to leave the existing try_from_secs_{f32,f64} as-is. It matches std presently, and I don't think there have been any reported problems with using Jiff's God error type here. I'm not really a fan of adding one specific error type for these routines without a stronger motivating reason.