-- 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.twinsun.com/tz/tz-link.htm. 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. @package timezone-olson @version 0.1.2 -- | 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 putOlson :: OlsonData -> Put -- | Render Olson timezone data in binary Olson timezone file format as a -- lazy ByteString -- -- 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 -- 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. 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