span printout question

[fdncred]

First of all, thank you for creating this crate and taking input from twitter/x with how people would like to see a new datetime crate. ❤️

I'm exploring jiff in the hopes that it can replace chrono in nushell. I'm working on a nushell plugin to do this. If we set aside the lackluster implementation details of my dt plugin, I get a span printed like the example below for trying to find the verbose difference between two datetimes.

❯ '2019-05-10T09:59:12-07:00' | dt diff '2024-08-07T09:36:42.367322100-05:00'
P5y2m27dT23h37m30.3673221s

What I'm curious about is why it says 5y2m27d instead of 5y2m3wk6d? i.e. there is no week component even though there are 27 days. Knowing your work, I can only assume that week is being left out intentionally and left up to me to translate from days to weeks.

[BurntSushi]

Yes it is indeed being left out intentionally! This decision comes straight from Temporal. I'm short on time at the moment, so I can't find a precise Temporal reference for you (I'll follow-up probably tomorrow) explaining things, but here's my understanding:

• It is probably not expected in general for weeks to be inserted into durations without them being explicitly requested.
• Weeks are a little bit weirder than other units in that they don't necessarily divide evenly into bigger units. For example, there is always a whole number of days in a month and always a whole number of months in a year. (You'd have to switch to a different calendar, like the ISO 8601 week calendar---which lacks months---to get years that always have a whole number of weeks.)

Note: In non-Gregorian calendars, weeks aren't always 7 days. But this on its own isn't necessarily disqualifying since it just makes it non-uniform, and spans already support other types of non-uniform units.

Fun fact: ISO 8601-1 actually doesn't allow week units to appear with other units. They are only allowed as part of an extension in ISO 8601-2.

I'll dig through the Temporal materials and see if I can fine a more concrete answer. I'm about 95% confident in my above answer though.

I'm exploring jiff in the hopes that it can replace chrono in nushell.

Please let me know if there's anything I can do to help! Feel free to DM me on Discord or Zulip. I'm burntsushi or burntsushi5 everywhere.

[fdncred]

Right. I'm doing something similar with this code:

civil_date_provided
  .until(
      DateTimeDifference::new(civil_input_datetime)
          .smallest(as_unit)
          .largest(as_unit)
          .mode(RoundMode::HalfExpand),
  )

What I'm really looking for is a "mode" that allows me to specify all the units I want returned. I thought .smallest(nanos).largest(years) would give me what I'm looking for, but as you've said, weeks gets left out intentionally. I'm going to have to think about the way to properly do this. 🤔

[BurntSushi]

Can you say more about the high level problem you're trying to solve? And how did you do it with Chrono?

[fdncred]

High level problem: Display date math durations in as many date time units as possible. Eventually nushell could allow people via configuration to say they want 1,2,3, etc. unit(s) and then we could round to get that.

More details:
A little history. Over the years at nushell we've gone back and forth/commit and revert of this topic about how nushell displays durations. Durations in nushell are first class citizens and a Value type. Currently, the largest duration unit that nushell will show is weeks. The reason for this is that the nushell date math wasn't able to accommodate date math because under-the-hood after the math happens nushell stores it as 1 i64, then to display it, nushell takes that i64 and makes a duration out of it. When it does that, the result is wrong because now we no longer have any concept for first date - second date. Another way we tried to solve this previously was to average days per month and days per year, which of course has its own set of problems.

Jiff, by itself, won't solve that historical problem with how nushell stores durations. This is why I've started experimenting by creating a datetime plugin named dt that can exist in the nushell ecosystem but allow us to learn about jiff to see where and how it can help. It's been clear to me for some time that in order to do date math correctly, store it as a value, and render it in a human readable way, we need to store more than 1 i64.

You can see some of this date math (which is now kind of a hack in nushell script) in this screenshot that shows the last line of the nushell banner on startup.

Here's another example in the nushell repl. We have datetime literals that you can do things within the repl. Below I'm subtracting datetimes.

❯ 2024-08-07T09:36:42.367322100-05:00 - 2019-05-10T09:59:12-07:00
273wk 4day 21hr 37min 30sec 367ms 322µs 100ns

After making some changes to my dt plugin, it now says this.

❯ '2019-05-10T09:59:12-07:00' | dt diff '2024-08-07T09:36:42.367322100-05:00'
P5y2m27dT23h37m30.3673221s
5yrs 2mths 3wks 6days 23hrs 37mins 30secs 367ms 322µs 100ns

Both this recent output and the original one that I posted originally are pretty close to https://www.timeanddate.com/date/timezoneduration.html?d1=10&m1=5&y1=2019&d2=07&m2=08&y2=2024&h1=9&i1=59&s1=12&h2=09&i2=36&s2=42& which I'm not sure it should be treated as "the gospel" but I'm trying to. The hours are off in my jiff implementation (21 vs 23) but that may be because I'm doing something wrong or either the website is wrong.

[BurntSushi]

With respect to the 23 hours versus 21 hours, it looks to me like there's an input discrepancy. Here's a Rust program using the datetimes shown in your nushell snippet:

use jiff::{tz::TimeZone, Unit, Zoned};

fn main() -> anyhow::Result<()> {
    let zdt1: Zoned = "2019-05-10T09:59:12-07:00[-07]".parse()?;
    let zdt2: Zoned = "2024-08-07T09:36:42.367322100-05:00[-05]".parse()?;

    let zdt1 = zdt1.with_time_zone(TimeZone::UTC);
    let zdt2 = zdt2.with_time_zone(TimeZone::UTC);

    dbg!(&zdt1);
    dbg!(&zdt2);

    let span = zdt1.until((Unit::Year, &zdt2))?;
    dbg!(span);

    Ok(())
}

And its output:

$ cargo -q r
[main.rs:12:5] &zdt1 = 2019-05-10T16:59:12+00:00[UTC]
[main.rs:13:5] &zdt2 = 2024-08-07T14:36:42.3673221+00:00[UTC]
[main.rs:16:5] span = P5y2m27dT21h37m30.3673221s

Notice the UTC times. But in your timeanddate link, it looks like you entered the datetimes without a location or offset. So it's classic "parse a local datetime and accidentally assume it's UTC" bug. Now in your screenshot, it looks like you have entered the locations and it reports 21 hours. So I'm pretty sure there's just a data entry problem here.

I'm also still struggling to understand why specifically you want weeks in the duration output. timeanddate.com doesn't seem to do it either. Is it just a matter of exploring what's possible here? I think for your specific use case, and for the Gregorian calendar at least, it would be pretty straight-forward to adapt any span to include weeks:

use jiff::{tz::TimeZone, Unit, Zoned};

fn main() -> anyhow::Result<()> {
    let zdt1: Zoned = "2019-05-10T09:59:12-07:00[-07]".parse()?;
    let zdt2: Zoned = "2024-08-07T09:36:42.367322100-05:00[-05]".parse()?;

    let zdt1 = zdt1.with_time_zone(TimeZone::UTC);
    let zdt2 = zdt2.with_time_zone(TimeZone::UTC);

    let span = zdt1.until((Unit::Year, &zdt2))?;
    dbg!(span);
    let span = span.weeks(span.get_days() / 7).days(span.get_days() % 7);
    dbg!(span);

    let span = zdt1.since((Unit::Year, &zdt2))?;
    dbg!(span);
    let span = span.weeks(span.get_days() / 7).days(span.get_days() % 7);
    dbg!(span);

    Ok(())
}

Has this output:

$ cargo -q r
[main.rs:13:5] span = P5y2m27dT21h37m30.3673221s
[main.rs:15:5] span = P5y2m3w6dT21h37m30.3673221s
[main.rs:18:5] span = -P5y2m27dT21h37m30.3673221s
[main.rs:20:5] span = -P5y2m3w6dT21h37m30.3673221s

---

OK, as for the issue of why weeks don't appear in your original example, I did a crawl of the Temporal issue tracker to better understand why they went with this behavior. It's actually surprisingly difficult to tease out the exact motivation because there's a lot of high-context discussion in the issues. But, from this issue (among some mentions in other issues), I think the best overall answer to your question is what I said initially: it is hard to know whether weeks ought to be in the duration if they weren't there originally or explicitly requested. And I think the position of the Temporal folks is that in most cases, it is not expected for years, months, weeks and days to appear in the duration. Just years, months and days. Moreover, there isn't really any room in the API to configure this change. It only permits smallest and largest unit designations. A new API knob could be added to "allow weeks" in the output, but Temporal doesn't support this and it would be quite the effort I think to think through all of the ramifications of this.

There is also a little discussion of how to deal with weeks in this issue.

Aside from user expectations, I think the other problem is also what I said originally: weeks overlap with both days and months in a duration. And unlike all other units, weeks don't divide evenly into bigger units. There is no "4 weeks is 1 month" or anything like that. So you can't ever really know when weeks should be balanced up to months.

And here's the PR that added weeks to Temporal.Duration.

And the initial issue wondering whether to support weeks in Temporal.Duration. I actually found this issue not as helpful as the ones I linked above.

I also searched through the meeting notes, but they didn't have much insight in them beyond what's in the issues. The meeting notes were how I found the related issues though!

The reason for this is that the nushell date math wasn't able to accommodate date math because under-the-hood after the math happens nushell stores it as 1 i64, then to display it, nushell takes that i64 and makes a duration out of it. When it does that, the result is wrong because now we no longer have any concept for first date - second date. ... snip ... It's been clear to me for some time that in order to do date math correctly, store it as a value, and render it in a human readable way, we need to store more than 1 i64.

Yes. In Temporal/Jiff terminology, the problem is that of non-uniform units. When dealing with civil time in the Gregorian calendar, then only years and months are non-uniform. That is, to know their length you need a reference date. But when dealing with time zone aware datetimes in the Gregorian calendar, then years, months, weeks and days are all non-uniform. (And if one were inclined to support leap seconds, then hours and minutes would also be non-uniform. Which is one reason why most datetime libraries don't support them.) If you are using time zones now, then the fact that you show up to weeks by assuming they are uniform is probably producing incorrect durations in some cases. Jiff makes it difficult to get this wrong through its API design and fallible routines. Like, if you are using a Zoned type, then you should never be able to have any of its APIs interpret "1 day" as a uniform unit that is always 24 hours. It will always take time zones into account.

But there is another dimension here to a Span in Jiff: it treats 120 minutes and 2 hours as distinct spans even though they represent the same length of time. This decision came from the coupling of "duration arithmetic" to internationalization in the Javascript standardization process. That is, the intent of a Temporal duration (a Jiff Span) is for it to own all of the math involved with rounding or re-balancing units, and for the internationalization APIs to just be "pass through." That is, they print what they're given. I think this is a very powerful API to have because it means your display logic can become "dumb" (or entirely focused on the user's locale). But in order to do this, your duration has to track the values of individual units. The obvious trade-off is that this can be expensive.

Please let me know how else I can help. :-)

[fdncred]

Thanks for taking the time to explain these concepts to me. I'm going to continue to read through the code & docs because there are still a few things I'm not getting. I may ping you again.