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

CopyrightYitzchak Gale 2010
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 are specified by the tzfile(5) man page on Unix-like systems. For more information about this format, see http://www.twinsun.com/tz/tz-link.htm. Functions are provided for converting the parsed data into TimeZoneSeries and TimeZone objects.

Synopsis

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

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

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

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

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

Eq abbr => Eq (TtInfo abbr) 
Ord abbr => Ord (TtInfo abbr) 
Show abbr => Show (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

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.