-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | A pure Haskell parser and renderer for binary Olson timezone files -- -- A parser and renderer for binary Olson timezone files whose format is -- specified by the tzfile(5) man page on Unix-like systems. For more -- information about this format, see -- http://www.iana.org/time-zones/repository/tz-link.html. -- Functions are provided for converting the parsed data into -- TimeZoneSeries objects from the timezone-series package. On -- many platforms, binary Olson timezone files suitable for use with this -- package are available in the directory usrshare/zoneinfo and -- its subdirectories on your computer. For a way to read binary Olson -- timezone files at compile time, see the timezone-olson-th package -- (http://hackage.haskell.org/package/timezone-olson-th). @package timezone-olson @version 0.1.9 -- | 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. module Data.Time.LocalTime.TimeZone.Olson -- | 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. getTimeZoneSeriesFromOlsonFile :: FilePath -> IO TimeZoneSeries -- | 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. getOlsonFromFile :: FilePath -> IO OlsonData -- | Convert parsed Olson timezone data into a TimeZoneSeries. olsonToTimeZoneSeries :: OlsonData -> Maybe TimeZoneSeries -- | A binary parser for binary Olson timezone files getOlson :: SizeLimits -> Get OlsonData -- | An exception indicating that the binary data being parsed was not -- valid Olson timezone data data OlsonError -- | 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. renderTimeZoneSeriesToOlsonFile :: FilePath -> TimeZoneSeries -> IO () -- | Convert a TimeZoneSeries to OlsonData for rendering. timeZoneSeriesToOlson :: TimeZoneSeries -> Maybe OlsonData -- | 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. renderOlsonToFile :: FilePath -> OlsonData -> IO () -- | Check whether OlsonData is within size limits. verifyOlsonLimits :: SizeLimits -> OlsonData -> Bool -- | Render Olson timezone data in binary Olson timezone file format as a -- lazy ByteString putOlson :: OlsonData -> Put -- | Extract Olson timezone data that can be rendered using Version 1 -- format extractOlsonV1 :: OlsonData -> 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. data OlsonData OlsonData :: [Transition] -> [TtInfo String] -> [LeapInfo] -> (Maybe String) -> OlsonData [olsonTransitions] :: OlsonData -> [Transition] [olsonTypes] :: OlsonData -> [TtInfo String] [olsonLeaps] :: OlsonData -> [LeapInfo] -- | Optional POSIX TZ string for times after the last Transition [olsonPosixTZ] :: OlsonData -> (Maybe String) -- | 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. data Transition Transition :: Integer -> Int -> Transition -- | Unix timestamp indicating the time when the clocks change [transTime] :: Transition -> Integer -- | 0-based index in the list of TtInfo that describes the new -- time [transIndex] :: Transition -> Int -- | 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. data TransitionType Std :: TransitionType Wall :: TransitionType UTC :: TransitionType -- | 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). data TtInfo abbr TtInfo :: Int -> Bool -> TransitionType -> abbr -> TtInfo abbr -- | The offset of local clocks from UTC, in seconds [tt_gmtoff] :: TtInfo abbr -> Int -- | True if local clocks are summer time [tt_isdst] :: TtInfo abbr -> Bool [tt_ttype] :: TtInfo abbr -> TransitionType -- | The timezone abbreviation string. [tt_abbr] :: TtInfo abbr -> abbr -- | Olson timezone files can contain leap second specifications, though -- most do not. data LeapInfo LeapInfo :: Integer -> Int -> LeapInfo -- | A Unix timestamp indicating the time that the leap second occurred [leapTime] :: LeapInfo -> Integer -- | The new total offset of UTC from UT1 after this leap second [leapOffset] :: LeapInfo -> Int -- | The reference C implentation imposes size limits on the data -- structures in a timezone file. data SizeLimits SizeLimits :: Maybe Int -> Maybe Int -> Maybe Int -> Maybe Int -> SizeLimits -- | The maximum number of transition times [maxTimes] :: SizeLimits -> Maybe Int -- | The maximum number of TtInfo clock settings [maxTypes] :: SizeLimits -> Maybe Int -- | The maximum total number of bytes in all timezone abbreviations. [maxAbbrChars] :: SizeLimits -> Maybe Int -- | The maximum number of leap second specifications. [maxLeaps] :: SizeLimits -> Maybe Int -- | 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. defaultLimits :: SizeLimits -- | limitsNoSolar contains the tighter size limits imposed on -- some platforms that do not allow timezones that are based on solar -- time. limitsNoSolar :: 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. noLimits :: SizeLimits