Data.Thyme.Clock

Coördinated universal time (UTCTime) is the most commonly used standard for civil timekeeping. It is synchronised with TAI (Data.Thyme.Clock.AbsoluteTime) and both tick in increments of SI seconds, but UTC includes occasional leap-seconds to keep it close to UT1 (UniversalTime).

> utcTime # UTCView (gregorian # YearMonthDay 2016 1 15) (timeOfDay # TimeOfDay 12 34 56.78)
2016-01-15 12:34:56.78 UTC

> UTCTime (gregorian # YearMonthDay 2016 1 15) (timeOfDay # TimeOfDay 12 34 56.78)
2016-01-15 12:34:56.78 UTC

> mkUTCTime 2016 1 15  12 34 56.78
2016-01-15 12:34:56.78 UTC

UTCTime is an AffineSpace with NominalDiffTime as its Diff. See Data.Thyme.Docs#spaces for details.

> let t0 = mkUTCTime 2016 1 15  23 59 0
> let t1 = mkUTCTime 2016 1 16  00  1 1
> let dt = t1 .-. t0
> dt
121s :: NominalDiffTime

> t1 .+^ dt
2016-01-16 00:03:02 UTC

> t1 .+^ 3 *^ dt
2016-01-16 00:07:04 UTC

To decompose a UTCTime into a separate Day and time-of-day, use utcTime. To convert to a local time zone, see zonedTime or utcLocalTime.

Notes

Internally UTCTime is just a 64-bit count of microseconds since the Modified Julian Day epoch, so (.+^), (.-.) et cetera ought to be fast.

UTCTime cannot represent leap seconds. If leap seconds matter, use AbsoluteTime from Data.Thyme.Clock.TAI instead, along with absoluteTime' and UTCView for presentation.

Accessor for the calendar Day component of an UTCTime.

utctDay = view _utctDay

Accessor for the time-of-day DiffTime component of an UTCTime.

utctDayTime = view _utctDayTime

Lens' for the calendar Day component of a UTCTime.

Lens' for the time-of-day DiffTime component of a UTCTime.

Construct a UTCTime from a gregorian date and time-of-day.

mkUTCTime yy mm dd h m s ≡ utcTime # UTCView
    (gregorian # YearMonthDay yy mm dd)
    (timeOfDay # TimeOfDay h m (fromSeconds s))

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

This is an improper lens: utcvDayTime outside the range of [zeroV, posixDayLength) will carry over into utcvDay, with the expected behaviour.

> view utcTime <$> getCurrentTime
UTCView {utcvDay = 2016-01-15, utcvDayTime = 49322.287688s}

> utcTime # UTCView (gregorian # YearMonthDay 2016 1 15) (timeOfDay # TimeOfDay 12 34 56.78)
2016-01-15 12:34:56.78 UTC

With {-# LANGUAGE ViewPatterns #-}, you can write: e.g.

f :: UTCTime -> (Day, DiffTime)
f (view utcTime -> UTCView day dt) = (day, dt)

Unpacked UTCTime, partly for compatibility with time.

As of GHC 7.10, you can also use the UTCTime pattern synonym.

Lens' for the calendar Day component of a UTCView.

Lens' for the time-of-day DiffTime component of a UTCView.

The nominal interval between two UTCTimes, which does not take leap seconds into account.

For example, 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 is an instance of AdditiveGroup as well as VectorSpace, with Rational as its Scalar. We do not provide Num, Real, Fractional nor RealFrac instances here. See Data.Thyme.Docs#spaces for details.

> let d = fromSeconds' 2 :: NominalDiffTime
> d
2s
> d ^/ 3
0.666667s

See also: UTCTime.

Get the current UTC date and time from the local system clock.

> getCurrentTime
2016-01-15 13:42:02.287688 UTC

See also: getZonedTime, getPOSIXTime.

An interval or duration of time, as would be measured by a stopwatch.

DiffTime is an instance of AdditiveGroup as well as VectorSpace, with Rational as its Scalar. We do not provide Num, Real, Fractional nor RealFrac instances here. See Data.Thyme.Docs#spaces for details.

> fromSeconds' 100 :: DiffTime
100s
> fromSeconds' 100 ^+^ fromSeconds' 100 ^* 4
500s
> fromSeconds' 100 ^-^ fromSeconds' 100 ^/ 4
75s

Time intervals, encompassing both DiffTime and NominalDiffTime.

Notes

Still affected by http://hackage.haskell.org/trac/ghc/ticket/7611?

Convert a time interval to some Fractional type.

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.

Type-restricted toSeconds to avoid constraint-defaulting warnings.

Type-restricted fromSeconds to avoid constraint-defaulting warnings.

Conversion between TimeDiff and picoseconds. In the reverse direction, picoseconds are rounded to the nearest microsecond.

The principal form of universal time, namely UT1.

UT1 is defined by the rotation of the Earth around its axis relative to the Sun. The length of each UT1 day varies and is never exactly 86400 SI seconds, unlike UTC or TAI.

The difference between UT1 and UTC is DUT1.

Convert between UniversalTime and the fractional number of days since the Modified Julian Date epoch.

Convert a UniversalTime to the fractional number of days since the Modified Julian Date epoch.

getModJulianDate = view modJulianDate

Construct a UniversalTime from the fractional number of days since the Modified Julian Date epoch.

mkModJulianDate = review modJulianDate

Construct a DiffTime from some number of seconds.

This is just fromSeconds with a more constrained type.

secondsToDiffTime = fromSeconds

Construct a DiffTime from some number of picoseconds. The input will be rounded to the nearest microsecond.

picosecondsToDiffTime a = microseconds # quot (a + signum a * 500000) 1000000

Decompose a UTCTime into a UTCView.

unUTCTime = view utcTime

With {-# LANGUAGE ViewPatterns #-}, you can write: e.g.

f :: UTCTime -> (Day, DiffTime)
f (unUTCTime -> UTCView day dt) = (day, dt)

For GHC 7.8 or later, there is also the pattern synonym UTCTime.

Add a duration to a point in time.

addUTCTime = flip (.+^)
addUTCTime d t ≡ t .+^ d

See also the AffineSpace instance for UTCTime.

The duration difference between two time points.

diffUTCTime = (.-.)
diffUTCTime a b = a .-. b

See also the AffineSpace instance for UTCTime.

The number of microseconds in a DiffTime or NominalDiffTime.

toMicroseconds :: DiffTime -> Int64
toMicroseconds :: NominalDiffTime -> Int64
toMicroseconds = view microseconds
toMicroseconds d ≡ d ^. microseconds

Construct a DiffTime or NominalDiffTime from a number of microseconds.

fromMicroseconds :: Int64 -> DiffTime
fromMicroseconds :: Int64 -> NominalDiffTime
fromMicroseconds = review microseconds
fromMicroseconds n ≡ microseconds # n