# 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

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.