Timezone-aware datetime - zdt

  • datetime and timezone handling in one lib
  • no separate types for date and time
  • hybrid approach: datetime combines incremental and field based representation (Unix time, year, month, etc. fields)
  • relatively simple concept for time zone type (IANA-db file and/or offset from UTC)
  • uses the TZif parser from the Zig standard library

This post is sort of a follow-up to What’s the state of datetime in Zig?. I’m happy that writing a library to handle datetime with time zones worked out well, Zig is fun to code in and its context (the community etc.) is nice. The goal for zdt is “exploration”, not to build something according to some spec. There’s probably a lot to do better, and a lot of edge cases to catch.

Some context; the proposal to add datetime functionality to the Zig standard lib is still open. There also has been a pull request, which is now closed (2024-01-08).


Time for an update.

Thanks to you people here, answering all my noob question, I could add a couple of features :sunglasses: Notably,

  • an ISO8601 string parser, which infers the input format at runtime
  • implementation of the IANA time zone database within the package, so it can be used cross-platform
  • a method to obtain the local time zone (Linux and Windows)

You can find demos for these features in the examples. There’s a build-step to compile them, zig build examples.


DST transition coming up for folks in Europe :sunny:

var tz_Paris = try zdt.Timezone.fromTzfile("Europe/Paris", allocator);
defer tz_Paris.deinit();

_ = zdt.Datetime.fromFields(.{
    .year = 2024,
    .month = 3,
    .day = 31,
    .hour = 2,
    .tzinfo = tz_Paris,
}) catch |err| {
    std.debug.print("oops, cannot create datetime; {}", .{err});
>>> oops, cannot create datetime; error.NonexistentDatetime

concerning zdt code, I’ve made a “clone” on github,

…mainly to try github actions with Zig and autodoc generation on github pages (not working at the moment due to this problem).


That’s cool. Things like date time are so complex that some people find unattractive, but so fundamental that we need them for any mundane work.

Last time I wanted a decent date time library with Zig, I reached out for a very crude solution with strftime attached with a microsecond timestamp (as Python did). I believe established Zig users such as Bun and Tigerbeetle have their own implementation, too, but there seems not to be a standalone excerpt anyway.

Cool, man!

1 Like

BTW, how popular is Code Berg in Deutschland?

Thanks! Yeah there’s a couple of related projects out there, I’ve collected a few in the misc/advanced document in the docs. I think it is perfectly fine to make a case-specific date/time implementation; that’s part of Zig’s philosophy I guess. In many cases, you don’t need time zone support for example, which makes things a lot simpler. Performance and memory limitations might also play a role, if you think embedded devices for instance. And as you say, using a platform’s C library (time struct, strftime/strptime etc.) is also relatively easy to include in Zig.

BTW, how popular is Code Berg in Deutschland?

I have no idea actually; I started using it the same time I started dabbling in Zig, which was only end of last year ^^