Skip to content
Weaverv0.5.0

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 UTC
val 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}"))
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 Timestamp has no time zone: "${t}" writes it in UTC, 2025-03-28T09:12:44Z.
  • Monotonic never 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 Duration is added to an instant, a Period to 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, unless overflow: .reject says otherwise.
  • until(other) gives the Period between two dates; weekday(), isLeapYear(), lengthOfMonth().
  • LocalDate.today(in: zone): today depends on where.

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.

  • "${x}" writes ISO 8601, which X.parse(text) reads back: 2025-03-30T10:00:00+02:00[Europe/Paris] for a Zoned.
  • x.format(fmt"…") writes any other form, and X.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.
  • Duration writes 2h0m0s and reads it back, iso() gives PT2H; Period writes P1Y2M3D.

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 an await waits for: sleep(2.seconds()).await.
  • withTimeout(d, () => work()) fails with Timeout past d, cancelling the work.
  • await any(rx.receiving(), sleep(d)) waits for a message at most d.