time: add more UTC/local time conversion functions, make Time.format_rfc3339 more stable

vlib/time/format.v

@@ -24,7 +24,7 @@ pub fn (t Time) format_ss_milli() string {
 // RFC3339 is an Internet profile, based on the ISO 8601 standard for for representation of dates and times using the Gregorian calendar.
 // It is intended to improve consistency and interoperability, when representing and using date and time in Internet protocols.
 pub fn (t Time) format_rfc3339() string {
-	u := t.add(-offset() * second)
+	u := t.local_to_utc()
 	return '${u.year:04d}-${u.month:02d}-${u.day:02d}T${u.hour:02d}:${u.minute:02d}:${u.second:02d}.${(u.microsecond / 1000):03d}Z'
 }
 

vlib/time/time.v

@@ -401,3 +401,51 @@ pub fn offset() int {
 	local := t.local()
 	return int(local.unix - t.unix)
 }
+
+// local_to_utc converts the receiver `t` to the corresponding UTC time, if it contains local time.
+// If the receiver already does contain UTC time, it returns it unchanged.
+pub fn (t Time) local_to_utc() Time {
+	if !t.is_local {
+		return t
+	}
+	return Time{
+		...t.add(-offset() * time.second)
+		is_local: false
+	}
+}
+
+// utc_to_local converts the receiver `u` to the corresponding local time, if it contains UTC time.
+// If the receiver already does contain local time, it returns it unchanged.
+pub fn (u Time) utc_to_local() Time {
+	if u.is_local {
+		return u
+	}
+	return Time{
+		...u.add(offset() * time.second)
+		is_local: true
+	}
+}
+
+// as_local returns the exact same time, as the receiver `t`, but with its .is_local field set to true.
+// See also #Time.utc_to_local .
+pub fn (t Time) as_local() Time {
+	return Time{
+		...t
+		is_local: true
+	}
+}
+
+// as_utc returns the exact same time, as the receiver `t`, but with its .is_local field set to false.
+// See also #Time.local_to_utc .
+pub fn (t Time) as_utc() Time {
+	return Time{
+		...t
+		is_local: false
+	}
+}
+
+// is_utc returns true, when the receiver `t` is a UTC time, and false otherwise.
+// See also #Time.utc_to_local .
+pub fn (t Time) is_utc() bool {
+	return !t.is_local
+}

vlib/time/utc_vs_local_time_test.v

@@ -0,0 +1,48 @@
+import time
+
+fn test_as_utc() {
+	t := time.now()
+	u := t.as_utc()
+	dump(u)
+	assert u.is_local == false
+}
+
+fn test_as_local() {
+	t := time.now()
+	l := t.as_local()
+	dump(l)
+	assert l.is_local == true
+}
+
+fn test_local_to_utc() {
+	n := time.now()
+	u := n.local_to_utc()
+	dump(u)
+	o := time.offset()
+	dump(o)
+	if o != 0 {
+		assert n != u
+		back := u.utc_to_local() // convert it back to local time
+		assert n == back, 'the converted original local->utc->local time, should be the same as the original local time'
+
+		double_u := u.local_to_utc()
+		assert u == double_u, 'calling t.local_to_utc().local_to_utc() several times, should not change the time'
+	}
+}
+
+fn test_utc_to_local() {
+	z := time.Time{}
+	assert z.is_local == false, 'simply constructing a time instance, should construct an UTC time'
+	l := z.utc_to_local()
+	dump(l)
+	o := time.offset()
+	dump(o)
+	if o != 0 {
+		assert z != l, 'when there is a time offset, the local time and the utc time should be different'
+		assert l == l.utc_to_local(), 'converting a local to local time should not change the time'
+		assert l == l.utc_to_local().utc_to_local(), 'double converting a local to local time to local time, should not change the time'
+	}
+	sz := z.format_rfc3339()
+	dump(sz)
+	assert sz == '0000-00-00T00:00:00.000Z'
+}