std.instant

Instants: points on the time line, the same everywhere, to the nanosecond — what std.time’s clock tells, and what no calendar or clock on the wall does alone. NodaTime’s Instant is the model: an instant is its nanoseconds since the Unix epoch, 1970-01-01T00:00:00Z, fewer than none before it, of any size, as an Int is. It moves by a std.duration, and two are a std.duration apart. Its date and time in UTC is a std.localdatetime (inUtc, fromUtc); at another offset, a std.offsetdatetime’s at. The second here is SI’s, and a day of UTC is 86400 of them: no leap second, as POSIX time has none. Import it by a name, import std.instant as Instant, as its names are short.

import std.duration as Duration
import std.instant as Instant

-- | the instant a day after
-- | >>> show (tomorrow Instant.epoch)
-- | "1970-01-02T00:00:00Z"
tomorrow : Instant.Instant -> Instant.Instant
tomorrow t = Instant.plus t (Duration.days 1)

Instant

data Instant

An instant: its nanoseconds since the Unix epoch.

epoch

epoch : Instant

The Unix epoch, 1970-01-01T00:00:00Z.

fromUnixNanoseconds

fromUnixNanoseconds : Int -> Instant

The instant n nanoseconds after the Unix epoch, before it for fewer than none.

unixNanoseconds

unixNanoseconds : Instant -> Int

Its nanoseconds since the Unix epoch.

plus

plus : Instant -> Duration.Duration -> Instant

The instant the duration after it.

minus

minus : Instant -> Duration.Duration -> Instant

The instant the duration before it.

between

between : Instant -> Instant -> Duration.Duration

How long it is from the first to the second: between a b is b less a, less than none if b comes first.

>>> show (between (fromUnixNanoseconds 1500000000) epoch)
"-1.5s"

inUtc

inUtc : Instant -> LocalDateTime.LocalDateTime

Its date and time in UTC.

>>> List.map (\n -> show (inUtc (fromUnixNanoseconds n))) [0, 1709219045500000000, -1, -62167219200000000001]
["1970-01-01T00:00:00", "2024-02-29T15:04:05.5", "1969-12-31T23:59:59.999999999", "-0001-12-31T23:59:59.999999999"]

fromUtc

fromUtc : LocalDateTime.LocalDateTime -> Instant

The instant the date and time is in UTC: inUtc’s inverse.

>>> List.all (\n -> unixNanoseconds (fromUtc (inUtc (fromUnixNanoseconds n))) == n) [0, 1709219045500000000, -1, -62167219200000000001, 253402300799999999999]
True

instanceEqualityInstant

instance instanceEqualityInstant : Equality Instant

The same instant.

instanceOrderInstant

instance instanceOrderInstant : Order Instant

The earlier first.

>>> epoch < fromUnixNanoseconds 1 && max epoch (fromUnixNanoseconds (-1)) == epoch
True

instanceDebugInstant

instance instanceDebugInstant : Debug Instant

As show writes it, 2024-02-29T15:04:05.5Z, as NodaTime’s debug form is.

>>> debug epoch
"1970-01-01T00:00:00Z"

instanceShowInstant

instance instanceShowInstant : Show Instant

As RFC 3339 writes it in UTC, as Go’s RFC3339Nano does: a fraction of a second only where there is one, without the 0s it ends with, and a Z (2024-02-29T15:04:05.5Z); a year out of 0000 to 9999 as std.localdate writes it, though RFC 3339 has none.

>>> List.map (\n -> show (fromUnixNanoseconds n)) [1709219045500000000, 1700000000123456789, -1]
["2024-02-29T15:04:05.5Z", "2023-11-14T22:13:20.123456789Z", "1969-12-31T23:59:59.999999999Z"]
>>> show (plus epoch (Duration.hours 1 + Duration.seconds 1))
"1970-01-01T01:00:01Z"
>>> show (minus epoch (Duration.days 365))
"1969-01-01T00:00:00Z"