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

-- | Unix time parser/formatter and utilities
--   
--   Fast parser/formatter/utilities for Unix time
@package unix-time
@version 0.4.17

module Data.UnixTime

-- | Data structure for Unix time.
--   
--   Please note that this uses GHC-derived Eq and Ord
--   instances. Notably
--   
--   
--   >>> UnixTime 1 0 > UnixTime 0 999999999
--   True
--   
--   
--   You should instead use UnixDiffTime along with its helpers such
--   as microSecondsToUnixDiffTime which will ensure that such
--   unusual values are never created.
data UnixTime
UnixTime :: {-# UNPACK #-} !CTime -> {-# UNPACK #-} !Int32 -> UnixTime

-- | Seconds from 1st Jan 1970
[utSeconds] :: UnixTime -> {-# UNPACK #-} !CTime

-- | Micro seconds (i.e. 10^(-6))
[utMicroSeconds] :: UnixTime -> {-# UNPACK #-} !Int32

-- | Get current UnixTime from OS.
getUnixTime :: IO UnixTime

-- | Parsing ByteString to UnixTime interpreting as
--   localtime. This is a wrapper for strptime_l(). Many implementations of
--   strptime_l() do not support %Z and some implementations of
--   strptime_l() do not support %z, either. utMicroSeconds is
--   always set to 0.
parseUnixTime :: Format -> ByteString -> UnixTime

-- | Parsing ByteString to UnixTime interpreting as GMT. This
--   is a wrapper for strptime_l(). utMicroSeconds is always set to
--   0.
--   
--   
--   >>> parseUnixTimeGMT webDateFormat "Thu, 01 Jan 1970 00:00:00 GMT"
--   UnixTime {utSeconds = 0, utMicroSeconds = 0}
--   
parseUnixTimeGMT :: Format -> ByteString -> UnixTime

-- | Formatting UnixTime to ByteString in local time. This is
--   a wrapper for strftime_l(). utMicroSeconds is ignored. The
--   result depends on the TZ environment variable.
formatUnixTime :: Format -> UnixTime -> IO ByteString

-- | Formatting UnixTime to ByteString in GMT. This is a
--   wrapper for strftime_l(). utMicroSeconds is ignored.
--   
--   
--   >>> formatUnixTimeGMT webDateFormat $ UnixTime 0 0
--   "Thu, 01 Jan 1970 00:00:00 GMT"
--   
--   >>> let ut = UnixTime 100 200
--   
--   >>> let str = formatUnixTimeGMT "%s" ut
--   
--   >>> let ut' = parseUnixTimeGMT "%s" str
--   
--   >>> ((==) `on` utSeconds) ut ut'
--   True
--   
--   >>> ((==) `on` utMicroSeconds) ut ut'
--   False
--   
formatUnixTimeGMT :: Format -> UnixTime -> ByteString

-- | Format of the strptime()/strftime() style.
type Format = ByteString

-- | Format for web (RFC 2616). The value is "%a, %d %b %Y %H:%M:%S GMT".
--   This should be used with formatUnixTimeGMT and
--   parseUnixTimeGMT.
webDateFormat :: Format

-- | Format for e-mail (RFC 5322). The value is "%a, %d %b %Y %H:%M:%S %z".
--   This should be used with formatUnixTime and
--   parseUnixTime.
mailDateFormat :: Format

-- | Data structure for UnixTime diff.
--   
--   It is up to the user to ensure that udtMicroSeconds <
--   1000000. Helpers such as microSecondsToUnixDiffTime can
--   help you to create valid values. For example, it's a mistake to use
--   addUnixDiffTime with a value UnixDiffTime 0 9999999 as
--   it will produce an incorrect value back. You should instead use
--   functions such as microSecondsToUnixDiffTime to create values
--   that are in-range. This avoids any gotchas when then doing
--   comparisons.
data UnixDiffTime
UnixDiffTime :: {-# UNPACK #-} !CTime -> {-# UNPACK #-} !Int32 -> UnixDiffTime

-- | Seconds
[udtSeconds] :: UnixDiffTime -> {-# UNPACK #-} !CTime

-- | Micro seconds (i.e. 10^(-6))
[udtMicroSeconds] :: UnixDiffTime -> {-# UNPACK #-} !Int32

-- | Calculating difference between two UnixTime.
--   
--   
--   >>> UnixTime 100 2000 `diffUnixTime` UnixTime 98 2100
--   UnixDiffTime {udtSeconds = 1, udtMicroSeconds = 999900}
--   
diffUnixTime :: UnixTime -> UnixTime -> UnixDiffTime

-- | Adding difference to UnixTime.
--   
--   
--   >>> UnixTime 100 2000 `addUnixDiffTime` microSecondsToUnixDiffTime ((-1003000) :: Int)
--   UnixTime {utSeconds = 98, utMicroSeconds = 999000}
--   
addUnixDiffTime :: UnixTime -> UnixDiffTime -> UnixTime

-- | Creating difference from seconds.
--   
--   
--   >>> secondsToUnixDiffTime (100 :: Int)
--   UnixDiffTime {udtSeconds = 100, udtMicroSeconds = 0}
--   
secondsToUnixDiffTime :: Integral a => a -> UnixDiffTime

-- | Creating difference from micro seconds.
--   
--   
--   >>> microSecondsToUnixDiffTime (12345678 :: Int)
--   UnixDiffTime {udtSeconds = 12, udtMicroSeconds = 345678}
--   
--   
--   
--   >>> microSecondsToUnixDiffTime ((-12345678) :: Int)
--   UnixDiffTime {udtSeconds = -12, udtMicroSeconds = -345678}
--   
microSecondsToUnixDiffTime :: Integral a => a -> UnixDiffTime

-- | From EpochTime to UnixTime setting utMicroSeconds
--   to 0.
fromEpochTime :: EpochTime -> UnixTime

-- | From UnixTime to EpochTime ignoring
--   utMicroSeconds.
toEpochTime :: UnixTime -> EpochTime

-- | From ClockTime to UnixTime.
fromClockTime :: ClockTime -> UnixTime

-- | From UnixTime to ClockTime.
toClockTime :: UnixTime -> ClockTime
