timezone-detect-0.3.0.1: Haskell bindings for the zone-detect C library; plus tz-aware utils.

Data.Time.LocalTime.TimeZone.Detect

Description

Exposes utilities derived from the excellent ZoneDetect library https://github.com/BertoldVdb/ZoneDetect. To use this module, you need to obtain database files from the aforementioned library's server.

Additionally, if you have a local time, latitude and longitude, we use the timezone-series and timezone-olson packages to help determine the equivalent UTC instant to that point in geography and time.

The only relevant binding to ZoneDetect is lookupTimeZoneName, richer information that plays neatly with the notion of TimeZone could be derived, but I didn't have a personal need for that yet.

Functions to open, close, and work with an open database (from a valid file) are provided.

Synopsis

# Documentation

Alias for clarity, timezones are path-like strings that follow the IANA conventions documented here: https://data.iana.org/time-zones/tz-link.html and here: https://en.wikipedia.org/wiki/Tz_database#Names_of_time_zones

A reference to a timezone database.

Open a timezone database file and obtain a pointer to the database, as interpreted by the underlying C code.

Given a pointer to a timezone database, close any allocated resources.

withTimeZoneDatabase :: FilePath -> (TimeZoneDatabase -> IO a) -> IO a Source #

Given a path to a timezone database file, and a computation to run with it, takes care of opening the file, running the computation and then closing it.

Given a timezone database, latitude and longitude, try to determine the timezone name. Follow the instructions in the C library's repository to obtain timezone database files (https://github.com/BertoldVdb/ZoneDetect/tree/05567e367576d7f3efa00083b7661a01e43dc8ca/database) Once in possesion of said files, the lookup looks as follows:

>>> db <- openTimeZoneDatabase "./test/tz_db/timezone21.bin"
>>> let tz = lookupTimeZoneName db 40.7831 (-73.9712) :: Maybe TimeZoneName
Just "America/New_York"
>>> closeTimeZoneDatabase db


An invalid database pointer, or invalid coordinates, will cause the given monad to fail. Note that we follow the original library's pattern of obtaining the TimeZoneDatabase separately (which could prove advantageous in e.g a web server.) If you're doing a one-off lookup, or are okay with the IO cost of opening the DB file, see lookupTimeZoneNameFromFile.

Same as lookupTimeZoneName, but takes the path to the database file and only works in IO.

Given a timezone database, latitude, longitude and a local reference time, find the UTC Time equivalent of that reference time in the given timezone. The reference time helps determine which offset was in effect, since daylight savings, historical circumstances, political revisions and other circumstances (documented in the olson tz database) may have been in effect at that point in spacetime.

Same as timeAtPointToUTC, but takes the path to the timezone database file and takes care of opening and closing the file.

Given a timezone name (presumably obtained via lookupTimeZoneName,) and a reference time in LocalTime, find the UTC equivalent.