Fix ambiguity in nil DST flag

Formerly nil meant both that DST was not in effect and that
the DST flag was unknown, and different functions interpreted
the flag differently.  Now the meaning is consistently nil for
DST not in effect, and -1 for DST flag not known.
* doc/lispref/os.texi (Time Conversion): The DST slot is
now three-valued, not two-.
* doc/misc/emacs-mime.texi (time-date): Adjust to new behavior.
* etc/NEWS: Mention this.
* lisp/calendar/parse-time.el (parse-time-string):
* src/editfns.c (Fdecode_time):
Return -1 for unknown DST flag.
* test/lisp/calendar/parse-time-tests.el (parse-time-tests):
Adjust tests to match new behavior, and add a new
test for nil vs -1.

6 files changed, 32 insertions, 17 deletions

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 0b9dd1c9cc3..43ca9ede00b 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1423,7 +1423,8 @@ The year, an integer typically greater than 1900.
 The day of week, as an integer between 0 and 6, where 0 stands for
 Sunday.
 @item dst
-@code{t} if daylight saving time is effect, otherwise @code{nil}.
+@code{t} if daylight saving time is effect, @code{nil} if it is not
+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.
diff --git a/doc/misc/emacs-mime.texi b/doc/misc/emacs-mime.texi
index b71cc3755bf..45f37fb8557 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 nil 7200)
+@result{} (54 21 12 12 9 1998 6 -1 7200)
 
 (date-to-time "Sat Sep 12 12:21:54 1998 +0200")
 @result{} (13818 19266)
diff --git a/etc/NEWS b/etc/NEWS
index 736955be0cb..2158fdc10dd 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1060,6 +1060,14 @@ a multibyte string even if its second argument is an ASCII character.
 ** (format "%d" X) no longer mishandles a floating-point number X that
 does not fit in a machine integer.
 
++++
+** In the DST slot, encode-time and parse-time-string now return -1
+if it is not known whether daylight saving time is in effect.
+Formerly they were inconsistent: encode-time returned t in this
+situation, whereas parse-time-string returned nil.  Now they
+consistently use use nil to mean that DST is not in effect, and use -1
+to mean that it is not known whether DST is in effect.
+
 ** New JSON parsing and serialization functions 'json-serialize',
 'json-insert', 'json-parse-string', and 'json-parse-buffer'.  These
 are implemented in C using the Jansson library.
diff --git a/lisp/calendar/parse-time.el b/lisp/calendar/parse-time.el
index 2f9e557dabc..d6c1e9ea169 100644
--- a/lisp/calendar/parse-time.el
+++ b/lisp/calendar/parse-time.el
@@ -29,8 +29,9 @@
 
 ;; `parse-time-string' parses a time in a string and returns a list of 9
 ;; values, just like `decode-time', where unspecified elements in the
-;; string are returned as nil.  `encode-time' may be applied on these
-;; values to obtain an internal time value.
+;; string are returned as nil (except unspecfied DST is returned as -1).
+;; `encode-time' may be applied on these values to obtain an internal
+;; time value.
 
 ;;; Code:
 
@@ -151,8 +152,9 @@ STRING should be on something resembling an RFC2822 string, a la
 somewhat liberal in what format it accepts, and will attempt to
 return a \"likely\" value even for somewhat malformed strings.
 The values returned are identical to those of `decode-time', but
-any values that are unknown are returned as nil."
-  (let ((time (list nil nil nil nil nil nil nil nil nil))
+any unknown values other than DST are returned as nil, and an
+unknown DST value is returned as -1."
+  (let ((time (list nil nil nil nil nil nil nil -1 nil))
         (temp (parse-time-tokenize (downcase string))))
     (while temp
       (let ((parse-time-elt (pop temp))
diff --git a/src/editfns.c b/src/editfns.c
index 8c7491beedc..047a73f0b8c 100644
--- a/src/editfns.c
+++ b/src/editfns.c
@@ -2165,7 +2165,8 @@ between 0 and 23.  DAY is an integer between 1 and 31.  MONTH is an
 integer between 1 and 12.  YEAR is an integer indicating the
 four-digit year.  DOW is the day of week, an integer between 0 and 6,
 where 0 is Sunday.  DST is t if daylight saving time is in effect,
-otherwise nil.  UTCOFF is an integer indicating the UTC offset in
+nil if it is not in effect, and -1 if this information is
+not available.  UTCOFF is an integer indicating the UTC offset in
 seconds, i.e., the number of seconds east of Greenwich.  (Note that
 Common Lisp has different meanings for DOW and UTCOFF.)
 
@@ -2194,7 +2195,8 @@ usage: (decode-time &optional TIME ZONE)  */)
                 make_fixnum (local_tm.tm_mon + 1),
                 make_fixnum (local_tm.tm_year + tm_year_base),
                 make_fixnum (local_tm.tm_wday),
-                local_tm.tm_isdst ? Qt : Qnil,
+                (local_tm.tm_isdst < 0 ? make_fixnum (-1)
+                 : local_tm.tm_isdst == 0 ? Qnil : Qt),
                 (HAVE_TM_GMTOFF
                  ? make_fixnum (tm_gmtoff (&local_tm))
                  : gmtime_r (&time_spec, &gmt_tm)
diff --git a/test/lisp/calendar/parse-time-tests.el b/test/lisp/calendar/parse-time-tests.el
index 3a956a56621..9689997f793 100644
--- a/test/lisp/calendar/parse-time-tests.el
+++ b/test/lisp/calendar/parse-time-tests.el
@@ -28,21 +28,23 @@
 
 (ert-deftest parse-time-tests ()
   (should (equal (parse-time-string "Mon, 22 Feb 2016 19:35:42 +0100")
-                 '(42 35 19 22 2 2016 1 nil 3600)))
+                 '(42 35 19 22 2 2016 1 -1 3600)))
   (should (equal (parse-time-string "22 Feb 2016 19:35:42 +0100")
-                 '(42 35 19 22 2 2016 nil nil 3600)))
+                 '(42 35 19 22 2 2016 nil -1 3600)))
   (should (equal (parse-time-string "22 Feb 2016 +0100")
-                 '(nil nil nil 22 2 2016 nil nil 3600)))
+                 '(nil nil nil 22 2 2016 nil -1 3600)))
   (should (equal (parse-time-string "Mon, 22 Feb 16 19:35:42 +0100")
-                 '(42 35 19 22 2 2016 1 nil 3600)))
+                 '(42 35 19 22 2 2016 1 -1 3600)))
   (should (equal (parse-time-string "Mon, 22 February 2016 19:35:42 +0100")
-                 '(42 35 19 22 2 2016 1 nil 3600)))
+                 '(42 35 19 22 2 2016 1 -1 3600)))
   (should (equal (parse-time-string "Mon, 22 feb 2016 19:35:42 +0100")
-                 '(42 35 19 22 2 2016 1 nil 3600)))
+                 '(42 35 19 22 2 2016 1 -1 3600)))
   (should (equal (parse-time-string "Monday, 22 february 2016 19:35:42 +0100")
-                 '(42 35 19 22 2 2016 1 nil 3600)))
-  (should (equal (parse-time-string "Monday, 22 february 2016 19:35:42 PDT")
-                 '(42 35 19 22 2 2016 1 t -25200)))
+                 '(42 35 19 22 2 2016 1 -1 3600)))
+  (should (equal (parse-time-string "Monday, 22 february 2016 19:35:42 PST")
+                 '(42 35 19 22 2 2016 1 nil -28800)))
+  (should (equal (parse-time-string "Friday, 21 Sep 2018 13:47:58 PDT")
+                 '(58 47 13 21 9 2018 5 t -25200)))
   (should (equal (parse-iso8601-time-string "1998-09-12T12:21:54-0200")
                  '(13818 33666)))
   (should (equal (parse-iso8601-time-string "1998-09-12T12:21:54-0230")