Functions

`add`

fn (temporal: PlainDateTime, duration: Duration): PlainDateTime

Add a Duration to a PlainDateTime.

Example


dt ::hot::time/PlainDateTime(2024, 12, 25, 10, 0, 0)
::hot::time/add(dt, ::hot::time/days(7))  // 2025-01-01T10:00:00

`day`

fn (date: PlainDate | PlainDateTime): Int

Extract the day of month component (1-31).

Example


date ::hot::time/PlainDate(2024, 12, 25)
::hot::time/day(date)  // 25

`days`

fn (amount: Any): Duration

Create a Duration representing amount days.

Example


::hot::time/days(30)  // Duration of 30 days

`end-of-day`

fn (date: PlainDate | PlainDateTime): PlainDateTime

Return a PlainDateTime at 23:59:59 for the given date.

Example


date ::hot::time/PlainDate(2024, 12, 25)
::hot::time/end-of-day(date)  // 2024-12-25T23:59:59

`epoch-millis`

fn (instant: Instant): Int

Get milliseconds since Unix epoch for instant.

Example


ms ::hot::time/epoch-millis(::hot::time/now())
// 1733312400000

`epoch-nanos`

fn (instant: Instant): Int

Get nanoseconds since Unix epoch for instant.

Example


ns ::hot::time/epoch-nanos(::hot::time/now())
// 1733312400000000000

`format`

fn (temporal: Any, pattern: Str): Str

Format a date/time value using a pattern string.

Works with PlainDate, PlainTime, PlainDateTime, ZonedDateTime, and Instant. Uses English month/day names. For ISO output, use Str() coercion instead.

Pattern tokens:

Token	Meaning	Example
YYYY	4-digit year	2026
YY	2-digit year	26
MMMM	Full month name	February
MMM	Short month name	Feb
MM	2-digit month	02
M	Month number	2
DD	2-digit day	17
D	Day of month	17
dddd	Full weekday name	Tuesday
ddd	Short weekday name	Tue
HH	24-hour hour (2-dig)	14
H	24-hour hour	14
hh	12-hour hour (2-dig)	02
h	12-hour hour	2
mm	Minutes (2-digit)	30
ss	Seconds (2-digit)	05
SSS	Milliseconds	123
A	AM/PM	PM
a	am/pm	pm
z	Timezone abbrev	CST
Z	UTC offset	-06:00
X	Unix seconds	1771362600

Example


date ::hot::time/PlainDate(2026, 2, 17)
::hot::time/format(date, "MMMM D, YYYY")          // "February 17, 2026"
::hot::time/format(date, "MM/DD/YYYY")             // "02/17/2026"

dt ::hot::time/PlainDateTime(2026, 2, 17, 14, 30, 0)
::hot::time/format(dt, "h:mm A")                   // "2:30 PM"
::hot::time/format(dt, "dddd, MMMM D YYYY HH:mm") // "Tuesday, February 17 2026 14:30"

`hour`

fn (time: PlainTime | PlainDateTime): Int

Extract the hour component (0-23).

Example


time ::hot::time/PlainTime(14, 30, 0)
::hot::time/hour(time)  // 14

`hours`

fn (amount: Any): Duration

Create a Duration representing amount hours.

Example


::hot::time/hours(24)  // Duration of 24 hours

`microsecond`

fn (time: PlainTime | PlainDateTime): Int

Extract the microsecond component (0-999).

Example


time ::hot::time/PlainTime("14:30:45.123456")
::hot::time/microsecond(time)  // 456

`millisecond`

fn (time: PlainTime | PlainDateTime): Int

Extract the millisecond component (0-999).

Example


time ::hot::time/PlainTime("14:30:45.123")
::hot::time/millisecond(time)  // 123

`minute`

fn (time: PlainTime | PlainDateTime): Int

Extract the minute component (0-59).

Example


time ::hot::time/PlainTime(14, 30, 45)
::hot::time/minute(time)  // 30

`minutes`

fn (amount: Any): Duration

Create a Duration representing amount minutes.

Example


::hot::time/minutes(30)  // Duration of 30 minutes

`month`

fn (date: PlainDate | PlainDateTime): Int

Extract the month component (1-12).

Example


date ::hot::time/PlainDate(2024, 12, 25)
::hot::time/month(date)  // 12

`months`

fn (amount: Any): Duration

Create a Duration representing amount months.

Example


::hot::time/months(6)  // Duration of 6 months

`nanosecond`

fn (time: PlainTime | PlainDateTime): Int

Extract the nanosecond component (0-999).

Example


time ::hot::time/PlainTime("14:30:45.123456789")
::hot::time/nanosecond(time)  // 789

`now`

fn (): Instant

Get the current instant.

Example


current ::hot::time/now()
Str(current)  // "2024-12-04T10:30:00Z"

`now-zoned`

fn (timezone: Str): ZonedDateTime

Get the current time as a ZonedDateTime in the given timezone.

Example


chicago ::hot::time/now-zoned("America/Chicago")
tokyo ::hot::time/now-zoned("Asia/Tokyo")
chicago.timezone  // "America/Chicago"

`parse`

fn (date-string: Str): PlainDateTime | PlainDate | PlainTime

Parse an ISO-like date/time string into PlainDateTime, PlainDate or PlainTime.

Example


::hot::time/parse("2024-12-25")           // PlainDate
::hot::time/parse("14:30:00")             // PlainTime
::hot::time/parse("2024-12-25T14:30:00")  // PlainDateTime

`second`

fn (time: PlainTime | PlainDateTime): Int

Extract the second component (0-59).

Example


time ::hot::time/PlainTime(14, 30, 45)
::hot::time/second(time)  // 45

`seconds`

fn (amount: Any): Duration

Create a Duration representing amount seconds.

Example


::hot::time/seconds(60)  // Duration of 60 seconds

`since`

fn (start: PlainDateTime, end: PlainDateTime): Duration

Return the Duration from end to start.

Example


start ::hot::time/PlainDateTime(2024, 1, 1, 0, 0, 0)
end ::hot::time/PlainDateTime(2024, 12, 31, 23, 59, 59)
duration ::hot::time/since(start, end)
// duration.days = -365

`start-of-day`

fn (date: PlainDate | PlainDateTime): PlainDateTime

Return a PlainDateTime at 00:00:00 for the given date.

Example


date ::hot::time/PlainDate(2024, 12, 25)
::hot::time/start-of-day(date)  // 2024-12-25T00:00:00

`subtract`

fn (temporal: PlainDateTime, duration: Duration): PlainDateTime

Subtract a Duration from a PlainDateTime.

Example


dt ::hot::time/PlainDateTime(2024, 12, 25, 10, 0, 0)
::hot::time/subtract(dt, ::hot::time/days(25))  // 2024-11-30T10:00:00

`to-instant`

fn (zdt: ZonedDateTime): Instant

Extract the exact moment from a ZonedDateTime as an Instant, discarding the timezone.

Example


zdt ZonedDateTime("2026-02-17T10:30:00-06:00[America/Chicago]")
inst ::hot::time/to-instant(zdt)
::hot::time/epoch-millis(inst)  // epoch millis for that moment

`to-plain-date`

fn (zdt: ZonedDateTime): PlainDate

Extract the date from a ZonedDateTime, discarding time and timezone. Returns a PlainDate.

Example


zdt ZonedDateTime("2026-02-17T10:30:00-06:00[America/Chicago]")
d ::hot::time/to-plain-date(zdt)
Str(d)  // "2026-02-17"

`to-plain-date-time`

fn (zdt: ZonedDateTime): PlainDateTime

Extract the wall-clock date and time from a ZonedDateTime, discarding the timezone. Returns a PlainDateTime.

Example


zdt ZonedDateTime("2026-02-17T10:30:00-06:00[America/Chicago]")
dt ::hot::time/to-plain-date-time(zdt)
Str(dt)  // "2026-02-17T10:30:00"

`to-plain-time`

fn (zdt: ZonedDateTime): PlainTime

Extract the wall-clock time from a ZonedDateTime, discarding date and timezone. Returns a PlainTime.

Example


zdt ZonedDateTime("2026-02-17T10:30:00-06:00[America/Chicago]")
t ::hot::time/to-plain-time(zdt)
Str(t)  // "10:30:00"

`until`

fn (start: PlainDateTime, end: PlainDateTime): Duration

Return the Duration from start to end.

Example


start ::hot::time/PlainDateTime(2024, 1, 1, 0, 0, 0)
end ::hot::time/PlainDateTime(2024, 12, 31, 23, 59, 59)
duration ::hot::time/until(start, end)
// duration.days = 365

`weeks`

fn (amount: Any): Duration

Create a Duration representing amount weeks.

Example


::hot::time/weeks(2)  // Duration of 2 weeks

`with-timezone`

fn (zdt: ZonedDateTime, timezone: Str): ZonedDateTime

Convert a ZonedDateTime to a different timezone. The underlying instant remains the same; the wall-clock fields change to reflect the new zone.

Example


chicago ZonedDateTime("2026-02-17T10:30:00-06:00[America/Chicago]")
tokyo ::hot::time/with-timezone(chicago, "Asia/Tokyo")
tokyo.hour      // 1 (next day)
tokyo.timezone  // "Asia/Tokyo"

`year`

fn (date: PlainDate | PlainDateTime): Int

Extract the year component.

Example


date ::hot::time/PlainDate(2024, 12, 25)
::hot::time/year(date)  // 2024

`years`

fn (amount: Any): Duration

Create a Duration representing amount years.

Example


::hot::time/years(2)  // Duration of 2 years

Types

`Day`

Day time unit. Wraps an Int value.

`Duration`

fn (iso: Str): Duration
fn (components: Map): Duration

Duration type {
    years: Dec,
    months: Dec,
    weeks: Dec,
    days: Dec,
    hours: Dec,
    minutes: Dec,
    seconds: Dec,
    milliseconds: Dec,
    microseconds: Dec,
    nanoseconds: Dec
}

A length of time. Can be used to add/subtract from dates and times.

Example

d ::hot::time/days(7)              // 7-day duration
d Duration({"hours": 2, "minutes": 30})  // 2h 30m duration
Str(d)                             // "PT2H30M"

`Hour`

Hour time unit. Wraps an Int value.

`Instant`

fn (epoch-millis: Millisecond): Instant
fn (epoch-micros: Microsecond): Instant
fn (epoch-nanos: Nanosecond): Instant
fn (plain-date: PlainDate): Instant
fn (plain-time: PlainTime): Instant
fn (plain-date-time: PlainDateTime): Instant

Instant type {
    epochNanoseconds: Int
}

An exact moment in time (UTC). Based on Temporal.Instant.

Example

now ::hot::time/now()           // Current instant
Str(now)                        // "2024-12-04T15:30:00Z"
::hot::time/epoch-millis(now)   // 1733324400000

`Microsecond`

Microsecond time unit. Wraps an Int value.

`Millisecond`

Millisecond time unit. Wraps an Int value.

`Minute`

Minute time unit. Wraps an Int value.

`Month`

Month time unit. Wraps an Int value.

`Nanosecond`

Nanosecond time unit. Wraps an Int value.

`PlainDate`

fn (): PlainDate
fn (date: Str): PlainDate
fn (year: Int, month: Int, day: Int): PlainDate

PlainDate type {
    year: Int,
    month: Int,
    day: Int,
    calendar: Str
}

A calendar date without time or timezone. Based on Temporal.PlainDate.

Example

today PlainDate()                   // Today's date
christmas PlainDate(2024, 12, 25)   // Specific date
parsed PlainDate("2024-12-25")      // From ISO string
Str(christmas)                      // "2024-12-25"

`PlainDateTime`

fn (): PlainDateTime
fn (datetime: Str): PlainDateTime
fn (year: Int, month: Int, day: Int, hour: Int, minute: Int, second: Int): PlainDateTime

PlainDateTime type {
    year: Int,
    month: Int,
    day: Int,
    hour: Int,
    minute: Int,
    second: Int,
    millisecond: Int,
    microsecond: Int,
    nanosecond: Int,
    calendar: Str
}

A date and time without timezone. Based on Temporal.PlainDateTime.

Example

now PlainDateTime()                            // Current date/time
party PlainDateTime(2024, 12, 31, 23, 59, 0)   // New Year's Eve
parsed PlainDateTime("2024-12-31T23:59:00")    // From ISO string
Str(party)                                     // "2024-12-31T23:59:00"

`PlainTime`

fn (): PlainTime
fn (time: Str): PlainTime
fn (hour: Int, minute: Int, second: Int): PlainTime

PlainTime type {
    hour: Int,
    minute: Int,
    second: Int,
    millisecond: Int,
    microsecond: Int,
    nanosecond: Int
}

A wall-clock time without date or timezone. Based on Temporal.PlainTime.

Example

now PlainTime()                  // Current time
noon PlainTime(12, 0, 0)         // Specific time
parsed PlainTime("14:30:00")     // From ISO string
Str(noon)                        // "12:00:00"

`Second`

Second time unit. Wraps an Int value.

`Week`

Week time unit. Wraps an Int value.

`Year`

Year time unit. Wraps an Int value.

`ZonedDateTime`

fn (ixdtf: Str): ZonedDateTime
fn (instant: Instant, timezone: Str): ZonedDateTime
fn (plain-date-time: PlainDateTime, timezone: Str): ZonedDateTime

ZonedDateTime type {
    epochNanoseconds: Int,
    timezone: Str,
    offset: Str,
    year: Int,
    month: Int,
    day: Int,
    hour: Int,
    minute: Int,
    second: Int,
    millisecond: Int,
    microsecond: Int,
    nanosecond: Int,
    calendar: Str
}

A date and time with timezone. Based on Temporal.ZonedDateTime.

Represents an exact moment in time, projected into a specific timezone. Combines the exactness of Instant with the human-readable fields of PlainDateTime, aware of DST transitions and UTC offset changes.

Example

// From IXDTF string
zdt ZonedDateTime("2026-02-17T10:30:00-06:00[America/Chicago]")

// From Instant + timezone
zdt ZonedDateTime(::hot::time/now(), "America/Chicago")

// From PlainDateTime + timezone
zdt ZonedDateTime(PlainDateTime(2026, 3, 8, 2, 30, 0), "America/Chicago")

zdt.year       // 2026
zdt.hour       // 10
zdt.offset     // "-06:00"
zdt.timezone   // "America/Chicago"
Str(zdt)       // "2026-02-17T10:30:00-06:00[America/Chicago]"

::test ::type