Portability | unknown |
---|---|
Stability | experimental |
Maintainer | Vincent Hanquez <vincent@snarc.org> |
Safe Haskell | None |
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:
timeGetElapsed (Date 1 2 3) :: Elapsed timeFromElapsed 123 :: DateTime
Local time is represented by any other time types (Elapsed, Date, DateTime, ..), but augmented by a Timezone offset in minutes.
localTime (Date 2014 May 4) 600 -- local time at UTC+10 of May 4th 2014
- class Timeable t => Time t where
- timeFromElapsedP :: ElapsedP -> t
- timeFromElapsed :: Elapsed -> t
- class Timeable t where
- timeGetElapsedP :: t -> ElapsedP
- timeGetElapsed :: t -> Elapsed
- timeGetNanoSeconds :: t -> NanoSeconds
- timeGetTimezone :: t -> Maybe TimezoneOffset
- newtype Elapsed = Elapsed Seconds
- data ElapsedP = ElapsedP !Elapsed !NanoSeconds
- timeConvert :: (Timeable t1, Time t2) => t1 -> t2
- timeGetDate :: Timeable t => t -> Date
- timeGetDateTimeOfDay :: Timeable t => t -> DateTime
- timeGetTimeOfDay :: Timeable t => t -> TimeOfDay
- data TimeDiff = TimeDiff {}
- timeAdd :: Time t => t -> TimeDiff -> t
- timeDiff :: (Timeable t1, Timeable t2) => t1 -> t2 -> Seconds
- timeDiffP :: (Timeable t1, Timeable t2) => t1 -> t2 -> (Seconds, NanoSeconds)
- module Data.Hourglass.Types
- data TimeFormatElem
- = Format_Year2
- | Format_Year4
- | Format_Year
- | Format_Month
- | Format_Month2
- | Format_MonthName_Short
- | Format_DayYear
- | Format_Day
- | Format_Day2
- | Format_Hour
- | Format_Minute
- | Format_Second
- | Format_UnixSecond
- | Format_TimezoneName
- | Format_TzHM_Colon
- | Format_TzHM
- | Format_Tz_Offset
- | Format_Spaces
- | Format_Text Char
- | Format_Fct TimeFormatFct
- data TimeFormatFct = TimeFormatFct {
- timeFormatFctName :: String
- timeFormatParse :: DateTime -> String -> Either String (DateTime, String)
- timeFormatPrint :: DateTime -> String
- newtype TimeFormatString = TimeFormatString [TimeFormatElem]
- class TimeFormat format where
- toFormat :: format -> TimeFormatString
- data ISO8601_Date = ISO8601_Date
- data ISO8601_DateAndTime = ISO8601_DateAndTime
- timePrint :: (TimeFormat format, Timeable t) => format -> t -> String
- timeParse :: TimeFormat format => format -> String -> Maybe (LocalTime DateTime)
- timeParseE :: TimeFormat format => format -> String -> Either (TimeFormatElem, String) (LocalTime DateTime, String)
- data LocalTime t = LocalTime {}
- localTime :: Time t => TimezoneOffset -> t -> LocalTime t
- localTimeToGlobal :: Time t => LocalTime t -> t
- localTimeSetTimezone :: Time t => TimezoneOffset -> LocalTime t -> LocalTime t
- localTimeConvert :: (Time t1, Time t2) => LocalTime t1 -> LocalTime t2
- class Timezone tz where
- timezoneOffset :: tz -> Int
- timezoneName :: tz -> String
- data UTC = UTC
- newtype TimezoneMinutes = TimezoneMinutes Int
- isLeapYear :: Int -> Bool
- getWeekDay :: Date -> WeekDay
- getDayOfTheYear :: Date -> Int
Generic time classes
class Timeable t => Time t whereSource
Represent time types that can be created from other time types.
Every conversion happens throught ElapsedP or Elapsed types.
timeFromElapsedP :: ElapsedP -> tSource
convert from a number of elapsed seconds and nanoseconds to another time representation
timeFromElapsed :: Elapsed -> tSource
convert from a number of elapsed seconds and nanoseconds to another time representation
defaults to timeFromElapsedP unless defined explicitely by an instance.
Timeable represent every type that can be made to look like time types.
- can be converted to ElapsedP and Elapsed
- optionally have a timezone associated
- have nanoseconds accessor (which can return 0 when the type is not more precise than seconds)
timeGetElapsedP :: t -> ElapsedPSource
convert a time representation to the number of elapsed seconds and nanoseconds to a specific epoch
timeGetElapsed :: t -> ElapsedSource
convert a time representation to the number of elapsed seconds to a specific epoch.
defaults to timeGetElapsedP unless defined explicitely by an instance
timeGetNanoSeconds :: t -> NanoSecondsSource
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 timeGetElapsedP
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.
timeGetTimezone :: t -> Maybe TimezoneOffsetSource
return the time zone offset in minute.
If the time is not a local time representation (offseted by timezone), then Nothing should be returned.
Elapsed time
A number of seconds elapsed since the unix epoch.
A number of seconds and nanoseconds elapsed since the unix epoch.
Generic conversion
timeConvert :: (Timeable t1, Time t2) => t1 -> t2Source
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:
Date and Time
timeGetDate :: Timeable t => t -> DateSource
Get the calendar Date (year-month-day) from a time representation
specialization of timeConvert
timeGetDateTimeOfDay :: Timeable t => t -> DateTimeSource
Get the date and time of day from a time representation
specialization of timeConvert
timeGetTimeOfDay :: Timeable t => t -> TimeOfDaySource
Get the day time (hours:minutes:seconds) from a time representation
specialization of timeConvert
Arithmetic
A simple Time difference structure.
A null time difference can be created with mempty
and
the structures can be combined with mappend
or mconcat
.
Example:
mempty { timeDiffMonths = 1 } `mappend` mempty { timeDiffSeconds = 24 }
TimeDiff | |
|
timeAdd :: Time t => t -> TimeDiff -> tSource
add some values with time units to a time representation and returns this new time representation
example:
t1 `timeAdd` mempty { timeDiffHours = 12 }
timeDiff :: (Timeable t1, Timeable t2) => t1 -> t2 -> SecondsSource
Get the difference in seconds between two time representation
effectively:
t2 `timeDiff` t1 = t2 - t1
timeDiffP :: (Timeable t1, Timeable t2) => t1 -> t2 -> (Seconds, NanoSeconds)Source
Get the difference in seconds and nanoseconds between two time representation
effectively:
@t2 `timeDiffP` t1 = t2 - t1
module Data.Hourglass.Types
Parsing and Printing
Format strings
data TimeFormatElem Source
All the various formatter that can be part of a time format string
Format_Year2 | 2 digit years (70 is 1970, 69 is 2069) |
Format_Year4 | 4 digits years |
Format_Year | any digits years |
Format_Month | months (1 to 12) |
Format_Month2 | months padded to 2 chars (01 to 12) |
Format_MonthName_Short | name of the month short ( |
Format_DayYear | day of the year (1 to 365, 366 for leap years) |
Format_Day | day of the month (1 to 31) |
Format_Day2 | day of the month (01 to 31) |
Format_Hour | hours (0 to 23) |
Format_Minute | minutes (0 to 59) |
Format_Second | seconds (0 to 59, 60 for leap seconds) |
Format_UnixSecond | number of seconds since 1 jan 1970. unix epoch. |
Format_TimezoneName | timezone name (e.g. GMT, PST). not implemented yet | Format_TimezoneOffset -- ^ timeoffset offset (+02:00) |
Format_TzHM_Colon | timeoffset offset with colon (+02:00) |
Format_TzHM | timeoffset offset (+0200) |
Format_Tz_Offset | timeoffset in minutes |
Format_Spaces | one or many space-like chars |
Format_Text Char | a verbatim char |
Format_Fct TimeFormatFct |
data TimeFormatFct Source
A generic format function composed of a parser and a printer.
TimeFormatFct | |
|
newtype TimeFormatString Source
A time format string, composed of list of TimeFormatElem
class TimeFormat format whereSource
A generic class for anything that can be considered a Time Format string.
toFormat :: format -> TimeFormatStringSource
Common built-in formats
data ISO8601_Date Source
ISO8601 Date format string.
e.g. 2014-04-05
data ISO8601_DateAndTime Source
ISO8601 Date and Time format string.
e.g. 2014-04-05T17:25:04+00:00 2014-04-05T17:25:04Z
Format methods
:: (TimeFormat format, Timeable t) | |
=> format | the format to use for printing |
-> t | the time to print |
-> String | the resulting string |
Pretty print time to a string.
The actual output is determined by the format used.
:: TimeFormat format | |
=> format | the format to use for parsing |
-> String | the string to parse |
-> Maybe (LocalTime DateTime) |
Try parsing a string as time using the format explicitely specified
The error handling is simplified in this case, for more elaborate need
use timeParseE
.
:: TimeFormat format | |
=> format | the format to use for parsing |
-> String | the string to parse |
-> Either (TimeFormatElem, String) (LocalTime DateTime, String) |
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
Local time
Local time type
Local time representation
this is a loca time representation augmented by a timezone to get back to a global time, the timezoneOffset needed to be added to the local time.
LocalTime | |
|
Local time creation and manipulation
localTime :: Time t => TimezoneOffset -> t -> LocalTime tSource
Create a local time type from a timezone and a time type.
the time value is converted to represent local time
localTimeToGlobal :: Time t => LocalTime t -> tSource
Get back a global time value
localTimeSetTimezone :: Time t => TimezoneOffset -> LocalTime t -> LocalTime tSource
Change the timezone, and adjust the local value to represent the new local value.
localTimeConvert :: (Time t1, Time t2) => LocalTime t1 -> LocalTime t2Source
convert the local time representation to another time representation determined by context.
standard representation for timezone
timezoneOffset :: tz -> IntSource
offset in minutes from UTC. valid values should be between -12*60 to +14*60
timezoneName :: tz -> StringSource
the name of the timezone. by default will be +-HH:MM encoding.
Universal Time Coordinated. The generic computer timezone.
newtype TimezoneMinutes Source
Simple timezone containing the number of minutes difference with UTC.
Valid values should be between -12*60 to +14*60
Calendar misc functions
isLeapYear :: Int -> BoolSource
Return if this year is a leap year (366 days) or not (365 days in a year)
getWeekDay :: Date -> WeekDaySource
Return the day of the week a specific date fall in
getDayOfTheYear :: Date -> IntSource
return the day of the year where Jan 1 is 0
between 0 and 364. 365 for leap years