| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
Data.Thyme.Clock
Description
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.
Data.Thyme.Time provides Num, Real, Fractional and RealFrac
instances for DiffTime and NominalDiffTime, but their use is
discouraged. See Data.Thyme.Docs for details.
Use fromSeconds and toSeconds to convert between DiffTime
/ NominalDiffTime and other numeric types; use fromSeconds' for
literals to avoid type defaulting warnings.
Synopsis
- data UTCTime
- utctDay :: UTCTime -> Day
- utctDayTime :: UTCTime -> DiffTime
- _utctDay :: Lens' UTCTime Day
- _utctDayTime :: Lens' UTCTime DiffTime
- pattern UTCTime :: Day -> DiffTime -> UTCTime
- mkUTCTime :: Year -> Month -> DayOfMonth -> Hour -> Minute -> Double -> UTCTime
- utcTime :: Iso' UTCTime UTCView
- data UTCView = UTCView {
- utcvDay :: !Day
- utcvDayTime :: !DiffTime
- _utcvDay :: Lens' UTCView Day
- _utcvDayTime :: Lens' UTCView DiffTime
- data NominalDiffTime
- getCurrentTime :: IO UTCTime
- data DiffTime
- class (HasBasis t, Basis t ~ (), Scalar t ~ Rational) => TimeDiff t where
- microseconds :: Iso' t Int64
- toSeconds :: (TimeDiff t, Fractional n) => t -> n
- fromSeconds :: (Real n, TimeDiff t) => n -> t
- toSeconds' :: TimeDiff t => t -> Rational
- fromSeconds' :: TimeDiff t => Rational -> t
- picoseconds :: TimeDiff t => Iso' t Integer
- data UniversalTime
- pattern UniversalTime :: Rational -> UniversalTime
- modJulianDate :: Iso' UniversalTime Rational
- getModJulianDate :: UniversalTime -> Rational
- mkModJulianDate :: Rational -> UniversalTime
- secondsToDiffTime :: Int64 -> DiffTime
- picosecondsToDiffTime :: Integer -> DiffTime
- unUTCTime :: UTCTime -> UTCView
- addUTCTime :: NominalDiffTime -> UTCTime -> UTCTime
- diffUTCTime :: UTCTime -> UTCTime -> NominalDiffTime
- toMicroseconds :: TimeDiff t => t -> Int64
- fromMicroseconds :: TimeDiff t => Int64 -> t
UTC
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#YearMonthDay2016 1 15) (timeOfDay#TimeOfDay12 34 56.78) 2016-01-15 12:34:56.78 UTC >UTCTime(gregorian#YearMonthDay2016 1 15) (timeOfDay#TimeOfDay12 34 56.78) 2016-01-15 12:34:56.78 UTC >mkUTCTime2016 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 for details.
> let t0 =mkUTCTime2016 1 15 23 59 0 > let t1 =mkUTCTime2016 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.
Instances
utctDayTime :: UTCTime -> DiffTime Source #
Accessor for the time-of-day DiffTime component of an UTCTime.
utctDayTime=view_utctDayTime
_utctDayTime :: Lens' UTCTime DiffTime Source #
mkUTCTime :: Year -> Month -> DayOfMonth -> Hour -> Minute -> Double -> UTCTime Source #
Construct a UTCTime from a gregorian date and time-of-day.
mkUTCTimeyy mm dd h m s ≡utcTime#UTCView(gregorian#YearMonthDayyy mm dd) (timeOfDay#TimeOfDayh m (fromSecondss))
utcTime :: Iso' UTCTime UTCView Source #
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
[ will carry over into zeroV, posixDayLength)utcvDay, with the
expected behaviour.
>viewutcTime<$>getCurrentTimeUTCView{utcvDay= 2016-01-15,utcvDayTime= 49322.287688s} >utcTime#UTCView(gregorian#YearMonthDay2016 1 15) (timeOfDay#TimeOfDay12 34 56.78) 2016-01-15 12:34:56.78 UTC
With {-# LANGUAGE ViewPatterns #-}, you can write: e.g.
f ::UTCTime-> (Day,DiffTime) f (viewutcTime->UTCViewday dt) = (day, dt)
Unpacked UTCTime, partly for compatibility with time.
As of GHC 7.10, you can also use the UTCTime pattern synonym.
Constructors
| UTCView | |
Fields
| |
Instances
_utcvDayTime :: Lens' UTCView DiffTime Source #
data NominalDiffTime Source #
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 for details.
> let d =fromSeconds'2 ::NominalDiffTime> d 2s > d^/3 0.666667s
See also: UTCTime.
Instances
getCurrentTime :: IO UTCTime Source #
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.
Absolute intervals
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 for details.
>fromSeconds'100 ::DiffTime100s >fromSeconds'100^+^fromSeconds'100^*4 500s >fromSeconds'100^-^fromSeconds'100^/4 75s
Instances
Time interval conversion
class (HasBasis t, Basis t ~ (), Scalar t ~ Rational) => TimeDiff t where Source #
Time intervals, encompassing both DiffTime and NominalDiffTime.
Notes
Still affected by http://hackage.haskell.org/trac/ghc/ticket/7611?
Methods
microseconds :: Iso' t Int64 Source #
Conversion between TimeDiff and Int64 microseconds.
> (fromSeconds'3 ::DiffTime)^.microseconds3000000 >microseconds#4000000 ::DiffTime4s
Instances
| TimeDiff DiffTime Source # | |
Defined in Data.Thyme.Clock.Internal Methods microseconds :: Iso' DiffTime Int64 Source # | |
| TimeDiff NominalDiffTime Source # | |
Defined in Data.Thyme.Clock.Internal Methods microseconds :: Iso' NominalDiffTime Int64 Source # | |
toSeconds :: (TimeDiff t, Fractional n) => t -> n Source #
Convert a time interval to some Fractional type.
fromSeconds :: (Real n, TimeDiff t) => n -> t Source #
toSeconds' :: TimeDiff t => t -> Rational Source #
Type-restricted toSeconds to avoid constraint-defaulting warnings.
fromSeconds' :: TimeDiff t => Rational -> t Source #
Type-restricted fromSeconds to avoid constraint-defaulting warnings.
picoseconds :: TimeDiff t => Iso' t Integer Source #
Universal Time
data UniversalTime Source #
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.
Instances
pattern UniversalTime :: Rational -> UniversalTime Source #
modJulianDate :: Iso' UniversalTime Rational Source #
Convert between UniversalTime and the fractional number of days since the
Modified Julian Date epoch.
Compatibility
getModJulianDate :: UniversalTime -> Rational Source #
Convert a UniversalTime to the fractional number of days since the
Modified Julian Date epoch.
getModJulianDate=viewmodJulianDate
mkModJulianDate :: Rational -> UniversalTime Source #
Construct a UniversalTime from the fractional number of days since the
Modified Julian Date epoch.
mkModJulianDate=reviewmodJulianDate
secondsToDiffTime :: Int64 -> DiffTime Source #
Construct a DiffTime from some number of seconds.
This is just fromSeconds with a more constrained type.
secondsToDiffTime=fromSeconds
picosecondsToDiffTime :: Integer -> DiffTime Source #
Construct a DiffTime from some number of picoseconds.
The input will be rounded to the nearest microsecond.
picosecondsToDiffTimea =microseconds#quot(a+signuma*500000) 1000000
addUTCTime :: NominalDiffTime -> UTCTime -> UTCTime Source #
Add a duration to a point in time.
addUTCTime=flip(.+^)addUTCTimed t ≡ t.+^d
See also the AffineSpace instance for UTCTime.
diffUTCTime :: UTCTime -> UTCTime -> NominalDiffTime Source #
The duration difference between two time points.
diffUTCTime= (.-.)diffUTCTimea b = a.-.b
See also the AffineSpace instance for UTCTime.
toMicroseconds :: TimeDiff t => t -> Int64 Source #
The number of microseconds in a DiffTime or NominalDiffTime.
toMicroseconds::DiffTime->Int64toMicroseconds::NominalDiffTime->Int64toMicroseconds=viewmicrosecondstoMicrosecondsd ≡ d^.microseconds
fromMicroseconds :: TimeDiff t => Int64 -> t Source #
Construct a DiffTime or NominalDiffTime from a number of
microseconds.
fromMicroseconds::Int64->DiffTimefromMicroseconds::Int64->NominalDiffTimefromMicroseconds=reviewmicrosecondsfromMicrosecondsn ≡microseconds#n