The caltime library interface

Calendar dates and times

     #include <caltime.h>

     struct caltime ct;

A struct caltime value is a calendar date and time with an offset in minutes from UTC. It has five components:

date (a struct caldate),
hour (0 through 23),
minute (0 through 59),
second (0 through 60), and
offset (-5999 through 5999).

For example, a leap second occurred on 30 June 1997 at 23:59:60 UTC. The local time in New York was 30 June 1997 19:59:60 -0400. This local time is represented inside a struct caltime with date containing 1997, 6, 30; hour 19; minute 59; second 60; and offset -240 (4 hours).

ASCII input and output

     #include <caltime.h>

     struct caltime ct;
     char *s;
     unsigned int len;

     len = caltime_fmt(s,&ct);
     len = caltime_scan(s,&ct);

caltime_fmt prints ct in ISO style (YYYY-MM-DD HH:MM:SS +OOOO) into the character buffer s, without a terminating \0. It returns the number of characters printed. s may be zero; then caltime_fmt returns the number of characters that would have been printed.

caltime_scan reads a calendar date, time, and offset in ISO style from the beginning of the character buffer s and puts them into ct. It returns the number of characters read. If s does not start with an ISO-style date and time (including offset), caltime_scan returns 0, and may or may not touch ct.

Note that year numbers may be larger than 9999; len will not always be equal to 25. Please don't contribute to the Y10K problem.

Time arithmetic

     #include <caltime.h>
     #include <tai.h>

     struct caltime ct;
     struct tai t;
     int *weekday;
     int *yearday;

     caltime_tai(&ct,&t);
     caltime_utc(&ct,&t,weekday,yearday);

caltime_tai reads a date, time, and UTC offset from ct. It puts the corresponding TAI64 label into t.

caltime_utc reads a TAI64 label from t. It puts the corresponding date and time into ct, with UTC offset 0. caltime_utc fills in *weekday and *yearday the same way as caldate_frommjd.

The current version of libtai does not include conversions to calendar dates and times in zones other than UTC.

Beware that, although the sequence of TAI64 labels has been determined for the next few hundred billion years, the sequence of calendar dates and times has not been determined. New leap seconds are added every year or two, and the Gregorian calendar will change in a few thousand years. This means that caltime_tai and caltime_utc are not useful for dates far in the future.