tempo/instant

The Instant type is the most complete representation of system time. It is a monotonic type that represents a unique point in time on the host system. It is the only way to get the current time on the host system as a value, and means very little on other systems. Try to keep Instant values as this type as long as possible in your programs. It can be safely used for timing tasks, sorting times, and recording times.

If you would like to send this value outside of Gleam, it will have to be converted to a DateTime value first.

Timing Tasks

import tempo/instant

pub fn main() {
  let monotonic_timer = instant.now()
  // Do long task ...
  instant.since(monotonic_timer)
  // -> duration.minutes(42)

  instant.format_since(monotonic_timer)
  // -> "42 minutes"
}

Sorting Times

import tempo/instant

pub fn main() {
  let completed_async_tasks = // ...

  let task_by_completion_time = 
    list.sort(
      completed_async_tasks,
      fn(a, b) { instant.compare(a.completion_time, b.completion_time) },
    )
}

Recording Times

import tempo/instant

pub type Record {
  Record(name: String, created_time: instant.Instant)
}

pub fn new_record(name) {
  Record(name: name, created_time: instant.now())
}

pub fn render_record_created_time(record: Record) {
  instant.format(record.created_time, tempo.ISO8601Milli)
}

Functions

as_local_date

</>

pub fn as_local_date(instant: Instant) -> Date

Converts an instant to a local date value.

Example

tempo.now()
|> instant.as_local_date
// -> date.literal("2024-12-26")

as_local_datetime

</>

pub fn as_local_datetime(instant: Instant) -> DateTime

Converts an instant to a local datetime value. Do not use this with datetime.difference to time tasks!

Example

tempo.now()
|> instant._as_local_datetime
// -> datetime.literal("2024-12-26T12:32:34-04:00")

as_local_time

</>

pub fn as_local_time(instant: Instant) -> Time

Converts an instant to a local time value.

Example

tempo.now()
|> instant.as_local_time
// -> time.literal("12:32:34")

as_utc_date

</>

pub fn as_utc_date(instant: Instant) -> Date

Converts an instant to a UTC date value.

Example

tempo.now()
|> instant.as_utc_date
// -> date.literal("2024-12-27")

as_utc_datetime

</>

pub fn as_utc_datetime(instant: Instant) -> DateTime

Converts an instant to a UTC datetime value. Do not use this with datetime.difference to time tasks!

Example

instant.now()
|> instant.as_utc_datetime
// -> datetime.literal("2024-12-26T16:32:34Z")

as_utc_time

</>

pub fn as_utc_time(instant: Instant) -> Time

Converts an instant to a UTC time value.

Example

tempo.now()
|> instant.as_utc_time
// -> time.literal("16:32:34")

compare

</>

pub fn compare(a: Instant, b: Instant) -> Order

Compares two instants.

Example

let start = tempo.now()
let end = tempo.now()

instant.compare(start, end)
// -> order.Lt

difference

</>

pub fn difference(from a: Instant, to b: Instant) -> Duration

Gets the difference between two instants.

Example

let start = tempo.now()
let end = tempo.now()

instant.difference(from: start, to: end)
// -> duration.microseconds(1)

format_local

</>

pub fn format_local(
  instant: Instant,
  in format: DateTimeFormat,
) -> String

Formats an instant as a local datetime value.

Example

tempo.now()
|> instant.format_local(tempo.ISO8601Micro)
// -> "2024-12-26T12:32:34.534223-04:00"

format_since

</>

pub fn format_since(start start: Instant) -> String

Formats the duration between the current system time and the provided instant.

Example

let monotonic_timer = instant.now()
// Do long task ...
instant.format_since(monotonic_timer)
// -> "42 minutes"

format_utc

</>

pub fn format_utc(
  instant: Instant,
  in format: DateTimeFormat,
) -> String

Formats an instant as a UTC datetime value.

Example

tempo.now()
|> instant.format_utc(tempo.ISO8601Milli)
// -> "2024-12-26T16:32:34.254Z"

is_earlier

</>

pub fn is_earlier(a: Instant, than b: Instant) -> Bool

Checks if the first instant is earlier than the second instant.

Example

let start = tempo.now()
let end = tempo.now()

instant.is_earlier(start, than: end)
// -> True

is_earlier_or_equal

</>

pub fn is_earlier_or_equal(a: Instant, to b: Instant) -> Bool

Checks if the first instant is earlier or equal to the second instant.

Example

let start = tempo.now()
let end = tempo.now()

instant.is_earlier_or_equal(start, to: end)
// -> True

is_equal

</>

pub fn is_equal(a: Instant, to b: Instant) -> Bool

Checks if the first instant is equal to the second instant.

Example

let start = tempo.now()
let end = tempo.now()

instant.is_equal(start, to: end)
// -> False

is_later

</>

pub fn is_later(a: Instant, than b: Instant) -> Bool

Checks if the first instant is later than the second instant.

Example

let start = tempo.now()
let end = tempo.now()

instant.is_later(start, than: end)
// -> False

is_later_or_equal

</>

pub fn is_later_or_equal(a: Instant, to b: Instant) -> Bool

Checks if the first instant is later or equal to the second instant.

Example

let start = tempo.now()
let end = tempo.now()

instant.is_later_or_equal(start, to: end)
// -> False

now

</>

pub fn now() -> Instant

The current instant on the host system.

since

</>

pub fn since(start start: Instant) -> Duration

Gets the duration between the current system time and the provided instant.

Example

let monotonic_timer = instant.now()
// Do long task ...
instant.since(monotonic_timer)
// -> duration.minutes(42)