Portability | portable |
---|---|
Maintainer | Yitzchak Gale <gale@sefer.org> |
Safe Haskell | None |
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.
- 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
- data TtInfo abbr = TtInfo {}
- data LeapInfo = LeapInfo {
- leapTime :: Integer
- leapOffset :: Int
- data SizeLimits = SizeLimits {}
- defaultLimits :: SizeLimits
- limitsNoSolar :: SizeLimits
- noLimits :: SizeLimits
Parsing Olson timezone files
getTimeZoneSeriesFromOlsonFile :: FilePath -> IO TimeZoneSeriesSource
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 OlsonDataSource
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 TimeZoneSeriesSource
Convert parsed Olson timezone data into a TimeZoneSeries
.
getOlson :: SizeLimits -> Get OlsonDataSource
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 OlsonDataSource
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 -> BoolSource
Check whether OlsonData
is within size limits.
putOlson :: OlsonData -> PutSource
Render Olson timezone data in binary Olson timezone file format
as a lazy ByteString
extractOlsonV1 :: OlsonData -> OlsonDataSource
Extract Olson timezone data that can be rendered using Version 1 format
Olson timezone datatypes
OlsonData
represents a full set of timezone data for a location.
OlsonData
can represent timezone data from files in Version 1 format
or Version 2 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.
OlsonData | |
|
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.
Transition | |
|
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.
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).
Olson timezone files can contain leap second specifications, though most do not.
LeapInfo | |
|
Size limits for Olson timezone data
data SizeLimits Source
The reference C implentation imposes size limits on the data structures in a timezone file.
defaultLimits :: SizeLimitsSource
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 :: SizeLimitsSource
limitsNoSolar
contains the tighter size limits imposed on some
platforms that do not allow timezones that are based on solar time.
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.