Getting all ISO weeks for a year

[luc4hu]

Hi there!

First of all, let me say that I really enjoy jiff and its thorough documentation.

My use case is that I want to aggregate some statistics for every week of a given target year. I need the weeks to always contain 7 days, so I think going for the ISO week date format is the correct choice.

Here's a working version:

use jiff::civil::ISOWeekDate;

fn main() {
    let target_year = 2024;
    let iso_week_date = ISOWeekDate::new(target_year, 1, jiff::civil::Weekday::Monday).unwrap();

    let weeks_in_year = if iso_week_date.in_long_year() { 53 } else { 52 };

    for week_number in 1..=weeks_in_year {
        let start_of_week = ISOWeekDate::new(
            iso_week_date.year(),
            week_number,
            jiff::civil::Weekday::Monday,
        )
        .unwrap();

        let end_of_week = ISOWeekDate::new(
            iso_week_date.year(),
            week_number,
            jiff::civil::Weekday::Sunday,
        )
        .unwrap();

        println!(
            "ISO week {}: {} - {}",
            week_number,
            start_of_week.date(),
            end_of_week.date()
        );
    }
}

Is there a better way to calculate this?
One thing that bothers me a little is that I need some manual handling for getting the number of weeks in a year.

C# offers a convenient function to get the number of weeks.

Is there a specific design decision behind omitting this function?

[BurntSushi]

I see this as similar to Date::days_in_month, so yeah, I'd be happy to have ISOWeekDate::weeks_in_year.

I mostly kept ISO 8601 week date support pretty bare bones because I was unclear on how broadly used it was. But I'm generally happy to beef up the ISOWeekDate type with more methods.

Another thing that would probably make this easier is adding an analog to Date::series, but for ISOWeekDate. Then you could do something like this: https://docs.rs/jiff/latest/jiff/civil/struct.Date.html#example-how-many-times-do-i-mow-the-lawn-in-a-year

And it probably makes sense to have ISOWeekDate::{first_of_week,last_of_week,first_of_year,last_of_year} as well. If you combine those with ISOWeekDate::series, then it should simplify your code quite a bit I think:

use jiff::civil::ISOWeekDate;

fn main() {
    let target_year = 2024;
    let iso_week_date = ISOWeekDate::new(target_year, 1, jiff::civil::Weekday::Monday).unwrap();
    let end = iso_week_date.last_of_year().unwrap(); // i think this has to be fallible? maybe not
    for start_of_week in iso_week_date.series(1.week()).take_while(|&wd| wd <= end) {
        let end_of_week = start_of_week.last_of_week().unwrap(); // i think also needs to be fallible
        println!(
            "ISO week {}: {} - {}",
            start_of_week.week(),
            start_of_week.date(),
            end_of_week.date()
        );
    }
}

Or something like that. Main I think I think is that the first-of/last-of routines might need to be fallible because I believe they can overflow Jiff's datetime limits. Kind of a bummer, but probably not a big deal. They would only fail near -009999-01-01 and 9999-12-31.

[luc4hu]

Sounds great! Good catch regarding the fallibility.

Aside:
Is there a typo here? (It mentions every 5 hours but increases in periods of 15 hours)

[BurntSushi]

Yeah, definitely a typo. Probably just leftovers from my initial attempt at an example. Or a copy-and-paste error.

[BurntSushi]

Filled out an issue requesting this more specifically: #227

I'm going to try to sneak this into jiff 0.1 before the jiff 0.2 release. It shouldn't be too much work.

[BurntSushi]

OK, once #229 is merged and released, you should be able to write the snippet above like so:

use jiff::{
    civil::{ISOWeekDate, Weekday},
    ToSpan,
};

fn main() -> anyhow::Result<()> {
    let target_year = 2024;
    let iso_week_date = ISOWeekDate::new(target_year, 1, Weekday::Monday)?;
    let weeks = iso_week_date
        .date()
        .series(1.week())
        .map(|d| d.iso_week_date())
        .take_while(|wd| wd.year() == target_year);
    for start_of_week in weeks {
        let end_of_week = start_of_week.last_of_week()?;
        println!(
            "ISO week {}: {} - {}",
            start_of_week.week(),
            start_of_week.date(),
            end_of_week.date()
        );
    }
    Ok(())
}

See the PR description for why I didn't add ISOWeekDate::series. I think it would end up provoking bugs. But it's easy enough I think to map between Gregorian and the ISO 8601 week calendar. So overall, I think the main simplification here compared to what you had is just letting Date::series do the work of enumerating dates for you, and the new ISOWeekDate::last_of_week absolves you of needing to hand-construct the end of the week.