thyme-0.3.5.5: A faster time library

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.

`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 DiffTime ≡ Scalar NominalDiffTime ≡ Rational```.

Using `fromSeconds` and `toSeconds` to convert between `TimeDiff`s 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 UTCTime ≡ NominalDiffTime`.

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

Synopsis

# Universal Time

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.

View `UniversalTime` as a fractional number of days since the Modified Julian Date epoch.

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

# UTC

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 `UTCTime`s.

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

data UTCView Source

Unpacked `UTCTime`, partly for compatibility with `time`.

Constructors

 UTCTime FieldsutctDay :: !Day utctDayTime :: !DiffTime

Instances

 Eq UTCView Data UTCView Ord UTCView Read UTCView Show UTCView Generic UTCView NFData UTCView Unbox UTCView Typeable * UTCView Vector Vector UTCView MVector MVector UTCView Thyme UTCTime UTCView type Rep UTCView data Vector UTCView = V_UTCView (Vector (Day, DiffTime)) data MVector s0 UTCView = MV_UTCView (MVector s (Day, DiffTime))

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.

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

Get the current UTC time from the system clock.

# Time interval conversion

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

Time intervals, encompassing both `DiffTime` and `NominalDiffTime`.

`Issues`

Methods

Escape hatch; avoid.

Instances

 TimeDiff DiffTime TimeDiff NominalDiffTime

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

Convert a time interval to some `Fractional` type.

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

Make a time interval from some `Real` type.

`Performance`
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 -> Rational Source

Type-restricted `toSeconds` to avoid constraint-defaulting warnings.

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

Type-restricted `fromSeconds` to avoid constraint-defaulting warnings.

# Lenses

`Lens'` for the `Day` component of an `UTCTime`.

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