Re: encode-time vs decode-time

[Paul Eggert <eggert@cs.ucla.edu>]

Eli Zaretskii wrote:
> Was this inspection done on Emacs' own code, or also outside Emacs?

Lars didn't say. I assume he meant Emacs's own code.

Although almost all uses of decode-time will be unaffected by the change, 
there's little doubt that some user code somewhere will break because it 
(mistakenly) assumes that decode-time's result format will never be extended. If 
this is a real concern, we can go about the change in some other way.

One alternative would be to leave decode-time's API unchanged from Emacs 26 and 
put the new functionality into a new function, say "time-calendrical". While 
we're at it, we could call the data structure that the new function returns a 
"calendrical timestamp" instead of a "decoded timestamp", and rename the 
recently-added functions make-decoded-time, decoded-time-hour, decoded-time-year 
etc. to make-calendrical-time, calendrical-hour, calendrical-year, etc. This 
would reduce confusion, as it is harder to remember what a "decoded time" is 
than to remember what a "calendrical time" is, at least for me. Also, we could 
document that the calendrical data structure may change in future versions, and 
that programs should use the new functions rather than inspect the raw data 
structure.

Using the word "calendrical" in the new names would help avoid confusion with 
existing functions, which don't use that word in their names.