Date and time handling.

[ori@eigenstate.org]

Hi,

Date handling on 9front is almost adequate today if you don't
have to parse dates or deal with timezones, and don't do
multithreading. Otherwise, it's difficult to get right, and
we often don't.

We've got a crappy home-rolled date parser in seconds(1),
a few in the upas source tree to deal with mail formats,
and git9 has a few hacks around this as well.

Out of tree, joe9 has been trying to write code that takes
stock information in one timezone and moves them to another,
and our APIs there are completely inadequate.

So, I tried to write a library that is adequate, without
being complicated.

It allows working with times in multiple timezones at the
same time. It is thread safe, including timezone loading.
It allows parsing and formatting arbitrary formats. It lets
you adjust the day and figure out the timeshift-shift
adjusted time.

Eventually, when it's ready (not yet), I'd like to put this
into libc. The API additions are small, and all of our curent
time APIs can be implemented trivially in terms of this api.
At worst, I'd like to add the field additions from struct tmd
to it.

There are a few known bugs -- not all fields of the time struct
are filled in yet, for example.

The code is here:

	https://git.eigenstate.org/ori/date.git

The formatted draft of the manpage is below, for comments and
thoughts:

     TMDATE(2)                                               TMDATE(2)

     NAME
          tmnow, tmtime, tmstime, tmshiftzone, tmparse, tmfmt, tmnorm,
          - convert date and time

     SYNOPSIS
          #include <u.h>
          #include <libc.h>

          typedef struct Tmd Tmd;
          struct {
                vlong    abs; /* milliseconds since Jan 1 1970, GMT */
                int sec; /* seconds (range 0..59) */
                int min; /* minutes (0..59) */
                int hour;     /* hours (0..23) */
                int mday;     /* day of the month (1..31) */
                int mon; /* month of the year (0..11) */
                int year;     /* year A.D. - 1900 */
                int wday;     /* day of week (0..6, Sunday = 0) */
                int yday;     /* day of year (0..365) */
                char     zone[];   /* time zone name */
                int tzoff;    /* time   zone delta from GMT */
          };

          Tm   *tmnow(Tm *tm, char *tz);
          Tm   *tmtime(Tm *tm, vlong abs, char *tz);
          Tm   *tmstime(Tm *tm, vlong sec, char *tz);
          Tm   *tmshiftzone(Tm *dst, Tm *src, char *tz);
          Tm   *tmparse(Tm *dst, char *fmt, char *tm);
          int   tmfmt(char *buf, usize nbuf, char *fmt, Tm *tm);
          void tmnorm(Tm *tm);
          void tmfmtinstall(char *fmt);

     DESCRIPTION
          This family of functions handles simple date and time manpu-
          lation.  Times are represented as an absolute instant in
          time, combined with a time zone.

          Time zones are represented as strings.  They can be provided
          as the abbreviated timezone name, the full timezone name,
          the path to a timezone file, or an absolute offset in the
          HHMM form.

          When given as a timezone name, any instant-dependent adjust-
          ments such as leap seconds and daylight savings time will be
          applied to the derived fields of struct tm, but will not
          affect the absolute time.  The time zone name local always
          refers to the time in /env/timezone.

          Tmnow gets the current time of day in the requested time
          zone.

          Tmtime converts the millisecond-resolution timestamp 'abs'
          into a Tm struct in the requested timezone.

          Tmstime is identical to tmtime, but accepts the time in sec-
          onds.

          Tmshiftzone moves a time from one timezone to another, doing
          the appropriate conversions.

          Tmparse parses a time from a string according to the format
          argument. The format argument takes the form of a special
          date string, with the following components:

          1,Jan,January
               Represents the month in numeric, short, or long form,
               respectively.

          2    The day of month.

          3,Mon,Monday
               The day of week in numeric, short, or long form,
               respectively.

          3,15 The hour in 12 or 24 hour time, respectively.

          4    The minute.

          5    The second.

          6,2006
               The year in 2 and 4 digit forms, respectively.

          7,MST
               The time zone offset in numeric or abbreviated form.
               As a special case, 7:00 will fill in both the hour and
               minutes in the timezone.

          _    Pads the following field with spaces.  0 Pads the fol-
               lowing field with zeroes.

          If the format argument is nil, it makes an attempt to parse
          common human readable date formats.  These formats include
          ISO-8601,RFC-3339 and RFC-2822 dates.

          Tmfmt formats a Tm struct according to the format fmt. If
          fmt is nil, we format as in ctime(2). At most nbuf-1 char-
          actters are written into buf, which is nul-terminated.

          Tmrecalc takes a manually adjusted Tm structure, and recal-
          culates the absolute time from it.  This recalculation
          respects the time zone stored in struct tm.  It also takes
          out of range values and wraps them around, simplifying cal-
          culations

          Tmfmtinstall installs a time format specifier %T. The time
          format behaves as in tmfmt

     Examples
          All examples assume tmfmtinstall has been called.

          Get the current date in the local timezone, GMT, and
          US_Pacific time. Print it using the default format.

           Tm t;
           print("local: %T0, tmnow(&t, "local"));
           print"gmt: %T0, tmnow(&t, "GMT"));
           print("eastern: %T0, tmnow(&t, "US_Pacific"));

          Compare if two times are the same, regardless of timezone.

           Tm a, b;

           tmparse(&a, nil, "Tue Dec 10 12:36:00 PST 2019");
           tmparse(&b, nil, "Tue Dec 10 15:36:00 EST 2019");
           if(a.abs == b.abs)
                print("same0);
           else
                print("different0);

          Add a day to two times. Because we picked daylight savings
          time to adjust over, only 23 hours are added.

           Tm t;
           tmparse(&t, nil, "Sun Nov 2 13:11:11 PST 2019");
           tm.day++;
           tmrecalc(&t);
           print("%T", &t); /*  Mon Nov 3 13:11:11 PST 2019 */