Index of /wtime
Name Last modified Size Description
![[DIR]](/icons/back.gif)
Parent Directory -
![[ ]](/icons/unknown.gif)
COPYRIGHT 27-Jun-2007 09:31 2.0K
Makefile 01-Jul-2007 06:08 171
![[TXT]](/icons/text.gif)
base.h 30-Jun-2007 15:22 3.7K
main-wtime-tester.c 01-Jul-2007 06:07 7.2K
wtime-specification.txt 30-Jun-2007 15:32 14K
wtime-tester.out 28-Jun-2007 02:14 1.6K
wtime.c 30-Jun-2007 14:55 18K
wtime.h 30-Jun-2007 15:14 9.0K
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.