hourglass-0.2.0: simple performant time related library

Portabilityunknown
Stabilityexperimental
MaintainerVincent Hanquez <vincent@snarc.org>
Safe HaskellNone

Data.Hourglass

Contents

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

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.

Methods

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.

Instances

class Timeable t whereSource

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)

Methods

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.

Elapsed time

newtype Elapsed Source

A number of seconds elapsed since the unix epoch.

Constructors

Elapsed Seconds 

data ElapsedP Source

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

Constructors

ElapsedP !Elapsed !NanoSeconds 

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

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

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 

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

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

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_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.

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.

Methods

toFormat :: format -> TimeFormatStringSource

Common built-in formats

data ISO8601_Date Source

ISO8601 Date format string.

e.g. 2014-04-05

Constructors

ISO8601_Date 

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 

Format methods

timePrintSource

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 DateTimeSource

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.

localTimePrintSource

Arguments

:: (TimeFormat format, Timeable t) 
=> format

the format to use for printing

-> LocalTime t

the local time to print

-> LocalTime String

the resulting local time string

Pretty print local time to a string.

The actual output is determined by the format used.

localTimeParseSource

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.

localTimeParseESource

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 
Eq t => Eq (LocalTime t) 
(Ord t, Time t) => Ord (LocalTime t) 
Show t => Show (LocalTime t) 

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 assumed to be local to the timezone offset set, so no transformation is done.

localTimeUnwrap :: LocalTime t -> tSource

unwrap the LocalTime value. the time value is local.

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

Get back a global time value

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

create a local time value from a global one

localTimeGetTimezone :: LocalTime t -> TimezoneOffsetSource

get the timezone associated with LocalTime

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.

class Timezone tz whereSource

standard representation for timezone

Methods

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.

data UTC Source

Universal Time Coordinated. The generic computer timezone.

Constructors

UTC 

Instances

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 

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