Thoughts and questions on making fallible Span operations more intuitive/ergonomic?

[mqudsi]

So I've read through the discussions on why Span doesn't implement PartialOrd (performance when doing so in a semantically correct manner), but I'm wondering if it's possible to make it more expressive.

This is the approach the design of the library has guided me towards using in order to determine if the difference between two timestamps exceeds a certain maximum (let me know if I'm wrong!):

    if matches!(
        (Timestamp::now() - invite.created)
            .compare((Span::new().days(7), SpanRelativeTo::days_are_24_hours()))
            // After specifying `days_are_24_hours()`, this becomes safe to unwrap in this context
            .unwrap(),
        core::cmp::Ordering::Greater
    ) {
        return Err(foo);
    }

This requires importing/qualifying four distinct types (Timestamp, Span, SpanRelativeTo, and Greater), aside from figuring out and using the tuple trick.

The lowest hanging fruit that requires no changes to the api would be to add is_gt()/is_eq()/is_lt() to Span (you could remove the is_ prefix, but then people might think it implements PartialOrd, not that that's the worst thing in the world), allowing the following syntax instead, getting rid of the matches!() macro call and the Greater type:

    if (Timestamp::now() - invite.created)
        .is_gt((Span::new().days(7), SpanRelativeTo::days_are_24_hours()))
        .unwrap()
    {
        return Err(foo);
    }

At this point, the discussion diverges into a more aggressive change to the api. I don't mean to disparage the work, time, and effort you've already put into the library or to imply that you might not have already considered and rejected these design proposals in the past, but in the name of airing out the dirty laundry before 1.0 ships I feel it would be remiss not to point out a few things that have felt very awkward to me (sort of the opposite of 'the pit of success') when learning to use this library instead of chrono (which I've contributed to) and coming from years of experience with other libraries that have tried to tackle the very hard problem of designing a strictly correct but not impossible to use date/time library (such as Joda Time/Noda Time, the .NET DateOnly/DateTime/DateTimeOffset misadventure, etc).

First, some observations (in no particular order) that have contributed to a mixed experience using the library:

• The documentation about fallible Span operations uses the term "relative datetime" but the definition of this was hard to find (it's in the docs for SpanRelativeTo). From a CS perspective, "relative" would make one think about the difference between two absolute values (vs the absolute value itself), but more concretely, since Timestamp can be infallibly round-tripped to/from Zoned, it's kind of weird to say that one is "relative" and one isn't, making it hard to logically infer what "relative" means in this context (I believe the intention is that the length of a day is relative? But with civil dates, the length of a day is assumed, making it absolute rather than relative?). I would humbly suggest using "civil/Zoned" in place of "relative", assuming that is indeed the intended meaning.

• Most of the issues I encountered with the library had to do with the panicking/erroring behavior that occurs when using calendar units. I imagine I'm not the only one that's going to have this issue. I've read what I could find in the repo issues and PRs about the current behavior and have some reflections on the details of the current implementation (being careful not to revisit whether the approach to larger units itself is the right one or not),

• While I personally would have been fine with the original jiff behavior with silently assuming 24 hour days by default unless a zoned/civil date(time) was provided, and would have resolved the ambiguities by extending Timestamp to assume 24-hour days by default as well; anecdotally when I was using calendar units to perform arithmetic on Timestamp values and being personally aware that without specifying a date/timezone operations such as adding or subtracting n days would be a rough estimate at best, there was one instance where I admit that the current design (after running into panics at runtime because I assumed std::ops::Sub would have Output=Result<..> if it could panic on routine math) led me to revisit the approach and have a more precise result (though it was admittedly outnumbered by the number of places I did indeed just want a 24-hour approximation of a day).

• I personally found the concept of using tuples to create a "tagged version" of the original value that has the SpanRelativeTo::days_are_24_hours() marker to be unorthodox. I understand how it simplifies/optimizes the design of the library types, but it's neigh undiscoverable without referencing the docs (and not at all via editor completions). Providing an api that allows opting into certain behavior is difficult without an explosion of types; generics would make this a lot easier but I'm assuming you've intentionally made a decision to forgo their use. The obvious suggestions that occur to me:

  • Using a two-member generic struct in place of the tuple would aid discoverability, but it wouldn't be my preference for various reasons it still shares with the current design;
  • one option is introducing a FixedLength counterpart to Unit that can be silently assumed to have larger calendar units built on a 24-hour day that can be used everywhere Unit can be used;
  • another is adding helpers to Unit that convert larger calendar units into hours, e.g. Unit::from_days() or Unit::hours_from_days(), etc. bypassing the matter altogether (which would require minimal changes to the rest of the library, as the result would be Unit::Hour but created from a convenience function) - subjectively, quite a lot of the times when grepping codebases for "days" or "weeks" they are simply out of convenience for not having to specify 86400 or 604800 seconds;
  • or adding an internal bit to Unit denoting that it's safe to assume 24-hour days (can be done with bitwise operators without taking more space via an struct-enum hack), then adding a fn assume_24_hour_days(self) -> Self member to set that bit, removing the need to use a tuple to associate a Unit with a marker;
  • or taking a leaf from some other libraries, restructure the resulting Error to internally include the would-be result if 24-hour days were assumed, then add a helper method to Result<_, Error> to assert 24-hour days post-facto, converting a would-be-error into success; this is possibly best illustrated by example:

  assert!(1.month().compare(30.days()).is_err());
  assert!(1.month().compare(30.days()).assume_24_hour_days().is_ok())

  • and doing something similar to both the above to support providing civil/Zoned contexts for cases where fixed-length days should not be assumed.

• I've mentioned the question of making std::ops::Sub/Add return a result instead of panicking elsewhere, esp. given how easy it is to run into the relative calendar units problem;

• It's hinted at with the first part of this issue, but I'm uneasy with the lack of PartialOrd and Eq for Span values; it really does drive one towards SignedDuration which is rather unfortunate since it's not the intended way to hold the library. I wonder if documenting repeatedly the possible performance gotchas of using the Eq and PartialOrd impls would be sufficient to avoid the current song and dance needed to compare spans? Also (and only from an abundance of precaution), I am unsure if the fieldwise() method might lead unwary devs to incorrectly using that to perform equivalence checks? I really don't see much use for the fieldwise operation in general date/time-programming aside from unit testing the library itself; I wonder if it's possible to perform a semantic eq() (if not also cmp()) operation fast enough with some clever tricks to make it acceptable. Otherwise, maybe lean into SignedDuration more and have diffing two Timestamp values return SignedDuration instead of Span, as that's probably the most common/likely reason to compare?

[BurntSushi]

Thank you very much for this feedback! It is very appreciated.

So I've read through the discussions on why Span doesn't implement PartialOrd (performance when doing so in a semantically correct manner), but I'm wondering if it's possible to make it more expressive.

Hmmm it's not just performance. It's the fact that in order for it to work for all possible inputs, you must provide a relative datetime. Otherwise the duration of years, months, weeks and days is not known. Days could be safely assumed to be 24 hours in some contexts (hence why SpanRelativeTo::days_are_24_hours() exists), and thus weeks could be known too. But there is no safe value to assume for the length of years or months. Crates like humantime claim that months are always 30.44 days and years are always 365.25 days, but I'm convinced most people don't use that crate with calendar units or otherwise just accept the inaccuracy.

Since some extra data is required to do a correct calculation in all cases, it would I suppose be feasible to implement PartialOrd. But I think that would just wind up being very annoying and not especially helpful.

This is the approach the design of the library has guided me towards using in order to determine if the difference between two timestamps exceeds a certain maximum (let me know if I'm wrong!):

    if matches!(
        (Timestamp::now() - invite.created)
            .compare((Span::new().days(7), SpanRelativeTo::days_are_24_hours()))
            // After specifying `days_are_24_hours()`, this becomes safe to unwrap in this context
            .unwrap(),
        core::cmp::Ordering::Greater
    ) {
        return Err(foo);
    }

I prefer working with complete examples that we can both compile, so I took the liberty here:

use jiff::{Span, SpanRelativeTo, Timestamp};

fn main() -> anyhow::Result<()> {
    let created: Timestamp = "2025-07-05T05:30-04".parse()?;

    if matches!(
        (Timestamp::now() - created)
            .compare((
                Span::new().days(7),
                SpanRelativeTo::days_are_24_hours()
            ))
            .unwrap(),
        core::cmp::Ordering::Greater
    ) {
        return Err(anyhow::anyhow!("failure"));
    }

    Ok(())
}

I can see how you got here, but there are some simplifications you can make. The first is that you can use Ordering::is_gt:

use jiff::{Span, SpanRelativeTo, Timestamp};

fn main() -> anyhow::Result<()> {
    let created: Timestamp = "2025-07-05T05:30-04".parse()?;

    if (Timestamp::now() - created)
        .compare((Span::new().days(7), SpanRelativeTo::days_are_24_hours()))
        .unwrap()
        .is_gt()
    {
        return Err(anyhow::anyhow!("failure"));
    }

    Ok(())
}

The second approach is to just use Zoned and specify a correct relative datetime:

use jiff::{ToSpan, Zoned};

fn main() -> anyhow::Result<()> {
    let created: Zoned = "2025-07-05T05:30-04[UTC]".parse()?;
    let now = Zoned::now();

    if (&now - &created).compare((7.days(), &now)).unwrap().is_gt() {
        return Err(anyhow::anyhow!("failure"));
    }

    Ok(())
}

(I also imported the ToSpan trait to get the nicer 7.days() syntax.)

The unwrap() here is still okayish since it's reasonable to assume that now() + 7 days is never going to overflow. But if now were, say, user input, then you'd want to do error handling here in some way.

Now, if you really just want to do classic Unix timestamp arithmetic, then I think it's acceptable to use SignedDuration here. IMO, if you've already convinced yourself that something like SpanRelativeTo::days_are_24_hours() is correct for your use case, then probably you can just drop down into regular 96-bit integer arithmetic:

use jiff::Timestamp;

fn main() -> anyhow::Result<()> {
    let created: Timestamp = "2025-07-05T05:30-04".parse()?;
    if Timestamp::now().duration_since(created).as_hours() > (7 * 24) {
        return Err(anyhow::anyhow!("failure"));
    }

    Ok(())
}

This gets you down to one import, no unwraps and no faffing about with the stricter but harder to misuse Span APIs.

It's true that the library pushes you toward Span, but the Span APIs are about making it harder to do incorrect datetime calculations in the face of both calendar and time zone arithmetic. If you're specifically opting out of caring about time zones (and this is exactly what you're doing by using SpanRelativeTo::days_are_24_hours()), then I don't see a problem with opting out all the way and just doing what is effectively classic integer arithmetic on Unix timestamps.

There is a gradient here that is perhaps hard to discover. It makes sense that people will want to use the library in the "most correct" way possible. And so they might "feel bad" about the most succinct solution I posted above. But I think this is an education problem that #24 touches on. I plan to try to address this in a Jiff book.

This requires importing/qualifying four distinct types (Timestamp, Span, SpanRelativeTo, and Greater), aside from figuring out and using the tuple trick.

The lowest hanging fruit that requires no changes to the api would be to add is_gt()/is_eq()/is_lt() to Span (you could remove the is_ prefix, but then people might think it implements PartialOrd, not that that's the worst thing in the world), allowing the following syntax instead, getting rid of the matches!() macro call and the Greater type:

    if (Timestamp::now() - invite.created)
        .is_gt((Span::new().days(7), SpanRelativeTo::days_are_24_hours()))
        .unwrap()
    {
        return Err(foo);
    }

My guess is that you didn't know about the Ordering APIs. They are an odd corner of std and I don't see them used much, but I think that their existence means this suggestion is probably moot. Defining is_gt on Span ends up not saving much.

Apologies, but this is all I had time to answer tonight. I'll address your other points tomorrow. :-)

[BurntSushi]

The documentation about fallible Span operations uses the term "relative datetime" but the definition of this was hard to find (it's in the docs for SpanRelativeTo). From a CS perspective, "relative" would make one think about the difference between two absolute values (vs the absolute value itself), but more concretely, since Timestamp can be infallibly round-tripped to/from Zoned, it's kind of weird to say that one is "relative" and one isn't, making it hard to logically infer what "relative" means in this context (I believe the intention is that the length of a day is relative? But with civil dates, the length of a day is assumed, making it absolute rather than relative?). I would humbly suggest using "civil/Zoned" in place of "relative", assuming that is indeed the intended meaning.

The terminology comes from phrases like, "3 months relative to 2025-02-01" or "1 year relative to 2023-04-01." The span of time "3 months" or "1 year" has no defined meaning unless it is interpreted relative to some specific datetime. I'm not really sure where the "CS perspective" comes in here.

I don't really get why "civil/Zoned" would be better here. It's awkward to use. It's more like "relative civil date," "relative civil datetime" or "relative zoned datetime." Or, more generically, "relative datetime."

The reason why Timestamp doesn't apply here is because a timestamp doesn't let you resolve the length of a single day. A Timestamp and a Zoned are not equivalent. A Zoned has strictly more information.

Most of the issues I encountered with the library had to do with the panicking/erroring behavior that occurs when using calendar units. I imagine I'm not the only one that's going to have this issue. I've read what I could find in the repo issues and PRs about the current behavior and have some reflections on the details of the current implementation (being careful not to revisit whether the approach to larger units itself is the right one or not),

This makes sense to me. I expect people to chafe against this a bit since it's a somewhat novel approach to datetime library design. The only other library that has a type like Span (a type that combines calendar and time units with no loss of fidelity) is Temporal. And in order to make it work in a way that avoids silent correctness footguns in the presence of time zones and variable length calendar units. In older school approaches, this same complexity exists, you just don't see it up front. This design is forcing you to confront it.

Now, the "old school" approach isn't always wrong. If you don't care about time zones and just want to work with Unix timestamps and unambiguous duration units, then Jiff's Timestamp and SignedDuration types should make this relatively easy to do.

While I personally would have been fine with the original jiff behavior with silently assuming 24 hour days by default unless a zoned/civil date(time) was provided, and would have resolved the ambiguities by extending Timestamp to assume 24-hour days by default as well; anecdotally when I was using calendar units to perform arithmetic on Timestamp values and being personally aware that without specifying a date/timezone operations such as adding or subtracting n days would be a rough estimate at best, there was one instance where I admit that the current design (after running into panics at runtime because I assumed std::ops::Sub would have Output=Result<..> if it could panic on routine math) led me to revisit the approach and have a more precise result (though it was admittedly outnumbered by the number of places I did indeed just want a 24-hour approximation of a day).

Yeah I think for something like this where you specifically don't care about time zones, I wouldn't use Span.

The original design of the library tried to get away with just a Span type. But I was convinced to add SignedDuration. The use cases you describe is one reason. If you're specifically saying, "my use case doesn't have calendar or time zone footguns and all I care about is UTC," then it's fine IMO to abdice Span.

I personally found the concept of using tuples to create a "tagged version" of the original value that has the SpanRelativeTo::days_are_24_hours() marker to be unorthodox. I understand how it simplifies/optimizes the design of the library types, but it's neigh undiscoverable without referencing the docs (and not at all via editor completions). Providing an api that allows opting into certain behavior is difficult without an explosion of types; generics would make this a lot easier but I'm assuming you've intentionally made a decision to forgo their use. The obvious suggestions that occur to me:

I don't think it's unorthodox? The tuples are just targets for the Into trait for convenient call sites. If you don't like the tuples, you can use the builder types. If editor completions aren't working for that use case, then they can and should be improved. It doesn't seem crazy for LSP servers to account for something like that.

or taking a leaf from some other libraries, restructure the resulting Error to internally include the would-be result if 24-hour days were assumed, then add a helper method to Result<_, Error> to assert 24-hour days post-facto, converting a would-be-error into success; this is possibly best illustrated by example

This is kinda interesting but feels a little too cute. IMO, the better answer is for you to just use SignedDuration since it seems like you don't care about calendar units anyway?

It's hinted at with the first part of this issue, but I'm uneasy with the lack of PartialOrd and Eq for Span values; it really does drive one towards SignedDuration which is rather unfortunate since it's not the intended way to hold the library. I wonder if documenting repeatedly the possible performance gotchas of using the Eq and PartialOrd impls would be sufficient to avoid the current song and dance needed to compare spans? Also (and only from an abundance of precaution), I am unsure if the fieldwise() method might lead unwary devs to incorrectly using that to perform equivalence checks? I really don't see much use for the fieldwise operation in general date/time-programming aside from unit testing the library itself; I wonder if it's possible to perform a semantic eq() (if not also cmp()) operation fast enough with some clever tricks to make it acceptable.

Where did you get the impression that the missing Eq and Ord impls is because of performance? That's really not it at all. It's maybe a factor, but it's because units of days are higher are ambiguous in their precise length. You need a relative datetime to resolve it.

Otherwise, maybe lean into SignedDuration more and have diffing two Timestamp values return SignedDuration instead of Span, as that's probably the most common/likely reason to compare?

This is an interesting suggestion. Particularly since I've suggested using SignedDuration with Timestamp. But this also seems surprising. Every other subtraction operation between datetime types in Jiff returns a Span. I think that's a pattern worth keeping even if it makes the "I only care about Unix timestamps" use case a pinch more verbose.

[mqudsi]

Thanks for your time and answers; I get where you're coming from with the naming convention and it makes sense now that you explain it that way (but I think I might still file an issue as it still continues to trip me up unless I'm consciously thinking about it, as I'm so used to names reflecting the quantity of the composing unit).

One question: every time I think I have a handle on what is and isn't allowed in terms of date/time arithmetic, I still run into something that makes me think I'm not there yet. Is there a reason Zoned doesn't implement Add/Sub<Span> (but you can do the math with .checked_add/sub(Span{}))? I thought from my understanding that this, at last, was finally an operation that one could fairly reliably perform even with calendar units (currently I'm unwrapping the result of Zoned::checked_add(Span) if the span input is hard-coded... should I not be, i.e. is there a gotcha I'm not taking into account?)

[BurntSushi]

Those traits are implemented, but on &Zoned instead of Zoned because Zoned is not Copy (unlike every other datetime primitive in Jiff). I wish it were Copy. There are closed issues discussing the problems with making it Copy.

There are examples of arithmetic in the docs for Zoned.

(currently I'm unwrapping the result of Zoned::checked_add(Span) if the span input is hard-coded... should I not be, i.e. is there a gotcha I'm not taking into account?)

The only error that can occur here is overflow. So if you're okay with a panic on overflow then what you're doing is fine.

[mqudsi]

Thanks, that would explain it. It is unfortunate that Zoned isn't Copy, but must it be in order to have this impl? There are legitimate cases where you want to (or don't care if you) consume the Zoned you have on hand, and for the cases where that's not the case, well, rust users are very used to going back and adding & before a value they logged or did something else with to prevent it from being consumed and extend its lifetime.

e.g. the usecase I ran into, lifted as-is from my code (as guided by the one-to-one conversion between Timestamp and Zoned and the requirement to use relative dates for performing arithmetic):

let one_year_ago =  Timestamp::now()
                    .in_tz("Asia/Jerusalem")
                    .expect("TZ data must be available!")
                    .checked_sub(Span::new().years(1))
                    .unwrap()
                    .timestamp();

where I'd have happily used std::ops::Sub<Span> directly instead of using the checked_sub() route.

[BurntSushi]

I think you're suggesting adding the impl in addition to what is there? Can you open an issue for that? I am open to it. I worry about inference failures, but I think it might be worth it.

[mqudsi]

I am indeed and will do.