GNU bug report logs - #66502
30.0.50; [PATCH; DOC] time-to-days and days-to-time use different epochs

Previous Next

Full log

View this message in rfc822 format

From: help-debbugs <at> gnu.org (GNU bug Tracking System)
To: Bob Rogers <rogers <at> rgrjr.com>
Subject: bug#66502: closed (Re: bug#66502: 30.0.50; [PATCH; DOC]
 time-to-days and days-to-time use different epochs)
Date: Sat, 14 Oct 2023 09:03:02 +0000

[Message part 1 (text/plain, inline)]

Your bug report

#66502: 30.0.50; [PATCH; DOC] time-to-days and days-to-time use different epochs

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to 66502 <at> debbugs.gnu.org.

-- 
66502: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=66502
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems

[Message part 2 (message/rfc822, inline)]

From: Eli Zaretskii <eliz <at> gnu.org>
To: Bob Rogers <rogers <at> rgrjr.com>
Cc: 66502-done <at> debbugs.gnu.org
Subject: Re: bug#66502: 30.0.50; [PATCH;
 DOC] time-to-days and days-to-time use different epochs
Date: Sat, 14 Oct 2023 12:02:10 +0300

> From: Bob Rogers <rogers <at> rgrjr.com>
> Date: Thu, 12 Oct 2023 10:23:35 -0700
> 
>    Imagine my surprise when converting back using days-to-time gave me
> something almost two millenia in the future.  Of course, the problem was
> that days-to-time uses a different epoch from time-to-days.  The fix was
> pretty easy . . . and then I discovered all the code that depends on the
> existing behavior.  So I offer the following modest documentation patch,
> in the hope that others will be spared any similar confusion.

Thanks, installed on the emacs-29 branch, and closing the bug.

Please in the future accompany the patches by a ChangeLog-style commit
log message, it makes the patches easier to install.

[Message part 3 (message/rfc822, inline)]

From: Bob Rogers <rogers <at> rgrjr.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 30.0.50; [PATCH;
 DOC] time-to-days and days-to-time use different epochs
Date: Thu, 12 Oct 2023 10:23:35 -0700

[Message part 4 (text/plain, inline)]

   Imagine my surprise when converting back using days-to-time gave me
something almost two millenia in the future.  Of course, the problem was
that days-to-time uses a different epoch from time-to-days.  The fix was
pretty easy . . . and then I discovered all the code that depends on the
existing behavior.  So I offer the following modest documentation patch,
in the hope that others will be spared any similar confusion.

					-- Bob Rogers
					   http://www.rgrjr.com/

[rgr-days-to-time-doc-1.patch (text/x-patch, inline)]

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 5400d492f0a..2f6bb4e190c 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -2127,6 +2127,14 @@ Time Calculations
 The operating system limits the range of time and zone values.
 @end defun
 
+@defun days-to-time days
+This is not quite the inverse of the @code{time-to-days} function, as
+it uses the Emacs epoch (instead of the year 1) for historical
+reasons.  To get the inverse, subtract @code{(time-to-days 0)} from
+@var{days}, in which case @code{days-to-time} may return @code{nil} if
+@var{days} is negative.
+@end defun
+
 @defun time-to-day-in-year time-value
 This returns the day number within the year corresponding to @var{time-value},
 assuming the default time zone.
diff --git a/lisp/calendar/time-date.el b/lisp/calendar/time-date.el
index 9cbe8e0f53c..786134d8ac5 100644
--- a/lisp/calendar/time-date.el
+++ b/lisp/calendar/time-date.el
@@ -181,7 +181,10 @@ seconds-to-time
 
 ;;;###autoload
 (defun days-to-time (days)
-  "Convert DAYS into a time value."
+  "Convert Emacs-epoch DAYS into a time value.
+Note that this does not use the same epoch as time-to-days; you
+must subtract (time-to-days 0) first to convert, and may get nil
+if the result is before the start."
   ;; FIXME: We should likely just pass `t' to `time-convert'.
   ;; All uses I could find in Emacs, GNU ELPA, and NonGNU ELPA can handle
   ;; any valid time representation as return value.
@@ -243,7 +246,7 @@ time-to-day-in-year
 
 ;;;###autoload
 (defun time-to-days (time)
-  "The absolute date corresponding to TIME, a time value.
+  "The absolute pseudo-Gregorian date for TIME, a time value.
 The absolute date is the number of days elapsed since the imaginary
 Gregorian date Sunday, December 31, 1 BC."
   (let* ((tim (decode-time time))

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.