Instant

The built-in type Instant represents instantaneous points on the time-line to millisecond precision.

components : Instant -> Instant::Components

Returns the underlying representation of the Instant. The returned data type has the following definition:

module Instant {
  type Components {
    second : Int,
    millisecond : Int
  }
}

The two components specify an instant on the time-line relative to the epoch 1970-01-01 00:00:00.000 in UTC. The millisecond adjustment component is always in the non-negative range [0 .. 999].

Examples

// Example demonstrating that the millisecond adjustment is always non-negative. 600ms before epoch is represented
// as -1 second plus 400 milliseconds.
val a = Instant::components #1969-12-31T23:59:59.400#
//    = Instant::Components { millisecond = 400, second = -1 }

val b = Instant::components #2000-01-01T01:30:50.456Z#
//    = Instant::Components { millisecond = 456, second = 946690250 }

fromComponents : Instant::Components -> Instant

Constructs an Instant from a number of seconds and millisecond adjustment. There are no range constraints on the components, specifically the millisecond adjustment is allowed to be outside the range [0 .. 999]. The components are normalized internally to bring the millisecond adjustment into the normal range. The function is partial and fails if normalization of the millisecond adjustment causes the number of seconds to overflow.

Examples

val a = Instant::fromComponents Instant::Components { millisecond = 0, second = 0 }
//    = #1970-01-01T00:00:00Z#

val b = Instant::fromComponents Instant::Components { millisecond = -1000, second = 1 }
//    = #1970-01-01T00:00:00Z#

val c = Instant::fromComponents Instant::Components { millisecond = 4600, second = 1 }
//    = #1970-01-01T00:00:05.6Z#

from : Int -> Int -> Instant

Convenience wrapper around Instant::fromComponents which takes the individual components as positional arguments. The order of arguments is

  1. second
  2. millisecond adjustment

The function is partial and fails if normalization of the millisecond adjustment causes the number of seconds to overflow.

addDuration : Duration -> Instant -> Instant

Adds a duration to the given instant. The function is partial and fails if the number of seconds in the underlying representation overflows.

Examples

val a = Instant::addDuration (Duration::fromHours 32) #2000-01-01T12:00Z#
//    = #2000-01-02T20:00:00Z#

addSeconds : Int -> Instant -> Instant

Convenience wrapper around Instant::addDuration. The function is partial and fails if the number of seconds in the underlying representation overflows.

addDays : Int -> Instant -> Instant

Convenience wrapper around Instant::addDuration. A day is treated as exactly 24 hours.

The function is partial and fails if the number of seconds in the underlying representation overflows.