From f98c3f4426fecf794f47f27aebe1f3b854fb1bfd Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Wed, 20 Apr 2022 12:03:19 -0700 Subject: [PATCH] More encode-time pitfall doc fixes * doc/lispref/os.texi (Time Conversion): Improve discussion of encode-time pitfalls based on comments by Max Nikulin (Bug#54764#63). --- doc/lispref/os.texi | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index cabae08970..4138dab09f 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -1670,7 +1670,7 @@ Time Conversion convention, @var{dst} is @minus{}1 and @var{zone} defaults to the current time zone rule (@pxref{Time Zone Rules}). When modernizing an obsolescent caller, ensure that the more-modern -list equivalent contains 9 elements with a a @code{dst} element that +list equivalent contains 9 elements with a @code{dst} element that is @minus{}1, not @code{nil}. Year numbers less than 100 are not treated specially. If you want them @@ -1695,22 +1695,28 @@ Time Conversion For example: @lisp -;; Try to compute the time four years from now. +;; Try to compute the time one month from now. ;; Watch out; this might not work as expected. (let ((time (decode-time))) - (setf (decoded-time-year time) - (+ (decoded-time-year time) 4)) + (setf (decoded-time-month time) + (+ (decoded-time-month time) 1)) time) @end lisp @noindent Unfortunately, this code might not work as expected if the resulting -time is invalid due to daylight saving transitions, time zone changes, +time is invalid due to month length differences, +daylight saving transitions, time zone changes, or missing leap days or leap seconds. For example, if executed on -February 29, 2096 this code yields a nonexistent date because 2100 is -not a leap year. To avoid some (though not all) of the problem, you +January 30 this code yields a nonexistent date February 30, +which @code{encode-time} would adjust to early March. +Similarly, adding four years to February 29, 2096 would yield the +nonexistent date February 29, 2100; and adding one hour to 01:30 on +March 13, 2022 in New York would yield a timestamp 02:30 that does not +exist because clocks sprang forward from 02:00 to 03:00 that day. +To avoid some (though not all) of the problem, you can base calculations on the middle of the affected unit, e.g., start -at July 1 when adding years. Alternatively, you can use the +at the 15th of the month when adding months. Alternatively, you can use the @file{calendar} and @file{time-date} libraries. @end defun -- 2.32.0