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


-- | Use a time unit class, but hold a concrete time type.
--   
--   Two common ways to represent and hold short time intervals seem to be:
--   
--   <ol>
--   <li>Hold time in microseconds as an <a>Int</a> or <a>Integer</a></li>
--   <li>Use time units abstraction, e.g. see the time-units package</li>
--   </ol>
--   
--   While the second option is a great abstraction to use in APIs, it
--   works for datatypes a bit less well than for function types. That's
--   because a datatype which a <a>Data.Time.Units.TimeUnit</a> field
--   suddenly becomes polymorphic over that field, and all function type
--   signatures involving that datatype need to be updated. This is less an
--   issue for functions, because you don't specify the type of every
--   function at the call site.
--   
--   Perhaps there is a solution for that which involves datatype related
--   language extensions, but this package tries to offer a simple clean
--   solution as follows. You store time in your datatype as an integer,
--   but it is wrapped by an opaque <a>Data.Time.Interval.TimeInterval</a>
--   type. You then get the best of both worlds:
--   
--   <ul>
--   <li>On one hand, you can set the time field using any time unit thanks
--   to the time-units package, so you get a nice abstraction</li>
--   <li>On the other hand, your datatype holds a concrete time type</li>
--   </ul>
--   
--   The time type can be equally used to represent time intervals, time
--   durations and generally time lengths. But since high precision is used
--   (microseconds), you'll probably want this library for short time
--   lengths (at most seconds, minutes, hours). For calendar based and
--   related time functions and types, see the <tt>time</tt> package.
@package time-interval
@version 0.1.1


-- | Suppose you have <tt>Settings</tt> type, and one of its fields
--   specifies an amount of time. Suppose you want to use
--   <a>Data.Time.Units</a> for that, because it abstracts away the direct
--   use or <a>Int</a> or <a>Integer</a>. Using <a>TimeUnit</a> directly
--   would require to add the concrete time unit type as a type parameter
--   of <tt>Settings</tt> (or use GHC type related extensions):
--   
--   <pre>
--   data Settings t = Settings
--       { x :: Int
--       , y :: Text
--       , z :: t
--       }
--   </pre>
--   
--   And any use of <tt>z</tt> would require to specify the <tt>TimeUnit t
--   =&gt;</tt> constraint. If you want to add more settings fields later
--   which are time durations, you'll need to add more type variables which
--   may break code which uses the <tt>Settings</tt> type.
--   
--   <pre>
--   data Settings t1 t2 t3 = Settings
--       { x :: Int
--       , y :: Text
--       , z :: t1
--       , u :: t2
--       , v :: t3
--       }
--   </pre>
--   
--   This package provides something between <a>Int</a> and
--   <a>TimeUnit</a>. A concrete type for specifying time durations, which
--   both hide the integers and avoid the type variables:
--   
--   <pre>
--   data Settings = Settings
--       { x :: Int
--       , y :: Text
--       , z :: TimeInterval
--       , u :: TimeInterval
--       , v :: TimeInterval
--       }
--   </pre>
--   
--   There is nothing magical here, this is simply a convenience package
--   for people who encounter this issue in their code.
--   
--   Note that currently <a>TimeInterval</a> stores time as microseconds
--   internally. This may be a problem if you plan to work with smaller
--   intervals (nanoseconds, picoseconds, etc.). If you have such needs,
--   please contact the maintainer to discuss a solution.
module Data.Time.Interval

-- | A time duration.
data TimeInterval

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

-- | Convert a <a>TimeInterval</a> to a <a>TimeUnit</a> instance.
toTimeUnit :: TimeUnit t => TimeInterval -> t

-- | Specialized <a>toTimeUnit</a> for converting to <a>Microsecond</a>
--   units.
toMicroUnit :: TimeInterval -> Microsecond

-- | Deprecated alias of <a>fromTimeUnit</a>.

-- | <i>Deprecated: Use <a>fromTimeUnit</a> instead</i>
time :: TimeUnit t => t -> TimeInterval

-- | Express a <a>TimeInterval</a> in microseconds.
microseconds :: TimeInterval -> Integer
instance GHC.Show.Show Data.Time.Interval.TimeInterval
instance GHC.Real.Real Data.Time.Interval.TimeInterval
instance GHC.Num.Num Data.Time.Interval.TimeInterval
instance GHC.Classes.Ord Data.Time.Interval.TimeInterval
instance GHC.Real.Integral Data.Time.Interval.TimeInterval
instance GHC.Classes.Eq Data.Time.Interval.TimeInterval
instance GHC.Enum.Enum Data.Time.Interval.TimeInterval