More-compatible subsecond calendrical timestamps

Instead of appending a subseconds member to the result of
‘decode-time’, this keeps the format unchanged unless you give
a new optional argument to ‘decode-time’.  Also, the augmented
format now puts the subsecond info in the SECONDS element, so
the total number of elements is unchanged; this is more
compatible with code that expects the traditional 9 elements,
such as ‘(pcase decoded-time (`(,SEC ,MIN ,HOUR ,DAY ,MON
,YEAR ,DOW ,DST ,ZONE) ...) ...)’.
* doc/lispref/os.texi, doc/misc/emacs-mime.texi, etc/NEWS:
* lisp/net/soap-client.el (soap-decode-date-time):
* lisp/simple.el (decoded-time):
Document the new behavior.
* lisp/calendar/icalendar.el (icalendar--decode-isodatetime):
* lisp/calendar/iso8601.el (iso8601-parse)
(iso8601-parse-time, iso8601-parse-duration)
(iso8601--decoded-time):
* lisp/calendar/parse-time.el (parse-time-string):
* lisp/calendar/time-date.el (decoded-time-add)
(decoded-time--alter-second):
* lisp/org/org.el (org-parse-time-string):
* lisp/simple.el (decoded-time):
* src/timefns.c (Fdecode_time, Fencode_time):
* test/lisp/calendar/icalendar-tests.el:
(icalendar--decode-isodatetime):
* test/lisp/calendar/iso8601-tests.el (test-iso8601-date-years)
(test-iso8601-date-dates, test-iso8601-date-obsolete)
(test-iso8601-date-weeks, test-iso8601-date-ordinals)
(test-iso8601-time, test-iso8601-combined)
(test-iso8601-duration, test-iso8601-intervals)
(standard-test-dates, standard-test-time-of-day-fractions)
(standard-test-time-of-day-beginning-of-day)
(standard-test-time-of-day-utc)
(standard-test-time-of-day-zone)
(standard-test-date-and-time-of-day, standard-test-interval):
* test/lisp/calendar/parse-time-tests.el (parse-time-tests):
* test/src/timefns-tests.el (format-time-string-with-zone)
(encode-time-dst-numeric-zone):
Revert recent changes that added a SUBSECS member to
calendrical timestamps, since that component is no longer
present (the info, if any, is now in the SECONDS member).
* lisp/calendar/time-date.el (decoded-time-add)
(decoded-time--alter-second):
Support fractional seconds in the new form.  Simplify.
* src/timefns.c (Fdecode_time): Support new arg FORM.
(Fencode_time): Support subsecond resolution.
* test/src/timefns-tests.el (format-time-string-with-zone)
(decode-then-encode-time): Test subsecond calendrical timestamps.

1 files changed, 16 insertions, 6 deletions

diff --git a/etc/NEWS b/etc/NEWS
index edce7b3e57d..53408a871e7 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2116,10 +2116,20 @@ probing the innards of a timestamp directly, or creating a timestamp
 by hand.
 
 +++
-*** Decoded (calendrical) timestamps now have a new subsecond member.
-This affects functions like decode-time and parse-time-string that
-generate these timestamps, and functions like encode-time that accept
-them.
+*** Decoded (calendrical) timestamps now have subsecond resolution.
+This affects decode-time, which generates these timestamps, as well as
+functions like encode-time that accept them.  The subsecond info is
+present as a (TICKS . HZ) value in the seconds element of a decoded
+timestamp, and decode-time has a new optional FORM argument specifying
+the form of the seconds member.  For example, if X is the timestamp
+(1566009571321878186 . 1000000000), which represents 2019-08-17
+02:39:31.321878186 UTC, (decode-time X t t) returns ((31321878186
+. 1000000000) 39 2 17 8 2019 6 nil 0) instead of the traditional (31
+39 2 17 8 2019 6 nil 0) returned by plain (decode-time X t).  Although
+the default FORM is currently 'integer', which truncates the seconds
+to an integer and is the traditional behavior, this default may change
+in future Emacs versions, so callers requiring an integer should
+specify FORM explicitly.
 
 +++
 *** 'encode-time' supports a new API '(encode-time TIME)'.
@@ -2152,8 +2162,8 @@ with POSIX.1-2017.
 *** To access (or alter) the elements a decoded time value, the
 'decoded-time-second', 'decoded-time-minute', 'decoded-time-hour',
 'decoded-time-day', 'decoded-time-month', 'decoded-time-year',
-'decoded-time-weekday', 'decoded-time-dst', 'decoded-time-zone',
-and 'decoded-time-subsec' accessors can be used.
+'decoded-time-weekday', 'decoded-time-dst' and 'decoded-time-zone'
+accessors can be used.
 
 *** The new functions 'date-days-in-month' (which will say how many
 days there are in a month in a specific year), 'date-ordinal-to-time'