Why no Zoned::iso_week() or Zoned::iso_week_day()?

[35VLG84]

Currently ISO-Week-Date related APIs are under jiff::civil::iso_week_date::ISOWeekDate.

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

let weekdate = date(1948, 12, 31).to_iso_week_date();
assert_eq!(weekdate.year(), 1948);
assert_eq!(weekdate.week(), 53);
assert_eq!(weekdate.weekday(), Weekday::Friday);

The first question is why there isn't direct Zoned based access to iso-week?

The iso-week-date is changing with the Date Line, and hence it's bound to timezone. So my initial thought was that it must be located on Zoned. It's also confusing (to me) that Zoned have year(), month() and day(), days_in_month(), day_of_year(), etc. functions, but no iso_week_year(), iso_week() or iso_week_day() API-functions. This makes the API (to me at least) asymmetrical, and I was actually so confused about this, that I had to ripgrep it.

So could there be an option to have iso_week APIs on Zoned? Or if this is not possible, some explanation could help to approach the API structure.

The second question on #196 was the usage of ISO week calendar in the first place:

The context here is Northern Europe (Finland and Scandinavia) and metric country (but also applicable pretty much to whole Europe). First day of week is Monday and the first week of the year is the week which have Thursday. So actually calendars are based on ISO-Weeks naturally by standardization.

On top of that, it's really common to refer weeks by their numbers in spoken and written communication: "I go on vacation on week 8" etc. Also all printed calendars have week numbers on the left column, and people enable week number views in Outlook. So (iso) week numbers are widely used, and pretty much every system should support them (if you like to do any "calendary" stuff).

The situation is different in other parts of world, but here it's very common, especially the iso-week numbers (2025-01-10 -> W2).

[BurntSushi]

The second question on #196 was the usage of ISO week calendar in the first place:

The context here is Northern Europe (Finland and Scandinavia) and metric country (but also applicable pretty much to whole Europe). First day of week is Monday and the first week of the year is the week which have Thursday. So actually calendars are based on ISO-Weeks naturally by standardization.

On top of that, it's really common to refer weeks by their numbers in spoken and written communication: "I go on vacation on week 8" etc. Also all printed calendars have week numbers on the left column, and people enable week number views in Outlook. So (iso) week numbers are widely used, and pretty much every system should support them (if you like to do any "calendary" stuff).

The situation is different in other parts of world, but here it's very common, especially the iso-week numbers (2025-01-10 -> W2).

This is a fascinating response! Thank you. I had no idea. Here in my part of the world (New England), ISO week dates are unheard of in every day life. I thought it was mostly used in finance applications or other bespoke systems. So this improves my understanding quite a bit, thank you.

So could there be an option to have iso_week APIs on Zoned? Or if this is not possible, some explanation could help to approach the API structure.

OK, so yeah, this is almost 100% an API design question. I shipped the current API as a conservative posture. In part, because I didn't understand when or how often ISO week dates would be used and in part because there are some costs involved here. Methods like Zoned::year and Zoned::day are zero cost getters. But computing the ISO week date takes some work. With that said, there are methods on Zoned, like weekday, that also do non-trivial work. So this isn't a super compelling answer on its own.

Here is what I propose:

• Add Zoned::to_iso_week_date and civil::DateTime::to_iso_week_date methods as convenience routines for x.date().to_iso_week_date().
• In jiff 0.2, rename all to_iso_week_date methods to iso_week_date to make them consistent with other getter APIs (since not all getter APIs are free per se).

This proposal does leave out iso_week{_year,,_day} methods. My motivation for that is that the above API encourages users to compute the ISO week date once, where as forwarding the getters on ISOWeekDate for year/week/day will cause code to unnecessarily re-compute the week date for each access of year, week, day.

I also still generally perceive the ISO week dates as at least a couple orders of magnitude (if not more) less common than the Gregorian calendar, so I'm not sure it's common enough to warrant proxying all of its methods (or even beefing up Zoned to pre-compute the ISO week date like it does for the civil Gregorian datetime so as to make hypothetical methods like iso_week_year effectively free).

I think if Zoned had a to_iso_week_date method, then that would have at least solved your discoverability problem.

What do you think?

[35VLG84]

I think this is very well balanced and really good way to go forward, thank you!

The iso-weeks are not so widely used, the getters are not free, and secondly this API:

• In jiff 0.2, rename all to_iso_week_date methods to iso_week_date to make them consistent with other getter APIs (since not all getter APIs are free per se).

This proposal does leave out iso_week{_year,,_day} methods.

Would also encourage people to use iso_week_date to get real ISOWeekDate object and avoid the trap of using Zoned::year as iso-year accidentally:

        let zdt: Zoned = "2010-01-03 12:00:00[UTC]".parse()?;
        
        let iso_week_year = zdt.date().to_iso_week_date().year();
        
        assert_eq!(zdt.year(),    2010);
        assert_eq!(iso_week_year, 2009);

So +1 for dropping direct iso_week_year, etc. getters from Zoned. Also the iso_week_date nicely conveys the fact that for actual iso-week-date, you need the full triplet to have the real date. For example 2010-01-03 it's 2009-W53-7 .

On the same token, could it be possible to have ISOWeekDate::day which would give iso-week day number (7)? (As a companion getter to the existing ISOWeekDate::weekday)?

If so, then the API would be:

• ISOWeekDate::year -> i16
• ISOWeekDate::week -> i8
• ISOWeekDate::weekday -> Weekday
• ISOWeekDate::day -> i8

Which covers the most common (all?) use cases nicely.

I think if Zoned had a to_iso_week_date method, then that would have at least solved your discoverability problem.

Absolutely. Thank you for taking this into consideration, and coming up with this solution!

[35VLG84]

Out of curiosity, question about maintaining libraries and compatibility in general with Rust:

Why could not Zoned and civil::DateTime have directly iso_week_date as convenience routines in 0.1? There aren't any such methods at the moment, and then there would be compatible path over 0.1 to 0.2, wouldn't there?

[BurntSushi]

With respect to ISOWeekDate::day, I originally did not add that because I think it might be too easy to get tripped up over whether the day is zero or one offset, and which day of the week is the beginning. The "monday starts the week at offset 1" might be very natural to you, but it is very weird to me and I imagine others. And yes, I know a monday start with offset 1 is what ISO 8601 mandates so it is technically correct, but I am still concerned about making it too easy to flub things. With the current API, you need to be very explicit to get an ISO week day offset and I think makes it harder to mess up.

So for now at least, I'm probably going to pass on that API. Since it's an API addition, I'm willing to revisit it as we all collectively get more experience with Jiff and where pain points are. But I wouldn't be surprised if it never appears to be honest.

Why could not Zoned and civil::DateTime have directly iso_week_date as convenience routines in 0.1? There aren't any such methods at the moment, and then there would be compatible path over 0.1 to 0.2, wouldn't there?

They can. But Date::to_iso_week_date already exists, and I'd rather their naming be consistent. So we can add Zoned::to_iso_week_date and civil::DateTime::to_iso_week_date in jiff 0.1, and then switch all of them over to the X::iso_week_date naming convention.

I think there are some other to_ APIs worth renaming too. ISOWeekDate::to_date I guess should just be date. I think the to_ prefix is technically correct here according to Rust API naming conventions, but there are a whole bunch of methods like Zoned::weekday that don't follow this convention. And it feels unergonomic to do so. On the other hand, if we consistently applied the to_ prefix to methods that "do work" for the conversion, then it would be clearer which methods are effectively free getters and which methods are doing actual work. On the other hand, this is potentially an implementation detail that could change in the future.

Sorry for the word vomit, but that's what's in my head. :-)

[35VLG84]

That's good, thanks for the explanation. I will close this as answered as I don't have any other questions or comments for now. Thank you again for taking this proposal into consideration (and working with jiff! - Implementing sane and good datetime library is really tricky business).