lib: add date and time related functions

Add five new functions to deal with date calculation and timing:

 - localtime(), gmtime() - return a broken down calendar date and time
   specification from the given epoch (or now, if absent) in local and
   UTC time respectively

 - timelocal(), timegm() - the inverse operation for the former functions,
   taking a date and time specification (interpreted as local or UTC time
   respectively) and turning it into an epoch value

 - clock() - return the second and nanosecond values of the system clock,
   useful for time/performance measurements

Signed-off-by: Jo-Philipp Wich <jo@mein.io>

5 files changed, 213 insertions, 0 deletions

diff --git a/tests/custom/03_stdlib/51_localtime b/tests/custom/03_stdlib/51_localtime
new file mode 100644
index 0000000..d16f279
--- /dev/null
+++ b/tests/custom/03_stdlib/51_localtime
@@ -0,0 +1,36 @@
+The `localtime()` function returns the given epoch timestamp (or now,
+if omitted) as a dictionary containing broken-down date and time
+information according to the local system timezone.
+
+-- Testcase --
+{%
+	let t = time();
+	let d1 = localtime();
+	let d2 = localtime(1647953502);
+
+	// assert that localtime without epoch returns the current time
+	let c = timelocal(d1);
+	assert(c >= t && c <= t + 5, "localtime() result does not match time()");
+
+	// dump fixed time and check expected output
+	printf("%.J\n", d2);
+%}
+-- End --
+
+-- Vars --
+TZ=CET-1CEST,M3.5.0/2,M10.5.0/3
+-- End --
+
+-- Expect stdout --
+{
+	"sec": 42,
+	"min": 51,
+	"hour": 13,
+	"mday": 22,
+	"mon": 3,
+	"year": 2022,
+	"wday": 2,
+	"yday": 81,
+	"isdst": 0
+}
+-- End --
diff --git a/tests/custom/03_stdlib/52_gmtime b/tests/custom/03_stdlib/52_gmtime
new file mode 100644
index 0000000..2d73a12
--- /dev/null
+++ b/tests/custom/03_stdlib/52_gmtime
@@ -0,0 +1,32 @@
+The `gmtime()` function returns the given epoch timestamp (or now,
+if omitted) as a dictionary containing broken-down date and time
+information interpreted as UTC time.
+
+-- Testcase --
+{%
+	let t = time();
+	let d1 = gmtime();
+	let d2 = gmtime(1647953502);
+
+	// assert that localtime without epoch returns the current time
+	let c = timegm(d1);
+	assert(c >= t && c <= t + 5, "gmtime() result does not match time()");
+
+	// dump fixed time and check expected output
+	printf("%.J\n", d2);
+%}
+-- End --
+
+-- Expect stdout --
+{
+	"sec": 42,
+	"min": 51,
+	"hour": 12,
+	"mday": 22,
+	"mon": 3,
+	"year": 2022,
+	"wday": 2,
+	"yday": 81,
+	"isdst": 0
+}
+-- End --
diff --git a/tests/custom/03_stdlib/53_timelocal b/tests/custom/03_stdlib/53_timelocal
new file mode 100644
index 0000000..e4d0db4
--- /dev/null
+++ b/tests/custom/03_stdlib/53_timelocal
@@ -0,0 +1,58 @@
+The `timelocal()` function performs the inverse operation of `localtime()`
+by taking a broken-down date and time dictionary and transforming it into
+an epoch value according to the local system timezone.
+
+-- Testcase --
+{%
+	// check expected epoch
+	let d1 = {
+		"sec": 42,
+		"min": 51,
+		"hour": 13,
+		"mday": 22,
+		"mon": 3,
+		"year": 2022,
+		"wday": 2,
+		"yday": 81,
+		"isdst": 0
+	};
+
+	// check that out of range values are normalized
+	let d2 = {
+		"sec": 33,
+		"min": 22,
+		"hour": 11,
+		"mday": 40,
+		"mon": 10,
+		"year": 2022,
+		"wday": 2,
+		"yday": 81,
+		"isdst": 0
+	};
+
+	// check that everything except mday, mon, year is optional
+	let d3 = {
+		"mday": 1,
+		"mon": 1,
+		"year": 2000
+	};
+
+	printf("%.J\n", [
+		timelocal(d1),
+		timelocal(d2),
+		timelocal(d3)
+	]);
+%}
+-- End --
+
+-- Vars --
+TZ=CET-1CEST,M3.5.0/2,M10.5.0/3
+-- End --
+
+-- Expect stdout --
+[
+	1647953502,
+	1667989353,
+	946681200
+]
+-- End --
diff --git a/tests/custom/03_stdlib/54_timegm b/tests/custom/03_stdlib/54_timegm
new file mode 100644
index 0000000..9c0b59a
--- /dev/null
+++ b/tests/custom/03_stdlib/54_timegm
@@ -0,0 +1,54 @@
+The `timegm()` function performs the inverse operation of `gmtime()`
+by taking a broken-down date and time dictionary and transforming it into
+an epoch value, assuming UTC time.
+
+-- Testcase --
+{%
+	// check expected epoch
+	let d1 = {
+		"sec": 42,
+		"min": 51,
+		"hour": 13,
+		"mday": 22,
+		"mon": 3,
+		"year": 2022,
+		"wday": 2,
+		"yday": 81,
+		"isdst": 0
+	};
+
+	// check that out of range values are normalized
+	let d2 = {
+		"sec": 33,
+		"min": 22,
+		"hour": 11,
+		"mday": 40,
+		"mon": 10,
+		"year": 2022,
+		"wday": 2,
+		"yday": 81,
+		"isdst": 0
+	};
+
+	// check that everything except mday, mon, year is optional
+	let d3 = {
+		"mday": 1,
+		"mon": 1,
+		"year": 2000
+	};
+
+	printf("%.J\n", [
+		timegm(d1),
+		timegm(d2),
+		timegm(d3)
+	]);
+%}
+-- End --
+
+-- Expect stdout --
+[
+	1647957102,
+	1667992953,
+	946684800
+]
+-- End --
diff --git a/tests/custom/03_stdlib/55_clock b/tests/custom/03_stdlib/55_clock
new file mode 100644
index 0000000..109ce21
--- /dev/null
+++ b/tests/custom/03_stdlib/55_clock
@@ -0,0 +1,33 @@
+The `clock()` function reads the current second and microsecond value of
+the system clock, optionally using the monotonic clock instead of the
+default realtime one.
+
+-- Testcase --
+{%
+	let t1 = clock();
+	let t3 = clock(true);
+
+	sleep(250);
+
+	let t2 = clock();
+	let t4 = clock(true);
+
+	let delta1 = (t2[0] - t1[0]) * 1000000000 + (t2[1] - t1[1]);
+	let delta2 = (t4[0] - t3[0]) * 1000000000 + (t4[1] - t3[1]);
+
+	assert(delta1 >= 0, "Realtime clock went backwards!");
+	assert(delta2 >= 0, "Monotonic clock went backwards!");
+
+	printf("%.J\n", [
+		(delta1 >= 240000000 && delta1 <= 260000000) ? true : "unexpected delta: " + delta1,
+		(delta2 >= 240000000 && delta2 <= 260000000) ? true : "unexpected delta: " + delta2
+	]);
+%}
+-- End --
+
+-- Expect stdout --
+[
+	true,
+	true
+]
+-- End --