hare

The Hare programming language
git clone https://git.torresjrjr.com/hare.git
Log | Files | Refs | README | LICENSE

commit b84158453d6b3015641fb9647b16626127e6f972
parent bb31979d91647ecf8b125b5644acbf5bd12058ee
Author: Byron Torres <b@torresjrjr.com>
Date:   Sat, 12 Mar 2022 16:27:24 +0000

brush up comments and code for review

Signed-off-by: Byron Torres <b@torresjrjr.com>

Diffstat:
Mdatetime/arithmetic.ha | 17+++++++++--------
Mdatetime/datetime.ha | 13+++++++------
Mdatetime/format.ha | 2+-
Mdatetime/time.ha | 2++
Mtime/arithm.ha | 2+-
Mtime/chrono/README | 7++++++-
Mtime/chrono/leapsec.ha | 46+++++++++++++++++++---------------------------
Mtime/chrono/timescale.ha | 6++++++
8 files changed, 51 insertions(+), 44 deletions(-)

diff --git a/datetime/arithmetic.ha b/datetime/arithmetic.ha @@ -2,14 +2,6 @@ use fmt; use time::chrono; use time; -fn absi(n: i64) i64 = { - if (n < 0) { - return -n; - } else { - return n; - }; -}; - // Represents a span of time in the proleptic Gregorian calendar, // using relative units of time. Used for calendar arithmetic. export type period = struct { @@ -419,6 +411,15 @@ export fn subtract(dt: datetime, flag: calculus, pp: period...) datetime = { return add(dt, flag, pp...); }; +// Copied from math:: to avoid dependancy. +fn absi(n: i64) i64 = { + if (n < 0) { + return -n; + } else { + return n; + }; +}; + @test fn eq() void = { const dt = new(2022, 02, 04, 03, 14, 07, 00, 0, chrono::UTC_Z)!; const cases = [ diff --git a/datetime/datetime.ha b/datetime/datetime.ha @@ -108,7 +108,7 @@ export fn new( // `invaliddatetime = !void` ? // `invaliddatetime = !datetime::builder` ? ) (datetime | errors::invalid) = { - // TODO: set the correct values according to the given zoffset and + // TODO: Set the correct values according to the given zoffset and // locality/timezone. let m = chrono::new( calc_epochal_from_ymd(year, month, day)?, @@ -118,16 +118,17 @@ export fn new( // figuring out what zone this moment observes if (zoffset is time::duration) { - // transform inversely to the moment that would transform back + // Transform inversely to the moment that would transform back // to the current moment, then perform a zone lookup. m = chrono::transform(m, -(zoffset as time::duration)); chrono::lookupzone(&m); } else { - // just perform a zone lookup, then try that zone and the - // zones that are observed before and after. + // Just perform a zone lookup, then try that zone and the + // zones that are observed before and after. This requires + // knowlegde of the transition index. //const z0 = chrono::lookupzone(*m); //m = chrono::transform(m, -z0.zoffset); - void; + abort("TODO"); // TODO }; const dt = from_moment(m); @@ -158,7 +159,7 @@ export fn now() datetime = { // Creates a copy of a [[datetime]] // -// TODO: remove, seems useless. +// TODO: remove, purge from other functions, seems useless. export fn clone(dt: datetime) datetime = dt; // Creates a [[datetime]] from a [[chrono::moment]] diff --git a/datetime/format.ha b/datetime/format.ha @@ -51,7 +51,7 @@ def MONTHS_SHORT: [_]str = [ // Parses a datetime string into a [[builder]], using a "layout" format string // with a subset of specifiers from POSIX strptime(3). Partial, incremental -// parsing is allowed. +// parsing is possible. // // datetime::parse(&b, "%Y-%m-%d", "2038-01-19"); // datetime::parse(&b, "%H:%M:%S", "03:14:07"); diff --git a/datetime/time.ha b/datetime/time.ha @@ -3,6 +3,8 @@ use time; // Calculates the wall clock (hour, minute, second, nanosecond), // given a time since the start of a day +// +// TODO: implement special case for leap seconds where this function is called. fn calc_hmsn(t: time::duration) (int, int, int, int) = { const hour = (t / time::HOUR): int; const min = ((t / time::MINUTE) % 60): int; diff --git a/time/arithm.ha b/time/arithm.ha @@ -20,7 +20,7 @@ export fn diff(a: instant, b: instant) duration = { // 0 if a and b are simultaneous; // +1 if b precedes a; // -// Notes: +// XXX: // At first seems superceded by elapsed, but useful when you need values at // compile time: // switch (compare(a, b)) { diff --git a/time/chrono/README b/time/chrono/README @@ -1,6 +1,11 @@ The time::chrono submodule provides the basis for chronology in Hare, namely [[timescale]]s (leap second handling), [[timezone]]s, and the -[[moment]] type, an abstracted datetime for calendars to interface with. +[[moment]] type, an abstracted datetime for external modules to +interface with. For working with the ISO 8601 Gregorian calendar, see the [[datetime]] submodule. + +Hare defines a chronology as a system used to name and order moments in +time. In practice, a chronology is the combination of a calendar (for +handling days) and a wall clock (for handling times throughout a day). diff --git a/time/chrono/leapsec.ha b/time/chrono/leapsec.ha @@ -1,36 +1,28 @@ use time; -// UTC timestamps and their TAI offsets, sourced from leap-seconds.list -// updated: 8 July 2016 -// expires: 28 June 2022 -// -// TODO: -// this is a temporary hard-coded list. read leap-second data from a source. -// -// Separating concerns of timezones and timescale has proven troublesome, since -// data of timezone transitions and leap seconds are both encoded in the TZif -// files generated from the Olson/tz project, and typically installed at -// /usr/share/zoneinfo. Thus, for typical programs in a minimal system like -// Alpine, the entire system can only be configured to run either with or -// without adherence to leap second information. +// Hare uses raw leap second informtion when dealing with the UTC and TAI +// timescales. This information is source from a standard file installed at +// /usr/share/zoneinfo/leap-seconds.list, which itself is fetched from and +// periodically maintained at: // -// Olson himself has expressed for the support of Martian time, which with our -// approach, may depend on multi-timescale support: +// <ftp://ftp.nist.gov/pub/time/leap-seconds.list> +// <ftp://ftp.boulder.nist.gov/pub/time/leap-seconds.list> // -// > The tz database does not currently support Mars time, but it is documented -// > here in the hopes that support will be added eventually. 8 +// This is in contrast to legacy systems which rely on TZif files, which are +// installed typically at /usr/share/zoneinfo, as part of the "Olson" IANA +// Timezone databse. These files couple timezone and leap second information +// into one datablock. // -// Some systems have an ideal /usr/share/zoneinfo/leap-seconds.list file, which -// is directly downloaded from a periodically maintained file at -// <ftp://ftp.nist.gov/pub/time/leap-seconds.list> or -// <ftp://ftp.boulder.nist.gov/pub/time/leap-seconds.list>. This file contains a -// list of Unix timestamps (2272060800) and absolute timescale offsets (+10). A -// good solution ought to use this. +// Depending on a system's installation, leap second information may be +// deliberately left out of the TZif files, or duplicated throughout. This +// design also inhibits our ambitions for dealing with multiple, dynamic +// timescales. Therefore, we have decided to take an alternative approach. + +// UTC timestamps and their TAI offsets, sourced from leap-seconds.list +// updated: 8 July 2016 +// expires: 28 June 2022 // -// Some systems have a less ideal /usr/share/zoneinfo/leapseconds file, which is -// generated from leap-seconds.list using an awk script, and contains Gregorian -// datetime timestamps (1972 Jun 30 23:59:60) and relative timescale corrections -// (+S, -S). This may be a fallback solution. +// TODO: Initialise this data from /usr/share/zoneinfo/leap-seconds.list const leaps_utc: [](i64, i64) = [ (2272060800, 10), (2287785600, 11), diff --git a/time/chrono/timescale.ha b/time/chrono/timescale.ha @@ -151,6 +151,12 @@ fn conv_tt_tai(tt: time::instant) (time::instant | time::error) = { }; +// Authur David Olson had expressed for Martian time support in this database +// project <https://data.iana.org/time-zones/theory.html>: +// +// > The tz database does not currently support Mars time, but it is documented +// > here in the hopes that support will be added eventually. 8 + // Coordinated Mars Time // // Used for local solar time on Mars.