revise ergonomics / stringIO

README.md

@@ -1,4 +1,5 @@
 <!-- -*- coding: utf-8 -*- -->
+[![Zig](https://img.shields.io/badge/-Zig-F7A41D?style=flat&logo=zig&logoColor=white)](https://ziglang.org/)  [![tests](https://github.com/FObersteiner/zdt/actions/workflows/zdt-tests.yml/badge.svg)](https://github.com/FObersteiner/zdt/actions/workflows/zdt-tests.yml)  [![License: MPL 2.0](https://img.shields.io/badge/License-MPL_2.0-brightgreen.svg)](https://github.com/FObersteiner/zdt/blob/master/LICENSE)
 
 # zdt
 
@@ -7,15 +8,19 @@
 - [on Codeberg](https://codeberg.org/FObersteiner/zdt)
 - [on github](https://github.com/FObersteiner/zdt)
 
-Demo:
+[Demo](https://github.com/FObersteiner/zdt/blob/master/examples/ex_demo.zig):
 
 ```zig
+  var gpa = std.heap.GeneralPurposeAllocator(.{}){};
+  defer _ = gpa.deinit();
+  const allocator = gpa.allocator();
+
   var tz_LA = try zdt.Timezone.fromTzfile("America/Los_Angeles", allocator);
   defer tz_LA.deinit();
   var tz_Paris = try zdt.Timezone.fromTzfile("Europe/Paris", allocator);
   defer tz_Paris.deinit();
 
-  const a_datetime = try zdt.stringIO.parseISO8601("2022-03-07");
+  const a_datetime = try zdt.parseISO8601("2022-03-07");
   const this_time_LA = try a_datetime.tzLocalize(tz_LA);
   const this_time_Paris = try this_time_LA.tzConvert(tz_Paris);
 
@@ -55,17 +60,18 @@ See [changelog](https://codeberg.org/FObersteiner/zdt/src/branch/main/docs/chang
 
 ## Zig version
 
-This library is developed with Zig `0.14.0-dev`, might not compile with older versions. As of 2024-08-07, Zig-0.13 stable or higher should work.
+This library is developed with Zig `0.14.0-dev`, might not compile with older versions. As of 2024-08-28, Zig-0.13 stable or higher should work.
 
-## Dependencies
+## IANA timezone database version
 
-- none
+- `zdt v0.2.1`: `2024a`
+- `zdt v0.2.0`: `2024a`
 
-## Time zone database
+## Dependencies, Development and 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-tz-database && zig build update-tz-version`.
+For development, to update the time zone database and the version info, run the following build steps: `zig build update-tz-database && zig build update-tz-version`. Some of the code generation is done with Python scripts, which require Python >= 3.9 (no third party packages required).
 
 ## License
 

docs/change.log

@@ -1,5 +1,10 @@
 # CHANGELOG
 
+## 2024-08-28, v0.2.1
+
+- change of ergonomics: `formatToString`, `parseToDatetime` and `parseISO8601` functions are now methods of the `zdt` struct (formerly `stringIO.[...]`). After importing zdt, they can be called like `zdt.formatToString` etc.
+- this is the first version that will be on github only. Having the same repository at both Codeberg and github is just too cumbersome.
+
 ## 2024-08-07, v0.2.0
 
 - add a complete embedding of the IANA tzdb that allows cross-compilation

examples/ex_datetime.zig

@@ -5,7 +5,6 @@ const zdt = @import("zdt");
 const Datetime = zdt.Datetime;
 const Duration = zdt.Duration;
 const Tz = zdt.Timezone;
-const str = zdt.stringIO;
 
 pub fn main() !void {
     println("---> datetime example", .{});

examples/ex_demo.zig

@@ -11,7 +11,7 @@ pub fn main() !void {
     var tz_Paris = try zdt.Timezone.fromTzfile("Europe/Paris", allocator);
     defer tz_Paris.deinit();
 
-    const a_datetime = try zdt.stringIO.parseISO8601("2022-03-07");
+    const a_datetime = try zdt.parseISO8601("2022-03-07");
     const this_time_LA = try a_datetime.tzLocalize(tz_LA);
     const this_time_Paris = try this_time_LA.tzConvert(tz_Paris);
 

examples/ex_offsetTz.zig

@@ -4,7 +4,6 @@ const builtin = @import("builtin");
 const zdt = @import("zdt");
 const Datetime = zdt.Datetime;
 const Tz = zdt.Timezone;
-const str = zdt.stringIO;
 
 pub fn main() !void {
     println("---> UTC offset time zone example", .{});

examples/ex_strings.zig

@@ -6,7 +6,6 @@ const zdt = @import("zdt");
 const Datetime = zdt.Datetime;
 const Duration = zdt.Duration;
 const Timezone = zdt.Timezone;
-const str = zdt.stringIO;
 
 pub fn main() !void {
     println("---> datetime example", .{});
@@ -18,20 +17,20 @@ pub fn main() !void {
     println("", .{});
     println("---> (usage) ISO8601: parse some allowed formats", .{});
     const date_only = "2014-08-23";
-    var parsed = try str.parseISO8601(date_only);
+    var parsed = try zdt.parseISO8601(date_only);
     assert(parsed.hour == 0);
     println("parsed '{s}'\n  to {s}", .{ date_only, parsed });
     // the default string representation of a zdt.Datetime instance is always ISO8601
 
     // we can have fractional seconds:
     const datetime_with_frac = "2014-08-23 12:15:56.123456789";
-    parsed = try str.parseISO8601(datetime_with_frac);
+    parsed = try zdt.parseISO8601(datetime_with_frac);
     assert(parsed.nanosecond == 123456789);
     println("parsed '{s}'\n  to {s}", .{ datetime_with_frac, parsed });
 
     // we can also have a leap second, and a time zone specifier (Z == UTC):
     const leap_datetime = "2016-12-31T23:59:60Z";
-    parsed = try str.parseISO8601(leap_datetime);
+    parsed = try zdt.parseISO8601(leap_datetime);
     assert(parsed.second == 60);
     assert(std.meta.eql(parsed.tzinfo.?, Timezone.UTC));
     println("parsed '{s}'\n  to {s}", .{ leap_datetime, parsed });
@@ -41,7 +40,7 @@ pub fn main() !void {
     println("", .{});
     println("---> (usage): parse some non-standard format", .{});
     const dayfirst_dtstr = "23.7.2021, 9:45h";
-    parsed = try str.parseToDatetime("%d.%m.%Y, %H:%Mh", dayfirst_dtstr);
+    parsed = try zdt.parseToDatetime("%d.%m.%Y, %H:%Mh", dayfirst_dtstr);
     assert(parsed.day == 23);
     println("parsed '{s}'\n  to {s}", .{ dayfirst_dtstr, parsed });
 
@@ -55,7 +54,7 @@ pub fn main() !void {
     var s = std.ArrayList(u8).init(allocator);
     defer s.deinit();
     // the formatting directive is comptime-known:
-    try str.formatToString(s.writer(), "%a, %b %d %Y, %H:%Mh", parsed);
+    try zdt.formatToString(s.writer(), "%a, %b %d %Y, %H:%Mh", parsed);
     println("formatted {s}\n  to '{s}'", .{ parsed, s.items });
 }
 

examples/ex_timezones.zig

@@ -4,7 +4,6 @@ const builtin = @import("builtin");
 const zdt = @import("zdt");
 const Datetime = zdt.Datetime;
 const Tz = zdt.Timezone;
-const str = zdt.stringIO;
 
 pub fn main() !void {
     println("---> time zones example", .{});

lib/Timezone.zig

@@ -67,7 +67,7 @@ pub fn abbreviation(tz: *Timezone) []const u8 {
     return std.mem.sliceTo(tz.tzOffset.?.__abbrev_data[0..], 0);
 }
 
-/// Make a time zone from a IANA tz database TZif data, taken from the embedded tzdata.
+/// Make a time zone from IANA tz database TZif data, taken from the embedded tzdata.
 /// The caller must make sure to de-allocate memory used for storing the TZif file's content
 /// by calling the deinit method of the returned TZ instance.
 pub fn fromTzdata(identifier: []const u8, allocator: std.mem.Allocator) TzError!Timezone {
@@ -90,6 +90,8 @@ pub fn fromTzdata(identifier: []const u8, allocator: std.mem.Allocator) TzError!
 }
 
 /// Make a time zone from a IANA tz database TZif file. The identifier must be comptime-known.
+/// This method allows the usage of a user-supplied tzdata; that path has to be specified
+/// via the tzdb_prefix option in the build.zig.
 /// The caller must make sure to de-allocate memory used for storing the TZif file's content
 /// by calling the deinit method of the returned TZ instance.
 pub fn fromTzfile(comptime identifier: []const u8, allocator: std.mem.Allocator) !Timezone {

lib/windows/windows_tznames.zig

@@ -3,7 +3,7 @@
 //
 // --- Do not edit ---
 //
-// latest referesh: 2024-08-07T15:27:54+00:00
+// latest referesh: 2024-08-28T14:40:36+00:00
 // windows_names are sorted alphabetically so we can do binary search (later)
 pub const windows_names = [_][]const u8{
     "AUS Central Standard Time",