libghc-hourglass-doc 0.2.10-3build1 / usr / share / doc / libghc-hourglass-doc / html / hourglass.txt

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


-- | simple performant time related library
--   
--   Simple time library focusing on simple but powerful and performant API
--   
--   The backbone of the library are the Timeable and Time type classes.
--   
--   Each Timeable instances can be converted to type that has a Time
--   instances, and thus are different representations of current time.
@package hourglass
@version 0.2.10


-- | Basic times units and types.
--   
--   While pratically some units could hold infinite values, for practical
--   and efficient purpose they are limited to int64 types for seconds and
--   int types for years.
--   
--   Most units use the unix epoch referential, but by no means reduce
--   portability. the unix referential works under the Windows platform or
--   any other platforms.
module Time.Types

-- | Nanoseconds
newtype NanoSeconds
NanoSeconds :: Int64 -> NanoSeconds

-- | Number of seconds without a referential.
--   
--   Can hold a number between [-2^63,2^63-1], which should be good for
--   some billions of years.
--   
--   However, because of limitation in the calendar conversion currently
--   used, seconds should be in the range [-2^55,2^55-1], which is good for
--   only 1 billion of year.
newtype Seconds
Seconds :: Int64 -> Seconds

-- | Number of minutes without a referential.
newtype Minutes
Minutes :: Int64 -> Minutes

-- | Number of hours without a referential.
newtype Hours
Hours :: Int64 -> Hours

-- | Represent any time interval that has an equivalent value to a number
--   of seconds.
class TimeInterval i
toSeconds :: TimeInterval i => i -> Seconds
fromSeconds :: TimeInterval i => Seconds -> (i, Seconds)

-- | Month of the year
data Month
January :: Month
February :: Month
March :: Month
April :: Month
May :: Month
June :: Month
July :: Month
August :: Month
September :: Month
October :: Month
November :: Month
December :: Month

-- | Day of the week
--   
--   the enumeration starts on Sunday.
data WeekDay
Sunday :: WeekDay
Monday :: WeekDay
Tuesday :: WeekDay
Wednesday :: WeekDay
Thursday :: WeekDay
Friday :: WeekDay
Saturday :: WeekDay

-- | Offset against UTC in minutes to obtain from UTC time, local time.
--   
--   <ul>
--   <li>a positive number represent a location East of UTC.</li>
--   <li>a negative number represent a location West of UTC.</li>
--   </ul>
--   
--   LocalTime t (-300) = t represent a time at UTC-5 LocalTime t (+480) =
--   t represent a time at UTC+8
--   
--   should be between -11H and +14H
--   
--   Example: in AUSEDT (UTC+1000 with daylight = UTC+1100), local time is
--   15:47; Thus, UTC time is 04:47, and TimezoneOffset is +660 (minutes)
newtype TimezoneOffset
TimezoneOffset :: Int -> TimezoneOffset

-- | return the number of minutes
[timezoneOffsetToMinutes] :: TimezoneOffset -> Int

-- | Return the number of seconds associated with a timezone
timezoneOffsetToSeconds :: TimezoneOffset -> Seconds

-- | The UTC timezone. offset of 0
timezone_UTC :: TimezoneOffset

-- | A number of seconds elapsed since the unix epoch.
newtype Elapsed
Elapsed :: Seconds -> Elapsed

-- | A number of seconds and nanoseconds elapsed since the unix epoch.
data ElapsedP
ElapsedP :: {-# UNPACK #-} !Elapsed -> {-# UNPACK #-} !NanoSeconds -> ElapsedP

-- | human date representation using common calendar
data Date
Date :: {-# UNPACK #-} !Int -> !Month -> {-# UNPACK #-} !Int -> Date

-- | year (Common Era)
[dateYear] :: Date -> {-# UNPACK #-} !Int

-- | month of the year
[dateMonth] :: Date -> !Month

-- | day of the month, between 1 to 31
[dateDay] :: Date -> {-# UNPACK #-} !Int

-- | human time representation of hour, minutes, seconds in a day.
data TimeOfDay
TimeOfDay :: {-# UNPACK #-} !Hours -> {-# UNPACK #-} !Minutes -> {-# UNPACK #-} !Seconds -> {-# UNPACK #-} !NanoSeconds -> TimeOfDay

-- | hours, between 0 and 23
[todHour] :: TimeOfDay -> {-# UNPACK #-} !Hours

-- | minutes, between 0 and 59
[todMin] :: TimeOfDay -> {-# UNPACK #-} !Minutes

-- | seconds, between 0 and 59. 60 when having leap second */
[todSec] :: TimeOfDay -> {-# UNPACK #-} !Seconds

-- | nanoseconds, between 0 and 999999999 */
[todNSec] :: TimeOfDay -> {-# UNPACK #-} !NanoSeconds

-- | Date and Time
data DateTime
DateTime :: Date -> TimeOfDay -> DateTime
[dtDate] :: DateTime -> Date
[dtTime] :: DateTime -> TimeOfDay
instance Data.Data.Data Time.Types.DateTime
instance GHC.Classes.Ord Time.Types.DateTime
instance GHC.Classes.Eq Time.Types.DateTime
instance GHC.Read.Read Time.Types.DateTime
instance GHC.Show.Show Time.Types.DateTime
instance Data.Data.Data Time.Types.TimeOfDay
instance GHC.Classes.Ord Time.Types.TimeOfDay
instance GHC.Classes.Eq Time.Types.TimeOfDay
instance GHC.Read.Read Time.Types.TimeOfDay
instance GHC.Show.Show Time.Types.TimeOfDay
instance Data.Data.Data Time.Types.Date
instance GHC.Classes.Ord Time.Types.Date
instance GHC.Classes.Eq Time.Types.Date
instance GHC.Read.Read Time.Types.Date
instance GHC.Show.Show Time.Types.Date
instance Control.DeepSeq.NFData Time.Types.TimezoneOffset
instance Data.Data.Data Time.Types.TimezoneOffset
instance GHC.Classes.Ord Time.Types.TimezoneOffset
instance GHC.Classes.Eq Time.Types.TimezoneOffset
instance GHC.Enum.Bounded Time.Types.WeekDay
instance Data.Data.Data Time.Types.WeekDay
instance GHC.Enum.Enum Time.Types.WeekDay
instance GHC.Classes.Ord Time.Types.WeekDay
instance GHC.Classes.Eq Time.Types.WeekDay
instance GHC.Read.Read Time.Types.WeekDay
instance GHC.Show.Show Time.Types.WeekDay
instance GHC.Enum.Bounded Time.Types.Month
instance Data.Data.Data Time.Types.Month
instance GHC.Enum.Enum Time.Types.Month
instance GHC.Classes.Ord Time.Types.Month
instance GHC.Classes.Eq Time.Types.Month
instance GHC.Read.Read Time.Types.Month
instance GHC.Show.Show Time.Types.Month
instance Data.Data.Data Time.Types.ElapsedP
instance GHC.Classes.Ord Time.Types.ElapsedP
instance GHC.Classes.Eq Time.Types.ElapsedP
instance GHC.Read.Read Time.Types.ElapsedP
instance Control.DeepSeq.NFData Time.Types.Elapsed
instance Data.Data.Data Time.Types.Elapsed
instance GHC.Num.Num Time.Types.Elapsed
instance GHC.Classes.Ord Time.Types.Elapsed
instance GHC.Classes.Eq Time.Types.Elapsed
instance GHC.Read.Read Time.Types.Elapsed
instance Control.DeepSeq.NFData Time.Types.Hours
instance Data.Data.Data Time.Types.Hours
instance GHC.Real.Integral Time.Types.Hours
instance GHC.Real.Real Time.Types.Hours
instance GHC.Num.Num Time.Types.Hours
instance GHC.Enum.Enum Time.Types.Hours
instance GHC.Classes.Ord Time.Types.Hours
instance GHC.Classes.Eq Time.Types.Hours
instance GHC.Read.Read Time.Types.Hours
instance Control.DeepSeq.NFData Time.Types.Minutes
instance Data.Data.Data Time.Types.Minutes
instance GHC.Real.Integral Time.Types.Minutes
instance GHC.Real.Real Time.Types.Minutes
instance GHC.Num.Num Time.Types.Minutes
instance GHC.Enum.Enum Time.Types.Minutes
instance GHC.Classes.Ord Time.Types.Minutes
instance GHC.Classes.Eq Time.Types.Minutes
instance GHC.Read.Read Time.Types.Minutes
instance Control.DeepSeq.NFData Time.Types.Seconds
instance Data.Data.Data Time.Types.Seconds
instance GHC.Real.Integral Time.Types.Seconds
instance GHC.Real.Real Time.Types.Seconds
instance GHC.Num.Num Time.Types.Seconds
instance GHC.Enum.Enum Time.Types.Seconds
instance GHC.Classes.Ord Time.Types.Seconds
instance GHC.Classes.Eq Time.Types.Seconds
instance GHC.Read.Read Time.Types.Seconds
instance Control.DeepSeq.NFData Time.Types.NanoSeconds
instance Data.Data.Data Time.Types.NanoSeconds
instance GHC.Num.Num Time.Types.NanoSeconds
instance GHC.Classes.Ord Time.Types.NanoSeconds
instance GHC.Classes.Eq Time.Types.NanoSeconds
instance GHC.Read.Read Time.Types.NanoSeconds
instance GHC.Show.Show Time.Types.NanoSeconds
instance Time.Types.TimeInterval Time.Types.NanoSeconds
instance GHC.Show.Show Time.Types.Seconds
instance Time.Types.TimeInterval Time.Types.Seconds
instance GHC.Show.Show Time.Types.Minutes
instance Time.Types.TimeInterval Time.Types.Minutes
instance GHC.Show.Show Time.Types.Hours
instance Time.Types.TimeInterval Time.Types.Hours
instance GHC.Show.Show Time.Types.Elapsed
instance GHC.Show.Show Time.Types.ElapsedP
instance Control.DeepSeq.NFData Time.Types.ElapsedP
instance GHC.Num.Num Time.Types.ElapsedP
instance GHC.Real.Real Time.Types.ElapsedP
instance GHC.Show.Show Time.Types.TimezoneOffset
instance Control.DeepSeq.NFData Time.Types.Date
instance Control.DeepSeq.NFData Time.Types.TimeOfDay
instance Control.DeepSeq.NFData Time.Types.DateTime


-- | Basic times units and types.
--   
--   While pratically some units could hold infinite values, for practical
--   and efficient purpose they are limited to int64 types for seconds and
--   int types for years.
--   
--   Most units use the unix epoch referential, but by no means reduce
--   portability. the unix referential works under the Windows platform or
--   any other platforms.
--   
--   This module will be depreciated in favor of Time.Types
module Data.Hourglass.Types


-- | Epoch tracking
module Data.Hourglass.Epoch

-- | A number of seconds elapsed since an epoch.
newtype ElapsedSince epoch
ElapsedSince :: Seconds -> ElapsedSince epoch

-- | A number of seconds and nanoseconds elapsed since an epoch.
data ElapsedSinceP epoch
ElapsedSinceP :: {-# UNPACK #-} !(ElapsedSince epoch) -> {-# UNPACK #-} !NanoSeconds -> ElapsedSinceP epoch

-- | epoch related.
--   
--   We use the well known Unix epoch as the reference timezone for doing
--   conversion between epochs.
--   
--   Each methods of this typeclass should not use the actual value, but
--   only get the information needed from the type itself.
class Epoch epoch

-- | The name of this epoch
epochName :: Epoch epoch => epoch -> String

-- | number of seconds of difference with 1st January 1970.
--   
--   a negative number means that this epoch start before the unix epoch.
epochDiffToUnix :: Epoch epoch => epoch -> Seconds

-- | Unix Epoch, starting 1st January 1970
data UnixEpoch
UnixEpoch :: UnixEpoch

-- | Windows Epoch, starting 1st January 1601
data WindowsEpoch
WindowsEpoch :: WindowsEpoch
instance GHC.Classes.Eq Data.Hourglass.Epoch.WindowsEpoch
instance GHC.Show.Show Data.Hourglass.Epoch.WindowsEpoch
instance GHC.Classes.Eq Data.Hourglass.Epoch.UnixEpoch
instance GHC.Show.Show Data.Hourglass.Epoch.UnixEpoch
instance Data.Data.Data epoch => Data.Data.Data (Data.Hourglass.Epoch.ElapsedSinceP epoch)
instance GHC.Classes.Ord (Data.Hourglass.Epoch.ElapsedSinceP epoch)
instance GHC.Classes.Eq (Data.Hourglass.Epoch.ElapsedSinceP epoch)
instance GHC.Read.Read (Data.Hourglass.Epoch.ElapsedSinceP epoch)
instance GHC.Show.Show (Data.Hourglass.Epoch.ElapsedSinceP epoch)
instance Control.DeepSeq.NFData (Data.Hourglass.Epoch.ElapsedSince epoch)
instance Data.Data.Data epoch => Data.Data.Data (Data.Hourglass.Epoch.ElapsedSince epoch)
instance GHC.Num.Num (Data.Hourglass.Epoch.ElapsedSince epoch)
instance GHC.Classes.Ord (Data.Hourglass.Epoch.ElapsedSince epoch)
instance GHC.Classes.Eq (Data.Hourglass.Epoch.ElapsedSince epoch)
instance GHC.Read.Read (Data.Hourglass.Epoch.ElapsedSince epoch)
instance GHC.Show.Show (Data.Hourglass.Epoch.ElapsedSince epoch)
instance Control.DeepSeq.NFData (Data.Hourglass.Epoch.ElapsedSinceP e)
instance GHC.Num.Num (Data.Hourglass.Epoch.ElapsedSinceP e)
instance Data.Hourglass.Epoch.Epoch Data.Hourglass.Epoch.UnixEpoch
instance Data.Hourglass.Epoch.Epoch Data.Hourglass.Epoch.WindowsEpoch
instance Data.Hourglass.Epoch.Epoch epoch => Data.Hourglass.Time.Timeable (Data.Hourglass.Epoch.ElapsedSince epoch)
instance Data.Hourglass.Epoch.Epoch epoch => Data.Hourglass.Time.Time (Data.Hourglass.Epoch.ElapsedSince epoch)
instance Data.Hourglass.Epoch.Epoch epoch => Data.Hourglass.Time.Timeable (Data.Hourglass.Epoch.ElapsedSinceP epoch)
instance Data.Hourglass.Epoch.Epoch epoch => Data.Hourglass.Time.Time (Data.Hourglass.Epoch.ElapsedSinceP epoch)


-- | Get the system timezone and current time value in multiple formats
module Time.System

-- | Get the current elapsed seconds since epoch
timeCurrent :: IO Elapsed

-- | Get the current elapsed seconds (precise to the nanosecond) since
--   epoch
timeCurrentP :: IO ElapsedP

-- | Get the current global date
--   
--   This is equivalent to:
--   
--   <pre>
--   timeGetDateTimeOfDay `fmap` timeCurrentP
--   </pre>
dateCurrent :: IO DateTime

-- | Get the localized date by using <a>timezoneCurrent</a> and
--   <a>dateCurrent</a>
localDateCurrent :: IO (LocalTime DateTime)

-- | Get the localized date at a specific timezone offset.
localDateCurrentAt :: TimezoneOffset -> IO (LocalTime DateTime)

-- | Get the current timezone offset
--   
--   This include daylight saving time when in operation.
timezoneCurrent :: IO TimezoneOffset


-- | Get the system timezone and current time value in multiple formats
--   
--   This module will be depreciated in favor of Time.System
module System.Hourglass


-- | Types and methods for time manipulation.
--   
--   The most basic type for time representation is Elapsed, which
--   represent a number of elapsed seconds since the unix epoch.
--   
--   Every other defined types can be convert to and from Elapsed type:
--   
--   <pre>
--   timeGetElapsed (Date 1 2 3) :: Elapsed
--   timeFromElapsed 123         :: DateTime
--   </pre>
--   
--   Local time is represented by any other time types (Elapsed, Date,
--   DateTime, ..), but augmented by a Timezone offset in minutes.
--   
--   <pre>
--   localTime (Date 2014 May 4) 600 -- local time at UTC+10 of May 4th 2014
--   </pre>
module Data.Hourglass

-- | Represent time types that can be created from other time types.
--   
--   Every conversion happens throught ElapsedP or Elapsed types.
class Timeable t => Time t where timeFromElapsed e = timeFromElapsedP (ElapsedP e 0)

-- | convert from a number of elapsed seconds and nanoseconds to another
--   time representation
timeFromElapsedP :: Time t => ElapsedP -> t

-- | convert from a number of elapsed seconds and nanoseconds to another
--   time representation
--   
--   defaults to timeFromElapsedP unless defined explicitely by an
--   instance.
timeFromElapsed :: Time t => Elapsed -> t

-- | Timeable represent every type that can be made to look like time
--   types.
--   
--   <ul>
--   <li>can be converted to ElapsedP and Elapsed</li>
--   <li>optionally have a timezone associated</li>
--   <li>have nanoseconds accessor (which can return 0 when the type is not
--   more precise than seconds)</li>
--   </ul>
class Timeable t where timeGetElapsed t = e where ElapsedP e _ = timeGetElapsedP t timeGetNanoSeconds t = ns where ElapsedP _ ns = timeGetElapsedP t

-- | convert a time representation to the number of elapsed seconds and
--   nanoseconds to a specific epoch
timeGetElapsedP :: Timeable t => t -> ElapsedP

-- | convert a time representation to the number of elapsed seconds to a
--   specific epoch.
--   
--   defaults to timeGetElapsedP unless defined explicitely by an instance
timeGetElapsed :: Timeable t => t -> Elapsed

-- | return the number of optional nanoseconds.
--   
--   If the underlaying type is not precise enough to record nanoseconds
--   (or any variant between seconds and nanoseconds), 0 should be returned
--   
--   defaults to <a>timeGetElapsedP</a> unless defined explicitely by an
--   instance, for efficiency reason, it's a good idea to override this
--   methods if you know the type is not more precise than Seconds.
timeGetNanoSeconds :: Timeable t => t -> NanoSeconds

-- | A number of seconds elapsed since the unix epoch.
newtype Elapsed
Elapsed :: Seconds -> Elapsed

-- | A number of seconds and nanoseconds elapsed since the unix epoch.
data ElapsedP
ElapsedP :: {-# UNPACK #-} !Elapsed -> {-# UNPACK #-} !NanoSeconds -> ElapsedP

-- | Convert one time representation into another one
--   
--   The return type need to be infer by the context.
--   
--   If the context cannot be infer through this, some specialized
--   functions are available for built-in types:
--   
--   <ul>
--   <li><a>timeGetDate</a></li>
--   <li><a>timeGetDateTimeOfDay</a></li>
--   <li><a>timeGetElapsed</a>, <a>timeGetElapsedP</a></li>
--   </ul>
timeConvert :: (Timeable t1, Time t2) => t1 -> t2

-- | Get the calendar Date (year-month-day) from a time representation
--   
--   specialization of <a>timeConvert</a>
timeGetDate :: Timeable t => t -> Date

-- | Get the date and time of day from a time representation
--   
--   specialization of <a>timeConvert</a>
timeGetDateTimeOfDay :: Timeable t => t -> DateTime

-- | Get the day time (hours:minutes:seconds) from a time representation
--   
--   specialization of <a>timeConvert</a>
timeGetTimeOfDay :: Timeable t => t -> TimeOfDay

-- | An amount of time in terms of constant value like hours (3600
--   seconds), minutes (60 seconds), seconds and nanoseconds.
data Duration
Duration :: !Hours -> !Minutes -> !Seconds -> !NanoSeconds -> Duration

-- | number of hours
[durationHours] :: Duration -> !Hours

-- | number of minutes
[durationMinutes] :: Duration -> !Minutes

-- | number of seconds
[durationSeconds] :: Duration -> !Seconds

-- | number of nanoseconds
[durationNs] :: Duration -> !NanoSeconds

-- | An amount of conceptual calendar time in terms of years, months and
--   days.
--   
--   This allow calendar manipulation, representing things like days and
--   months irrespective on how long those are related to timezone and
--   daylight changes.
--   
--   See <a>Duration</a> for the time-based equivalent to this class.
data Period
Period :: !Int -> !Int -> !Int -> Period
[periodYears] :: Period -> !Int
[periodMonths] :: Period -> !Int
[periodDays] :: Period -> !Int

-- | Represent any time interval that has an equivalent value to a number
--   of seconds.
class TimeInterval i
toSeconds :: TimeInterval i => i -> Seconds
fromSeconds :: TimeInterval i => Seconds -> (i, Seconds)

-- | add some time interval to a time representation and returns this new
--   time representation
--   
--   example:
--   
--   <pre>
--   t1 `timeAdd` mempty { durationHours = 12 }
--   </pre>
timeAdd :: (Time t, TimeInterval ti) => t -> ti -> t

-- | Get the difference in seconds between two time representation
--   
--   effectively:
--   
--   <pre>
--   t2 `timeDiff` t1 = t2 - t1
--   </pre>
timeDiff :: (Timeable t1, Timeable t2) => t1 -> t2 -> Seconds

-- | Get the difference in seconds and nanoseconds between two time
--   representation
--   
--   effectively:
--   
--   <pre>
--   @t2 `timeDiffP` t1 = t2 - t1
--   </pre>
timeDiffP :: (Timeable t1, Timeable t2) => t1 -> t2 -> (Seconds, NanoSeconds)

-- | add a period of time to a date
dateAddPeriod :: Date -> Period -> Date

-- | All the various formatter that can be part of a time format string
data TimeFormatElem

-- | 2 digit years (70 is 1970, 69 is 2069)
Format_Year2 :: TimeFormatElem

-- | 4 digits years
Format_Year4 :: TimeFormatElem

-- | any digits years
Format_Year :: TimeFormatElem

-- | months (1 to 12)
Format_Month :: TimeFormatElem

-- | months padded to 2 chars (01 to 12)
Format_Month2 :: TimeFormatElem

-- | name of the month short (<tt>Jan</tt>, <tt>Feb</tt> ..)
Format_MonthName_Short :: TimeFormatElem

-- | day of the year (1 to 365, 366 for leap years)
Format_DayYear :: TimeFormatElem

-- | day of the month (1 to 31)
Format_Day :: TimeFormatElem

-- | day of the month (01 to 31)
Format_Day2 :: TimeFormatElem

-- | hours (0 to 23)
Format_Hour :: TimeFormatElem

-- | minutes (0 to 59)
Format_Minute :: TimeFormatElem

-- | seconds (0 to 59, 60 for leap seconds)
Format_Second :: TimeFormatElem

-- | number of seconds since 1 jan 1970. unix epoch.
Format_UnixSecond :: TimeFormatElem

-- | Milliseconds (000 to 999)
Format_MilliSecond :: TimeFormatElem

-- | MicroSeconds (000000 to 999999)
Format_MicroSecond :: TimeFormatElem

-- | NanoSeconds (000000000 to 999999999)
Format_NanoSecond :: TimeFormatElem

-- | sub seconds display with a precision of N digits. with N between 1 and
--   9
Format_Precision :: Int -> TimeFormatElem

-- | timezone name (e.g. GMT, PST). not implemented yet |
--   Format_TimezoneOffset -- ^ timeoffset offset (+02:00)
Format_TimezoneName :: TimeFormatElem

-- | timeoffset offset with colon (+02:00)
Format_TzHM_Colon :: TimeFormatElem

-- | timeoffset offset (+0200)
Format_TzHM :: TimeFormatElem

-- | timeoffset in minutes
Format_Tz_Offset :: TimeFormatElem

-- | one or many space-like chars
Format_Spaces :: TimeFormatElem

-- | a verbatim char
Format_Text :: Char -> TimeFormatElem
Format_Fct :: TimeFormatFct -> TimeFormatElem

-- | A generic format function composed of a parser and a printer.
data TimeFormatFct
TimeFormatFct :: String -> (DateTime -> String -> Either String (DateTime, String)) -> (DateTime -> String) -> TimeFormatFct
[timeFormatFctName] :: TimeFormatFct -> String
[timeFormatParse] :: TimeFormatFct -> DateTime -> String -> Either String (DateTime, String)
[timeFormatPrint] :: TimeFormatFct -> DateTime -> String

-- | A time format string, composed of list of <a>TimeFormatElem</a>
newtype TimeFormatString
TimeFormatString :: [TimeFormatElem] -> TimeFormatString

-- | A generic class for anything that can be considered a Time Format
--   string.
class TimeFormat format
toFormat :: TimeFormat format => format -> TimeFormatString

-- | ISO8601 Date format string.
--   
--   e.g. 2014-04-05
data ISO8601_Date
ISO8601_Date :: ISO8601_Date

-- | ISO8601 Date and Time format string.
--   
--   e.g. 2014-04-05T17:25:04+00:00 2014-04-05T17:25:04Z
data ISO8601_DateAndTime
ISO8601_DateAndTime :: ISO8601_DateAndTime

-- | Pretty print time to a string
--   
--   The actual output is determined by the format used
timePrint :: (TimeFormat format, Timeable t) => format -> t -> String

-- | Just like <a>localTimeParse</a> but the time is automatically
--   converted to global time.
timeParse :: TimeFormat format => format -> String -> Maybe DateTime

-- | like <a>localTimeParseE</a> but the time value is automatically
--   converted to global time.
timeParseE :: TimeFormat format => format -> String -> Either (TimeFormatElem, String) (DateTime, String)

-- | Pretty print local time to a string.
--   
--   The actual output is determined by the format used.
localTimePrint :: (TimeFormat format, Timeable t) => format -> LocalTime t -> String

-- | Try parsing a string as time using the format explicitely specified
--   
--   Unparsed characters are ignored and the error handling is simplified
--   
--   for more elaborate need use <a>localTimeParseE</a>.
localTimeParse :: TimeFormat format => format -> String -> Maybe (LocalTime DateTime)

-- | Try parsing a string as time using the format explicitely specified
--   
--   On failure, the parsing function returns the reason of the failure. If
--   parsing is successful, return the date parsed with the remaining
--   unparsed string
localTimeParseE :: TimeFormat format => format -> String -> Either (TimeFormatElem, String) (LocalTime DateTime, String)

-- | Local time representation
--   
--   this is a time representation augmented by a timezone to get back to a
--   global time, the timezoneOffset needed to be added to the local time.
data LocalTime t

-- | Create a local time type from a timezone and a time type.
--   
--   The time value is assumed to be local to the timezone offset set, so
--   no transformation is done.
localTime :: Time t => TimezoneOffset -> t -> LocalTime t

-- | unwrap the LocalTime value. the time value is local.
localTimeUnwrap :: LocalTime t -> t

-- | Get back a global time value
localTimeToGlobal :: Time t => LocalTime t -> t

-- | create a local time value from a global one
localTimeFromGlobal :: Time t => t -> LocalTime t

-- | get the timezone associated with LocalTime
localTimeGetTimezone :: LocalTime t -> TimezoneOffset

-- | Change the timezone, and adjust the local value to represent the new
--   local value.
localTimeSetTimezone :: Time t => TimezoneOffset -> LocalTime t -> LocalTime t

-- | convert the local time representation to another time representation
--   determined by context.
localTimeConvert :: (Time t1, Time t2) => LocalTime t1 -> LocalTime t2

-- | standard representation for timezone
class Timezone tz where timezoneName = tzMinutesPrint . timezoneOffset

-- | offset in minutes from UTC. valid values should be between -12*60 to
--   +14*60
timezoneOffset :: Timezone tz => tz -> Int

-- | the name of the timezone. by default will be +-HH:MM encoding.
timezoneName :: Timezone tz => tz -> String

-- | Universal Time Coordinated. The generic computer "timezone".
data UTC
UTC :: UTC

-- | Simple timezone containing the number of minutes difference with UTC.
--   
--   Valid values should be between -12*60 to +14*60
newtype TimezoneMinutes
TimezoneMinutes :: Int -> TimezoneMinutes

-- | Return if this year is a leap year (366 days) or not (365 days in a
--   year)
isLeapYear :: Int -> Bool

-- | Return the day of the week a specific date fall in
getWeekDay :: Date -> WeekDay

-- | return the day of the year where Jan 1 is 0
--   
--   between 0 and 364. 365 for leap years
getDayOfTheYear :: Date -> Int


-- | Basic Time conversion compatibility.
--   
--   This module aims to help conversion between the types from the package
--   time to the package hourglass.
--   
--   Example of use (extracted from file Example<i>Time</i>Compat.hs):
--   
--   <pre>
--   import Data.Hourglass        as H
--   import Data.Hourglass.Compat as C
--   import Data.Time             as T
--   
--   transpose :: T.ZonedTime
--             -&gt; H.LocalTime H.DateTime
--   transpose oldTime =
--       H.localTime
--           offsetTime
--           (H.DateTime newDate timeofday)
--     where
--       newDate :: H.Date
--       newDate = C.dateFromTAIEpoch $ T.toModifiedJulianDay $ T.localDay $ T.zonedTimeToLocalTime oldTime
--   
--       timeofday :: H.TimeOfDay
--       timeofday = C.diffTimeToTimeOfDay $ T.timeOfDayToTime $ T.localTimeOfDay $ T.zonedTimeToLocalTime oldTime
--   
--       offsetTime = H.TimezoneOffset $ fromIntegral $ T.timeZoneMinutes $ T.zonedTimeZone oldTime
--   </pre>
module Time.Compat

-- | Convert an integer which represent the Number of days (To/From) POSIX
--   Epoch to a Date (POSIX Epoch is 1970-01-01).
dateFromPOSIXEpoch :: Integer -> Date

-- | Convert an integer which represents the Number of days (To/From) TAI
--   Epoch This function allows use of the package time to easily convert
--   the Day into the Hourglass Date representation (TAI Epoch is
--   1858-11-17).
--   
--   This function allows user to easily convert a Data.Time.Calendar.Day
--   into Date
--   
--   <pre>
--   import qualified Data.Time.Calendar as T
--   
--   timeDay :: T.Day
--   
--   dateFromTAIEpoch $ T.toModifiedJulianDay timeDay
--   </pre>
dateFromTAIEpoch :: Integer -> Date

-- | Convert of differential of time of a day. (it convers a
--   Data.Time.Clock.DiffTime into a TimeOfDay)
--   
--   Example with DiffTime type from time:
--   
--   <pre>
--   import qualified Data.Time.Clock as T
--   
--   difftime :: T.DiffTime
--   
--   diffTimeToTimeOfDay difftime
--   </pre>
--   
--   Example with the TimeOfDay type from time:
--   
--   <pre>
--   import qualified Data.Time.Clock as T
--   
--   timeofday :: T.TimeOfDay
--   
--   diffTimeToTimeOfDay $ T.timeOfDayToTime timeofday
--   </pre>
diffTimeToTimeOfDay :: Real t => t -> TimeOfDay


-- | Basic Time conversion compatibility.
--   
--   This module aims to help conversion between the types from the package
--   time to the package hourglass.
--   
--   Example of use (extracted from file Example<i>Time</i>Compat.hs):
--   
--   <pre>
--   import Data.Hourglass        as H
--   import Data.Hourglass.Compat as C
--   import Data.Time             as T
--   
--   transpose :: T.ZonedTime
--             -&gt; H.LocalTime H.DateTime
--   transpose oldTime =
--       H.localTime
--           offsetTime
--           (H.DateTime newDate timeofday)
--     where
--       newDate :: H.Date
--       newDate = C.dateFromTAIEpoch $ T.toModifiedJulianDay $ T.localDay $ T.zonedTimeToLocalTime oldTime
--   
--       timeofday :: H.TimeOfDay
--       timeofday = C.diffTimeToTimeOfDay $ T.timeOfDayToTime $ T.localTimeOfDay $ T.zonedTimeToLocalTime oldTime
--   
--       offsetTime = H.TimezoneOffset $ fromIntegral $ T.timeZoneMinutes $ T.zonedTimeZone oldTime
--   </pre>
--   
--   This module will be depreciated in favor of Time.Compat
module Data.Hourglass.Compat