Data.Time.LocalTime.TimeZone.Olson

timezone-olson-0.2.1: A pure Haskell parser and renderer for binary Olson timezone files

Copyright | Yitzchak Gale 2019
Maintainer | Yitzchak Gale <gale@sefer.org>
Portability | portable
Safe Haskell | Safe-Inferred
Language | Haskell2010

Data.Time.LocalTime.TimeZone.Olson

Description

A parser and renderer for binary Olson timezone files whose format is specified by RFC 8536. Functions are provided for converting the parsed data into `TimeZoneSeries` and `TimeZone` objects.

Synopsis

- getTimeZoneSeriesFromOlsonFile :: FilePath -> IO TimeZoneSeries
- getOlsonFromFile :: FilePath -> IO OlsonData
- olsonToTimeZoneSeries :: OlsonData -> Maybe TimeZoneSeries
- getOlson :: SizeLimits -> Get OlsonData
- data OlsonError
- renderTimeZoneSeriesToOlsonFile :: FilePath -> TimeZoneSeries -> IO ()
- timeZoneSeriesToOlson :: TimeZoneSeries -> Maybe OlsonData
- renderOlsonToFile :: FilePath -> OlsonData -> IO ()
- verifyOlsonLimits :: SizeLimits -> OlsonData -> Bool
- putOlson :: OlsonData -> Put
- extractOlsonV1 :: OlsonData -> OlsonData
- data OlsonData = OlsonData {
  - olsonTransitions :: [Transition]
  - olsonTypes :: [TtInfo String]
  - olsonLeaps :: [LeapInfo]
  - olsonPosixTZ :: Maybe String
  }
- data Transition = Transition {
  - transTime :: Integer
  - transIndex :: Int
  }
- data TransitionType
  - = Std
  - | Wall
  - | UTC
- data TtInfo abbr = TtInfo {
  - tt_utoff :: Int
  - tt_isdst :: Bool
  - tt_ttype :: TransitionType
  - tt_abbr :: abbr
  }
- data LeapInfo = LeapInfo {
  - leapTime :: Integer
  - leapOffset :: Int
  }
- data SizeLimits = SizeLimits {
  - maxTimes :: Maybe Int
  - maxTypes :: Maybe Int
  - maxAbbrChars :: Maybe Int
  - maxLeaps :: Maybe Int
  }
- defaultLimits :: SizeLimits
- limitsNoSolar :: SizeLimits
- noLimits :: SizeLimits

# Documentation

getTimeZoneSeriesFromOlsonFile :: FilePath -> IO TimeZoneSeries #

Read timezone data from a binary Olson timezone file and convert it into a `TimeZoneSeries` for use together with the types and fucntions of Data.Time. This is the function from this module for which you are most likely to have use.

If the values in the Olson timezone file exceed the standard size limits (see `defaultLimits`), this function throws an exception. For other behavior, use `getOlson` and `runGet` directly.

getOlsonFromFile :: FilePath -> IO OlsonData #

Parse a binary Olson timezone file.

If the values in the Olson timezone file exceed the standard size limits (see `defaultLimits`), this function throws an exception. For other behavior, use `getOlson` and `runGet` directly.

olsonToTimeZoneSeries :: OlsonData -> Maybe TimeZoneSeries #

Convert parsed Olson timezone data into a `TimeZoneSeries`.

getOlson :: SizeLimits -> Get OlsonData #

A binary parser for binary Olson timezone files

data OlsonError #

An exception indicating that the binary data being parsed was not valid Olson timezone data

#### Instances

Instances details

Exception OlsonError # |
Instance details Defined in Data.Time.LocalTime.TimeZone.Olson.Parse Methods toException :: OlsonError -> SomeException # fromException :: SomeException -> Maybe OlsonError # displayException :: OlsonError -> String # backtraceDesired :: OlsonError -> Bool #
Show OlsonError # |
Instance details Defined in Data.Time.LocalTime.TimeZone.Olson.Parse Methods showsPrec :: Int -> OlsonError -> ShowS # show :: OlsonError -> String # showList :: [OlsonError] -> ShowS #

renderTimeZoneSeriesToOlsonFile :: FilePath -> TimeZoneSeries -> IO () #

Render a `TimeZoneSeries` as a binary Olson timezone file.

If the values in the Olson timezone data exceed the standard size limits (see `defaultLimits`), this function throws an exception. For other behavior, use `timeZoneSeriesToOlson`, `verifyOlsonLimits`, `putOlson` and `runPut` directly.

timeZoneSeriesToOlson :: TimeZoneSeries -> Maybe OlsonData #

Convert a `TimeZoneSeries` to `OlsonData` for rendering.

renderOlsonToFile :: FilePath -> OlsonData -> IO () #

Render Olson timezone data as a binary Olson timezone file

If the values in the Olson timezone data exceed the standard size limits (see `defaultLimits`), this function throws an exception. For other behavior, use `verifyOlsonLimits`, `putOlson` and `runPut` directly.

verifyOlsonLimits :: SizeLimits -> OlsonData -> Bool #

Check whether `OlsonData` is within size limits.

putOlson :: OlsonData -> Put #

Render Olson timezone data in binary Olson timezone file format as a lazy `ByteString`

extractOlsonV1 :: OlsonData -> OlsonData #

Extract Olson timezone data that can be rendered using Version 1 format

data OlsonData #

`OlsonData` represents a full set of timezone data for a location.

`OlsonData` can represent timezone data from files in Version 1, 2, or 3 format.

Version 1 format files can only contain timestamp values that can be represented in less than 32 bits, and cannot contain a POSIX TZ string.

In a Version 2 format file, the timezone data is split into two parts. The first part contains timezone data for which all timestamp values can be represented in less than 32 bits, and the second part contains timezone data for which 32 bits or more are required to represent timestamp values. The POSIX TZ string, if present, can only be rendered in a Version 2 file, and appears after both parts of the timezone data.

Version 3 format files relax certain syntax requirements for the POSIX TZ string. Since we represent the POSIX TZ string as an unparsed `String`, Version 3 is identical to Version 2 for our purposes.

Constructors

OlsonData |
Fields olsonTransitions :: [Transition] olsonTypes :: [TtInfo String] olsonLeaps :: [LeapInfo] olsonPosixTZ :: Maybe String Optional POSIX TZ string for times after the last `Transition`

#### Instances

Instances details

Monoid OlsonData # |
Instance details Defined in Data.Time.LocalTime.TimeZone.Olson.Types Methods mempty :: OlsonData # mappend :: OlsonData -> OlsonData -> OlsonData # mconcat :: [OlsonData] -> OlsonData #
Semigroup OlsonData # |
Instance details Defined in Data.Time.LocalTime.TimeZone.Olson.Types Methods (<>) :: OlsonData -> OlsonData -> OlsonData # sconcat :: NonEmpty OlsonData -> OlsonData # stimes :: Integral b => b -> OlsonData -> OlsonData #
Show OlsonData # |
Instance details Defined in Data.Time.LocalTime.TimeZone.Olson.Types Methods showsPrec :: Int -> OlsonData -> ShowS # show :: OlsonData -> String # showList :: [OlsonData] -> ShowS #
Eq OlsonData # |
Instance details Defined in Data.Time.LocalTime.TimeZone.Olson.Types Methods (==) :: OlsonData -> OlsonData -> Bool # (/=) :: OlsonData -> OlsonData -> Bool #

data Transition #

A `Transition` represents a moment when the clocks change in a timezone. It consists of a Unix timestamp value that indicates the exact moment in UTC when the clocks change, and the 0-based index in the list of `TtInfo` specifications for the description of the new time after the clocks change.

Constructors

Transition |
Fields transTime :: Integer Unix timestamp indicating the time when the clocks change transIndex :: Int 0-based index in the list of `TtInfo` that describes the new time

#### Instances

Instances details

Show Transition # |
Instance details Defined in Data.Time.LocalTime.TimeZone.Olson.Types Methods showsPrec :: Int -> Transition -> ShowS # show :: Transition -> String # showList :: [Transition] -> ShowS #
Eq Transition # |
Instance details Defined in Data.Time.LocalTime.TimeZone.Olson.Types Methods (==) :: Transition -> Transition -> Bool # (/=) :: Transition -> Transition -> Bool #

data TransitionType #

A `TransitionType` is historical information about whether the official body that announced a time change specified the time of the change in terms of UTC, standard time (i.e., non-summer time) for the time zone, or the current wall clock time in the time zone. This historical trivia may seem rather boring, but unfortunately it is needed to interpret a POSIX-style TZ string timezone specification correctly.

Constructors

Std |
Wall |
UTC |

#### Instances

Instances details

Show TransitionType # |
Instance details Defined in Data.Time.LocalTime.TimeZone.Olson.Types Methods showsPrec :: Int -> TransitionType -> ShowS # show :: TransitionType -> String # showList :: [TransitionType] -> ShowS #
Eq TransitionType # |
Instance details Defined in Data.Time.LocalTime.TimeZone.Olson.Types Methods (==) :: TransitionType -> TransitionType -> Bool # (/=) :: TransitionType -> TransitionType -> Bool #
Ord TransitionType # |
Instance details Defined in Data.Time.LocalTime.TimeZone.Olson.Types Methods compare :: TransitionType -> TransitionType -> Ordering # (<) :: TransitionType -> TransitionType -> Bool # (<=) :: TransitionType -> TransitionType -> Bool # (>) :: TransitionType -> TransitionType -> Bool # (>=) :: TransitionType -> TransitionType -> Bool # max :: TransitionType -> TransitionType -> TransitionType # min :: TransitionType -> TransitionType -> TransitionType #

data TtInfo abbr #

A `TtInfo` is a specification of local time in a timezone for some period during which the clocks did not change. `abbr` is `String` if the timezone abbreviation is represented as a `String`, or `Int` if it is represented as an index into a long string of null-terminated abbreviation strings (as in an Olson binary timezone file).

Constructors

TtInfo |
Fields tt_utoff :: Int The offset of local clocks from UTC, in seconds tt_isdst :: Bool True if local clocks are summer time tt_ttype :: TransitionType tt_abbr :: abbr The timezone abbreviation string.

#### Instances

Instances details

Show abbr => Show (TtInfo abbr) # |
Instance details Defined in Data.Time.LocalTime.TimeZone.Olson.Types Methods showsPrec :: Int -> TtInfo abbr -> ShowS # show :: TtInfo abbr -> String # showList :: [TtInfo abbr] -> ShowS #
Eq abbr => Eq (TtInfo abbr) # |
Instance details Defined in Data.Time.LocalTime.TimeZone.Olson.Types Methods (==) :: TtInfo abbr -> TtInfo abbr -> Bool # (/=) :: TtInfo abbr -> TtInfo abbr -> Bool #
Ord abbr => Ord (TtInfo abbr) # |
Instance details Defined in Data.Time.LocalTime.TimeZone.Olson.Types Methods compare :: TtInfo abbr -> TtInfo abbr -> Ordering # (<) :: TtInfo abbr -> TtInfo abbr -> Bool # (<=) :: TtInfo abbr -> TtInfo abbr -> Bool # (>) :: TtInfo abbr -> TtInfo abbr -> Bool # (>=) :: TtInfo abbr -> TtInfo abbr -> Bool # max :: TtInfo abbr -> TtInfo abbr -> TtInfo abbr # min :: TtInfo abbr -> TtInfo abbr -> TtInfo abbr #

data LeapInfo #

Olson timezone files can contain leap second specifications, though most do not.

Constructors

LeapInfo |
Fields leapTime :: Integer A Unix timestamp indicating the time that the leap second occurred leapOffset :: Int The new total offset of UTC from UT1 after this leap second

#### Instances

Instances details

Show LeapInfo # |
Instance details Defined in Data.Time.LocalTime.TimeZone.Olson.Types Methods showsPrec :: Int -> LeapInfo -> ShowS # show :: LeapInfo -> String # showList :: [LeapInfo] -> ShowS #
Eq LeapInfo # |
Instance details Defined in Data.Time.LocalTime.TimeZone.Olson.Types Methods (==) :: LeapInfo -> LeapInfo -> Bool # (/=) :: LeapInfo -> LeapInfo -> Bool #

data SizeLimits #

The reference C implentation imposes size limits on the data structures in a timezone file.

Constructors

SizeLimits |
Fields maxTimes :: Maybe Int The maximum number of transition times maxTypes :: Maybe Int The maximum number of TtInfo clock settings maxAbbrChars :: Maybe Int The maximum total number of bytes in all timezone abbreviations. maxLeaps :: Maybe Int The maximum number of leap second specifications.

defaultLimits :: SizeLimits #

The size limits in `defaultLimits` are taken from the file tzfile.h from tzcode version 2010f. These are the limits for the C implementation on many platforms.

limitsNoSolar :: SizeLimits #

`limitsNoSolar` contains the tighter size limits imposed on some platforms that do not allow timezones that are based on solar time.

noLimits :: SizeLimits #

`noLimits` imposes no size limits. If you use `noLimits` when parsing, you may exhaust all available memory when reading a faulty or malicious timezone file. If you use `noLimits` when rendering, the rendered timezone file might not be readable on some systems.