tz- Efficient time zone handling

MaintainerMihaly Barasz <>
Safe HaskellNone







data TZ Source


utcTZ :: TZSource

The TZ definition for UTC.

Universal -> Local direction

diffForPOSIX :: TZ -> Int64 -> IntSource

Returns the time difference (in seconds) for TZ at the given POSIX time.

timeZoneForPOSIX :: TZ -> Int64 -> TimeZoneSource

Returns the TimeZone for the TZ at the given POSIX time.

timeZoneForUTCTime :: TZ -> UTCTime -> TimeZoneSource

Returns the TimeZone for the TZ at the given UTCTime.

utcToLocalTimeTZ :: TZ -> UTCTime -> LocalTimeSource

Returns the LocalTime corresponding to the given UTCTime in TZ.

utcToLocalTimeTZ tz ut is equivalent to utcToLocalTime (timeZoneForPOSIX tz ut) ut except when the time difference is not an integral number of minutes

Local -> Universal direction

data LocalToUTCResult Source

Fully descriptive result of a LocalTime to UTCTime conversion.

In case of LTUAmbiguous the first result is always earlier than the second one. Generally this only happens during the daylight saving -> standard time transition (ie. summer -> winter). So, the first result corresponds to interpreting the LocalTime as a daylight saving time and the second result as standard time in the given location.

But, if the location had some kind of administrative time transition during which the clocks jumped back, then both results can correspond to standard times (or daylight saving times) just before and after the transition. You can always inspect the timeZoneSummerOnly field of the returned TimeZones to get an idea what kind of transition was taking place.

TODO(klao): document the LTUNone behavior.

data FromLocal Source

Internal representation of LocalTime -> UTCTime conversion result:




_flIx :: !Int
_flRes :: !Int64


_flIx :: !Int
_flRes :: !Int64


_flIx :: !Int
_flRes1 :: !Int64
_flRes2 :: !Int64


Acquiring TZ information

loadTZFromFile :: FilePath -> IO TZSource

Reads and parses a time zone information file (in tzfile(5) aka. Olson file format) and returns the corresponding TZ data structure.

loadTZFromDB :: String -> IO TZSource

Reads the corresponding file from the time zone database shipped with this package.

loadSystemTZ :: String -> IO TZSource

Looks for the time zone file in the system timezone directory, which is /usr/share/zoneinfo, or if the TZDIR environment variable is set, then there.

loadLocalTZ :: IO TZSource

Returns the local TZ based on the TZ and TZDIR environment variables.

See tzset(3) for details, but basically:

  • If TZ environment variable is unset, we loadTZFromFile "/etc/localtime".
  • If TZ is set, but empty, we loadSystemTZ "UTC".
  • Otherwise, we just loadSystemTZ it.

Note, this means we don't support POSIX-style TZ variables (like "EST5EDT"), only those that are explicitly present in the time zone database.