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

module Data.UnixTime

-- | Data structure for Unix time.
--   
--   Please note that this uses GHC-derived <a>Eq</a> and <a>Ord</a>
--   instances. Notably
--   
--   <pre>
--   &gt;&gt;&gt; UnixTime 1 0 &gt; UnixTime 0 999999999
--   True
--   </pre>
--   
--   You should instead use <a>UnixDiffTime</a> along with its helpers such
--   as <a>microSecondsToUnixDiffTime</a> 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

-- | Getting <a>UnixTime</a> from OS.
getUnixTime :: IO UnixTime

-- | Parsing <a>ByteString</a> to <a>UnixTime</a> 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.
parseUnixTime :: Format -> ByteString -> UnixTime

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

-- | Formatting <a>UnixTime</a> to <a>ByteString</a> in local time. This is
--   a wrapper for strftime_l().
formatUnixTime :: Format -> UnixTime -> IO ByteString

-- | Formatting <a>UnixTime</a> to <a>ByteString</a> in GMT. This is a
--   wrapper for strftime_l().
--   
--   <pre>
--   &gt;&gt;&gt; formatUnixTimeGMT webDateFormat $ UnixTime 0 0
--   "Thu, 01 Jan 1970 00:00:00 GMT"
--   </pre>
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 <a>formatUnixTimeGMT</a> and
--   <a>parseUnixTimeGMT</a>.
webDateFormat :: Format

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

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

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

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

-- | Calculating difference between two <a>UnixTime</a>.
--   
--   <pre>
--   &gt;&gt;&gt; UnixTime 100 2000 `diffUnixTime` UnixTime 98 2100
--   UnixDiffTime {udtSeconds = 1, udtMicroSeconds = 999900}
--   </pre>
diffUnixTime :: UnixTime -> UnixTime -> UnixDiffTime

-- | Adding difference to <a>UnixTime</a>.
--   
--   <pre>
--   &gt;&gt;&gt; UnixTime 100 2000 `addUnixDiffTime` microSecondsToUnixDiffTime (-1003000)
--   UnixTime {utSeconds = 98, utMicroSeconds = 999000}
--   </pre>
addUnixDiffTime :: UnixTime -> UnixDiffTime -> UnixTime

-- | Creating difference from seconds.
--   
--   <pre>
--   &gt;&gt;&gt; secondsToUnixDiffTime 100
--   UnixDiffTime {udtSeconds = 100, udtMicroSeconds = 0}
--   </pre>
secondsToUnixDiffTime :: (Integral a) => a -> UnixDiffTime

-- | Creating difference from micro seconds.
--   
--   <pre>
--   &gt;&gt;&gt; microSecondsToUnixDiffTime 12345678
--   UnixDiffTime {udtSeconds = 12, udtMicroSeconds = 345678}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; microSecondsToUnixDiffTime (-12345678)
--   UnixDiffTime {udtSeconds = -12, udtMicroSeconds = -345678}
--   </pre>
microSecondsToUnixDiffTime :: (Integral a) => a -> UnixDiffTime

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

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

-- | From <a>ClockTime</a> to <a>UnixTime</a>.
fromClockTime :: ClockTime -> UnixTime

-- | From <a>UnixTime</a> to <a>ClockTime</a>.
toClockTime :: UnixTime -> ClockTime
