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


-- | Use a time unit class, but hold a concrete time type.
--   
@package time-interval
@version 0.1.0.0


-- | Suppose you have a program which periodically reloads state and saves
--   some logs, and you'd like the intervals for these periodic actions to
--   be expressed using time units, and abstract away the internal
--   representation until the site of actual use. Your code may look like
--   this:
--   
--   <pre>
--   data AppState tr ts = AppState
--       { userName       :: String
--       , newMessages    :: [String]
--       , reloadInterval :: tr
--       , saveInterval   :: ts
--       }
--   
--   type App tr ts = StateT (AppState tr ts) IO
--   
--   setReloadInterval :: TimeUnit t =&gt; t -&gt; App ()
--   setReloadInterval new = modify $ \ s -&gt; s { reloadInterval = new }
--   
--   syncStateWithFiles :: (TimeUnit tr, TimeUnit ts) =&gt; App tr ts ()
--   syncStateWithFiles = do
--       reloadMicrosec &lt;- liftM toMicroseconds $ gets reloadInterval
--       saveMicrosec &lt;- liftM toMicroseconds $ gets saveInterval
--       {- ... use the values ... -}
--   </pre>
--   
--   And usage looks like this:
--   
--   <pre>
--   setReloadInterval (5 :: Second)
--   </pre>
--   
--   So every time you add, change or remove a time field, all your type
--   signatures need to be updated and all your <tt>App</tt> actions, even
--   unrelated to those times, are stuck with time type parameters in their
--   type signatures.
--   
--   An easy and common approach to avoid all the mess is to store the time
--   as an integer, i.e. applying <a>toMicroseconds</a> when setting the
--   value rather than when using it. That makes things much easier, but
--   then your type (and your API) expose the time directly as a number of
--   microseconds, and people end up writing things like <tt>1000 * 1000 *
--   60 * 5</tt> to say "5 minuts". It's also an internal technical detail
--   there's no reason to expose, and should be possible to change without
--   breaking anything - e.g. what if your scheduling tool one day moves to
--   a higher precision than microseconds? Your high-level API would
--   ideally not let that change float all the way up.
--   
--   Here's how things can work when using this library.
--   
--   <pre>
--   data AppState = AppState
--       { userName       :: String
--       , newMessages    :: [String]
--       , reloadInterval :: TimeInterval
--       , saveInterval   :: TimeInterval
--       }
--   
--   type App = StateT AppState IO
--   
--   setReloadInterval :: TimeUnit t =&gt; t -&gt; App ()
--   setReloadInterval new = modify $ \ s -&gt; s { reloadInterval = time new }
--   
--   syncStateWithFiles :: App ()
--   syncStateWithFiles = do
--       reloadMicrosec &lt;- liftM microseconds $ gets reloadInterval
--       saveMicrosec &lt;- liftM microseconds $ gets saveInterval
--       {- ... use the values ... -}
--   </pre>
--   
--   And usage looks the same:
--   
--   <pre>
--   setReloadInterval (5 :: Second)
--   </pre>
--   
--   Also, even if you let the user use the <a>time</a> function in their
--   code, e.g. like this:
--   
--   <pre>
--   setReloadInterval $ time (5 :: Second)
--   </pre>
--   
--   ... you stil get the advantages from both worlds.
module Data.Time.Interval

-- | A time duration.
data TimeInterval

-- | Convert a time value expressed in a some time unit into a
--   <a>TimeInterval</a>.
time :: TimeUnit t => t -> TimeInterval

-- | Express a <a>TimeInterval</a> in microseconds.
microseconds :: TimeInterval -> Integer
instance Eq TimeInterval
instance Ord TimeInterval
instance Show TimeInterval