Proposal: Expose time zone transitions (if any)

[david7a68]

Hi!

I'm evaluating Jiff for a project specifically for its time zone support and it does everything that I need except for a way to list time zone transitions up front.

A method such similar to jiff::tz::TimeZoneDatabase::available(), like jiff::tz::TimeZone::transitions() would be very helpful.

Would it be possible to add support for such?

I took a look around and see that it is probably a relatively minor change, but no other time crate seems to support the same and I suspect there are reasons for that.

Edit: in particular, I want to extract the most recent 'standard time' and any following transitions' start and end date/time and UTC offset, as you note here.

[BurntSushi]

For Jiff specifically, the only reason these APIs don't exist is because I didn't have a solid use case in front of me. But they do actually exist internally:

https://github.com/BurntSushi/jiff/blob/d3e0a16495df21ba86b908f6152932178753e5f0/src/tz/mod.rs#L968-L995

For the other datetime libraries, the only one that offers any kind of tzdb integration at all is chrono with either chrono-tz or tzfile. But there are overall some problems with its integration. One of them is that chrono doesn't support dealing with gaps in any way other than erroring out of the box.

Now, the previous_transition and next_transition APIs aren't exactly what you're asking for. Specifically, they're a little more low level than just providing an iterator over all transitions. But you can of course build iteration on top of them. For example, this is a program I wrote a while back that finds odd entries in tzdb where the "start" of the day doesn't correspond to midnight:

// from: https://github.com/tc39/proposal-temporal/issues/2910#issuecomment-2210233347

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

fn main() -> anyhow::Result<()> {
    let start = date(1800, 1, 1).intz("UTC")?.timestamp();
    let end = date(2050, 1, 1).intz("UTC")?.timestamp();
    for tzname in tz::db().available() {
        if tzname.starts_with("posix/") || tzname.starts_with("right/") {
            continue;
        }
        let tz = tz::db().get(&tzname)?;
        let Some(mut instant) = tz.next_transition(start) else { continue };
        while instant <= end {
            let zdt = instant.to_zoned(tz.clone());
            let start = zdt.start_of_day()?;
            if zdt != start && start.hour() != 0 {
                println!("{zdt} != {start}");
            }

            instant = match tz.next_transition(instant) {
                None => break,
                Some(instant) => instant,
            };
        }
    }

    Ok(())
}

So, can you say more about what you need from this API? As in, what do you want to use it for?

[david7a68]

I have an embedded device that has to deal with scheduling in civil time with an API provided by its SDK akin to this:

struct DstTransitions {
    start: DateTime, // in local standard time
    end: DateTime, // in local standard time
}

fn set_time(utc_offset_seconds: u32, transitions: &[DstTransitions]); 

For some arbitrary number of transitions to-and-from DST (i.e. typically 2 per year). The expectation is that one provides as many DST transitions as the device is expected to operate (updating as necessary). If the local civil time authorities don't change anything, this would operate for a decade or more without needing any changes.

I fully acknowledge that this is probably a rather niche use case, and would totally understand if this isn't something you want to support.

[BurntSushi]

Aye. No I do want to support it. I do want to expose the transitions. I just want to be careful about the API that is exposed. :)

Thank you for sharing. I think I understand the use case. I believe that the existing internal API would work for you. But I do want to include the offset with the timestamp.

I'll open a PR soon and CC you and ask you to confirm that the API works for your use case

[david7a68]

Awesome, thank you.