-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | 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
--   <a>http://www.iana.org/time-zones/repository/tz-link.html</a>.
--   Functions are provided for converting the parsed data into
--   <a>TimeZoneSeries</a> objects from the timezone-series package. On
--   many platforms, binary Olson timezone files suitable for use with this
--   package are available in the directory <i>usr</i>share/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
--   (<a>http://hackage.haskell.org/package/timezone-olson-th</a>).
@package timezone-olson
@version 0.2.1


-- | 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 <tt>TimeZoneSeries</tt> and <tt>TimeZone</tt>
--   objects.
module Data.Time.LocalTime.TimeZone.Olson

-- | A binary parser for binary Olson timezone files
getOlson :: SizeLimits -> Get OlsonData

-- | Parse a binary Olson timezone file.
--   
--   If the values in the Olson timezone file exceed the standard size
--   limits (see <a>defaultLimits</a>), this function throws an exception.
--   For other behavior, use <a>getOlson</a> and <a>runGet</a> directly.
getOlsonFromFile :: FilePath -> IO OlsonData

-- | Read timezone data from a binary Olson timezone file and convert it
--   into a <tt>TimeZoneSeries</tt> for use together with the types and
--   fucntions of <a>Data.Time</a>. 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 <a>defaultLimits</a>), this function throws an exception.
--   For other behavior, use <a>getOlson</a> and <a>runGet</a> directly.
getTimeZoneSeriesFromOlsonFile :: FilePath -> IO TimeZoneSeries

-- | Convert parsed Olson timezone data into a <tt>TimeZoneSeries</tt>.
olsonToTimeZoneSeries :: OlsonData -> Maybe TimeZoneSeries

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

-- | Extract Olson timezone data that can be rendered using Version 1
--   format
extractOlsonV1 :: OlsonData -> OlsonData

-- | Render Olson timezone data in binary Olson timezone file format as a
--   lazy <tt>ByteString</tt>
putOlson :: OlsonData -> Put

-- | Render Olson timezone data as a binary Olson timezone file
--   
--   If the values in the Olson timezone data exceed the standard size
--   limits (see <a>defaultLimits</a>), this function throws an exception.
--   For other behavior, use <a>verifyOlsonLimits</a>, <a>putOlson</a> and
--   <a>runPut</a> directly.
renderOlsonToFile :: FilePath -> OlsonData -> IO ()

-- | Render a <tt>TimeZoneSeries</tt> as a binary Olson timezone file.
--   
--   If the values in the Olson timezone data exceed the standard size
--   limits (see <a>defaultLimits</a>), this function throws an exception.
--   For other behavior, use <a>timeZoneSeriesToOlson</a>,
--   <a>verifyOlsonLimits</a>, <a>putOlson</a> and <a>runPut</a> directly.
renderTimeZoneSeriesToOlsonFile :: FilePath -> TimeZoneSeries -> IO ()

-- | Convert a <tt>TimeZoneSeries</tt> to <tt>OlsonData</tt> for rendering.
timeZoneSeriesToOlson :: TimeZoneSeries -> Maybe OlsonData

-- | Check whether <tt>OlsonData</tt> is within size limits.
verifyOlsonLimits :: SizeLimits -> OlsonData -> Bool

-- | The size limits in <tt>defaultLimits</tt> are taken from the file
--   tzfile.h from tzcode version 2010f. These are the limits for the C
--   implementation on many platforms.
defaultLimits :: SizeLimits

-- | <tt>limitsNoSolar</tt> contains the tighter size limits imposed on
--   some platforms that do not allow timezones that are based on solar
--   time.
limitsNoSolar :: SizeLimits

-- | <tt>noLimits</tt> imposes no size limits. If you use <tt>noLimits</tt>
--   when parsing, you may exhaust all available memory when reading a
--   faulty or malicious timezone file. If you use <tt>noLimits</tt> when
--   rendering, the rendered timezone file might not be readable on some
--   systems.
noLimits :: SizeLimits

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

-- | <tt>OlsonData</tt> represents a full set of timezone data for a
--   location.
--   
--   <tt>OlsonData</tt> 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
--   <a>String</a>, 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 <tt>Transition</tt>
[olsonPosixTZ] :: OlsonData -> Maybe String

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

-- | A <tt>Transition</tt> 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 <tt>TtInfo</tt> 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 <tt>TtInfo</tt> that describes the new
--   time
[transIndex] :: Transition -> Int

-- | A <tt>TransitionType</tt> 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 <tt>TtInfo</tt> is a specification of local time in a timezone for
--   some period during which the clocks did not change. <tt>abbr</tt> is
--   <tt>String</tt> if the timezone abbreviation is represented as a
--   <tt>String</tt>, or <tt>Int</tt> 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_utoff] :: 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
