refactoring and fix leap second bug

Author: devries

README.md

@@ -1,17 +1,17 @@
-# timezone
+# tzif
 
 <!--#
 [![Package Version](https://img.shields.io/hexpm/v/timezone)](https://hex.pm/packages/timezone)
 [![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/timezone/)
 -->
 
-Timezone support for Gleam time using the operating system's timezone database.
-This package loads the timezone database from the standard location
+Time zone support for Gleam time using the IANA Time Zone Database.
+This package loads the time zone database from the standard location
 (`/usr/share/zoneinfo`) on MacOS and Linux computers. It includes a parser for
 the Time Zone Information Format (TZif) or `tzfile` format, as well as utility
 functions to convert a timestamp from the
 [gleam_time](https://hexdocs.pm/gleam_time/) library into a date and time
-of day in the given timezone.
+of day in the given time zone.
 
 > We could really do with a timezone database package with a
 > fn(Timestamp, Zone) -> #(Date, TimeOfDay) function
@@ -21,13 +21,61 @@ of day in the given timezone.
 To use, add the following entry in your `gleam.toml` file dependencies:
 
 ```
-timezone = { git = "[email protected]:devries/timezone.git", ref = "main" }
+tzif = { git = "[email protected]:devries/timezone.git", ref = "main" }
 ```
+
+# Using the Package
+The most straightforward use would be to load the database from the default
+location on the operating system, and then obtain a timestamp using the
+[gleam_time](https://hexdocs.pm/gleam_time/) package, and convert that timestamp
+into a time of day in a time zone using the IANA time zone name. An example
+of that is shown in the code below.
+
+```gleam
+import gleam/int
+import gleam/io
+import gleam/string
+import gleam/time/timestamp
+import tzif/database
+import tzif/tzcalendar
+
+pub fn main() {
+    let now = timestamp.system_time()
+
+    // Load the database from the operating system
+    let db = database.load_from_os()
+
+    case tzcalendar.get_time_and_zone(now, "America/New_York", db) {
+        Ok(time_and_zone) -> {
+            // Successfully converted time to the requested time zone
+            io.println(
+                int.to_string(time_and_zone.time_of_day.hours)
+                |> string.pad_start(2, "0")
+                <> ":"
+                <> int.to_string(time_and_zone.time_of_day.minutes)
+                |> string.pad_start(2, "0")
+                <> ":"
+                <> int.to_string(time_and_zone.time_of_day.seconds)
+                |> string.pad_start(2, "0")
+                <> " "
+                <> time_and_zone.designation
+            )
+        }
+        Error(database.ZoneNotFound) -> io.println("Time zone not found")
+        Error(database.ProcessingError) -> io.println("Error processing time zone conversion")
+    }
+}
+```
+If you are on windows and have installed the IANA Time Zone Database, or want
+to use a custom version you can use the `database.load_from_path` function
+instead of the `database.load_from_os` function to specify a path to your
+database files.
+
 # Installing the zoneinfo data files
-Timezone information is frequently updated, therefore it makes sense to use the
-package manager for your operating system to keep the timezone database up to
-date. All common unix variants have timezone database packages and install the
-timezone database files into the `/usr/share/zoneinfo` directory by default.
+Time zone information is frequently updated, therefore it makes sense to use the
+package manager for your operating system to keep the time zone database up to
+date. All common unix variants have time zone database packages and install the
+time zone database files into the `/usr/share/zoneinfo` directory by default.
 
 ## MacOS
 The files should be included in your operating system by default. Check the
@@ -42,7 +90,7 @@ sudo apt install tzdata
 ```
 
 ### Debian based docker containers
-Installing and configuring the timezone database on a Debian or Ubuntu based
+Installing and configuring the time zone database on a Debian or Ubuntu based
 docker container can be done by adding the following to your `Dockerfile`:
 
 ```
@@ -58,14 +106,14 @@ RUN apt-get update && \
 ```
 
 ## Alpine Linux Systems
-The Alpine Package Keeper can install the timezone database using the command:
+The Alpine Package Keeper can install the time zone database using the command:
 
 ```
 sudo apk add tzdata
 ```
 
 ### Alpine based docker containers
-Installing and configuring the timezone database on an Alpine based docker
+Installing and configuring the time zone database on an Alpine based docker
 container can be done by adding the following to your `Dockerfile`:
 
 ```
@@ -81,7 +129,7 @@ RUN apk add --no-cache tzdata && \
 ```
 
 ## Red Hat/Rocky/Alma Linux Systems
-You can use the YUM package manager or DNF to install the timezone database
+You can use the YUM package manager or DNF to install the time zone database
 on Red Hat variants. To use YUM run the command:
 
 ```
@@ -94,4 +142,7 @@ Similarly, using DNF:
 sudo dnf install tzdata
 ```
 ## Windows
-At this time we have not tested the windows operating system.
+Microsoft Windows has a different mechanism for handling time zones, however
+you can install the IANA Time Zone Database by [downloading the latest
+version](https://www.iana.org/time-zones) and compiling the zone files using
+[the directions in the repository](https://data.iana.org/time-zones/tz-link.html).

examples/simple/.gitignore

@@ -0,0 +1,4 @@
+*.beam
+*.ez
+/build
+erl_crash.dump

examples/simple/README.md

@@ -0,0 +1,24 @@
+# simple
+
+[![Package Version](https://img.shields.io/hexpm/v/simple)](https://hex.pm/packages/simple)
+[![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/simple/)
+
+```sh
+gleam add simple@1
+```
+```gleam
+import simple
+
+pub fn main() -> Nil {
+  // TODO: An example of the project in use
+}
+```
+
+Further documentation can be found at <https://hexdocs.pm/simple>.
+
+## Development
+
+```sh
+gleam run   # Run the project
+gleam test  # Run the tests
+```

examples/simple/gleam.toml

@@ -0,0 +1,21 @@
+name = "simple"
+version = "1.0.0"
+
+# Fill out these fields if you intend to generate HTML documentation or publish
+# your project to the Hex package manager.
+#
+# description = ""
+# licences = ["Apache-2.0"]
+# repository = { type = "github", user = "", repo = "" }
+# links = [{ title = "Website", href = "" }]
+#
+# For a full reference of all the available options, you can have a look at
+# https://gleam.run/writing-gleam/gleam-toml/.
+
+[dependencies]
+gleam_stdlib = ">= 0.44.0 and < 2.0.0"
+tzif = { path = "../../" }
+gleam_time = ">= 1.4.0 and < 2.0.0"
+
+[dev-dependencies]
+gleeunit = ">= 1.0.0 and < 2.0.0"

examples/simple/manifest.toml

@@ -0,0 +1,17 @@
+# This file was generated by Gleam
+# You typically do not need to edit this file
+
+packages = [
+  { name = "filepath", version = "1.1.2", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "filepath", source = "hex", outer_checksum = "B06A9AF0BF10E51401D64B98E4B627F1D2E48C154967DA7AF4D0914780A6D40A" },
+  { name = "gleam_stdlib", version = "0.63.2", build_tools = ["gleam"], requirements = [], otp_app = "gleam_stdlib", source = "hex", outer_checksum = "962B25C667DA07F4CAB32001F44D3C41C1A89E58E3BBA54F183B482CF6122150" },
+  { name = "gleam_time", version = "1.4.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_time", source = "hex", outer_checksum = "DCDDC040CE97DA3D2A925CDBBA08D8A78681139745754A83998641C8A3F6587E" },
+  { name = "gleeunit", version = "1.6.1", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleeunit", source = "hex", outer_checksum = "FDC68A8C492B1E9B429249062CD9BAC9B5538C6FBF584817205D0998C42E1DAC" },
+  { name = "simplifile", version = "2.3.0", build_tools = ["gleam"], requirements = ["filepath", "gleam_stdlib"], otp_app = "simplifile", source = "hex", outer_checksum = "0A868DAC6063D9E983477981839810DC2E553285AB4588B87E3E9C96A7FB4CB4" },
+  { name = "tzif", version = "0.2.0", build_tools = ["gleam"], requirements = ["filepath", "gleam_stdlib", "gleam_time", "simplifile"], source = "local", path = "../.." },
+]
+
+[requirements]
+gleam_stdlib = { version = ">= 0.44.0 and < 2.0.0" }
+gleam_time = { version = ">= 1.4.0 and < 2.0.0" }
+gleeunit = { version = ">= 1.0.0 and < 2.0.0" }
+tzif = { path = "../../" }

examples/simple/src/simple.gleam

@@ -0,0 +1,34 @@
+import gleam/int
+import gleam/io
+import gleam/string
+import gleam/time/timestamp
+import tzif/database
+import tzif/tzcalendar
+
+pub fn main() {
+  let now = timestamp.system_time()
+
+  // Load the database from the operating system
+  let db = database.load_from_os()
+
+  case tzcalendar.get_time_and_zone(now, "America/New_York", db) {
+    Ok(time_and_zone) -> {
+      // Successfully converted time to the requested time zone
+      io.println(
+        int.to_string(time_and_zone.time_of_day.hours)
+        |> string.pad_start(2, "0")
+        <> ":"
+        <> int.to_string(time_and_zone.time_of_day.minutes)
+        |> string.pad_start(2, "0")
+        <> ":"
+        <> int.to_string(time_and_zone.time_of_day.seconds)
+        |> string.pad_start(2, "0")
+        <> " "
+        <> time_and_zone.designation,
+      )
+    }
+    Error(database.ZoneNotFound) -> io.println("Time zone not found")
+    Error(database.ProcessingError) ->
+      io.println("Error processing time zone conversion")
+  }
+}

examples/simple/test/simple_test.gleam

@@ -0,0 +1,13 @@
+import gleeunit
+
+pub fn main() -> Nil {
+  gleeunit.main()
+}
+
+// gleeunit test functions end in `_test`
+pub fn hello_world_test() {
+  let name = "Joe"
+  let greeting = "Hello, " <> name <> "!"
+
+  assert greeting == "Hello, Joe!"
+}

src/tzif/database.gleam

@@ -8,6 +8,9 @@ import gleam/time/timestamp
 import simplifile
 import tzif/tzparser
 
+/// Time Zone Database record. This is typically created by
+/// loading from the operating system with the `load_from_os`
+/// function.
 pub opaque type TzDatabase {
   TzDatabase(
     zone_names: List(String),

src/tzif/tzcalendar.gleam

@@ -1,13 +1,13 @@
 //// This module is for working with time zones and converting timestamps
 //// from the `gleam/time` library into dates and times of day in a
-//// timezone.
+//// time zone.
 ////
 //// This library makes use of the [IANA tz database](https://www.iana.org/time-zones)
 //// which is generally already installed on computers.
-//// This library will search for timezone data in the [tzfile](https://www.man7.org/linux/man-pages/man5/tzfile.5.html)
+//// This library will search for timezone data in the TZif or [tzfile](https://www.man7.org/linux/man-pages/man5/tzfile.5.html)
 //// file format. These are generally located in the `/usr/share/zoneinfo`
 //// directory on posix systems, however if they are installed elsewhere the
-//// ZONEINFO environment variable can be set to the full path of the directory
+//// then they can be loaded ysung the full path of the directory
 //// containing the tz database files.
 ////
 //// Time zone identifiers are generally of the form "Continent/City" for example
@@ -22,7 +22,10 @@ import gleam/time/duration.{type Duration}
 import gleam/time/timestamp.{type Timestamp}
 import tzif/database.{type TzDatabase, type TzDatabaseError}
 
-/// Representation of time in a time zone
+/// Representation of a date and time of day in a particular time zone
+/// along with the offset from UTC, the zone designation (i.e. "UTC",
+/// "EST", "CEDT") and a boolean indicating if it is daylight savings
+/// time.
 pub type TimeAndZone {
   TimeAndZone(
     date: Date,

src/tzif/tzparser.gleam

@@ -22,6 +22,9 @@ pub type TzFileError {
 
   /// Error parsing an integer
   IntegerParseError
+
+  /// Error Parsing leap second section
+  LeapSecondParseError
 }
 
 /// Header of the tzfile. This uses the same label names as
@@ -47,7 +50,7 @@ pub type TzFileFields {
     time_types: List(Int),
     ttinfos: List(TtInfo),
     designations: List(String),
-    leapsecond_values: List(List(Int)),
+    leapsecond_values: List(#(Int, Int)),
     standard_or_wall: List(Int),
     ut_or_local: List(Int),
   )
@@ -183,16 +186,13 @@ fn parse_section(
 
   let designations = designation_tuples |> list.map(fn(tup) { tup.0 })
 
-  // Get leap second information
-  use leapsecond_integers, remain <- parse_list(
+  use leapsecond_values, remain <- parse_list(
     header.leapcnt,
     remain,
     [],
-    integer_parser(integer_size),
+    leap_parser(integer_size),
   )
 
-  let leapsecond_values = leapsecond_integers |> list.sized_chunk(2)
-
   // Booleans to indicate if these are standard time or local time indicators
   use standard_wall_indicators, remain <- parse_list(
     header.ttisstdcnt,
@@ -276,6 +276,22 @@ fn unsigned_integer_parser(
   }
 }
 
+fn leap_parser(
+  bit_size: Int,
+) -> fn(BitArray, fn(#(Int, Int), BitArray) -> Result(a, TzFileError)) ->
+  Result(a, TzFileError) {
+  fn(bits: BitArray, next: fn(#(Int, Int), BitArray) -> Result(a, TzFileError)) {
+    case bits {
+      <<
+        tt:signed-int-big-size(bit_size),
+        leap:signed-int-big-size(32),
+        rest:bits,
+      >> -> next(#(tt, leap), rest)
+      _ -> Error(LeapSecondParseError)
+    }
+  }
+}
+
 fn parse_null_terminated_string(
   bits: BitArray,
   next: fn(String, BitArray) -> Result(a, TzFileError),