Add a routine to convert time and date to 0-2 timestamps given a time zone name

Author: devries

CHANGELOG.md

@@ -1,3 +1,10 @@
+## Upcoming
+- Add a `tzcalendar.from_calendar` function. Test shifts around daylight savings
+  time.
+- Fixed an issue with the time zone change where comparisons of the timestamp to
+  the transition times with a greater than, and it should have been greater than
+  or equal to.
+
 ## v1.0.1 - 2025-09-23
 - Fix bug where the library will crash if asked to load Time Zone information
   from a nonexistant directory.

gleam.toml

@@ -1,5 +1,5 @@
 name = "tzif"
-version = "1.0.1"
+version = "1.1.0"
 
 # Fill out these fields if you intend to generate HTML documentation or publish
 # your project to the Hex package manager.

src/tzif/database.gleam

@@ -264,7 +264,7 @@ fn get_slice(
 
   slices
   |> list.fold_until(default, fn(acc, slice) {
-    case slice.start_time < seconds {
+    case slice.start_time <= seconds {
       True -> list.Continue(Ok(slice))
       False -> list.Stop(acc)
     }

src/tzif/tzcalendar.gleam

@@ -16,6 +16,7 @@
 //// article on Wikipedia. The time zone identifiers are passed to many of the
 //// functions of this library as the `zone_name` parameter.
 
+import gleam/list
 import gleam/result
 import gleam/time/calendar.{type Date, type TimeOfDay}
 import gleam/time/duration.{type Duration}
@@ -108,3 +109,59 @@ pub fn to_calendar(
 
   #(tiz.date, tiz.time_of_day)
 }
+
+/// Create a list of timestamps from a calendar date and time. This may produce zero, one
+/// or two timestamps in a list depending on if that time is possible in the given
+/// time zone or if it is ambiguous. This tends to happen every daylight saving
+/// period. When moving forward one hour, the calendar times during the skipped hour
+/// are not possible, so no timestamp values would be returned. When moving back
+/// one hour the overlap period is repeated, yielding two timestamps per wall clock time.
+///
+/// This
+/// returns a `TzDatabaseError` if there is an issue finding time zone information.
+pub fn from_calendar(
+  date: calendar.Date,
+  time: calendar.TimeOfDay,
+  zone_name: String,
+  db: TzDatabase,
+) -> Result(List(timestamp.Timestamp), database.TzDatabaseError) {
+  // Assume no shift will be more than 24 hours
+  let ts_utc = timestamp.from_calendar(date, time, duration.seconds(0))
+
+  // What are the offsets at +/- the 24 hour window
+  use before_zone <- result.try(
+    timestamp.add(ts_utc, duration.hours(-24))
+    |> database.get_zone_parameters(zone_name, db),
+  )
+  use after_zone <- result.try(
+    timestamp.add(ts_utc, duration.hours(24))
+    |> database.get_zone_parameters(zone_name, db),
+  )
+
+  case before_zone.offset == after_zone.offset {
+    True -> {
+      // No time shift in the period of interest. Easy conversion.
+      Ok([timestamp.from_calendar(date, time, before_zone.offset)])
+    }
+    False -> {
+      // Check that we get the same UTC offset if we convert the date and
+      // time to a timestamp using that offset and then find the offset
+      // of the time zone at that timestamp. This is a round trip from utc
+      // offset back to utc offset which should yield the same value if the utc
+      // offset we use is correct for the time zone at that time and date.
+      [before_zone.offset, after_zone.offset]
+      |> list.filter(fn(offset) {
+        let zone =
+          timestamp.from_calendar(date, time, offset)
+          |> database.get_zone_parameters(zone_name, db)
+        case zone {
+          Ok(database.ZoneParameters(round_trip_offset, _, _)) ->
+            offset == round_trip_offset
+          Error(_) -> False
+        }
+      })
+      |> list.map(fn(offset) { timestamp.from_calendar(date, time, offset) })
+      |> Ok
+    }
+  }
+}

test/tzif/tzcalendar_test.gleam

@@ -10,16 +10,22 @@ const tzsample = "VFppZjIAAAAAAAAAAAAAAAAAAAAAAAAGAAAABgAAAAAAAADsAAAABgAAABSAAA
 
 const tzsample2 = "VFppZjIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAAAAQAAAAAAABVVEMAVFppZjIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAAAAQAAAAAAABVVEMAClVUQzAK"
 
+const canberra = "VFppZjIAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAAAAAAAACOAAAABAAAAA6AAAAAnE7CgJy8LwDLVLMAy8dlgMy3VoDNp0eAzqBzAM+HKYADcDmABA0cAAVQG4AF9jiABy/9gAfWGoAJD9+ACbX8gArvwYALnxkADNjeAA1++wAOuMAAD17dABCYogARPr8AEniEABMeoQAUWGYAFP6DABY4SAAXDImAGCFkgBjHgYAaAUaAGqdjgBvhKIAch0WAHcEKgB55nIAfl7IAIFl+gCGAzoAiQpsAI2nrACQifQAlSc0AJe/qACcprwAnz8wAKQmRACmvrgAq6XMAK5jKgCzSj4AteKyALrJxgC9YjoAwklOAMV1agDJyNYAzPTyANFIXgDUdHoA2MfmANv0AgDgbFgA43OKAOafpgDq8xIA72toAPKXhAD26vAA+hcMAP5qeAEBlpQBBg7qAQkWHAENjnIBELqOARUN+gEYFSwBHI2CAR/eiAEjnkwBJ14QASsd1AEu3ZgBMp1cATZdIAE6HOQBPdyoAUHBVgFFgRoBSUDeAU0AogFQwGYBVIAqAVg/7gFb/7IBX792AWN/OgFnPv4Bav7CAW7jcAFyozQBdmL4AXoivAF94oABgaJEAYViCAGJIcwBjOGQAZChVAGUYRgBmEXGAZwFigGfxU4Bo4USAadE1gGrBJoBrsReAbKEIgG2Q+YBugOqAb3DbgHBqBwBxWfgAcknpAHM52gB0KcsAdRm8AHYJrQB2+Z4Ad+mPAHjZgAB5yXEAerliAHuyjYB8on6AfZJvgH6CYIB/clGAAwECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQAAjcQAAAAAmrABBAAAjKAACQAAjKAACUxNVABBRURUAEFFU1QAAAEBAFRaaWYyAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAjgAAAAQAAAAO/////3MWfzz/////nE7CgP////+cvC8A/////8tUswD/////y8dlgP/////Mt1aA/////82nR4D/////zqBzAP/////PhymAAAAAAANwOYAAAAAABA0cAAAAAAAFUBuAAAAAAAX2OIAAAAAABy/9gAAAAAAH1hqAAAAAAAkP34AAAAAACbX8gAAAAAAK78GAAAAAAAufGQAAAAAADNjeAAAAAAANfvsAAAAAAA64wAAAAAAAD17dAAAAAAAQmKIAAAAAABE+vwAAAAAAEniEAAAAAAATHqEAAAAAABRYZgAAAAAAFP6DAAAAAAAWOEgAAAAAABcMiYAAAAAAGCFkgAAAAAAYx4GAAAAAABoBRoAAAAAAGqdjgAAAAAAb4SiAAAAAAByHRYAAAAAAHcEKgAAAAAAeeZyAAAAAAB+XsgAAAAAAIFl+gAAAAAAhgM6AAAAAACJCmwAAAAAAI2nrAAAAAAAkIn0AAAAAACVJzQAAAAAAJe/qAAAAAAAnKa8AAAAAACfPzAAAAAAAKQmRAAAAAAApr64AAAAAACrpcwAAAAAAK5jKgAAAAAAs0o+AAAAAAC14rIAAAAAALrJxgAAAAAAvWI6AAAAAADCSU4AAAAAAMV1agAAAAAAycjWAAAAAADM9PIAAAAAANFIXgAAAAAA1HR6AAAAAADYx+YAAAAAANv0AgAAAAAA4GxYAAAAAADjc4oAAAAAAOafpgAAAAAA6vMSAAAAAADva2gAAAAAAPKXhAAAAAAA9urwAAAAAAD6FwwAAAAAAP5qeAAAAAABAZaUAAAAAAEGDuoAAAAAAQkWHAAAAAABDY5yAAAAAAEQuo4AAAAAARUN+gAAAAABGBUsAAAAAAEcjYIAAAAAAR/eiAAAAAABI55MAAAAAAEnXhAAAAAAASsd1AAAAAABLt2YAAAAAAEynVwAAAAAATZdIAAAAAABOhzkAAAAAAE93KgAAAAAAUHBVgAAAAABRYEaAAAAAAFJQN4AAAAAAU0AogAAAAABUMBmAAAAAAFUgCoAAAAAAVg/7gAAAAABW/+yAAAAAAFfv3YAAAAAAWN/OgAAAAABZz7+AAAAAAFq/sIAAAAAAW7jcAAAAAABcqM0AAAAAAF2YvgAAAAAAXoivAAAAAABfeKAAAAAAAGBokQAAAAAAYViCAAAAAABiSHMAAAAAAGM4ZAAAAAAAZChVAAAAAABlGEYAAAAAAGYRcYAAAAAAZwFigAAAAABn8VOAAAAAAGjhRIAAAAAAadE1gAAAAABqwSaAAAAAAGuxF4AAAAAAbKEIgAAAAABtkPmAAAAAAG6A6oAAAAAAb3DbgAAAAABwagcAAAAAAHFZ+AAAAAAAcknpAAAAAABzOdoAAAAAAHQpywAAAAAAdRm8AAAAAAB2Ca0AAAAAAHb5ngAAAAAAd+mPAAAAAAB42YAAAAAAAHnJcQAAAAAAerliAAAAAAB7so2AAAAAAHyifoAAAAAAfZJvgAAAAAB+gmCAAAAAAH9yUYADAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAgECAQIBAACNxAAAAACasAEEAACMoAAJAACMoAAJTE1UAEFFRFQAQUVTVAAAAQEACkFFU1QtMTBBRURULE0xMC4xLjAsTTQuMS4wLzMK"
+
 fn get_database() -> database.TzDatabase {
   let assert Ok(tzdata) = bit_array.base64_decode(tzsample)
   let assert Ok(tz_ny) = parser.parse(tzdata)
 
   let assert Ok(tzdata2) = bit_array.base64_decode(tzsample2)
   let assert Ok(tz_utc) = parser.parse(tzdata2)
 
+  let assert Ok(tzdata3) = bit_array.base64_decode(canberra)
+  let assert Ok(tz_au) = parser.parse(tzdata3)
+
   database.new()
   |> database.add_tzfile("America/New_York", tz_ny)
   |> database.add_tzfile("UTC", tz_utc)
+  |> database.add_tzfile("Australia/Canberra", tz_au)
 }
 
 pub fn get_time_in_local_zone_test() {
@@ -67,3 +73,196 @@ pub fn get_time_only_in_utc_zone_test() {
       calendar.TimeOfDay(5, 18, 0, 0),
     ))
 }
+
+pub fn timestamp_from_calendar_test() {
+  let db = get_database()
+  assert tzcalendar.from_calendar(
+      calendar.Date(2025, calendar.January, 23),
+      calendar.TimeOfDay(13, 0, 0, 0),
+      "America/New_York",
+      db,
+    )
+    == Ok([timestamp.from_unix_seconds(1_737_655_200)])
+}
+
+pub fn us_daylight_start_test() {
+  let db = get_database()
+  let dst_start_date = calendar.Date(2025, calendar.March, 9)
+
+  let one = calendar.TimeOfDay(1, 0, 0, 0)
+  let one_thirty = calendar.TimeOfDay(1, 30, 0, 0)
+  let two = calendar.TimeOfDay(2, 0, 0, 0)
+  let two_thirty = calendar.TimeOfDay(2, 30, 0, 0)
+  let three = calendar.TimeOfDay(3, 0, 0, 0)
+  let three_thirty = calendar.TimeOfDay(3, 30, 0, 0)
+
+  assert tzcalendar.from_calendar(dst_start_date, one, "America/New_York", db)
+    == Ok([timestamp.from_unix_seconds(1_741_500_000)])
+  assert tzcalendar.from_calendar(
+      dst_start_date,
+      one_thirty,
+      "America/New_York",
+      db,
+    )
+    == Ok([timestamp.from_unix_seconds(1_741_501_800)])
+  assert tzcalendar.from_calendar(dst_start_date, two, "America/New_York", db)
+    == Ok([])
+  assert tzcalendar.from_calendar(
+      dst_start_date,
+      two_thirty,
+      "America/New_York",
+      db,
+    )
+    == Ok([])
+  assert tzcalendar.from_calendar(dst_start_date, three, "America/New_York", db)
+    == Ok([timestamp.from_unix_seconds(1_741_503_600)])
+  assert tzcalendar.from_calendar(
+      dst_start_date,
+      three_thirty,
+      "America/New_York",
+      db,
+    )
+    == Ok([timestamp.from_unix_seconds(1_741_505_400)])
+}
+
+pub fn us_daylight_stop_test() {
+  let db = get_database()
+  let dst_start_date = calendar.Date(2025, calendar.November, 2)
+
+  let one = calendar.TimeOfDay(1, 0, 0, 0)
+  let one_thirty = calendar.TimeOfDay(1, 30, 0, 0)
+  let two = calendar.TimeOfDay(2, 0, 0, 0)
+  let two_thirty = calendar.TimeOfDay(2, 30, 0, 0)
+  let three = calendar.TimeOfDay(3, 0, 0, 0)
+  let three_thirty = calendar.TimeOfDay(3, 30, 0, 0)
+
+  assert tzcalendar.from_calendar(dst_start_date, one, "America/New_York", db)
+    == Ok([
+      timestamp.from_unix_seconds(1_762_059_600),
+      timestamp.from_unix_seconds(1_762_063_200),
+    ])
+  assert tzcalendar.from_calendar(
+      dst_start_date,
+      one_thirty,
+      "America/New_York",
+      db,
+    )
+    == Ok([
+      timestamp.from_unix_seconds(1_762_061_400),
+      timestamp.from_unix_seconds(1_762_065_000),
+    ])
+  assert tzcalendar.from_calendar(dst_start_date, two, "America/New_York", db)
+    == Ok([timestamp.from_unix_seconds(1_762_066_800)])
+  assert tzcalendar.from_calendar(
+      dst_start_date,
+      two_thirty,
+      "America/New_York",
+      db,
+    )
+    == Ok([timestamp.from_unix_seconds(1_762_068_600)])
+  assert tzcalendar.from_calendar(dst_start_date, three, "America/New_York", db)
+    == Ok([timestamp.from_unix_seconds(1_762_070_400)])
+  assert tzcalendar.from_calendar(
+      dst_start_date,
+      three_thirty,
+      "America/New_York",
+      db,
+    )
+    == Ok([timestamp.from_unix_seconds(1_762_072_200)])
+}
+
+pub fn au_daylight_start_test() {
+  let db = get_database()
+  let dst_start_date = calendar.Date(2025, calendar.October, 5)
+
+  let one = calendar.TimeOfDay(1, 0, 0, 0)
+  let one_thirty = calendar.TimeOfDay(1, 30, 0, 0)
+  let two = calendar.TimeOfDay(2, 0, 0, 0)
+  let two_thirty = calendar.TimeOfDay(2, 30, 0, 0)
+  let three = calendar.TimeOfDay(3, 0, 0, 0)
+  let three_thirty = calendar.TimeOfDay(3, 30, 0, 0)
+
+  assert tzcalendar.from_calendar(dst_start_date, one, "Australia/Canberra", db)
+    == Ok([timestamp.from_unix_seconds(1_759_590_000)])
+  assert tzcalendar.from_calendar(
+      dst_start_date,
+      one_thirty,
+      "Australia/Canberra",
+      db,
+    )
+    == Ok([timestamp.from_unix_seconds(1_759_591_800)])
+  assert tzcalendar.from_calendar(dst_start_date, two, "Australia/Canberra", db)
+    == Ok([])
+  assert tzcalendar.from_calendar(
+      dst_start_date,
+      two_thirty,
+      "Australia/Canberra",
+      db,
+    )
+    == Ok([])
+  assert tzcalendar.from_calendar(
+      dst_start_date,
+      three,
+      "Australia/Canberra",
+      db,
+    )
+    == Ok([timestamp.from_unix_seconds(1_759_593_600)])
+  assert tzcalendar.from_calendar(
+      dst_start_date,
+      three_thirty,
+      "Australia/Canberra",
+      db,
+    )
+    == Ok([timestamp.from_unix_seconds(1_759_595_400)])
+}
+
+pub fn au_daylight_stop_test() {
+  let db = get_database()
+  let dst_start_date = calendar.Date(2025, calendar.April, 6)
+
+  let one = calendar.TimeOfDay(1, 0, 0, 0)
+  let one_thirty = calendar.TimeOfDay(1, 30, 0, 0)
+  let two = calendar.TimeOfDay(2, 0, 0, 0)
+  let two_thirty = calendar.TimeOfDay(2, 30, 0, 0)
+  let three = calendar.TimeOfDay(3, 0, 0, 0)
+  let three_thirty = calendar.TimeOfDay(3, 30, 0, 0)
+
+  assert tzcalendar.from_calendar(dst_start_date, one, "Australia/Canberra", db)
+    == Ok([timestamp.from_unix_seconds(1_743_861_600)])
+  assert tzcalendar.from_calendar(
+      dst_start_date,
+      one_thirty,
+      "Australia/Canberra",
+      db,
+    )
+    == Ok([timestamp.from_unix_seconds(1_743_863_400)])
+  assert tzcalendar.from_calendar(dst_start_date, two, "Australia/Canberra", db)
+    == Ok([
+      timestamp.from_unix_seconds(1_743_865_200),
+      timestamp.from_unix_seconds(1_743_868_800),
+    ])
+  assert tzcalendar.from_calendar(
+      dst_start_date,
+      two_thirty,
+      "Australia/Canberra",
+      db,
+    )
+    == Ok([
+      timestamp.from_unix_seconds(1_743_867_000),
+      timestamp.from_unix_seconds(1_743_870_600),
+    ])
+  assert tzcalendar.from_calendar(
+      dst_start_date,
+      three,
+      "Australia/Canberra",
+      db,
+    )
+    == Ok([timestamp.from_unix_seconds(1_743_872_400)])
+  assert tzcalendar.from_calendar(
+      dst_start_date,
+      three_thirty,
+      "Australia/Canberra",
+      db,
+    )
+    == Ok([timestamp.from_unix_seconds(1_743_874_200)])
+}