chmike / timez-go

Package timez provides a compact binary encoded UTC time with time offset.

TimeZ

Go package implementing Timez. A timez is 64 bit unsigned integer combining an UTC time value in microsecond, and a time zone time offset in minutes. Comparing two such unisgned integer yields the same as if the UTC time was first compared, and if equal, the time zone offset were compared.

Why ?

ISO issued the standard ISO 8601 to normalize text encoded time values. The IETF issued an equivalent standard (RFC3339https://www.ietf.org/rfc/rfc3339.txt) for the Internet. These time encodings combine a local time with a time offset relative to UTC. But they are text only. Timez is the binary equivalent of these time values.

What is a timez ?

A timez value encodes the UTC time with microsecond precision and the local time offset in a 64 bit unsigned integer. Both values can be retrieved independently. This makes timez a convenient stamp value in binary messages crossing time zone boundaries.

The most interseting property of timez values is that comparing the integer values is equivalent to compare UTC time, and when equal, to compare time zone time offsets. Timez values are then convenient and efficient to use as key in a sorted table, or as ordered index key in a database.

The microsecond resolution

The microsecond UTC time resolution is a compromise. A nanosecond resolution would have been preferable, but it wouldn't fit in a 64bit integer with the time offset. NTP can at very best synchronize around a few tens of microseconds. With GPS, the best time synchronization we could get is around a few tens of nanoseconds. Since a photon can travel at most 300m in a microsecond in vacuum, for message stamps with Internet application, a microsecond precision is an acceptable compromise.

Timez encoding

A Timez encodes the number of microseconds elapsed since 1970-01-01T00:00:00.000000Z in the 53 most significant bits of a 64 bit unsigned integer. The 53 bit microsecond counter will wrap 285 years after 1970, thus in the year 2255.

The time offset is encoded in the 11 less significant bits as a number of minutes relative to 1024. Thus the offset value 1024 is the time offset 00:00, the value 984 is the time offset -01:00, and the value 1084 it the time offset +01:00. The time offset value 0 is invalid.

64                                11        0   bits
|__________________  ______________|________|
|_________________//_______________|________|
|  number of microseconds elapsed  |  time  |
| since 1970-01-01T00:00:00.000000 | offset |

The default initializer of Go timez values yields an invalid timez value.

Note: the curent timez encoding of this package differ from the "github/chmike/timez" C library in that we now use 64 bit unsigned integer.

Feedback is welcome.

Note: This Work In Progress (WIP) and the encoding may change at any time.

timez-go's Issues

Discussion: is recording the offset usefull?

Hi Christophe,

I was working on/thinking about the same issue as this lib (and timez) addresses. Don't take this as criticism [I don't have a solution either, just some ideas], but I don't think [that's the conclusion I've come to at least] it is the right solution. What one needs, IMO, is together with the UTC-time, to record the IANA time-zone (or Windows-timezone). Unless you do that, it is not possible to convert back to local time under all conditions, i.e. iff you know UTC time and the time-zone it applies to, it should be possible to work out what the local time was/is in that timezone, taking into account (dynamic) DST. Offset cannot do this, due to DST (and possibly dynamic DST).

I think you worked out nicely that 53-bits for time does the trick, this works well with Windows FILETIME as well, as most of those lower bits [FILETIME is in nanoseconds (since the year 1601), the timers in Windows don't have a resolution better than 400 to 600 ns] are practically speaking just garbage, in other words, it's possible to encode things in the lower bits, while just using the encoded FILETIME with the Win32-API, without any noticeable effect.

I'm thinking about encoding the time-zones (IANA 459/ Windows Native 159), so iff numbered, they can easily be inside the 11 bits available.

I don't know, what are your thoughts?

Have a nice day (et salutations),

degski