Debian Codegraph @

time/date/date.ha

raw
1 // SPDX-License-Identifier: MPL-2.0
2 // (c) Hare authors <https://harelang.org>
3
4 use time;
5 use time::chrono;
6
7 // Invalid [[date]].
8 export type invalid = !void;
9
10 // A "datetime" object, optimized for the Gregorian chronology. All instantiated
11 // dates are valid, pertain to a [[locality]], and directly convertible to a
12 // [[time::chrono::moment]] or [[time::instant]].
13 //
14 // A date observes various chronological values, which are cached in its
15 // "observer" fields. To evaluate and obtain these values, use the various
16 // observer functions, documented inline.
17 //
18 // Unless interfaced via a [[virtual]], dates should be treated as immutable.
19 // Mutating or interrogating fields directly results in undefined behaviour.
20 export type date = struct {
21 chrono::moment,
22 // The [[locality]] with which to interpret this date.
23 loc: locality,
24 // The observed [[zonephase]]. Observe with [[zone]].
25 zonephase: nullable *zonephase,
26 // The observed [[daydate]] (scalar day number)
27 // since an abitrary epoch (e.g. the Unix epoch 1970-01-01).
28 daydate: (void | i64),
29 // The observed [[daytime]] (amount of daytime progressed in a day),
30 // assessed as a [[time::duration]].
31 daytime: (void | i64),
32 // The observed [[era]].
33 era: (void | int),
34 // The observed [[year]].
35 year: (void | int),
36 // The observed [[month]].
37 month: (void | int),
38 // The observed [[day]].
39 day: (void | int),
40 // The observed [[yearday]].
41 yearday: (void | int),
42 // The observed [[isoweekyear]].
43 isoweekyear: (void | int),
44 // The observed [[isoweek]].
45 isoweek: (void | int),
46 // The observed [[week]].
47 week: (void | int),
48 // The observed [[sundayweek]].
49 sundayweek: (void | int),
50 // The observed [[weekday]].
51 weekday: (void | int),
52 // The observed [[hour]].
53 hour: (void | int),
54 // The observed [[minute]].
55 minute: (void | int),
56 // The observed [[second]].
57 second: (void | int),
58 // The observed [[nanosecond]].
59 nanosecond: (void | int),
60 };
61
62 fn init() date = date {
63 sec = 0,
64 nsec = 0,
65 tsc = &chrono::utc,
66 loc = UTC,
67 zonephase = null,
68 daydate = void,
69 daytime = void,
70
71 era = void,
72 year = void,
73 month = void,
74 day = void,
75 yearday = void,
76 isoweekyear = void,
77 isoweek = void,
78 week = void,
79 sundayweek = void,
80 weekday = void,
81
82 hour = void,
83 minute = void,
84 second = void,
85 nanosecond = void,
86 };
87
88 // Evaluates and populates all of a [[date]]'s fields.
89 fn all(d: *date) *date = {
90 _era(d);
91 _year(d);
92 _month(d);
93 _day(d);
94 _yearday(d);
95 _isoweekyear(d);
96 _isoweek(d);
97 _week(d);
98 _sundayweek(d);
99 _weekday(d);
100
101 _hour(d);
102 _minute(d);
103 _second(d);
104 _nanosecond(d);
105
106 return d;
107 };
108
109 // Creates a new [[date]]. Accepts a [[locality]], a zone-offset, and up to
110 // seven chronological fields applied in the following order:
111 //
112 // - year
113 // - month
114 // - day
115 // - hour
116 // - minute
117 // - second
118 // - nanosecond
119 //
120 // 8 or more fields causes an abort. If omitted, the month and day default to 1,
121 // and the rest default to 0.
122 //
123 // If the desired zone-offset is known, it can be given as a [[time::duration]].
124 // Otherwise, use a zflag. See [[zflag]] on its effects to the result.
125 //
126 // An invalid combination of provided date/time/zoff values returns [[invalid]].
127 //
128 // Examples:
129 //
130 // // 0000-01-01 00:00:00.000000000 +0000 UTC UTC
131 // date::new(date::UTC, date::zflag::CONTIG);
132 //
133 // // 2000-01-02 15:04:05.600000000 +0000 UTC UTC
134 // date::new(date::UTC, 0,
135 // 2000, 1, 2, 15, 4, 5, 600000000);
136 //
137 // // 2000-01-02 15:00:00.000000000 +0100 CET Europe/Amsterdam
138 // date::new(date::tzdb("Europe/Amsterdam")!,
139 // 1 * time::HOUR, // standard time in January
140 // 2000, 1, 2, 15);
141 //
142 // // Could return [[zfunresolved]] by encountering a timezone transition.
143 // date::new(date::tzdb("Europe/Amsterdam")!,
144 // date::zflag::CONTIG,
145 // fields...);
146 //
147 // // Will never return [[zfunresolved]].
148 // date::new(date::tzdb("Europe/Amsterdam")!,
149 // date::zflag::LAP_EARLY | date::zflag::GAP_END,
150 // fields...);
151 //
152 // // On this day in Amsterdam, the clock jumped +1 hour at 02:00.
153 // // 02:30 is never observed. Note the difference in zone-offset.
154 // //
155 // // 2000-03-26 01:59:59.999999999 +0100 CET Europe/Amsterdam
156 // date::new(date::tzdb("Europe/Amsterdam")!,
157 // date::zflag::GAP_START,
158 // 2000, 3, 26, 2, 30);
159 // //
160 // // 2000-03-26 03:00:00.000000000 +0200 CET Europe/Amsterdam
161 // date::new(date::tzdb("Europe/Amsterdam")!,
162 // date::zflag::GAP_END,
163 // 2000, 3, 26, 2, 30);
164 //
165 // // On this day in Amsterdam, the clock jumped -1 hour at 03:00.
166 // // 02:30 is observed twice. Note the difference in zone-offset.
167 // //
168 // // 2000-10-29 02:30:00.000000000 +0200 CET Europe/Amsterdam
169 // date::new(date::tzdb("Europe/Amsterdam")!,
170 // date::zflag::LAP_EARLY,
171 // 2000, 10, 29, 2, 30);
172 // //
173 // // 2000-10-29 02:30:00.000000000 +0100 CET Europe/Amsterdam
174 // date::new(date::tzdb("Europe/Amsterdam")!,
175 // date::zflag::LAP_LATE,
176 // 2000, 10, 29, 2, 30);
177 //
178 export fn new(
179 loc: locality,
180 zoff: (time::duration | zflag),
181 fields: int...
182 ) (date | invalid | zfunresolved) = {
183 let _fields: [_]int = [
184 0, 1, 1, // year month day
185 0, 0, 0, 0, // hour minute second nanosecond
186 ];
187
188 assert(len(fields) <= len(_fields),
189 "time::date::new(): Too many field arguments");
190 _fields[..len(fields)] = fields;
191
192 let v = newvirtual();
193
194 v.vloc = loc;
195 v.zoff = zoff;
196 v.year = _fields[0];
197 v.month = _fields[1];
198 v.day = _fields[2];
199 v.hour = _fields[3];
200 v.minute = _fields[4];
201 v.second = _fields[5];
202 v.nanosecond = _fields[6];
203
204 let d = (realize(v, loc) as (date | invalid | zfunresolved))?;
205
206 let gap_flag_specified = (
207 zoff is zflag
208 && zoff as zflag & (zflag::GAP_START | zflag::GAP_END) != 0
209 );
210
211 // Some invalid inputs could theoretically calculate a valid date.
212 // zflags GAP_START and GAP_END may cause the resultant date to change.
213 // unless "GAP_" flags were specified, check if input values match the
214 // resultant date's values.
215 if (!gap_flag_specified) {
216 if (
217 _fields[0] != _year(&d)
218 || _fields[1] != _month(&d)
219 || _fields[2] != _day(&d)
220 || _fields[3] != _hour(&d)
221 || _fields[4] != _minute(&d)
222 || _fields[5] != _second(&d)
223 || _fields[6] != _nanosecond(&d)
224 ) {
225 return invalid;
226 };
227 };
228
229 return d;
230 };
231
232 // Returns a [[date]] of the current system time using
233 // [[time::clock::REALTIME]], in the [[UTC]] locality.
234 export fn now() date = {
235 return from_instant(UTC, time::now(time::clock::REALTIME));
236 };
237
238 // Returns a [[date]] of the current system time using
239 // [[time::clock::REALTIME]], in the [[LOCAL]] locality.
240 export fn localnow() date = {
241 return from_instant(LOCAL, time::now(time::clock::REALTIME));
242 };
243
244 // Creates a [[date]] from a [[time::chrono::moment]].
245 //
246 // [[time::chrono::tscmismatch]] is returned if the [[time::chrono::timescale]]s
247 // of the moment and the target [[locality]] are different.
248 export fn from_moment(loc: locality, m: chrono::moment) (date | chrono::tscmismatch) = {
249 if (loc.tsc != m.tsc) {
250 return (loc.tsc, m.tsc): chrono::tscmismatch;
251 };
252
253 const d = init();
254 d.sec = m.sec;
255 d.nsec = m.nsec;
256 d.tsc = m.tsc;
257 d.loc = loc;
258 return d;
259 };
260
261 // Creates a [[date]] from a [[time::instant]] in a [[locality]].
262 export fn from_instant(loc: locality, t: time::instant) date = {
263 return from_moment(loc, chrono::new(loc.tsc, t))!;
264 };
265
266 // Creates a [[date]] from a given [[locality]], zone-offset, daydate, and
267 // time-of-day.
268 export fn from_datetime(
269 loc: locality,
270 zo: time::duration,
271 dd: i64,
272 dt: i64,
273 ) date = {
274 return from_instant(loc, calc_instant(loc.daylength, zo, dd, dt));
275 };
276
277 // Creates a [[date]] from a string, parsed according to a layout format.
278 // See [[parse]] and [[format]]. Example:
279 //
280 // let new = date::from_str(
281 // date::STAMPLOC,
282 // "2000-01-02 15:04:05.600000000 +0100 CET Europe/Amsterdam",
283 // chrono::tz("Europe/Amsterdam")!
284 // )!;
285 //
286 // At least a complete calendar date has to be provided. If the hour, minute,
287 // second, or nanosecond values are not provided, they default to 0.
288 // If the zone-offset or zone-abbreviation are not provided, the [[zflag]]s
289 // LAP_EARLY and GAP_END are used.
290 //
291 // The date's [[locality]] will be selected from the provided locality
292 // arguments. The 'name' field of these localities will be matched against the
293 // parsed result of the %L specifier. If %L is not specified, or if no locality
294 // is provided, [[UTC]] is used.
295 export fn from_str(
296 layout: str,
297 s: str,
298 locs: locality...
299 ) (date | parsefail | insufficient | invalid) = {
300 // TODO: consider having defaults for year, month, day.
301 const v = newvirtual();
302 v.zoff = zflag::LAP_EARLY | zflag::GAP_END;
303 v.hour = 0;
304 v.minute = 0;
305 v.second = 0;
306 v.nanosecond = 0;
307
308 parse(&v, layout, s)?;
309
310 if (v.locname is void || len(locs) == 0) {
311 v.vloc = UTC;
312 };
313
314 return realize(v, locs...) as (date | insufficient | invalid);
315 };
316
317 // Extracts the [[time::chrono::moment]] of the given [[date]].
318 export fn to_moment(d: date) chrono::moment = *(&d: *chrono::moment);
319
320 // Extracts the [[time::instant]] of the given [[date]].
321 export fn to_instant(d: date) time::instant = *(&d: *time::instant);
322
323 // Returns true if two [[date]]s represent the same time in the same locality,
324 // which is to say that their [[locality]] and [[time::instant]] are both equal.
325 // Their observed chronological values should be the same in all cases.
326 //
327 // See [[time::chrono::compare]].
328 export fn coincident(a: *date, b: *date) bool = {
329 return a.loc == b.loc && a.sec == b.sec && a.nsec == b.nsec;
330 };
331
332 // Calculates the observed daydate and time-of-day of a [[time::instant]] in a
333 // [[locality]] at a particular zone-offset.
334 fn calc_datetime(
335 loc: locality,
336 t: time::instant,
337 zoff: time::duration,
338 ) (i64, time::duration) = {
339 const t = time::add(t, zoff);
340 const day = loc.daylength;
341 const daysec = day / time::SECOND;
342 const dd = if (t.sec >= 0) t.sec / daysec else (t.sec + 1) / daysec - 1;
343 const dt = ((t.sec % daysec + daysec) * time::SECOND + t.nsec) % day;
344 return (dd, dt);
345 };
346
347 fn calc_instant(
348 day: time::duration, // length of a day
349 zo: time::duration, // zone-offset
350 dd: i64, // date since epoch
351 dt: i64, // time since start of day (ns)
352 ) time::instant = {
353 const daysec = (day / time::SECOND): i64;
354 const dayrem = day % time::SECOND;
355 let t = time::instant {
356 sec = dd * daysec,
357 nsec = 0,
358 };
359 t = time::add(t, dd * dayrem);
360 t = time::add(t, dt);
361 t = time::add(t, -zo);
362 return t;
363 };
364
365 @test fn from_str() void = {
366 let testcases: [_](str, str, []locality, (date | error)) = [
367 (STAMPLOC, "2001-02-03 15:16:17.123456789 +0000 UTC UTC", [],
368 new(UTC, 0, 2001, 2, 3, 15, 16, 17, 123456789)!),
369 (STAMP, "2001-02-03 15:16:17", [],
370 new(UTC, 0, 2001, 2, 3, 15, 16, 17)!),
371 (RFC3339, "2001-02-03T15:16:17+0000", [],
372 new(UTC, 0, 2001, 2, 3, 15, 16, 17)!),
373 ("%F", "2009-06-30", [],
374 new(UTC, 0, 2009, 6, 30)!),
375 ("%F %L", "2009-06-30 GPS", [TAI, GPS],
376 new(GPS, 0, 2009, 6, 30)!),
377 ("%F %T", "2009-06-30 01:02:03", [],
378 new(UTC, 0, 2009, 6, 30, 1, 2, 3)!),
379 ("%FT%T%z", "2009-06-30T18:30:00Z", [],
380 new(UTC, 0, 2009, 6, 30, 18, 30)!),
381 ("%FT%T.%N%z", "2009-06-30T18:30:00.987654321Z", [],
382 new(UTC, 0, 2009, 6, 30, 18, 30, 0, 987654321)!),
383 // TODO: for the tests overhaul, when internal test timezones
384 // are available, check for %L
385 //("%FT%T%z %L", "2009-06-30T18:30:00+0200 Europe/Amsterdam", [amst],
386 // new(amst, 2 * time::HOUR, 2009, 6, 30, 18, 30)!),
387
388 ("%Y", "a", [], (0z, 'a'): parsefail),
389 ("%X", "2008", [], (0z, '2'): parsefail),
390 ];
391
392 let buf: [64]u8 = [0...];
393 for (let tc .. testcases) {
394 const expect = tc.3;
395 const actual = from_str(tc.0, tc.1, tc.2...);
396
397 match (expect) {
398 case let e: date =>
399 assert(actual is date, "wanted 'date', got 'error'");
400 assert(chrono::compare(&(actual as date), &e)! == 0,
401 "incorrect 'date' value");
402 case let e: parsefail =>
403 assert(actual is parsefail,
404 "wanted 'parsefail', got other");
405 case insufficient =>
406 assert(actual is insufficient,
407 "wanted 'insufficient', got other");
408 case invalid =>
409 assert(actual is invalid,
410 "wanted 'invalid', got other");
411 };
412 };
413 };