thyme- A faster time library

Safe HaskellNone




Types and functions for UTC and UT1.

If you don't care about leap seconds, keep to UTCTime and NominalDiffTime for your clock calculations, and you'll be fine.

Num, Real, Fractional and RealFrac instances for DiffTime and NominalDiffTime are only available by importing Data.Thyme.Time. In their stead are instances of AdditiveGroup, HasBasis and VectorSpace, with Scalar DiffTimeScalar NominalDiffTimeRational.

Using fromSeconds and toSeconds to convert between TimeDiffs and other numeric types. If you really must coerce between DiffTime and NominalDiffTime, view (microseconds . from microseconds).

UTCTime is an instance of AffineSpace, with Diff UTCTimeNominalDiffTime.

UTCTime is not Y294K-compliant. Please file a bug report on GitHub when this becomes a problem.


Universal Time

data UniversalTime Source

The principal form of universal time, namely UT1.

UniversalTime is defined by the rotation of the Earth around its axis relative to the Sun. Thus the length of a day by this definition varies from one to the next, and is never exactly 86400 SI seconds unlike TAI or AbsoluteTime. The difference between UT1 and UTC is DUT1.

Absolute intervals

data DiffTime Source

An absolute time interval as measured by a clock.

DiffTime forms an AdditiveGroup―so can be added using ^+^ (or ^-^ for subtraction), and also an instance of VectorSpace―so can be scaled using *^, where

 type Scalar DiffTime = Rational


data UTCTime Source

Coördinated universal time: the most common form of universal time for civil timekeeping. It is synchronised with AbsoluteTime and both tick in increments of SI seconds, but UTC includes occasional leap-seconds so that it does not drift too far from UniversalTime.

UTCTime is an instance of AffineSpace, with

 type Diff UTCTime = NominalDiffTime

Use .+^ to add (or .-^ to subtract) time intervals of type NominalDiffTime, and .-. to get the interval between UTCTimes.

Internally this is a 64-bit count of microseconds since the MJD epoch, so .+^, .-^ and .-. ought to be fairly fast.
UTCTime currently cannot represent leap seconds.

data UTCView Source

Unpacked UTCTime, partly for compatibility with time.




utctDay :: !Day
utctDayTime :: !DiffTime

utcTime :: Iso' UTCTime UTCViewSource

View UTCTime as an UTCView, comprising a Day along with a DiffTime offset since midnight.

This is an improper lens: utctDayTime offsets outside the range of [zeroV, posixDayLength) will carry over into the day part, with the expected behaviour.

data NominalDiffTime Source

A time interval as measured by UTC, that does not take leap-seconds into account.

For instance, the difference between 23:59:59 and 00:00:01 on the following day is always 2 seconds of NominalDiffTime, regardless of whether a leap-second took place.

NominalDiffTime forms an AdditiveGroup―so can be added using ^+^ (or ^-^ for subtraction), and also an instance of VectorSpace―so can be scaled using *^, where

 type Scalar NominalDiffTime = Rational

getCurrentTime :: IO UTCTimeSource

Get the current UTC time from the system clock.

Time interval conversion

class (HasBasis t, Basis t ~ (), Scalar t ~ Rational) => TimeDiff t whereSource

Time intervals, encompassing both DiffTime and NominalDiffTime.

Still affected by


microseconds :: Iso' t Int64Source

Escape hatch; avoid.

toSeconds :: (TimeDiff t, Fractional n) => t -> nSource

Convert a time interval to some Fractional type.

fromSeconds :: (Real n, TimeDiff t) => n -> tSource

Make a time interval from some Real type.

Try to make sure n is one of Float, Double, Int, Int64 or Integer, for which rewrite RULES have been provided.

toSeconds' :: TimeDiff t => t -> RationalSource

Type-restricted toSeconds to avoid constraint-defaulting warnings.

fromSeconds' :: TimeDiff t => Rational -> tSource

Type-restricted fromSeconds to avoid constraint-defaulting warnings.


_utctDay :: Lens' UTCTime DaySource

Lens' for the Day component of an UTCTime.

_utctDayTime :: Lens' UTCTime DiffTimeSource

Lens' for the time-of-day component of an UTCTime.