Data.Time.LocalTime.TimeZone.Olson

timezone-olson-0.2.0: 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

Contents

- Parsing Olson timezone files
- Rendering Olson timezone files
- Olson timezone datatypes
  - Size limits for Olson timezone data

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

# Parsing Olson timezone files

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

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

# Rendering Olson timezone files

If any of the transition times or leap second times specified require more than a 32-bit integer to represent as a Unix timestamp, or if a POSIX-style TZ string is specified, timezone data is rendered using Version 2 format. Otherwise, the timezone data is rendered using Version 1 format.

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

# Olson timezone datatypes

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

Eq OlsonData # |
Instance details Defined in Data.Time.LocalTime.TimeZone.Olson.Types Methods (==) :: OlsonData -> OlsonData -> Bool (/=) :: OlsonData -> OlsonData -> Bool
Show OlsonData # |
Instance details Defined in Data.Time.LocalTime.TimeZone.Olson.Types Methods showsPrec :: Int -> OlsonData -> ShowS show :: OlsonData -> String showList :: [OlsonData] -> ShowS
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
Monoid OlsonData # |
Instance details Defined in Data.Time.LocalTime.TimeZone.Olson.Types Methods mempty :: OlsonData mappend :: OlsonData -> OlsonData -> OlsonData mconcat :: [OlsonData] -> OlsonData

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

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

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

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
Show TransitionType # |
Instance details Defined in Data.Time.LocalTime.TimeZone.Olson.Types Methods showsPrec :: Int -> TransitionType -> ShowS show :: TransitionType -> String showList :: [TransitionType] -> ShowS

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

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
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

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

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

## Size limits for Olson timezone data

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.