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


-- | Time to manipulate time
--   
--   A simple type useful for representing timestamps as generated by
--   system events, along with conveniences for converting between time
--   types from common Haskell time libraries.
--   
--   Our original use was wanting to conveniently measure things happening
--   on distributed computer systems. Since machine clock cycles are in
--   units of nanoseconds, this has the nice property that, assuming the
--   system clock is not corrupted, two subsequent events from the same
--   source process are likely to have monotonically increasing timestamps.
--   And even if the system clock has skew, they're still decently likely
--   to be unique per device. These TimeStamps thus make good keys when
--   building Maps.
--   
--   The core type is in <a>Chrono.TimeStamp</a>, see there for full
--   documentation.
@package chronologique
@version 0.3.1.1

module Chrono.TimeStamp

-- | Number of nanoseconds since the Unix epoch.
--   
--   The Show instance displays the TimeStamp as seconds with the
--   nanosecond precision expressed as a decimal amount after the interger,
--   ie:
--   
--   <pre>
--   &gt;&gt;&gt; t &lt;- getCurrentTimeNanoseconds
--   
--   &gt;&gt;&gt; show t
--   2014-07-31T23:09:35.274387031Z
--   </pre>
--   
--   However this doesn't change the fact the underlying representation
--   counts nanoseconds since epoch:
--   
--   <pre>
--   &gt;&gt;&gt; show $ unTimeStamp t
--   1406848175274387031
--   </pre>
--   
--   There is a Read instance that is reasonably accommodating.
--   
--   <pre>
--   &gt;&gt;&gt; read "2014-07-31T13:05:04.942089001Z" :: TimeStamp
--   2014-07-31T13:05:04.942089001Z
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; read "1406811904.942089001" :: TimeStamp
--   2014-07-31T13:05:04.942089001Z
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; read "1406811904" :: TimeStamp
--   2014-07-31T13:05:04.000000000Z
--   </pre>
--   
--   In case you're wondering, the valid range of nanoseconds that fits
--   into the underlying Int64 is:
--   
--   <pre>
--   &gt;&gt;&gt; show $ minBound :: TimeStamp
--   1677-09-21T00:12:43.145224192Z
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; show $ maxBound :: TimeStamp
--   2262-04-11T23:47:16.854775807Z
--   </pre>
--   
--   so in a quarter millenium's time, yes, you'll have the Y2262 Problem.
--   Haskell code from today will, of course, still be running, so in the
--   mid Twenty-Third century you will need to replace this implementation
--   with something else.
newtype TimeStamp
TimeStamp :: Int64 -> TimeStamp
[unTimeStamp] :: TimeStamp -> Int64

-- | Get the current system time, expressed as a <a>TimeStamp</a> (which is
--   to say, number of nanoseconds since the Unix epoch).
getCurrentTimeNanoseconds :: IO TimeStamp

-- | Format string describing full (nanosecond) precision ISO8601 time,
--   
--   <pre>
--   2014-07-31T23:09:35.274387019Z
--   </pre>
data ISO8601_Precise
ISO8601_Precise :: ISO8601_Precise
instance GHC.Generics.Generic Chrono.TimeStamp.TimeStamp
instance GHC.Enum.Bounded Chrono.TimeStamp.TimeStamp
instance GHC.Real.Integral Chrono.TimeStamp.TimeStamp
instance GHC.Real.Real Chrono.TimeStamp.TimeStamp
instance GHC.Num.Num Chrono.TimeStamp.TimeStamp
instance GHC.Enum.Enum Chrono.TimeStamp.TimeStamp
instance GHC.Classes.Ord Chrono.TimeStamp.TimeStamp
instance GHC.Classes.Eq Chrono.TimeStamp.TimeStamp
instance Data.Vector.Unboxed.Base.Unbox Chrono.TimeStamp.TimeStamp
instance Data.Hourglass.Time.Timeable Chrono.TimeStamp.TimeStamp
instance Data.Hourglass.Time.Time Chrono.TimeStamp.TimeStamp
instance GHC.Show.Show Chrono.TimeStamp.TimeStamp
instance GHC.Read.Read Chrono.TimeStamp.TimeStamp
instance Data.Vector.Generic.Base.Vector Data.Vector.Unboxed.Base.Vector Chrono.TimeStamp.TimeStamp
instance Data.Vector.Generic.Mutable.Base.MVector Data.Vector.Unboxed.Base.MVector Chrono.TimeStamp.TimeStamp
instance Data.Aeson.Types.ToJSON.ToJSON Chrono.TimeStamp.TimeStamp
instance Data.Aeson.Types.FromJSON.FromJSON Chrono.TimeStamp.TimeStamp


-- | Compatibility with time types from other time handling libraries. Some
--   of these are just conveniences, but it's not always obvious how to
--   convert between time types even in the same package.
module Chrono.Compat

-- | Utility function to convert nanoseconds since Unix epoch to a
--   <a>NominalDiffTime</a>, allowing you to then use the time manipulation
--   functions in <a>Data.Time.Clock</a> from <b>time</b>.
convertToPosix :: TimeStamp -> POSIXTime
convertFromPosix :: POSIXTime -> TimeStamp

-- | Annoyingly, the various types in <b>time</b> don't interoperate. Quite
--   frequently you need to get to, or from, <a>UTCTime</a>.
convertToUTC :: TimeStamp -> UTCTime
convertFromUTC :: UTCTime -> TimeStamp

-- | Utility function to convert nanoseconds since Unix epoch to a
--   <a>ElapsedP</a>, allowing you to then use the time manipulation
--   functions in the <b>hourglass</b> package.
convertToHourglass :: TimeStamp -> ElapsedP
convertFromHourglass :: ElapsedP -> TimeStamp
