Octave date and time services

[Ian McCallion]

I recently posed a question about timezones on the list that received
no reply. No big deal, I solved my own problem and recognise this is
probably not an area that concerns most of the Octave community. But
in the process of solving it I identified a number of Octave bugs
and/or documentation inadequacies in the area of date and time
services. To give a flavour of what I found:

1. Documentation problem. Documentation for gmtime,
https://octave.org/doc/v4.4.0/Timing-Utilities.html#XREFgmtime, says:

    "Given a value returned from time, or any non-negative integer.
return a time structure
    corresponding to CUT (Coordinated Universal Time)."

What gmtime really does is

   "Given the number (>=0) of seconds since 00:00 on 1970/01/01(*) of
an event, returns
   a time structure describing that time of that event in UTC.

   (*) This measure of recent and future time referred to as Seconds
Since Epoch and is
        returned by time(), lstat(filename), and other functions.

This lack of precision applies to localtime and other functions also.

2. Bug. In the tm_struct returned by the localtime function, the
gmtoff field does not appear to be set correctly.

3. Bug (in code or documentation). The mktime function which takes a
tm_struct as parameter  and returns Seconds Since Epoch silently
ignores the gmtoff and zone elements of the tm_struct. See also point
4.

4. Bug or Omission. This function, which I wrote after much trial and
error to solve my original problem:

  function [] = settimezone(tz)
      % Provide access to timezone conversions using mktime and localtime
      if isempty(tz)  % Use the system's timezone
           unsetenv("TZ");
      else
           setenv("TZ", tz);
      end
      mktime(localtime(1)); % Force Octave to access the TZ environment variable
  end

sets the timezone for the running octave environment according to the
supplied timezone string, eg "EST+5EDT,M3.2.0/2,M11.1.0/2". The
function is necessary because merely setting TZ is not sufficient -
localtime and maybe other functions seem to reference a cache that is
only loaded by mktime.

The definition of timezone strings is available here:

    
https://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html#TZ-Variable

This should be be included into Octave documentation. There are also
theoretically ways of referencing the timezone such as
TZ=":America/New_York" which I have not been able to make work on
windows (and I have no access to unix systems)

5. Bug in the Octave GUI editor. On Windows setting TZ does not affect
file system APIs. So when the editor saves a function file the
system's UTC clock is naturally used to timestamp the file. However
when the editor loads a function file it (I am assuming) erroneously
translates the file's timestamp to local time using the TZ variable
but takes the local time from system APIs. The result is that the a
file just saved can be reported as having a timestamp in the future.

6. Bug, or documentation error. "Leap Seconds" are mentioned as
ignored in text under the datenum function, but leap seconds apply to
many APIs and what "ignored" means is ambiguous. If it is decided that
a particular day will have 86401 atomic clock-defined seconds does
"ignored" mean the seconds counter ranges 0:86400 instead of 0:86399?
Or does it mean the clock is ever after out of step with the world's
rotation and almost all other clocks in the world? Or does it mean the
system on which Octave is running has slowed its timing services for a
few hours or days to remain in sync with the accepted world standard
time.

I would be happy to cooperate in improving this small backwater of Octave.

Cheers...
Ian