Re: Octave date and time services

[Mike Miller]

On Fri, May 11, 2018 at 11:57:14 +0200, Ian McCallion wrote:
> 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.

I haven't seen your previous message. I am happy to try to address some
of the issues you bring up here. Maybe I can reply briefly to each one
and we can move this to octave-maintainers or to individual bug reports?

> 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.

These basically read the same to me. When we provide a wrapper for a C
standard library function, we typically expect that the user already
knows how to use the C function. I would rather see Octave include
something like "for more details, refer to the C language reference
definition of gmtime".

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

Works for me. Can you give an example?

> 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.

Correct, those fields are informational extension fields for the user,
and are not used in the inverse operation. This is consistent with the C
function.

> 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.

Does the following not work for you?

    x = time ();
    t1 = localtime (x)
    setenv TZ UTC0
    t2 = localtime (x)
    setenv TZ CST6CDT
    t3 = localtime (x)

If not, that may be a defect in your operating system, it works for me.

> 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)

Any TZ setting that starts with a colon ':' is system-dependent, so it's
no surprise that it doesn't work on Windows, or may use different
definitions.

I don't think it's within the scope of the Octave documentation to
describe the TZ environment variable. I think it would be appropriate to
refer to the section in the GNU libc manual.

> 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.

Yes that may be a bug.

> 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.

It simply means that in the context of the datenum function, every day
is exactly 86400 seconds. The following two expressions return the same
datenum value:

    datenum (2016, 12, 31, 15, 59, 60)
    datenum (2016, 12, 31, 16, 00, 00)

in my local time zone UTC-08:00.

-- 
mike

signature.asc
Description: PGP signature