UTCTime package:thyme

Coördinated universal time (UTCTime) is the most commonly used standard for civil timekeeping. It is synchronised with TAI (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.

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)

Convert a UTCTime to a POSIXTime.

utcTimeToPOSIXSeconds = view posixTime

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.

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

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.

Construct a UTCTime from a POSIXTime.

posixSecondsToUTCTime = review posixTime
posixSecondsToUTCTime t ≡ posixTime # t

Using a TAIUTCMap, convert a AbsoluteTime to UTCTime.

taiToUTCTime = review . absoluteTime

Convert a TimeOfDay in some timezone to a UTC TimeOfDay, together with a day adjustment.

localToUTCTimeOfDay = addMinutes . negate . timeZoneMinutes