Index of /wtime

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