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

CopyrightYitzchak Gale 2019
MaintainerYitzchak Gale <gale@sefer.org>
Portabilityportable
Safe HaskellSafe
LanguageHaskell2010

Data.Time.LocalTime.TimeZone.Olson

Contents

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

Parsing Olson timezone files

getTimeZoneSeriesFromOlsonFile :: FilePath -> IO TimeZoneSeries Source #

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

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

Convert parsed Olson timezone data into a TimeZoneSeries.

getOlson :: SizeLimits -> Get OlsonData Source #

A binary parser for binary Olson timezone files

data OlsonError Source #

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

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 () Source #

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

Convert a TimeZoneSeries to OlsonData for rendering.

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

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

Check whether OlsonData is within size limits.

putOlson :: OlsonData -> Put Source #

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

extractOlsonV1 :: OlsonData -> OlsonData Source #

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

Olson timezone datatypes

data OlsonData Source #

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

data Transition Source #

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

data TransitionType Source #

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 

data TtInfo abbr Source #

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

Instances
Eq abbr => Eq (TtInfo abbr) Source # 
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) Source # 
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) Source # 
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 Source #

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

Size limits for Olson timezone data

data SizeLimits Source #

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

Constructors

SizeLimits 

Fields

defaultLimits :: SizeLimits Source #

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

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

noLimits :: SizeLimits Source #

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.