New function time-convert

This replaces the awkward reuse of encode-time to both convert
calendrical timestamps to Lisp timestamps, and to convert Lisp
timestamps to other forms.  Now, encode-time does just the
former and the new function does just the latter.
The new function builds on a suggestion by Lars Ingebrigtsen in:
https://lists.gnu.org/r/emacs-devel/2019-07/msg00801.html
and refined by Stefan Monnier in:
https://lists.gnu.org/r/emacs-devel/2019-07/msg00803.html
* doc/lispref/os.texi (Time of Day, Time Conversion):
* doc/misc/emacs-mime.texi (time-date):
* etc/NEWS: Update documentation.
* lisp/calendar/cal-dst.el (calendar-next-time-zone-transition):
* lisp/calendar/time-date.el (seconds-to-time, days-to-time):
* lisp/calendar/timeclock.el (timeclock-seconds-to-time):
* lisp/cedet/ede/detect.el (ede-detect-qtest):
* lisp/completion.el (cmpl-hours-since-origin):
* lisp/ecomplete.el (ecomplete-add-item):
* lisp/emacs-lisp/cl-extra.el (cl--random-time):
* lisp/emacs-lisp/timer.el (timer--time-setter)
(timer-next-integral-multiple-of-time):
* lisp/find-lisp.el (find-lisp-format-time):
* lisp/gnus/gnus-diary.el (gnus-user-format-function-d):
* lisp/gnus/gnus-group.el (gnus-group-set-timestamp):
* lisp/gnus/gnus-icalendar.el (gnus-icalendar-show-org-agenda):
* lisp/gnus/nnrss.el (nnrss-normalize-date):
* lisp/gnus/nnspool.el (nnspool-request-newgroups):
* lisp/net/ntlm.el (ntlm-compute-timestamp):
* lisp/net/pop3.el (pop3-uidl-dele):
* lisp/obsolete/vc-arch.el (vc-arch-add-tagline):
* lisp/org/org-clock.el (org-clock-get-clocked-time)
(org-clock-resolve, org-resolve-clocks, org-clock-in)
(org-clock-out, org-clock-sum):
* lisp/org/org-id.el (org-id-uuid, org-id-time-to-b36):
* lisp/org/ox-publish.el (org-publish-cache-ctime-of-src):
* lisp/proced.el (proced-format-time):
* lisp/progmodes/cc-cmds.el (c-progress-init)
(c-progress-update):
* lisp/progmodes/cperl-mode.el (cperl-time-fontification):
* lisp/progmodes/flymake.el (flymake--schedule-timer-maybe):
* lisp/progmodes/vhdl-mode.el (vhdl-update-progress-info)
(vhdl-fix-case-region-1):
* lisp/tar-mode.el (tar-octal-time):
* lisp/time.el (emacs-uptime):
* lisp/url/url-auth.el (url-digest-auth-make-cnonce):
* lisp/url/url-util.el (url-lazy-message):
* lisp/vc/vc-cvs.el (vc-cvs-parse-entry):
* lisp/vc/vc-hg.el (vc-hg-state-fast):
* lisp/xt-mouse.el (xterm-mouse-event):
* test/lisp/emacs-lisp/timer-tests.el:
(timer-next-integral-multiple-of-time-2):
Use time-convert, not encode-time.
* lisp/calendar/icalendar.el (icalendar--decode-isodatetime):
Don’t use now-removed FORM argument for encode-time.
It wasn’t crucial anyway.
* lisp/emacs-lisp/byte-opt.el (side-effect-free-fns): Add time-convert.
* lisp/emacs-lisp/elint.el (elint-unknown-builtin-args):
Update encode-time signature to match current arg set.
* lisp/emacs-lisp/timer.el (timer-next-integral-multiple-of-time):
Use timer-convert with t rather than doing it by hand.
* src/timefns.c (time_hz_ticks, time_form_stamp, lisp_time_form_stamp):
Remove; no longer needed.
(decode_lisp_time): Rturn the form instead of having a *PFORM arg.
All uses changed.
(time_arith): Just return TICKS if HZ is 1.
(Fencode_time): Remove argument FORM.  All callers changed.
Do not attempt to encode time values; just encode
decoded (calendrical) times.
Unless CURRENT_TIME_LIST, just return VALUE since HZ is 1.
(Ftime_convert): New function, which does the time value
conversion that bleeding-edge encode-time formerly did.
Return TIME if it is easy to see that it is already
of the correct form.
(Fcurrent_time): Mention in doc that the form is planned to change.
* test/src/timefns-tests.el (decode-then-encode-time):
Don’t use (encode-time nil).

1 files changed, 13 insertions, 10 deletions

diff --git a/doc/misc/emacs-mime.texi b/doc/misc/emacs-mime.texi
index 1f384f4f270..eb829b06124 100644
--- a/doc/misc/emacs-mime.texi
+++ b/doc/misc/emacs-mime.texi
@@ -1537,24 +1537,25 @@ Here's a bunch of time/date/second/day examples:
 (parse-time-string "Sat Sep 12 12:21:54 1998 +0200")
 @result{} (54 21 12 12 9 1998 6 -1 7200)
 
-(encode-time (date-to-time "Sat Sep 12 12:21:54 1998 +0200")
-             1000000)
-@result{} (905595714000000 . 1000000)
+(time-convert
+  (date-to-time "Sat Sep 12 12:21:54 1998 +0200")
+  'integer)
+@result{} 905595714
 
 (float-time '(905595714000000 . 1000000))
 @result{} 905595714.0
 
-(encode-time 905595714.0 1000000)
+(time-convert 905595714.0 1000000)
 @result{} (905595714000000 . 1000000)
 
 (time-to-days '(905595714000000 . 1000000))
 @result{} 729644
 
-(encode-time (days-to-time 729644) 1000000)
-@result{} (63041241600000000 . 1000000)
+(time-convert (days-to-time 729644) 'integer)
+@result{} 63041241600
 
-(encode-time (time-since '(905595714000000 . 1000000))
-             1000000)
+(time-convert (time-since '(905595714000000 . 1000000))
+              1000000)
 @result{} (631963244775642171 . 1000000000)
 
 (time-less-p '(905595714000000 . 1000000)
@@ -1622,12 +1623,14 @@ These are the functions available:
 @item date-to-time
 Take a date and return a time.
 
+@item time-convert
+Take a time and return a timestamp in a specified form.
+
 @item float-time
 Take a time and return seconds.
 
 @item encode-time
-Take seconds (and other ways to represent time, notably decoded time
-lists), and return a time.
+Take a decoded time and return a timestamp.
 
 @item time-to-days
 Take a time and return days.