Non local, non UTC timestamp display

[JohnMcHugh]

Timezones are an unavoidable complexity in dealing with time. Libcork represents its timestamps internally as a 64bit fixed point number with the implied point between the 32 bit epoch time and a 32 bit fraction where a single bit represents 1/2^32 of a second. By convention, the internal representation is an UTC offset since the beginning of the epoch, but there is no technically feasible way to enforce this.

Time stamps can be displayed as UTC in any format supported by the underlying gmtime function for deconstructing the time and the strftime function for formatting. They can also be displayed as local time based on the TZ environment variable of the host system and the localtime function. Recent additions also support display in an ISO8601 format for both UTC and local times.

Missing is the ability to display times in an arbitrary time zone, neither UTC nor local. This is a convenience function, but can avoid analysis errors when data recorded in one time zone must be processed in another along with logs and other sources that only have local time in human readable format. While it can be argued that this is poor experimental methodology, it happens with astounding regularity.

Adding a function like

bool cork_timestamp_format_tz(const cork_timestamp ts, const tz_t zone, const char *format, char *buf, size_t size)

and its ISO equivalent would allow the time to be formatted for an arbitrary timezone.

The choice of a representation for tz_t is not as simple as it might seem. The easy out for the developer is to make tz_t an alias for another cork_timestamp (or an epoch time or an integer value) with the requirement that the fraction must be zero and the epoch time must represent a legitimate time zone offset that can be printed either as +hh, -hh, +hh:30 or -hh:30. This leaves it up to the programmer to determine the proper offset, including coping with all the DST rules, etc., in effect at the UTC time
represented by ts. The easy out for the programmer is to make tz_t a string that can be looked up with the functions associated with the timezone database (see http://www.twinsun.com/tz/tz-link.htm - top of page) to determine the offset needed for the given time. A compromise would be to create a function that takes a timezone string and returns a tz_t containing the offset.

In any case, if it is desired to represent the time zone in the formatted output in any form other than the actual offset, additional computation may be needed.

It may be possible to wrap the localtime and strftime functions in such a way that the TZ environment variable is reset locally for the duration of the conversion in which case, tz_t could be any representation that can be assigned to this variable.