time

time

Dates, times and durations are literals, as ISO 8601 writes them:

d = 2024-01-31
d + 1 day             # 2024-02-01

now is the clock when the program runs. A date, a local time (10:30), an instant (2024-06-01T12:00Z) and a zoned time (2024-01-31T10:00[Europe/Berlin]) are kinds of time; fields read them: d.year, d.weekday, now.hour. A field a kind lacks is an error: date has no hour. An instant's fields are the local wall clock of the machine it runs on. type names the kind: type(now) is instant, type(1 day) is duration. Each kind is a type under time: now is instant and now is time are true, 2024-06-01 is date is true, type(now) == time is false (== is the exact type).

Durations

1 day, 2 hours, 1 month 2 days are durations. They add to times and to each other and multiply by whole numbers; two times of one kind subtract to a duration, two dates to their days apart:

2024-03-10 - 2024-03-01   # 9
2 hours * 3               # 6 hours
1 day in h                # 24h
d = 1 day; d in h         # 24h, a variable too
1 day as h                # 24h, `as` converts too

Durations compare when the answer holds on every date, as a day is 23 to 25 hours across daylight saving and a month 28 to 31 days:

1 day > 2 hours           # yes
1 month > 27 days         # yes
1 day < 24 hours          # error: they compare differently on different dates

A month is added first, then days, then the rest. A day the month lacks is an error naming the fix: 2024-01-31 + 1 month says "2024-02-31 does not exist: use add(…, overflow: clamp) for 2024-02-29".

Time zones

in places an instant in a zone; the offset follows the zone's summer rules:

t = 2024-06-01T12:00Z
t in "Europe/Berlin"      # 2024-06-01T14:00+02:00[Europe/Berlin]

A wall-clock time that a clock change skips or repeats is an error unless you choose: zoned(2024-03-31T02:30, "Europe/Berlin", disambiguation: later) is 03:30+02:00. z.offset is the seconds east of UTC.