hourglass-0.2.9: simple performant time related library

License | BSD-style
Maintainer | Vincent Hanquez <vincent@snarc.org>
Stability | experimental
Portability | unknown
Safe Haskell | None
Language | Haskell2010

Data.Hourglass

Contents

- Generic time classes
- Elapsed time
- Generic conversion
- Date and Time
- Arithmetic
- Parsing and Printing
  - Format strings
  - Common built-in formats
  - Format methods
- Local time
  - Local time type
  - Local time creation and manipulation
- Calendar misc functions

Description

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

Synopsis

- 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
- 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 Duration = Duration {
  - durationHours :: !Hours
  - durationMinutes :: !Minutes
  - durationSeconds :: !Seconds
  - durationNs :: !NanoSeconds
  }
- data Period = Period {
  - periodYears :: !Int
  - periodMonths :: !Int
  - periodDays :: !Int
  }
- class TimeInterval i where
  - toSeconds :: i -> Seconds
  - fromSeconds :: Seconds -> (i, Seconds)
- timeAdd :: (Time t, TimeInterval ti) => t -> ti -> t
- timeDiff :: (Timeable t1, Timeable t2) => t1 -> t2 -> Seconds
- timeDiffP :: (Timeable t1, Timeable t2) => t1 -> t2 -> (Seconds, NanoSeconds)
- dateAddPeriod :: Date -> Period -> Date
- 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_MilliSecond
  - | Format_MicroSecond
  - | Format_NanoSecond
  - | Format_Precision Int
  - | 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 DateTime
- timeParseE :: TimeFormat format => format -> String -> Either (TimeFormatElem, String) (DateTime, String)
- localTimePrint :: (TimeFormat format, Timeable t) => format -> LocalTime t -> String
- localTimeParse :: TimeFormat format => format -> String -> Maybe (LocalTime DateTime)
- localTimeParseE :: TimeFormat format => format -> String -> Either (TimeFormatElem, String) (LocalTime DateTime, String)
- data LocalTime t
- localTime :: Time t => TimezoneOffset -> t -> LocalTime t
- localTimeUnwrap :: LocalTime t -> t
- localTimeToGlobal :: Time t => LocalTime t -> t
- localTimeFromGlobal :: Time t => t -> LocalTime t
- localTimeGetTimezone :: LocalTime t -> TimezoneOffset
- 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 where Source

Represent time types that can be created from other time types.

Every conversion happens throught ElapsedP or Elapsed types.

Minimal complete definition

timeFromElapsedP

Methods

timeFromElapsedP :: ElapsedP -> t Source

convert from a number of elapsed seconds and nanoseconds to another time representation

timeFromElapsed :: Elapsed -> t Source

convert from a number of elapsed seconds and nanoseconds to another time representation

defaults to timeFromElapsedP unless defined explicitely by an instance.

Instances

Time CTime Source |
Time DateTime Source |
Time Date Source |
Time ElapsedP Source |
Time Elapsed Source |
Epoch epoch => Time (ElapsedSinceP epoch) Source |
Epoch epoch => Time (ElapsedSince epoch) Source |

class Timeable t where Source

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)

Minimal complete definition

timeGetElapsedP

Methods

timeGetElapsedP :: t -> ElapsedP Source

convert a time representation to the number of elapsed seconds and nanoseconds to a specific epoch

timeGetElapsed :: t -> Elapsed Source

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 -> NanoSeconds Source

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.

Instances

Timeable CTime Source |
Timeable DateTime Source |
Timeable Date Source |
Timeable ElapsedP Source |
Timeable Elapsed Source |
Epoch epoch => Timeable (ElapsedSinceP epoch) Source |
Epoch epoch => Timeable (ElapsedSince epoch) Source |

# Elapsed time

newtype Elapsed Source

A number of seconds elapsed since the unix epoch.

Constructors

Elapsed Seconds |

Instances

Eq Elapsed Source |
Data Elapsed Source |
Num Elapsed Source |
Ord Elapsed Source |
Read Elapsed Source |
Show Elapsed Source |
NFData Elapsed Source |
Time Elapsed Source |
Timeable Elapsed Source |

data ElapsedP Source

A number of seconds and nanoseconds elapsed since the unix epoch.

Constructors

ElapsedP !Elapsed !NanoSeconds |

Instances

Eq ElapsedP Source |
Data ElapsedP Source |
Num ElapsedP Source |
Ord ElapsedP Source |
Read ElapsedP Source |
Real ElapsedP Source |
Show ElapsedP Source |
NFData ElapsedP Source |
Time ElapsedP Source |
Timeable ElapsedP Source |

# Generic conversion

timeConvert :: (Timeable t1, Time t2) => t1 -> t2 Source

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:

- `timeGetDate`
- `timeGetDateTimeOfDay`
- `timeGetElapsed`, `timeGetElapsedP`

# Date and Time

timeGetDate :: Timeable t => t -> Date Source

Get the calendar Date (year-month-day) from a time representation

specialization of `timeConvert`

timeGetDateTimeOfDay :: Timeable t => t -> DateTime Source

Get the date and time of day from a time representation

specialization of `timeConvert`

timeGetTimeOfDay :: Timeable t => t -> TimeOfDay Source

Get the day time (hours:minutes:seconds) from a time representation

specialization of `timeConvert`

# Arithmetic

data Duration Source

An amount of time in terms of constant value like hours (3600 seconds), minutes (60 seconds), seconds and nanoseconds.

Constructors

Duration |

Fields

durationHours :: !Hours

  number of hours

durationMinutes :: !Minutes

  number of minutes

durationSeconds :: !Seconds

  number of seconds

durationNs :: !NanoSeconds

  number of nanoseconds

Instances

Eq Duration Source |
Data Duration Source |
Ord Duration Source |
Read Duration Source |
Monoid Duration Source |
NFData Duration Source |
TimeInterval Duration Source |

data Period Source

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 `Duration` for the time-based equivalent to this class.

Constructors

Period |

Fields

periodYears :: !Int
periodMonths :: !Int
periodDays :: !Int

Instances

Eq Period Source |
Data Period Source |
Ord Period Source |
Read Period Source |
Monoid Period Source |
NFData Period Source |

class TimeInterval i where Source

Represent any time interval that has an equivalent value to a number of seconds.

Methods

toSeconds :: i -> Seconds Source

fromSeconds :: Seconds -> (i, Seconds) Source

Instances

TimeInterval Hours Source |
TimeInterval Minutes Source |
TimeInterval Seconds Source |
TimeInterval NanoSeconds Source |
TimeInterval Duration Source |

timeAdd :: (Time t, TimeInterval ti) => t -> ti -> t Source

add some time interval to a time representation and returns this new time representation

example:

    t1 `timeAdd` mempty { durationHours = 12 }

timeDiff :: (Timeable t1, Timeable t2) => t1 -> t2 -> Seconds Source

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

dateAddPeriod :: Date -> Period -> Date Source

add a period of time to a date

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

Constructors

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 (`Jan`, `Feb` ..)
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_MilliSecond | Milliseconds (000 to 999)
Format_MicroSecond | MicroSeconds (000000 to 999999)
Format_NanoSecond | NanoSeconds (000000000 to 999999999)
Format_Precision Int | sub seconds display with a precision of N digits. with N between 1 and 9
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 |

Instances

Eq TimeFormatElem Source |
Show TimeFormatElem Source |
TimeFormat [TimeFormatElem] Source |

data TimeFormatFct Source

A generic format function composed of a parser and a printer.

Constructors

TimeFormatFct |

Fields

timeFormatFctName :: String
timeFormatParse :: DateTime -> String -> Either String (DateTime, String)
timeFormatPrint :: DateTime -> String

Instances

Eq TimeFormatFct Source |
Show TimeFormatFct Source |

newtype TimeFormatString Source

A time format string, composed of list of `TimeFormatElem`

Constructors

TimeFormatString [TimeFormatElem] |

Instances

Eq TimeFormatString Source |
Show TimeFormatString Source |
TimeFormat TimeFormatString Source |

class TimeFormat format where Source

A generic class for anything that can be considered a Time Format string.

Methods

toFormat :: format -> TimeFormatString Source

Instances

TimeFormat String Source |
TimeFormat ISO8601_DateAndTime Source |
TimeFormat ISO8601_Date Source |
TimeFormat TimeFormatString Source |
TimeFormat [TimeFormatElem] Source |

## Common built-in formats

data ISO8601_Date Source

ISO8601 Date format string.

e.g. 2014-04-05

Constructors

ISO8601_Date |

Instances

Eq ISO8601_Date Source |
Show ISO8601_Date Source |
TimeFormat ISO8601_Date Source |

data ISO8601_DateAndTime Source

ISO8601 Date and Time format string.

e.g. 2014-04-05T17:25:04+00:00 2014-04-05T17:25:04Z

Constructors

ISO8601_DateAndTime |

Instances

Eq ISO8601_DateAndTime Source |
Show ISO8601_DateAndTime Source |
TimeFormat ISO8601_DateAndTime Source |

## Format methods

timePrint Source

Arguments

:: (TimeFormat format, Timeable t) |
=> format | the format to use for printing
-> t | the global time to print
-> String | the resulting string

Pretty print time to a string

The actual output is determined by the format used

timeParse :: TimeFormat format => format -> String -> Maybe DateTime Source

Just like `localTimeParse` but the time is automatically converted to global time.

timeParseE :: TimeFormat format => format -> String -> Either (TimeFormatElem, String) (DateTime, String) Source

like `localTimeParseE` but the time value is automatically converted to global time.

localTimePrint Source

Arguments

:: (TimeFormat format, Timeable t) |
=> format | the format to use for printing
-> LocalTime t | the local time to print
-> String | the resulting local time string

Pretty print local time to a string.

The actual output is determined by the format used.

localTimeParse Source

Arguments

:: 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

Unparsed characters are ignored and the error handling is simplified

for more elaborate need use `localTimeParseE`.

localTimeParseE Source

Arguments

:: 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

data LocalTime t Source

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.

Instances

Functor LocalTime Source |
Eq t => Eq (LocalTime t) Source |
(Ord t, Time t) => Ord (LocalTime t) Source |
Show t => Show (LocalTime t) Source |

## Local time creation and manipulation

localTime :: Time t => TimezoneOffset -> t -> LocalTime t Source

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.

localTimeUnwrap :: LocalTime t -> t Source

unwrap the LocalTime value. the time value is local.

localTimeToGlobal :: Time t => LocalTime t -> t Source

Get back a global time value

localTimeFromGlobal :: Time t => t -> LocalTime t Source

create a local time value from a global one

localTimeGetTimezone :: LocalTime t -> TimezoneOffset Source

get the timezone associated with LocalTime

localTimeSetTimezone :: Time t => TimezoneOffset -> LocalTime t -> LocalTime t Source

Change the timezone, and adjust the local value to represent the new local value.

localTimeConvert :: (Time t1, Time t2) => LocalTime t1 -> LocalTime t2 Source

convert the local time representation to another time representation determined by context.

class Timezone tz where Source

standard representation for timezone

Minimal complete definition

timezoneOffset

Methods

timezoneOffset :: tz -> Int Source

offset in minutes from UTC. valid values should be between -12*60 to +14*60

timezoneName :: tz -> String Source

the name of the timezone. by default will be +-HH:MM encoding.

Instances

Timezone UTC Source |
Timezone TimezoneMinutes Source |

data UTC Source

Universal Time Coordinated. The generic computer "timezone".

Constructors

UTC |

Instances

Eq UTC Source |
Ord UTC Source |
Show UTC Source |
Timezone UTC Source |

newtype TimezoneMinutes Source

Simple timezone containing the number of minutes difference with UTC.

Valid values should be between -12*60 to +14*60

Constructors

TimezoneMinutes Int |

Instances

Eq TimezoneMinutes Source |
Ord TimezoneMinutes Source |
Show TimezoneMinutes Source |
Timezone TimezoneMinutes Source |

# Calendar misc functions

isLeapYear :: Int -> Bool Source

Return if this year is a leap year (366 days) or not (365 days in a year)

getWeekDay :: Date -> WeekDay Source

Return the day of the week a specific date fall in

getDayOfTheYear :: Date -> Int Source

return the day of the year where Jan 1 is 0

between 0 and 364. 365 for leap years