Dates, times and time zones
Module weaver.time: its API, wv doc weaver.time.
weaver.time keeps apart what is easily mixed up: an instant on the time
line, a date as a calendar shows it, and the time zone that links one to
the other. Each is an immutable value of its own type, and none turns into
another unless it is written.
import weaver.time.{Timestamp, TimeZone, Period, Monotonic, hours, date, time, fmt}
val now = Timestamp.now() // an instant, written in UTCval paris = TimeZone.named("Europe/Paris")!val meeting = date"2025-03-30".at(time"10:00").in(paris, resolve: .compatible)val sameTimeNextWeek = meeting.plus(Period(days: 7), resolve: .compatible)val exactlyADayLater = meeting + 24.hours()print(meeting.format(fmt"{day:02}/{month:02}/{year} at {hour}h{minute:02}"))Which type
Section titled “Which type”| To say | Use |
|---|---|
| when something happened, a log line, a file’s date | Timestamp |
| how long something took | Monotonic.now(), then elapsed() |
| an exact length, a timeout | Duration: 250.millis(), 5.seconds(), 2.hours() |
| a birthday, a due date, opening hours | LocalDate, LocalTime, LocalDateTime |
| “in a month”, “every week” | Period: Period(months: 1), Period(weeks: 2) |
| a meeting somewhere, a time to show a user | Zoned, a Timestamp in a TimeZone |
- A
Timestamphas no time zone:"${t}"writes it in UTC,2025-03-28T09:12:44Z. Monotonicnever goes back when the clock is set; it does not tell the time, only differences of it.- A local date has no time zone either, by design: a birthday changes for
no one. It meets one only through
.in(zone). - A
Durationis added to an instant, aPeriodto a date: “in 30 days” and “in a month” are two computations, and the type says which.
date"2025-03-30", time"14:30" and datetime"2025-03-30T10:00" are
checked when the program compiles; LocalDate.from(year:, month:, day:)
returns None for a date that does not exist.
plusDays(n),plus(Period(…)): a month after January 31st is February’s last day, unlessoverflow: .rejectsays otherwise.until(other)gives thePeriodbetween two dates;weekday(),isLeapYear(),lengthOfMonth().LocalDate.today(in: zone): today depends on where.
Time zones
Section titled “Time zones”TimeZone.utc, TimeZone.fixed(hours: 5, minutes: 30),
TimeZone.named("Europe/Paris"), from the system’s database, and
TimeZone.local(), the machine’s ($TZ).
Placing a wall-clock time in a zone can fail: on the night clocks go
forward, 02:30 does not exist; on the night they go back, it happens
twice. .in(zone) then returns an error saying which, and resolve:
decides beforehand:
.compatible: a missing time moves forward by the gap, a repeated one takes the earlier; what most calendars do..earlier,.later: one of the two instants.
Without resolve:, the error comes back, to ask the user; its pick(.later)
chooses afterwards.
z + 24.hours() is exactly 24 hours later, perhaps another wall-clock
time; z.plus(Period(days: 1)) is the same wall-clock time the next day,
whether that day has 23 hours or 25.
Writing and reading
Section titled “Writing and reading”"${x}"writes ISO 8601, whichX.parse(text)reads back:2025-03-30T10:00:00+02:00[Europe/Paris]for aZoned.x.format(fmt"…")writes any other form, andX.parse(text, fmt"…")reads it:{day:02}/{month:02}/{year},{weekday}, {month:long} {day},{hour}h{minute:02},{offset},{zone}. A format is checked when the program compiles: a field the type does not have is an error there.Durationwrites2h0m0sand reads it back,iso()givesPT2H;PeriodwritesP1Y2M3D.
Clocks, sleeping and timeouts
Section titled “Clocks, sleeping and timeouts”Timestamp.now(), Monotonic.now() and TimeZone.local() read the clock
of the task, a task val, the system’s by default. A test binds another:
val fixed = FixedClock(Timestamp.fromUnix(1_700_000_000), zone: "+09:00")clock.bind(fixed, () => run())FixedClock always gives the same instant; ManualClock moves only when
told, advance(5.minutes()), which wakes the sleepers it passes.
sleep(d)gives what anawaitwaits for:sleep(2.seconds()).await.withTimeout(d, () => work())fails withTimeoutpast d, cancelling the work.await any(rx.receiving(), sleep(d))waits for a message at most d.