NAME wtime_t -- wide time, world time, wall time DESCRIPTION Wtime is a signed 64-bit timestamp with over 8000 year span and microsecond resolution. 'Wtime' means 'wide time', 'world time' and/or 'wall time'. It represents civil time, or wall clock time, in a compact binary encoding while preserving both the relation to UTC and the local time. It is therefore suited for use in binary file formats (eg. log files), file systems and Internet messages. For many purposes, depending on the reader's need, having both universal time and the original local time preserved can be important. PROPERTIES Wtime values are not tied to a specific calendar system, but the default string representation uses the Julian/Gregorian calanders. The representation created by wtime_to_string() is based on ISO-8601. Days are assumed to consist of 86400 regular seconds, which may or may not correspond to SI-unit seconds. Wtime has a provision to represent leap seconds and elapsed time within leap seconds. The trade-off here is that in leap seconds the resolution is reduced by two digits (to 0.1ms, which is still more accurate than Java timestamps). Wtime can preserve local time zone information. A 6-bit tag is used for this purpose. Time zones can be one of the current time zones in existence, including irregular time zones such as that of Kathmandu (UTC+0545). Alternatively, time zones can be represented as an offset in minutes west or east from UTC, albeit at the expense of three digits in sub-second resolution. Except for timestamps with unknown local time zone, a wtime value is internally normalized to UTC. This reduces timestamp comparison to a basic integer compare operation. Some wtime values are invalid or reserved for future extensions. Most notably, the values 0 and -1 don't represent valid times and will never represent valid times in future versions of wtime. There may be reasons to put the leap year 4000 under discussion. The wtime era ends just before this problem year (in 3998). The wtime era starts on Julian Day Number 0.0 (that is January 1 of astronomical year -4712 or 4713 BC, 12:00 UTC). Wtime can be used for historical and astronomical purposes. The introduction date of the Gregorian calandar is assumed to have occurred from September 2 (Jul.) to September 14 (Gr.) 1752. This is the same as in the Unix cal(1) program. There is a reference implementation available in C. Implementations for Java, JavaScript and Python are being planned. C FUNCTIONS #include #include wtime_init -- initialize wtime library wtime_get_current -- get timestamp for current time in local time zone wtime_is_valid -- test validity of timestamp wtime_to_string -- convert timestamp to human-readable text wtime_from_string -- convert human-readable text to timestamp wtime_diff -- the difference between two timestamps in seconds wtime_diff_micros -- difference between two timestamps in microseconds wtime_add_micros -- add microseconds to timestamp wtime_add_seconds -- add seconds to timestamp wtime_add_days -- add days to timestamp wtime_set_zone -- set new time zone code in timestamp wtime_get_seconds -- get regular of seconds since epoch from timestamp wtime_get_micros -- get microsecond fraction from timestamp wtime_get_zone -- get time zone code from timestamp Additional functions when is included: #include #include #include wtime_posix_from_time_t -- convert time_t timestamp into wtime_t wtime_posix_to_time_t -- convert wtime_t timestamp into time_t wtime_posix_from_struct_tm -- construct timestamp from struct tm fields wtime_posix_to_struct_tm -- break-dowm timestamp into struct tm fields LAYOUT The following layout variants of the 64-bit wtime word are defined: Variant R (regular) +-------------------------------+----------------------+--------+ | seconds | fraction | zone | +-------------------------------+----------------------+--------+ 63 26 25 6 5 0 bit Fields: seconds(38) : regular seconds since wtime epoch (86400 seconds per day) fraction(20) : microseconds (0..999999) zone(6) : time zone code (0..54, 63) Variant RL (regular leap second) +-------------------------------+----------------------+--------+ | seconds | fraction | zone | +-------------------------------+----------------------+--------+ 63 26 25 6 5 0 bit Fields: seconds(38) : regular seconds since wtime epoch (86400 seconds per day), must be the end of a full minute (seconds % 60 == 59) fraction(20) : 1000000 + tenths-of-milliseconds (1000000..1009999) zone(6) : time zone code (1..54, 63) Variant W (solar-based time zone, west of UTC) +-------------------------------+----------+-----------+--------+ | seconds | fraction | minutes | zone | +-------------------------------+----------+-----------+--------+ 63 26 25 16 15 6 5 0 bit Fields: seconds(38) : regular seconds since wtime epoch (86400 seconds per day) fraction(10) : milliseconds (0...999) minutes(10) : 1024 - minutes west of UTC zone(6) : wtime_zone_solar_west (61) Variant E (solar-based time zone, east of UTC) +-------------------------------+----------+-----------+--------+ | seconds | fraction | minutes | zone | +-------------------------------+----------+-----------+--------+ 63 26 25 16 15 6 5 0 bit Fields: seconds(38) : regular seconds since wtime epoch (86400 seconds per day) fraction(10) : milliseconds (0..999) minutes(10) : minutes east of UTC zone(6) : wtime_zone_solar_east (62) Variant WL (solar-based time zone, west of UTC, leap second) +-------------------------------+----------+-----------+--------+ | seconds | fraction | minutes | zone | +-------------------------------+----------+-----------+--------+ 63 26 25 16 15 6 5 0 bit Fields: seconds(38) : regular seconds since wtime epoch (86400 seconds per day), must be the end of a full minute (seconds % 60 == 59) fraction(10) : 1000 + tenths-of-seconds (1000..1009) minutes(10) : 1024 - minutes west of UTC zone(6) : wtime_zone_solar_west (61) Variant EL (solar-based time zone, east of UTC, leap second) +-------------------------------+----------+-----------+--------+ | seconds | fraction | minutes | zone | +-------------------------------+----------+-----------+--------+ 63 26 25 16 15 6 5 0 bit Fields: seconds(38) : regular seconds since wtime epoch (86400 seconds per day), must be the end of a full minute (seconds % 60 == 59) fraction(10) : 1000 + tenths-of-seconds (1000..1009) minutes(10) : minutes east of UTC zone(6) : wtime_zone_solar_east (62) TIME ZONE CODES The time zones codes are: 0 invalid time zone 1..49 all half-hour and full-hour time zones from UTC-1200 to UTC+1200 Example: London/Z/UTC = 25 (= 0x19), Amsterdam/UTC+0100 = 27 50 UTC+1300 51 UTC+1400 52 UTC+0545 53 UTC+0845 54 UTC+1245 55..60 reserved for future extensions 61 solar-based time zone (given in minutes west of UTC) 62 solar-based time zone (given in minutes east of UTC) 63 unknown local (that is: a wtime value used to represent a local time with an unknown reference to UTC) EXAMPLES The following timelines illustrate the wtime epoch, era and its relation to POSIX time_t. 0x800002a300000031 v -+-----------+-----------:-----------+-----------+-----------+- | Mon : Tue | Wed UTC+1200 -> | -4712-01-01 : -4712-01-02 | -4712-01-03 00:00 12:00 00:00 12:00 00:00 12:00 -------------+-----------:-----------+-----------+-----------+--- Sun | Mon | Tue | UTC+0000 -> -4713-12-31 | -4712-01-01 | -4712-01-02 | 12:00 00:00 12:00 00:00 12:00 00:00 -+-----------+-----------:-----------+-----------+-----------+--- | Sun : Mon | Tue UTC-1200 -> | -4713-12-31 : -4712-01-01 | -4712-01-02 00:00 12:00 00:00 12:00 00:00 12:00 -+-----------+-----------:-----------+-----------+-----------+--- | JDN -1 : JDN 0 | JDN 1 -1.0 -0.5 0.0 0.5 1.0 1.5 JDN -> -+-----------+-----------:-----------+-----------+-----------+--- ^ ^ 0x8000000000000019 0x8000054600000019 wtime epoch -------------+-----------+-----------+-----------+-----------+--- Wed | Thu | Fri | UTC+0000 -> 1969-12-31 | 1970-01-01 | 1970-01-02 | 12:00 00:00 12:00 00:00 12:00 00:00 -+-----------+-----------+-----------+-----------+-----------+--- ^ 0x44628da500000019 (POSIX time_t epoch) -------------+-----------+------:----+-----------+-----------+--- Sat | Sun : | Mon | UTC+0000 -> 3998-06-06 | 3998-06-07 : | 3998-06-08 | 12:00 00:00 12:00 : 00:00 12:00 00:00 -+-----------+-----------+------:----+-----------+-----------+--- ^ 0x7fffffffffd08fd9 18:09:03.999999 end of wtime era FUTURE EXTENSIONS The following extensions of the wtime definition are under consideration: 1. Time zone extensions There are six unassigned time zone codes: 55..60. In the future these may be used for new time zones. (Note: Times within such time zones can already be represented using the solar-based time zone encoding, albeit with some loss of sub-second resolution. Adding a new pre-defined time zone code would merely give it full microsecond resolution.) 2. International Atomic Time support One currently unassigned time zone code could be used to designate TAI time. 3. Message bytes An encoding to embed small messages in wtime values, for use by stations that broadcast wtime values. Possible uses are: - announcement of leap seconds - announcement of new time zones - announcement of new versions of the wtime standard - identification of the broadcast station - information about the accuracy of the broadcast The contents of the messages are not defined yet. One second can hold upto 128 message bytes. It is not defined yet how to split longer messages. Variant M (message byte) +-------------------------------+----------------------+--------+ | seconds | msg-byte | zone | +-------------------------------+----------------------+--------+ 63 26 25 6 5 0 bit Fields: seconds(38) : regular seconds since epoch start (86400 seconds per day) msg-byte(20): 0xf8000 + (index<<8) + byte, where index: index within the message (0..127) byte : data byte (0..255) zone(6) : 1..54, 61..63 (ignored when valid) 4. Era extension The wtime era spans the years -4712 to +3998. A possible future extension could extend this period by trading off resolution. It is still unclear how to do that and if it will provide a benefit. Maybe by using time zone code 60 and defining a new layout variant based on floating point. SEE ALSO -- ISO 8601:2004(E): Representation of dates and times http://isotc.iso.org/livelink/livelink/4021199/ISO_8601_2004_E.zip\ ?func=doc.Fetch&nodeid=4021199 -- Wikipedia: List of time zones http://en.wikipedia.org/wiki/List_of_time_zones -- John Walker: Calendar Converter http://www.fourmilab.ch/documents/calendar/ A useful calendar converter. This page also contains a lot of interesting information about many calendar systems. -- David R. Tribble: ISO C 200X Proposal: Long Time Type http://david.tribble.com/text/c0xlongtime.html An earlier attempt to solve the time_t problem in the C standard. -- Markus Kuhn: Modernized API for ISO C http://www.cl.cam.ac.uk/~mgk25/time/c/ An earlier attempt to solve the time_t problem in the C standard. -- Steve Allen: Future of Leap Seconds http://www.ucolick.org/~sla/leapsecs/onlinebib.html Leap seconds are a relatively recent fenomenon to modern day time keeping that may be subject to change. Wtime treats them as a special encoding case. LICENSE The wtime definition and reference implementations are distributed with a BSD-style license. See the file COPYRIGHT for details. AUTHOR Marcel van Kervinck Taipei, Taiwan marcelk@bitpit.net HISTORY 2007-06-27 (marcelk) Documented initial wtime layout. 2007-06-30 (marcelk) Added C functions; Minor editting of text.