Why doesn't Jiff support 3.years() + 1.month() + 5.days() + 10.hours()?

[BurntSushi]

One of the most popular remarks about Jiff (other than the pronunciation of its name) is a question about why spans can't be added together using the + operator. Typically, this is asked about in the context of looking for a better way of constructing spans. For example, #37 suggests it as a way of avoiding getters with a get_ prefix. Others have suggested it because 3.years().months(1).days(5).hours(10) can read a little awkwardly because the 3 precedes the unit name, but the rest of the units follow the unit name. But 3.years() + 1.month() + 5.days() + 10.hours() reads pretty nicely and there is some precedent in other datetime libraries.

So why doesn't Jiff support that syntax? And if we really wanted to add it, how would we go about it?

[BurntSushi]

I think the simplest way to look at the essential problem here is to ask this: what is the answer to 2.months().days(25) + 10.days()? Well, Jiff provides Span::checked_add. And surely, span1 + span2 would just use Span::checked_add and panic on failure, right? Right? Right? And surely, there is absolutely nothing wrong with adding together these two spans!

use jiff::ToSpan;

fn main() -> anyhow::Result<()> {
    let sp1 = 2.months().days(25);
    let sp2 = 10.days();
    let sum = sp1.checked_add(sp2)?;
    println!("{sum}");
    Ok(())
}

Has this output:

$ cargo -q r
Error: using largest unit (which is 'month') in given span requires that a relative reference time be given, but none was provided

Oops. So that fails. Indeed, whenever adding spans with non-uniform units (like months), you need to provide a reference date. Otherwise, you can't know how long that month actually is. And crucially, Jiff specifically avoids returning "unbalanced" spans like 2 months 35 days. So add a date to the mix and things work fine:

use jiff::{civil::date, ToSpan};

fn main() -> anyhow::Result<()> {
    let sp1 = 2.months().days(25);
    let sp2 = 10.days();
    let sum = sp1.checked_add((sp2, date(2024, 7, 24)))?;
    println!("{sum}");
    Ok(())
}

And its output is:

$ cargo -q r
P3m5d

What we get out is a nice span that isn't bottom heavy. The smaller units "overflowed" and this caused the bigger units to go up. This behavior isn't going to change. It's a key selling point of Jiff's Span type.

You can probably already start to see the shape of the problem here. span1 + span2 leaves no room for reference dates. You just have spans. That means not all spans can be added together using Jiff's balancing logic, and this in turn means that if we were to rely on span1 + span2 to set units, then not all units could be set this way. This would be very sad.

An alternative would be to declare that span1 + span2 does component addition. That is, each corresponding component is added together without any "smarts." So, 2.months().days(25) + 10.days() would just be 2.months().days(35). It's a bottom heavy span, and while Jiff specifically never creates bottom heavy spans, it has no problem dealing with them. They are perfectly legal. For example, Span::new().months(2).days(35) is such a bottom heavy span that you can create today.

The main problem with the alternative, and one that I think is significant, is that its behavior doesn't match that of Span::checked_add. The only remedy to this, I think, is to make Span::checked_add provide component addition, and then introduce some new method for adding spans together in a way that is "smart" with a different name. I am very much against this approach because it promotes and emphasizes and makes easy the "wrong" thing. And the only benefit we get from it, as far as I can tell, is a nicer way of constructing spans. (I do agree that 2.days() + 5.hours() looks very nice.)

[epidemian]

Ohhh, alright! So, i missed a couple of important things when asking #37...

First, that Span did not support + another_span already. I thought it did, given the many impls of Add<Span> there already are. I should have actually tested it.

And i also missed all this re-balancing logic that Span::checked_add() does. It's quite nice that spans take care of this. But also, these are things that we probably don't care about when constructing a span. So i agree that overloading + for building spans doesn't seem right given the existence of checked_add.

When building spans, i guess what we want to say is "i want a span with these many days, and with these many hours, and so on".

---

So why doesn't Jiff support that syntax? And if we really wanted to add it, how would we go about it?

IDK if you're interested in brainstorming ideas given that this question is already answered. But if that's the case, here are some not-very-deeply-thought ideas 😅

• Having a Span::from() or Span::from_parts() that takes an array of other spans and just uses their fields naively without any addition logic:

  let span = Span::from([5.days(), 8.hours(), 1.minutes()]);

• Similarly, adding a .to_span() extension method to arrays of spans, or having an impl From<[Span; N]> for Span:

  let span = [5.days(), 8.hours(), 1.minutes()].to_span();
  // or...
  let span: Span = [5.days(), 8.hours(), 1.minutes()].into();

• Using another operator instead of +. The logical operators & or | immediately come to mind. Of these, my intuitive choice would be logical AND, since i'm reading this as "i want as span with this AND this AND this". But i guess a more set-theoretical person might scratch their head at this, since it would not be an intersection/logical conjunction, but more like a union of this, so they might prefer the logical OR:

  let span = 5.days() & 8.hours() & 1.minutes()];
  // or...
  let span = 5.days() | 8.hours() | 1.minutes()];

Of all these, my personal preference would be for the operator overloading approach (i don't have a strong preference for either & or | though). I think there's a sort of intuitiveness and beauty on trying to build more complex things by combining simpler things of the same kind 🙂

In fact, going the operator route, one could even imagine building the individual spans like 5.minutes() as multiples of unitary constant spans:

let span = 5 * DAY & 8 * HOUR & 1 * MINUTE;

IDK if i would prefer this TBH, but i wanted to mention it for brainstorming's sake.

[BurntSushi]

Yeah good brainstorms! The array ideas are interesting, and I don't think there would be anything wrong with having those construction APIs, but I don't think they improve much on the status quo.

The operator overloading for & or | is very intriguing. But I'd guess it would blow a "weirdness" budget. There would never be an end to "why use | instead of +?"

[epidemian]

The operator overloading for & or | is very intriguing. But I'd guess it would blow a "weirdness" budget.

It's funny how different languages have very different tolerances for what is consider weird. I think in Haskell or Smalltalk this would be tame, even the 5 * DAY & 8 * HOUR case 😅

There would never be an end to "why use | instead of +?"

True, but there'd be an authoritative answer, in the form of your own reply to this very discussion, which goes into detail about Span::checked_add 😉

The array ideas are interesting [...] but I don't think they improve much on the status quo.

Yeah, i would agree. I think it's important for a good API to have One True Way™ of doing things, and to consistently use it in all the documentation and examples.

Sometimes it can be justified to have two ways: the base API, with maximum flexibility but maybe not the most ideal ergonomics; and some convenient sugar API on top of it, to cover many common cases in a more with a more ergonomic alternative, but maybe not able to express all cases the base API covers. E.g., Iterator::sum() or any() being nice sugar over the more general for_each() or loops.

My intention here was to propose possible alternatives for the sugary API for common cases (what would now be the extension method on numbers + builder setters, i.e. 5.days().hours(8)).

But it definitely wouldn't be good to have too many different alternatives for doing the same thing.