notes

4.8 KB

1. # `hl:time` — the clock, timers, and time zones
3. Both realms. The native plugin is `time.zig` (`libtime.so`); the JavaScript
4. target and the browser run `server.js`. `server.hl` documents every call, and
5. `projects/homepage/docs/time.md` is generated from it.
7. | call | answers |
8. |---|---|
9. | `now()` | epoch milliseconds (UTC) |
10. | `timestamp(ms?)` | `"YYYY-MM-DDTHH:MM:SS.mmmZ"` |
11. | `monotonic()` | nanoseconds off a monotonic counter |
12. | `every(s)` / `after(s)` / `until(ms)` / `sleep(s)` | timers, see `server.hl` |
13. | `offset(ms, zone)` | the zone's offset at that instant, seconds east of UTC |
14. | `local(ms, zone)` | the wall-clock reading in the zone |
15. | `fromLocal(fields, zone)` | the instant a wall-clock reading names, epoch ms |
16. | `localTimestamp(ms, zone)` | `"YYYY-MM-DDTHH:MM:SS.mmm+HH:MM"` in the zone |
17. | `isZone(name)` | whether the zone database knows the name |
19. ## Time zones
21. Ticket #5; the creator's ruling on ident.worldapi.org#14 was "hybriel needs
22. time zone support".
24. ```hybriel
25. import { now, local, fromLocal, localTimestamp, offset, isZone } from 'hl:time'
27. localTimestamp(now(), 'Europe/Vienna') \\ "2026-09-26T14:05:00.000+02:00"
28. offset(now(), 'America/New_York') \\ -14400
29. t = local(now(), 'Australia/Lord_Howe') \\ { year, month, day, hour, … }
30. fromLocal({ year = 2026; month = 12; day = 24; hour = 18; }, 'Europe/Vienna')
31. isZone('Europe/Vienna') \\ true
32. ```
34. **A zone is an IANA name** such as `Europe/Vienna` or `UTC`, spelled exactly
35. as the database spells it, case included. There is no "local zone of the
36. server": pass the zone you mean.
38. **An instant is epoch milliseconds**, what `now()` answers. Every offset is in
39. **seconds east of UTC**, the same unit as every other duration in this package:
40. Vienna in summer is `7200`, New York in winter `-18000`, India `19800`.
42. **`local(ms, zone)`** answers `{ year, month, day, hour, minute, second,
43. millisecond, weekday, offset }`. `month` is 1–12, `weekday` is ISO: 1 is Monday
44. and 7 is Sunday. The calendar is the proleptic Gregorian one, for every year.
46. **`fromLocal(fields, zone)`** takes the same field names back. `year` is
47. required, `month` and `day` default to 1, the rest to 0. A field outside its
48. range carries over, so `month = 13` is January of the next year. The result
49. of `local()` is valid input. A wall-clock reading does not always name exactly
50. one instant, and these are the rules:
52. - **In a fold**, the hour a fall-back repeats, the reading names two instants.
53. `fromLocal` answers the **earlier** one. Vienna's 02:30 on 25 October 2026 is
54. `02:30+02:00`, not `02:30+01:00`.
55. - **In a gap**, the hour a spring-forward skips, the reading names no instant.
56. `fromLocal` moves it **forward by the gap's length**. Vienna's 02:30 on
57. 29 March 2026 is `03:30+02:00`.
59. These are the rules of Temporal's `"compatible"` disambiguation.
61. **`localTimestamp(ms, zone)`** is ISO-8601 with the offset in force, e.g.
62. `2026-03-29T03:00:00.000+02:00`. UTC renders as `+00:00`, not `Z`. Before a
63. zone's first rule its local mean time has an offset in seconds, and the
64. offset then carries them: `+01:05:21`. Years outside 0–9999 use ISO's
65. expanded form, e.g. `-000001` or `+010000`.
67. **`isZone(name)`** is the question to ask before trusting input. The other
68. four raise an error for a zone the database does not know, for example
69. `hl:time: unknown time zone 'Mars/Olympus_Mons'`. They never fall back to UTC.
70. Offsets such as `+01:00` are not zone names, and neither are `posix/…`,
71. `right/…`, `localtime`, `posixrules` or `Factory`.
73. The supported instants are the range of an ECMAScript Date, ±8.64e15 ms.
75. ### Where the zone data comes from
77. - **Native**: the system's tz database, the TZif files under
78. `/usr/share/zoneinfo` (RFC 8536), read directly with no library. The
79. footer's POSIX TZ rule answers for instants after the last stored
80. transition. A zone is parsed once per process.
81. - **Browser and Node**: `Intl.DateTimeFormat`, which carries its own copy of the
82. same database.
84. Only the offset comes from the zone data. `local`, `fromLocal` and
85. `localTimestamp` are the same arithmetic in `time.zig` and `server.js`, so
86. the realms can differ only where their copies of the database differ: a
87. country that changes its rules shows up in each realm once that realm's copy
88. is updated. The gates are `tests/pass/plugins/038_time_zones.hl` (native and
89. Node) and `plugins/time/tests/browser.mjs` (headless Chrome, same expected
90. file). They cover the DST edges of Europe/Vienna, America/New_York and
91. Australia/Lord_Howe (a 30-minute DST), and the historic changes of Austria's
92. 1980 DST, the US rules of 2007, Samoa's skipped 30 December 2011 and Brazil's
93. 2019 end of DST.
95. Out of scope: calendar arithmetic ("add a month"), free-form or localised
96. formatting, and zone abbreviations. Intl and TZif disagree on abbreviations
97. ("GMT+1" against "CET"), so the two realms could not give the same answer.