| @@ -0,0 +1,336 @@ |
| 1 | +/// Time, as an effect (ADR 0036): timestamps, durations, UTC dates and |
| 2 | +/// RFC 3339. |
| 3 | +/// |
| 4 | +/// let t = time.now() // a Timestamp |
| 5 | +/// show(t) // "2026-10-13T09:30:00.250Z" |
| 6 | +/// time.parse("2026-10-13T11:30:00+02:00") // Ok(the same instant) |
| 7 | +/// |
| 8 | +/// `now` and `monotonic` read the `clock` effect. The runtime handles it |
| 9 | +/// around `main`, each test and each actor: `now_unix_ns` is the system's |
| 10 | +/// real-time clock; `monotonic_ns` is the scheduler's clock, which is |
| 11 | +/// virtual until the program opens a socket (ADR 0004, Revision 3), so a |
| 12 | +/// program without sockets measures what `process.sleep` waited, the same |
| 13 | +/// on every run. A test can fix the time instead: |
| 14 | +/// |
| 15 | +/// time.with_fixed_clock(time.from_unix_ns(0), fn() { time.now() }) |
| 16 | +/// |
| 17 | +/// A handler does not follow `process.spawn`: a new actor always gets the |
| 18 | +/// system's clock. UTC only: there are no time zones here. |
| 19 | + |
| 20 | +import std/bytes |
| 21 | +import std/list |
| 22 | +import std/string |
| 23 | + |
| 24 | +/// Clocks. |
| 25 | +pub effect clock { |
| 26 | + /// Nanoseconds since 1970-01-01T00:00:00Z (the system's clock: it can |
| 27 | + /// jump backwards when the system's time is set). |
| 28 | + fn now_unix_ns() -> Int |
| 29 | + /// Nanoseconds since an arbitrary origin, never going backwards: for |
| 30 | + /// measuring durations. |
| 31 | + fn monotonic_ns() -> Int |
| 32 | +} |
| 33 | + |
| 34 | +/// An instant: nanoseconds since 1970-01-01T00:00:00Z (before it when |
| 35 | +/// negative). Shown in RFC 3339. |
| 36 | +@derive(Eq, Ord, Hash) |
| 37 | +pub opaque type Timestamp { Timestamp(Int) } |
| 38 | + |
| 39 | +/// A span of time, in nanoseconds (negative when going back). |
| 40 | +@derive(Eq, Ord, Hash) |
| 41 | +pub opaque type Duration { Duration(Int) } |
| 42 | + |
| 43 | +/// The current time. |
| 44 | +pub fn now() -> Timestamp / <clock> { |
| 45 | + Timestamp(now_unix_ns()) |
| 46 | +} |
| 47 | + |
| 48 | +/// The time on the monotonic clock: compare two to measure a duration. |
| 49 | +pub fn monotonic() -> Duration / <clock> { |
| 50 | + Duration(monotonic_ns()) |
| 51 | +} |
| 52 | + |
| 53 | +/// The instant `ns` nanoseconds after the Unix epoch. |
| 54 | +pub fn from_unix_ns(ns: Int) -> Timestamp { |
| 55 | + Timestamp(ns) |
| 56 | +} |
| 57 | + |
| 58 | +/// The instant `ms` milliseconds after the Unix epoch. |
| 59 | +pub fn from_unix_ms(ms: Int) -> Timestamp { |
| 60 | + Timestamp(ms * 1000000) |
| 61 | +} |
| 62 | + |
| 63 | +/// Nanoseconds since the Unix epoch. |
| 64 | +pub fn unix_ns(t: Timestamp) -> Int { |
| 65 | + match t { Timestamp(ns) -> ns } |
| 66 | +} |
| 67 | + |
| 68 | +/// Milliseconds since the Unix epoch, rounded down. |
| 69 | +pub fn unix_ms(t: Timestamp) -> Int { |
| 70 | + floor_div(unix_ns(t), 1000000) |
| 71 | +} |
| 72 | + |
| 73 | +pub fn nanoseconds(n: Int) -> Duration { Duration(n) } |
| 74 | +pub fn milliseconds(n: Int) -> Duration { Duration(n * 1000000) } |
| 75 | +pub fn seconds(n: Int) -> Duration { Duration(n * 1000000000) } |
| 76 | +pub fn minutes(n: Int) -> Duration { Duration(n * 60000000000) } |
| 77 | + |
| 78 | +/// The duration in nanoseconds. |
| 79 | +pub fn in_nanoseconds(d: Duration) -> Int { |
| 80 | + match d { Duration(ns) -> ns } |
| 81 | +} |
| 82 | + |
| 83 | +/// The duration in milliseconds, rounded down. |
| 84 | +pub fn in_milliseconds(d: Duration) -> Int { |
| 85 | + floor_div(in_nanoseconds(d), 1000000) |
| 86 | +} |
| 87 | + |
| 88 | +/// `t` moved by `d`. |
| 89 | +pub fn add(t: Timestamp, d: Duration) -> Timestamp { |
| 90 | + Timestamp(unix_ns(t) + in_nanoseconds(d)) |
| 91 | +} |
| 92 | + |
| 93 | +/// The time from `earlier` to `later` (negative if `later` is before). |
| 94 | +pub fn since(later: Timestamp, earlier: Timestamp) -> Duration { |
| 95 | + Duration(unix_ns(later) - unix_ns(earlier)) |
| 96 | +} |
| 97 | + |
| 98 | +/// The time from monotonic reading `start` to `end`. |
| 99 | +pub fn elapsed(end: Duration, start: Duration) -> Duration { |
| 100 | + Duration(in_nanoseconds(end) - in_nanoseconds(start)) |
| 101 | +} |
| 102 | + |
| 103 | +/// Run `action` with `now()` always `at`, and `monotonic()` always 0. |
| 104 | +pub fn with_fixed_clock(at: Timestamp, action: fn() -> a / <clock | e>) -> a / <e> { |
| 105 | + handle { action() } with { |
| 106 | + now_unix_ns() -> unix_ns(at), |
| 107 | + monotonic_ns() -> 0, |
| 108 | + } |
| 109 | +} |
| 110 | + |
| 111 | +// ---- UTC calendar ------------------------------------------------------------------ |
| 112 | + |
| 113 | +/// A date and time in UTC. |
| 114 | +@derive(Eq, Debug) |
| 115 | +pub type DateTime { |
| 116 | + DateTime(year: Int, month: Int, day: Int, hour: Int, minute: Int, second: Int, nanosecond: Int) |
| 117 | +} |
| 118 | + |
| 119 | +/// `t`'s date and time in UTC. |
| 120 | +pub fn to_utc(t: Timestamp) -> DateTime { |
| 121 | + let ns = unix_ns(t) |
| 122 | + let days = floor_div(ns, 86400000000000) |
| 123 | + let in_day = ns - days * 86400000000000 |
| 124 | + let (year, month, day) = civil_from_days(days) |
| 125 | + let secs = in_day / 1000000000 |
| 126 | + DateTime(year, month, day, secs / 3600, secs / 60 % 60, secs % 60, in_day % 1000000000) |
| 127 | +} |
| 128 | + |
| 129 | +/// The instant of a UTC date and time; `None` if a field is out of range |
| 130 | +/// (February 30, hour 24, second 60...). |
| 131 | +pub fn from_utc(dt: DateTime) -> Option<Timestamp> { |
| 132 | + match dt { |
| 133 | + DateTime(y, mo, d, h, mi, s, ns) -> |
| 134 | + if mo < 1 || mo > 12 || d < 1 || d > days_in_month(y, mo) || h < 0 || h > 23 || mi < 0 || mi > 59 || s < 0 || s > 59 || ns < 0 || ns > 999999999 { |
| 135 | + None |
| 136 | + } else { |
| 137 | + Some(Timestamp(((days_from_civil(y, mo, d) * 24 + h) * 60 + mi) * 60000000000 + s * 1000000000 + ns)) |
| 138 | + }, |
| 139 | + } |
| 140 | +} |
| 141 | + |
| 142 | +/// Days since 1970-01-01 of a proleptic Gregorian date (Howard Hinnant's |
| 143 | +/// `days_from_civil`). |
| 144 | +fn days_from_civil(y0: Int, m: Int, d: Int) -> Int { |
| 145 | + let y = if m <= 2 { y0 - 1 } else { y0 } |
| 146 | + let era = floor_div(y, 400) |
| 147 | + let yoe = y - era * 400 |
| 148 | + let mp = if m > 2 { m - 3 } else { m + 9 } |
| 149 | + let doy = (153 * mp + 2) / 5 + d - 1 |
| 150 | + let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy |
| 151 | + era * 146097 + doe - 719468 |
| 152 | +} |
| 153 | + |
| 154 | +/// The date of a day number since 1970-01-01 (Hinnant's `civil_from_days`). |
| 155 | +fn civil_from_days(z0: Int) -> (Int, Int, Int) { |
| 156 | + let z = z0 + 719468 |
| 157 | + let era = floor_div(z, 146097) |
| 158 | + let doe = z - era * 146097 |
| 159 | + let yoe = (doe - doe / 1460 + doe / 36524 - doe / 146096) / 365 |
| 160 | + let doy = doe - (365 * yoe + yoe / 4 - yoe / 100) |
| 161 | + let mp = (5 * doy + 2) / 153 |
| 162 | + let d = doy - (153 * mp + 2) / 5 + 1 |
| 163 | + let m = if mp < 10 { mp + 3 } else { mp - 9 } |
| 164 | + let y = yoe + era * 400 |
| 165 | + (if m <= 2 { y + 1 } else { y }, m, d) |
| 166 | +} |
| 167 | + |
| 168 | +fn is_leap(y: Int) -> Bool { |
| 169 | + y % 4 == 0 && (y % 100 != 0 || y % 400 == 0) |
| 170 | +} |
| 171 | + |
| 172 | +fn days_in_month(y: Int, m: Int) -> Int { |
| 173 | + match m { |
| 174 | + 2 -> if is_leap(y) { 29 } else { 28 }, |
| 175 | + 4 | 6 | 9 | 11 -> 30, |
| 176 | + _ -> 31, |
| 177 | + } |
| 178 | +} |
| 179 | + |
| 180 | +/// `a / b` rounded towards minus infinity (`/` truncates), for `b > 0`. |
| 181 | +fn floor_div(a: Int, b: Int) -> Int { |
| 182 | + let q = a / b |
| 183 | + if a % b < 0 { q - 1 } else { q } |
| 184 | +} |
| 185 | + |
| 186 | +// ---- RFC 3339 ---------------------------------------------------------------------- |
| 187 | + |
| 188 | +/// `t` in RFC 3339, in UTC: `2026-10-13T09:30:00Z`, with 3, 6 or 9 |
| 189 | +/// fraction digits when they aren't zero. Years outside 0–9999 use the |
| 190 | +/// expanded form (`+10000-01-01T00:00:00Z`). |
| 191 | +pub fn format(t: Timestamp) -> String { |
| 192 | + match to_utc(t) { |
| 193 | + DateTime(y, mo, d, h, mi, s, ns) -> |
| 194 | + "{year(y)}-{pad(mo, 2)}-{pad(d, 2)}T{pad(h, 2)}:{pad(mi, 2)}:{pad(s, 2)}{fraction(ns)}Z", |
| 195 | + } |
| 196 | +} |
| 197 | + |
| 198 | +fn year(y: Int) -> String { |
| 199 | + if y >= 0 && y <= 9999 { |
| 200 | + pad(y, 4) |
| 201 | + } else if y < 0 { |
| 202 | + "-{pad(-y, 5)}" |
| 203 | + } else { |
| 204 | + "+{pad(y, 5)}" |
| 205 | + } |
| 206 | +} |
| 207 | + |
| 208 | +fn fraction(ns: Int) -> String { |
| 209 | + if ns == 0 { |
| 210 | + "" |
| 211 | + } else if ns % 1000000 == 0 { |
| 212 | + ".{pad(ns / 1000000, 3)}" |
| 213 | + } else if ns % 1000 == 0 { |
| 214 | + ".{pad(ns / 1000, 6)}" |
| 215 | + } else { |
| 216 | + ".{pad(ns, 9)}" |
| 217 | + } |
| 218 | +} |
| 219 | + |
| 220 | +/// `n` (not negative) with zeros in front, to `width` digits at least. |
| 221 | +fn pad(n: Int, width: Int) -> String { |
| 222 | + let digits = show(n) |
| 223 | + "{string.repeat("0", width - string.length(digits))}{digits}" |
| 224 | +} |
| 225 | + |
| 226 | +/// An RFC 3339 date and time, converted to UTC: `2026-10-13T11:30:00+02:00`. |
| 227 | +/// Accepts `T`, `t` or a space between date and time, 1 to 9 fraction |
| 228 | +/// digits (more are cut), and `Z`, `z` or `±HH:MM`. Years have 4 digits; |
| 229 | +/// a leap second (`:60`) is refused. |
| 230 | +pub fn parse(text: String) -> Result<Timestamp, String> { |
| 231 | + let b = bytes.from_string(text) |
| 232 | + let fail = Error("not an RFC 3339 date and time: {text:?}") |
| 233 | + match (digits(b, 0, 4), digits(b, 5, 2), digits(b, 8, 2), digits(b, 11, 2), digits(b, 14, 2), digits(b, 17, 2)) { |
| 234 | + (Some(y), Some(mo), Some(d), Some(h), Some(mi), Some(s)) -> |
| 235 | + if !(at(b, 4, "-") && at(b, 7, "-") && (at(b, 10, "T") || at(b, 10, "t") || at(b, 10, " ")) && at(b, 13, ":") && at(b, 16, ":")) { |
| 236 | + fail |
| 237 | + } else { |
| 238 | + let (ns, i) = fraction_at(b, 19) |
| 239 | + match (offset_at(b, i), from_utc(DateTime(y, mo, d, h, mi, s, ns))) { |
| 240 | + (Some(off), Some(t)) -> Ok(add(t, minutes(-off))), |
| 241 | + _ -> fail, |
| 242 | + } |
| 243 | + }, |
| 244 | + _ -> fail, |
| 245 | + } |
| 246 | +} |
| 247 | + |
| 248 | +/// The `n`-digit number at byte `i`, if there is one. |
| 249 | +fn digits(b: Bytes, i: Int, n: Int) -> Option<Int> { |
| 250 | + digits_from(b, i, n, 0) |
| 251 | +} |
| 252 | + |
| 253 | +fn digits_from(b: Bytes, i: Int, n: Int, acc: Int) -> Option<Int> { |
| 254 | + if n == 0 { |
| 255 | + Some(acc) |
| 256 | + } else { |
| 257 | + match bytes.get(b, i) { |
| 258 | + Some(c) if c >= 48 && c <= 57 -> digits_from(b, i + 1, n - 1, acc * 10 + c - 48), |
| 259 | + _ -> None, |
| 260 | + } |
| 261 | + } |
| 262 | +} |
| 263 | + |
| 264 | +/// Whether byte `i` is `c` (one ASCII character). |
| 265 | +fn at(b: Bytes, i: Int, c: String) -> Bool { |
| 266 | + bytes.get(b, i) == bytes.get(bytes.from_string(c), 0) |
| 267 | +} |
| 268 | + |
| 269 | +/// A fraction `.ddd` at byte `i`: nanoseconds, and where it ends. |
| 270 | +fn fraction_at(b: Bytes, i: Int) -> (Int, Int) { |
| 271 | + if at(b, i, ".") { |
| 272 | + fraction_digits(b, i + 1, 0, 0) |
| 273 | + } else { |
| 274 | + (0, i) |
| 275 | + } |
| 276 | +} |
| 277 | + |
| 278 | +fn fraction_digits(b: Bytes, i: Int, n: Int, acc: Int) -> (Int, Int) { |
| 279 | + match bytes.get(b, i) { |
| 280 | + Some(c) if c >= 48 && c <= 57 -> |
| 281 | + if n < 9 { |
| 282 | + fraction_digits(b, i + 1, n + 1, acc * 10 + c - 48) |
| 283 | + } else { |
| 284 | + fraction_digits(b, i + 1, n, acc) |
| 285 | + }, |
| 286 | + _ -> (acc * power10(9 - n), if n == 0 { i - 1 } else { i }), |
| 287 | + } |
| 288 | +} |
| 289 | + |
| 290 | +fn power10(n: Int) -> Int { |
| 291 | + if n == 0 { 1 } else { 10 * power10(n - 1) } |
| 292 | +} |
| 293 | + |
| 294 | +/// The offset at byte `i`, in minutes east of UTC, if the text ends with |
| 295 | +/// it. |
| 296 | +fn offset_at(b: Bytes, i: Int) -> Option<Int> { |
| 297 | + if (at(b, i, "Z") || at(b, i, "z")) && bytes.length(b) == i + 1 { |
| 298 | + Some(0) |
| 299 | + } else if (at(b, i, "+") || at(b, i, "-")) && at(b, i + 3, ":") && bytes.length(b) == i + 6 { |
| 300 | + match (digits(b, i + 1, 2), digits(b, i + 4, 2)) { |
| 301 | + (Some(h), Some(m)) if h <= 23 && m <= 59 -> Some(if at(b, i, "-") { -(h * 60 + m) } else { h * 60 + m }), |
| 302 | + _ -> None, |
| 303 | + } |
| 304 | + } else { |
| 305 | + None |
| 306 | + } |
| 307 | +} |
| 308 | + |
| 309 | +impl Show<Timestamp> { |
| 310 | + fn show(t) { format(t) } |
| 311 | +} |
| 312 | + |
| 313 | +impl Debug<Timestamp> { |
| 314 | + fn debug(t) { "time.Timestamp({format(t)})" } |
| 315 | +} |
| 316 | + |
| 317 | +/// In the largest unit that keeps it exact: `2s`, `1500ms`, `3us`, |
| 318 | +/// `7ns`. |
| 319 | +impl Show<Duration> { |
| 320 | + fn show(d) { |
| 321 | + let ns = in_nanoseconds(d) |
| 322 | + if ns % 1000000000 == 0 { |
| 323 | + "{ns / 1000000000}s" |
| 324 | + } else if ns % 1000000 == 0 { |
| 325 | + "{ns / 1000000}ms" |
| 326 | + } else if ns % 1000 == 0 { |
| 327 | + "{ns / 1000}us" |
| 328 | + } else { |
| 329 | + "{ns}ns" |
| 330 | + } |
| 331 | + } |
| 332 | +} |
| 333 | + |
| 334 | +impl Debug<Duration> { |
| 335 | + fn debug(d) { "time.Duration({show(d)})" } |
| 336 | +} |