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

[Julien Fischer]

On Fri, 17 Apr 2026 at 14:15, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:
>
>
> 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.

That was my thought.

> > > +    % 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,

I'm aware of that particular grenade ;-)  It's not something we can
really resolve
in a sensible fashion until / if we get support for zoned date times.
That certainly
won't be before the next release.

BTW: What is the state of packing data constructor arguments? I ask, because we
should be able to represent a date_time in less than seven words it currently
requires.

> the diff is fine.

Thanks.

Julien.