[m-rev.] for review: rename two calendar functions

[Zoltan Somogyi]

On Fri, 17 Apr 2026 13:55:43 +1000, Julien Fischer <jfischer at opturion.com> wrote:
> > library/calendar.m:
> >      Rename the function duration/2, which shares its name with the duration
> >      type, to duration_between/2. Add a forwarding function using the old name
> >      and mark it as obsolete.

I suppose that name works. duration_between_date_times would be more
descriptive, but it is also too long for many people.

> > +    % fixed_duration_between(DateTimeA, DateTimeB) = Duration:
> > +    %
> > +    % Return the duration from DateTimeA to DateTimeB, expressed using only
> > +    % fixed-length units: days, hours, minutes, seconds and microseconds.
> > +    % The years and months components of the returned duration are always
> > +    % zero. The result is positive if DateTimeB is after DateTimeA and
> > +    % negative if DateTimeB is before DateTimeA. Leap seconds are ignored.
> >      %
> > +    % The dates should be in the same timezone and daylight savings phase;
> > +    % to find the duration between dates in different timezones or daylight
> > +    % savings phases, first convert them both to UTC.

And the two date_times should contain the same number of leap seconds.
If they don't, then whichever unit (day, hour or minute) you attribute the leap
second to, won't be fixed length anymore.

Because of this, and because the two date_times could easily differ on standard
vs daylight time, I don't think this function is all that useful. To use it in the general case,
you first have to check whether it is applicable to the two given date_times, and if not,
you have to convert both to an absolute time since some epoch and subtract. And if
you have code for doing that, then this function does not really help. What you would
want instead is something that converts the absolute number of seconds difference
into a duration.

Apart from that minor grenade, the diff is fine.

Zoltan.