https://github.com/fobersteiner/zdt
Timezoned Datetime in Zig
https://github.com/fobersteiner/zdt
date datetime duration time timezones zig zig-package ziglang
Last synced: about 1 month ago
JSON representation
Timezoned Datetime in Zig
- Host: GitHub
- URL: https://github.com/fobersteiner/zdt
- Owner: FObersteiner
- License: mpl-2.0
- Created: 2024-05-04T10:06:10.000Z (12 months ago)
- Default Branch: master
- Last Pushed: 2025-02-14T19:35:40.000Z (2 months ago)
- Last Synced: 2025-02-19T13:21:39.698Z (2 months ago)
- Topics: date, datetime, duration, time, timezones, zig, zig-package, ziglang
- Language: Zig
- Homepage: https://fobersteiner.github.io/zdt/
- Size: 10.4 MB
- Stars: 16
- Watchers: 1
- Forks: 2
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://ziglang.org/) ⚡ [](https://github.com/FObersteiner/zdt/actions/workflows/zdt-tests.yml) [](https://github.com/FObersteiner/zdt/releases) [](https://www.iana.org/time-zones) [](https://github.com/FObersteiner/zdt/blob/master/LICENSE)
# zdt
**Timezoned Datetime in Zig.** Opinionated, and mostly for learning purposes.
- [API overview](https://github.com/FObersteiner/zdt/wiki/API-overview)
- [Examples](https://github.com/FObersteiner/zdt/tree/master/examples)
- [Roadmap](https://github.com/FObersteiner/zdt/wiki/Roadmap)
### [Demo](https://github.com/FObersteiner/zdt/blob/master/examples/demo.zig)
```zig
// need an allocator for the time zones since the size of the rule-files varies.
var gpa = std.heap.GeneralPurposeAllocator(.{}){};
defer _ = gpa.deinit();
const allocator = gpa.allocator();
// zdt embeds the IANA tz database:
var tz_LA = try zdt.Timezone.fromTzdata("America/Los_Angeles", allocator);
defer tz_LA.deinit();
// you can also use your system's tz data at runtime;
// this will very likely not work on Windows, so we use the embedded version here as well.
var tz_Paris = switch (builtin.os.tag) {
.windows => try zdt.Timezone.fromTzdata("Europe/Paris", allocator),
else => try zdt.Timezone.fromSystemTzdata("Europe/Paris", zdt.Timezone.tzdb_prefix, allocator),
};
defer tz_Paris.deinit();
// ISO8601 parser on-board, accepts wide variety of compatible formats
const a_datetime = try zdt.Datetime.fromISO8601("2022-03-07");
const this_time_LA = try a_datetime.tzLocalize(.{ .tz = &tz_LA });
// string output also requires allocation...
var buf = std.ArrayList(u8).init(allocator);
defer buf.deinit();
try this_time_LA.toString("%I %p, %Z", buf.writer());
const this_time_Paris = try this_time_LA.tzConvert(.{ .tz = &tz_Paris });
// '{s}' directive gives ISO8601 format by default;
std.debug.print(
"Time, LA : {s} ({s})\n... that's {s} in Paris ({s})\n\n",
.{ this_time_LA, buf.items, this_time_Paris, this_time_Paris.tzAbbreviation() },
);
// Time, LA : 2022-03-07T00:00:00-08:00 (12 am, PST)
// ... that's 2022-03-07T09:00:00+01:00 in Paris
const wall_diff = try this_time_Paris.diffWall(this_time_LA);
const abs_diff = this_time_Paris.diff(this_time_LA);
std.debug.print("Wall clock time difference: {s}\nAbsolute time difference: {s}\n\n", .{ wall_diff, abs_diff });
// Wall clock time difference: PT9H
// Absolute time difference: PT0S
// Easteregg:
const now = zdt.Datetime.nowUTC();
const easter_date = try zdt.Datetime.EasterDate(now.year);
buf.clearAndFree();
try easter_date.toString("%B %d, %Y", buf.writer());
std.debug.print("Easter this year is on {s}\n", .{buf.items});
// Easter this year is on April 20, 2025
```
## Documentation
See [Wiki](https://github.com/FObersteiner/zdt/wiki)
## Credits
- inspiration for early version of parser, and most of the POSIX TZ code: [leroycep/zig-tzif](https://github.com/leroycep/zig-tzif)
- date <--> days since Unix epoch conversion, algorithm: [cassioneri/eaf](https://github.com/cassioneri/eaf) . Zig implementation: [travisstaloch/date-zig](https://github.com/travisstaloch/date-zig)
- general support from
## Development
See [changelog](https://github.com/FObersteiner/zdt/blob/master/CHANGELOG.md)
## Zig version
- zdt v0.6.x: Zig 0.14
- zdt v0.5.x: Zig 0.13 / 0.14
- zdt v0.4.x: Zig 0.13
This library is developed with Zig 'master' - this might sometimes introduce version incompatibilities. If you just want to use the library, use a tagged version that suites your Zig version.
## IANA timezone database version
- `v0.4.5+`: `2025a` (current)
- `v0.2.2+`: `2024b`
- `>= v0.2.1`: `2024a`
## Dependencies, Development and Time zone database
- No dependencies on other libraries.
- Time zone database: `zdt` comes with [eggert/tz](https://github.com/eggert/tz). The database is compiled and shipped with `zdt` (as-is; not tar-balled or compressed).
- if you wish to use your own version of the [IANA time zone db](https://www.iana.org/time-zones), you can set a path to it using the `-Dprefix-tzdb="path/to/your/tzdb"` option. See also `zig build --help`.
- For development: to update the time zone database and the version info, run the following build steps: `zig build update-tzdb`. Some of the code generation is done with Python scripts, which require Python >= 3.9 but no third party packages, i.e. a system installation will do.
## License
MPL. See the LICENSE file in the root directory of the repository.