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


-- | Type classes for types representing time
--   
--   This library defines a set of type classes for generic time
--   arithmetic. It supports universal time types like <tt>UTCTime</tt>
--   from the <a>time library</a> as well as physical time types like the
--   ones from <a>clock</a>.
@package timelike
@version 0.2.2


-- | Time can be captured in terms of affine spaces. These are basically
--   sets (points in time) enriched by a notion of relative movement (time
--   deltas). Think of the real line representing points in time. Now think
--   of left- and right-pointing arrows that represent relative motion by a
--   certain time duration. You may attach such an arrow to any point in
--   time, and its head will point to the destination point in time if you
--   were to perform the motion represented by the arrow.
--   
--   Given a <a>Time</a> type <tt>t</tt> its deltas are of type
--   <tt><a>Delta</a> t</tt>. Deltas should form a group under addition.
--   This is actually all the structure required for them, but for
--   compatibility reasons we require them to be a <a>Num</a> type.
module Data.Time.Class

-- | Class of time-like types, i.e. types that support time arithmetic with
--   the help of a time-delta type. Instances should satisfy the following
--   laws:
--   
--   <pre>
--   addTime 0 t = t
--   addTime dt1 (addTime dt2 t) = addTime (dt1 + dt2) t
--   addTime (diffTime t1 t2) t2 = t1
--   </pre>
--   
--   For the common case of one-dimensional, totally ordered time the
--   <a>diffTime</a> function is expected to act like subtraction. This
--   means that if <tt>t1</tt> is later than <tt>t0</tt>, then
--   <tt><a>diffTime</a> t1 t0</tt> will be a positive value.
class (Num (Delta t)) => Time t where type family Delta t

-- | Add the given time delta to the given point in time.
addTime :: Time t => Delta t -> t -> t

-- | The delta between the given points in time.
diffTime :: Time t => t -> t -> Delta t

-- | Some time types measure time relative to a (usually arbitrary but
--   well-defined) origin.
class (Time t) => TimeOrigin t

-- | The origin of time.
timeOrigin :: TimeOrigin t => t

-- | For most time types the deltas correspond to physical time.
--   
--   Note: In this library <i>physical</i> time essentially means "measured
--   in seconds", not necessarily real time. For example the CPU time
--   passed since program start counts as physical time.
class (Time t) => TimeSeconds t where deltaSecs _ = realToFrac

-- | The number of seconds the given delta represents.
--   
--   Default is <tt>const <a>realToFrac</a></tt> if <tt><a>Delta</a> t</tt>
--   is an instance of <a>Real</a>.
deltaSecs :: (TimeSeconds t, Fractional a) => proxy t -> Delta t -> a

-- | The duration of one second.
oneSecond :: TimeSeconds t => proxy t -> Delta t

-- | The number of seconds the given delta represents.
--   
--   This is a convenience wrapper around <a>deltaSecs</a> that allows you
--   to pass an existing time value instead of a proxy to communicate the
--   type.
deltaSecsFor :: (Fractional a, TimeSeconds t) => t -> Delta t -> a

-- | Time delta since the origin of time.
--   
--   <pre>
--   deltaSinceOrigin t = diffTime t timeOrigin
--   </pre>
deltaSinceOrigin :: (TimeOrigin t) => t -> Delta t

-- | The duration of one second.
--   
--   This is a convenience wrapper around <a>deltaSecs</a> that allows you
--   to pass an existing time value instead of a proxy to communicate the
--   type.
oneSecondFor :: (TimeSeconds t) => t -> Delta t

-- | Class of time types that measure time in common units.
--   
--   The <a>next</a> function is exclusive with respect to the given point
--   in time, while the <a>begin</a> function is inclusive. The
--   <tt>skip*</tt> family of functions just skips the given number of the
--   given unit. Examples (numbers represent seconds):
--   
--   <pre>
--   iterate (begin Second)   12.3 = [ 12.3, 13.0, 13.0, 13.0, ... ]
--   iterate (next Second)    12.3 = [ 12.3, 13.0, 14.0, 15.0, ... ]
--   iterate (skipOne Second) 12.3 = [ 12.3, 13.3, 14.3, 15.3, ... ]
--   </pre>
--   
--   These functions ignore leap seconds, unless <tt>t</tt> specifically
--   has a representation for them (such as TAI). For example skipping one
--   second with <i>time</i>'s <tt>UTCTime</tt> may skip up to two seconds
--   of physical time.
class (Time t) => SkipUnit t where skipOne = skip 1

-- | Skip to the beginning of the next given unit of time, unless already
--   at the beginning of a unit.
begin :: SkipUnit t => TimeUnit -> t -> t

-- | Skip to the beginning of the next given unit of time, even when
--   already at the beginning of a unit.
next :: SkipUnit t => TimeUnit -> t -> t

-- | Skip the given number of the given units of time, keeping the time
--   within that unit if possible.
skip :: SkipUnit t => Integer -> TimeUnit -> t -> t

-- | Skip one given unit of time, keeping the time within that unit if
--   possible.
--   
--   <pre>
--   skipOne = skip 1
--   </pre>
skipOne :: SkipUnit t => TimeUnit -> t -> t

-- | Common units of time with constant durations.
--   
--   The durations of minutes, hours and days are semi-constant. Days are
--   defined to be constant in universal time, but due to our technical
--   inability to build a universal time clock we use approximations (like
--   UTC), which admit leap seconds for synchronisation. This means that
--   the last minute of a day may take 59 or 61 seconds.
data TimeUnit

-- | Seconds.
Second :: TimeUnit

-- | Minutes.
Minute :: TimeUnit

-- | Hours.
Hour :: TimeUnit

-- | Days.
Day :: TimeUnit

-- | Class of time types that represent universal time and understand
--   weeks, months and years.
class (SkipUnit t) => SkipDate t where dateSkipOne = dateSkip 1

-- | Skip to the beginning of the next given unit of time according to the
--   represented calendar, unless already at the beginning of a unit.
dateBegin :: SkipDate t => DateUnit -> t -> t

-- | Skip to the beginning of the next given unit of time according to the
--   represented calendar, , even when already at the beginning of a unit.
dateNext :: SkipDate t => DateUnit -> t -> t

-- | Skip the given number of the given units of time according to the
--   represented calendar, keeping the time within that unit if possible.
dateSkip :: SkipDate t => Integer -> DateUnit -> t -> t

-- | Skip one given unit of time according to the represented calendar,
--   keeping the time within that unit if possible.
--   
--   <pre>
--   dateSkipOne = dateSkip 1
--   </pre>
dateSkipOne :: SkipDate t => DateUnit -> t -> t

-- | Common units of calendar time. The durations are not necessarily
--   constant.
data DateUnit

-- | Weeks starting at the given day (0 means Sunday).
Week :: Int -> DateUnit

-- | Months.
Month :: DateUnit

-- | Years.
Year :: DateUnit

-- | Convenient alias for <tt><a>Week</a> 0</tt>.
sunday :: DateUnit

-- | Convenient alias for <tt><a>Week</a> 1</tt>.
monday :: DateUnit

-- | Convenient alias for <tt><a>Week</a> 2</tt>.
tuesday :: DateUnit

-- | Convenient alias for <tt><a>Week</a> 3</tt>.
wednesday :: DateUnit

-- | Convenient alias for <tt><a>Week</a> 4</tt>.
thursday :: DateUnit

-- | Convenient alias for <tt><a>Week</a> 5</tt>.
friday :: DateUnit

-- | Convenient alias for <tt><a>Week</a> 6</tt>.
saturday :: DateUnit

-- | Most time types represent time as read by an actual clock. Instances
--   of this class support querying that clock.
class (Functor m, Time t) => GetTime m t

-- | Get the current time.
getTime :: GetTime m t => m t

-- | Get the current time. This is a convenience wrapper around
--   <a>getTime</a>.
getTimeAs :: (GetTime m t) => proxy t -> m t

-- | Get the time delta from now to the given point in time.
--   
--   <pre>
--   getDeltaSince t0 = fmap (`diffTime` t0) getTime
--   </pre>
getDeltaSince :: (GetTime m t) => t -> m (Delta t)

-- | Sleep until the given point in time. This function repeatedly uses
--   <a>threadDelay</a> with a maximum of the given delta, until the goal
--   time is reached.
--   
--   Note: Generally the maximum delta should not be set too high, because
--   changes in system time are only noticed between individual delays.
--   This is also the main motivation behind this function.
delayUntil :: (MonadIO m, GetTime m t, Ord (Delta t), TimeSeconds t) => Delta t -> t -> m ()

-- | Sleep until the given point in time. This function first uses
--   <a>delayUntil</a> to sleep until just before the goal time. Then it
--   switches to a busy loop until the goal time is reached.
--   
--   This function is provided for applications that need sub-millisecond
--   precision sleeping. However, please note that most applications do
--   not, thus it would just waste power. Also note that there are no
--   real-time guarantees whatsoever.
--   
--   The idle sleep threshold (first argument) specifies how long before
--   the goal time this function switches to busy sleeping. The best choice
--   is highly system- and application-dependent, but an estimate of
--   slightly above the system's context switching interval should be a
--   good initial guess.
--   
--   Note: the maximum delta generally should not be set too high, because
--   changes in system time are only noticed between individual delays.
busyDelayUntil :: (MonadIO m, GetTime m t, Ord (Delta t), TimeSeconds t) => Delta t -> Delta t -> t -> m ()
instance GHC.Show.Show Data.Time.Class.TimeUnit
instance GHC.Classes.Ord Data.Time.Class.TimeUnit
instance GHC.Classes.Eq Data.Time.Class.TimeUnit
instance GHC.Enum.Enum Data.Time.Class.TimeUnit
instance GHC.Enum.Bounded Data.Time.Class.TimeUnit
instance GHC.Show.Show Data.Time.Class.DateUnit
instance GHC.Classes.Ord Data.Time.Class.DateUnit
instance GHC.Classes.Eq Data.Time.Class.DateUnit