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


-- | Haskell bindings for the zone-detect C library; plus tz-aware utils.
--   
--   Please see the README on GitHub at
--   <a>https://github.com/lfborjas/timezone-detect#readme</a>
@package timezone-detect
@version 0.2.2.0

module Foreign.ZoneDetect
data ZoneDetectInfo
ZoneDetectInfo :: Int -> CInt -> Word8 -> Ptr Word8 -> Word8 -> Word8 -> Word8 -> Word8 -> CString -> Ptr CString -> Word32 -> Word32 -> Word32 -> ZoneDetectInfo
[fd] :: ZoneDetectInfo -> Int
[length] :: ZoneDetectInfo -> CInt
[closeType] :: ZoneDetectInfo -> Word8
[mapping] :: ZoneDetectInfo -> Ptr Word8
[tableType] :: ZoneDetectInfo -> Word8
[version] :: ZoneDetectInfo -> Word8
[precision] :: ZoneDetectInfo -> Word8
[numFields] :: ZoneDetectInfo -> Word8
[notice] :: ZoneDetectInfo -> CString
[fieldNames] :: ZoneDetectInfo -> Ptr CString
[bboxOffset] :: ZoneDetectInfo -> Word32
[metadataOffset] :: ZoneDetectInfo -> Word32
[dataOffset] :: ZoneDetectInfo -> Word32
c_ZDOpenDatabase :: CString -> IO (Ptr ZoneDetectInfo)
c_ZDHelperSimpleLookupString :: Ptr ZoneDetectInfo -> CFloat -> CFloat -> IO CString


-- | Exposes utilities derived from the excellent ZoneDetect library
--   <a>https://github.com/BertoldVdb/ZoneDetect</a>. To use this module,
--   you need to obtain database files from the aforementioned library's
--   server.
--   
--   Additionally, if you have a local time, latitude and longitude, we use
--   the timezone-series and timezone-olson packages to help determine the
--   equivalent UTC instant to that point in geography and time.
--   
--   The only relevant binding to ZoneDetect is <a>lookupTimeZoneName</a>,
--   richer information that plays neatly with the notion of
--   <a>TimeZone</a> could be derived, but I didn't have a personal need
--   for that yet.
module Data.Time.LocalTime.TimeZone.Detect

-- | Given a timezone database, latitude and longitude, try to determine
--   the timezone name. Follow the instructions in the C library's
--   repository to obtain timezone database files
--   (<a>https://github.com/BertoldVdb/ZoneDetect/tree/05567e367576d7f3efa00083b7661a01e43dc8ca/database</a>)
--   Once in possesion of said files, the lookup looks as follows:
--   
--   <pre>
--   &gt;&gt;&gt; tz &lt;- lookupTimeZoneName "./test/tz_db/timezone21.bin" 40.7831 (-73.9712) :: Maybe TimeZoneName
--   Just "America/New_York"
--   </pre>
--   
--   An invalid database file, or invalid coordinates, will cause the given
--   monad to <a>fail</a>.
lookupTimeZoneName :: MonadFail m => FilePath -> Double -> Double -> m TimeZoneName

-- | Given a timezone database, latitude, longitude and a local reference
--   time, find the UTC Time equivalent of that reference time in the given
--   timezone. The reference time helps determine which offset was in
--   effect, since daylight savings, historical circumstances, political
--   revisions and other circumstances (documented in the olson tz
--   database) may have been in effect at that point in spacetime.
timeAtPointToUTC :: FilePath -> Double -> Double -> LocalTime -> IO UTCTime

-- | Given a timezone name (presumably obtained via
--   <a>lookupTimeZoneName</a>,) and a reference time in <a>LocalTime</a>,
--   find the UTC equivalent.
timeInTimeZoneToUTC :: TimeZoneName -> LocalTime -> IO UTCTime

-- | Gets timezone info from the standard location in UNIX systems. The
--   name should be one of the standard tz database names, as returned by
--   <a>lookupTimeZoneName</a>. See:
--   <a>https://en.wikipedia.org/wiki/List_of_tz_database_time_zones</a>
getTimeZoneSeriesFromOlsonFileUNIX :: TimeZoneName -> IO TimeZoneSeries

-- | Alias for clarity, timezones are path-like strings that follow the
--   IANA conventions documented here:
--   <a>https://data.iana.org/time-zones/tz-link.html</a> and here:
--   <a>https://en.wikipedia.org/wiki/Tz_database#Names_of_time_zones</a>
type TimeZoneName = FilePath