Why have Timestamp hour as largest unit for addition/subtraction?

[snaggen]

I have a tool for managing some docker images, perfect for playing and getting familiar with new libraries like jiff. So, I wanted to list all images newer than 7 days. So I did Timestamp::now() - 7.days() that however, paniced since I only can use hour as the largest unit. But if I do Timestamp::now() - 7.days().round(SpanRound::new().largest(jiff::Unit::Hour)).unwrap() I get my expected result (I think I actually ended up using checked_sub, but that shouln't really matter for this question).

So, what is the rationale behind having a Hour unit limit for Timestamp?

[BurntSushi]

Good question. This has a few knots to it, and I suspect one implied aspect of your question is "why doesn't Timestamp support days, but I can round a Span in a way that assumes all days are 24 hours?"

So first, the Timestamp restriction to units of hours or smaller comes from Temporal:

The years, months, weeks, and days fields of duration must be zero. Temporal.Instant is independent of time zones and calendars, and so years, months, weeks, and days may be different lengths depending on which calendar or time zone they are reckoned in. This makes an addition with those units ambiguous. To add those units, convert the Temporal.Instant to a Temporal.ZonedDateTime by specifying the desired calendar and time zone, add the duration, and then convert it back.

(jiff::Timestamp is analogous to Temporal.Instant and jiff::Zoned is analogous to Temporal.ZonedDateTime.)

So from that alone, I think the suggestion here would be that you ought to be using Zoned if you want to perform operations involving a concept of "days." The idea here is that the restriction on Timestamp prevents you from making a mistake whereby you implicitly assume all days are 24 hours long.

Now, the reason why 7.days().round(SpanRound::new().largest(jiff::Unit::Hour)).unwrap() works is a bit more subtle. This also comes from Temporal and others have pointed out precisely the same inconsistency as you. And this has also been discussed on the Jiff repo in #48 too. The main reasoning here is one of trade-offs: it is common to create Span values that only have units of days (for example, when subtracting two civil::Date values) in a context where it is okay to assume that all days are 24 hours. If we were stricter on Span, then it would likely be more common that folks would use a "dummy" date just to get around the restriction. Particularly when dealing with civil datetimes.

Because of that, all of the Span APIs have this decision procedure:

• If all units are hours or less, than all units are uniform and the presence or absence of a relative datetime is irrelevant.
• Otherwise, if given a relative zoned datetime, then units of days or higher are interpreted with respect to that datetime, taking DST into account.
• If a relative civil datetime is given, then years/months are interpreted with respect to that datetime and days are always 24 hours. (Because there is no DST in this context.)
• If no relative datetime is given, days are always assumed to be 24 hours.

Now, as #48 discusses, this is perhaps not ideal. Temporal might have a different set of trade-offs to consider here. In particular, they are sticking with a single duration type. But in Jiff, I've already added a second duration type called SignedDuration. Moreover, I am fond of the "marker" idea suggested in tc39/proposal-temporal#2768. So at this point, I am planning to make 7.days().round(SpanRound::new().largest(jiff::Unit::Hour)) return an error in jiff 0.2. Instead, you'll either need to provide a relative date, or you'll need to use a new marker like this 7.days().round(SpanRound::new().relative(jiff::DaysAre24Hours).largest(jiff::Unit::Hour)).

Popping up a level, here is what my advice would be at this point:

• If you want to operate with calendar units, including "days," it's probably better to use Zoned and Span.
• If you just want to use "simple" math on UTC timestamps, then Timestamp and SignedDuration will achieve that for you. SignedDuration specifically omits a concept of "days" to avoid ambiguity over how long they are, but you can obviously do SignedDuration::from_hours(days * 24) to achieve the same effect.

[snaggen]

Thanks for your reply, even if it doesn't really matter in my case (no biggie if things get an hour or two off), I will probably still switch to zoned just for correctness.

Trying to figure out some trick to get this to fail at compile time, that wouldn't mess up the API... but I guess that is not very easy...

[BurntSushi]

Indeed, not easy. The most straight-forward approach would be to have a bunch of different duration types. But this would significantly complicate the API. There's a trade-off between API complexity and making illegal states unrepresentable. Moreover, jiff already does a ton in the area of using types to avoid mistakes.