Data.Time.Clock.TAI64

Implementation of TAI64 labels as specified by http://cr.yp.to/libtai/tai64.html

Mainly useful for working with logfiles generated by "multilog" (part of the daemontools suite) or "svlogd" (part of the runit suite).

Documentation

data TAI64

Representation of a TAI64 label with full precision

Instances

Bounded TAI64

Eq TAI64

Ord TAI64

Show TAI64

Arbitrary TAI64

Unbox TAI64

Vector Vector TAI64

MVector MVector TAI64

data Vector TAI64 = V_TAI64 (Vector (Word64, Word32, Word32))

data MVector s TAI64 = MV_TAI64 (MVector s (Word64, Word32, Word32))

tai64 :: Word64 -> Word32 -> Word32 -> TAI64

Construct a TAI64 from seconds, nanoseconds and attoseconds

taiSecs :: TAI64 -> Word64

Seconds of real time.

Integer s refers to

  * the TAI second beginning exactly 2^62 - s seconds before the
    beginning of 1970 TAI, if s is between 0 inclusive and 2^62 exclusive;
  * or the TAI second beginning exactly s - 2^62 seconds after the
    beginning of 1970 TAI, if s is between 2^62 inclusive and 2^63
    exclusive.

Integers 2^63 and larger are reserved for future extensions. Under many
cosmological theories, the integers under 2^63 are adequate to cover the
entire expected lifetime of the universe; in this case no extensions will
be necessary.

taiNanos :: TAI64 -> Word32

Nanoseconds [0 .. 999999999]

taiAttos :: TAI64 -> Word32

Attoseconds [0 .. 999999999]

data Label

A TAI64 label with precision as denoted by the data constructor. This is used to render the "external" (cf. toText, toByteString) respectively binary representation.

Constructors

TAI64S !TAI64

TAI64N !TAI64

TAI64NA !TAI64

Instances

Eq Label

Ord Label

Show Label

Arbitrary Label

Binary Label

External representation of a Label

• TAI64S: eight 8-bit bytes, big-endian, encoding the second
• TAI64N: twelve 8-bit bytes, big-endian, encoding the second, followed by the nanosecond
• TAI64NA: sixteen 8-bit bytes, big-endian, encoding the second, followed by the nanosecond, followed by the attosecond

Properties:

(Binary.decode . Binary.encode) x == x

fromLabel :: Label -> TAI64

Get the TAI64 stamp from the Label, truncated to the precision as denoted by the Label's data constructor.

addTAI64 :: DiffTime -> TAI64 -> TAI64

addTAI64 a b = a + b

Properties:

\d (PicosecondResolution t) -> addTAI64 d t === fromUTCTime (addUTCTime (realToFrac d) (toUTCTime t))

diffTAI64 :: TAI64 -> TAI64 -> DiffTime

diffTAI64 a b = a - b

Properties:

\(PicosecondResolution a) (PicosecondResolution b) -> b <= a ==> diffTAI64 a b === realToFrac (diffUTCTime (toUTCTime a) (toUTCTime b))

sumTAI64 :: TAI64 -> TAI64 -> TAI64

sumTAI64 a b = a + b

Properties:

sumTAI64 a b >= a

sumTAI64 a minBound === a

sumTAI64 b a === sumTAI64 a b

(a `sumTAI64` b) `sumTAI64` c === a `sumTAI64` (b `sumTAI64` c)

subTAI64 :: TAI64 -> TAI64 -> TAI64

subTAI64 a b = a - b

Properties:

subTAI64 a b <= a

b >= a ==> subTAI64 a b === minBound

subTAI64 a minBound === a

toUTCTime :: TAI64 -> UTCTime

Convert a TAI64 label to UTCTime.

Note that UTCTime has only picosecond precision, so the conversion is lossy.

Properties:

\(PicosecondResolution x) -> (fromUTCTime . toUTCTime) x === x

fromUTCTime :: UTCTime -> TAI64

Obtain a TAI64 label from UTCTime.

Properties:

(toUTCTime . fromUTCTime) x === x

toPOSIXTime :: TAI64 -> POSIXTime

Convert a TAI64 label to POSIXTime.

Note that POSIXTime has only picosecond precision, so the conversion is lossy.

Properties:

\(PicosecondResolution x) -> (fromPOSIXTime . toPOSIXTime) x === x

fromPOSIXTime :: POSIXTime -> TAI64

Obtain a TAI64 label from POSIXTime

Properties:

fromPOSIXTime x === fromUTCTime (posixSecondsToUTCTime x)

toText :: Label -> Text

Render a textual (ie. hexadecimal) representation of the external TAI64{N,NA} format of the given Label

Properties:

(fromText . toText) x === Right (fromLabel x)

fromText :: Text -> Either String TAI64

Parse a TAI64 label from it's textual (hexadecimal) representation.

Properties:

let x' = toText x in fromText x' === fromText ("@" <> x')

toByteString :: Label -> ByteString

Render a textual (ie. hexadecimal) representation of the external TAI64{N,NA} format of the given Label

Properties:

(fromByteString . toByteString) x === Right (fromLabel x)

fromByteString :: ByteString -> Either String TAI64

Parse a TAI64 label from it's textual (hexadecimal) representation.

Properties:

let x' = toByteString x in fromByteString x' === fromByteString ("@" <> x')

parse :: ParseInput a => Parser a TAI64

Attoparsec parser for the textual TAI64 format, generalized so it works for both Text and ByteString input.

parseText :: Parser Text TAI64

Type-specialisation of parse

parseByteString :: Parser ByteString TAI64

Type-specialisation of parse