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.

2 files changed, 38 insertions, 29 deletions

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 70ae39e6ab6..49c07380c5f 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1478,23 +1478,23 @@ Although @code{(time-convert nil nil)} is equivalent to
 @end example
 @end defun
 
-@defun decode-time &optional time zone
+@defun decode-time &optional time zone form
 This function converts a time value into calendrical information.  If
 you don't specify @var{time}, it decodes the current time, and similarly
 @var{zone} defaults to the current time zone rule.  @xref{Time Zone Rules}.
-The return value is a list of ten elements, as follows:
+The @var{form} argument controls the form of the returned
+@var{seconds} element, as described below.
+The return value is a list of nine elements, as follows:
 
 @example
-(@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year}
- @var{dow} @var{dst} @var{utcoff} @var{subsec})
+(@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{utcoff})
 @end example
 
 Here is what the elements mean:
 
 @table @var
 @item seconds
-The number of seconds past the minute, as an integer between 0 and 59.
-On some operating systems, this is 60 for leap seconds.
+The number of seconds past the minute, with form described below.
 @item minutes
 The number of minutes past the hour, as an integer between 0 and 59.
 @item hour
@@ -1514,22 +1514,33 @@ in effect, and @minus{}1 if this information is not available.
 @item utcoff
 An integer indicating the Universal Time offset in seconds, i.e., the number of
 seconds east of Greenwich.
-@item subsec
-The number of subseconds past the second, as either 0 or a Lisp
-timestamp @code{(@var{ticks} . @var{hz})} representing a nonnegative
-fraction less than 1.
 @end table
 
+The @var{seconds} element is a Lisp timestamp that is nonnegative and
+less than 61; it is less than 60 except during positive leap seconds
+(assuming the operating system supports leap seconds).  If the
+optional @var{form} argument is @code{t}, @var{seconds} uses the same
+precision as @var{time}; if @var{form} is @code{integer},
+@var{seconds} is truncated to an integer.  For example, if @var{time}
+is the timestamp @code{(1566009571321 . 1000)}, which represents
+2019-08-17 02:39:31.321 UTC on typical systems that lack leap seconds,
+then @code{(decode-time @var{time} t t)} returns @code{((31321 . 1000)
+39 2 17 8 2019 6 nil 0)}, whereas @code{(decode-time @var{time} t
+'integer)} returns @code{(31 39 2 17 8 2019 6 nil 0)}.  If @var{form}
+is omitted or @code{nil}, it currently defaults to @code{integer} but
+this default may change in future Emacs releases, so callers requiring
+a particular form should specify @var{form}.
+
 @strong{Common Lisp Note:} Common Lisp has different meanings for
-@var{dow} and @var{utcoff}, and lacks @var{subsec}.
+@var{dow} and @var{utcoff}, and its @var{second} is an integer between
+0 and 59 inclusive.
 
 To access (or alter) the elements in the time value, the
 @code{decoded-time-second}, @code{decoded-time-minute},
 @code{decoded-time-hour}, @code{decoded-time-day},
 @code{decoded-time-month}, @code{decoded-time-year},
-@code{decoded-time-weekday}, @code{decoded-time-dst},
-@code{decoded-time-zone} and @code{decoded-time-subsec}
-accessors can be used.
+@code{decoded-time-weekday}, @code{decoded-time-dst} and
+@code{decoded-time-zone} accessors can be used.
 
 For instance, to increase the year in a decoded time, you could say:
 
@@ -1551,7 +1562,7 @@ For instance, if you want ``same time next month'', you
 could say:
 
 @lisp
-(let ((time (decode-time))
+(let ((time (decode-time nil nil t))
       (delta (make-decoded-time :month 2)))
    (encode-time (decoded-time-add time delta)))
 @end lisp
@@ -1585,22 +1596,21 @@ It can act as the inverse of @code{decode-time}.
 
 Ordinarily the first argument is a list
 @code{(@var{second} @var{minute} @var{hour} @var{day} @var{month}
-@var{year} @var{ignored} @var{dst} @var{zone} @var{subsec})} that specifies a
+@var{year} @var{ignored} @var{dst} @var{zone})} that specifies a
 decoded time in the style of @code{decode-time}, so that
 @code{(encode-time (decode-time ...))}  works.  For the meanings of
 these list members, see the table under @code{decode-time}.
 
 As an obsolescent calling convention, this function can be given six
-through ten arguments.  The first six arguments @var{second},
+or more arguments.  The first six arguments @var{second},
 @var{minute}, @var{hour}, @var{day}, @var{month}, and @var{year}
-specify most of the components of a decoded time.  If there are seven
-through nine arguments the @emph{last} argument is used as @var{zone},
-and if there are ten arguments the ninth specifies @var{zone} and the
-tenth specifies @var{subsec}; in either case any other extra arguments
-are ignored, so that @code{(apply #'encode-time (decode-time ...))}
-works.  In this obsolescent convention, @var{zone} defaults to the
-current time zone rule (@pxref{Time Zone Rules}), @var{subsec}
-defaults to 0, and @var{dst} is treated as if it was @minus{}1.
+specify most of the components of a decoded time.  If there are more
+than six arguments the @emph{last} argument is used as @var{zone} and
+any other extra arguments are ignored, so that @code{(apply
+#'encode-time (decode-time ...))} works.  In this obsolescent
+convention, @var{zone} defaults to the current time zone rule
+(@pxref{Time Zone Rules}), and @var{dst} is treated as if it was
+@minus{}1.
 
 Year numbers less than 100 are not treated specially.  If you want them
 to stand for years above 1900, or years above 2000, you must alter them
@@ -1615,9 +1625,8 @@ the latter to the former as follows:
 @end example
 
 You can perform simple date arithmetic by using out-of-range values for
-@var{seconds}, @var{minutes}, @var{hour}, @var{day}, @var{month}, and
-@var{subsec}; for example, day 0 means the day preceding the given
-month.
+@var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month};
+for example, day 0 means the day preceding the given month.
 
 The operating system puts limits on the range of possible time values;
 if the limits are exceeded while encoding the time, an error results.
diff --git a/doc/misc/emacs-mime.texi b/doc/misc/emacs-mime.texi
index c411bf3d681..eb829b06124 100644
--- a/doc/misc/emacs-mime.texi
+++ b/doc/misc/emacs-mime.texi
@@ -1535,7 +1535,7 @@ Here's a bunch of time/date/second/day examples:
 
 @example
 (parse-time-string "Sat Sep 12 12:21:54 1998 +0200")
-@result{} (54 21 12 12 9 1998 6 -1 7200 0)
+@result{} (54 21 12 12 9 1998 6 -1 7200)
 
 (time-convert
   (date-to-time "Sat Sep 12 12:21:54 1998 +0200")