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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 66502 in the body.
You can then email your comments to 66502 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

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 1 (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))

Message #10 received at 66502-done <at> debbugs.gnu.org (full text, mbox):

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 #13 received at 66502-done <at> debbugs.gnu.org (full text, mbox):

From: Bob Rogers <rogers <at> rgrjr.com>
To: Eli Zaretskii <eliz <at> gnu.org>
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 07:19:46 -0700

   From: Eli Zaretskii <eliz <at> gnu.org>
   Date: Sat, 14 Oct 2023 12:02:10 +0300

   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.

Oops; I didn't do that, because I thought doc patches didn't need a
ChangeLog message.  In hindsight, they need at least a commit message,
so that was pretty silly.

					-- Bob

Message #16 received at 66502-done <at> debbugs.gnu.org (full text, mbox):

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 18:38:04 +0300

> From: Bob Rogers <rogers <at> rgrjr.com>
> Date: Sat, 14 Oct 2023 07:19:46 -0700
> CC: 66502-done <at> debbugs.gnu.org
> 
>    From: Eli Zaretskii <eliz <at> gnu.org>
>    Date: Sat, 14 Oct 2023 12:02:10 +0300
> 
>    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.
> 
> Oops; I didn't do that, because I thought doc patches didn't need a
> ChangeLog message.  In hindsight, they need at least a commit message,
> so that was pretty silly.

Yes.  What happened isn't a catastrophe: I typed the message for you.
It just takes more time and more manual work, so is best avoided.

TIA

Message #19 received at 66502-done <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Bob Rogers <rogers <at> rgrjr.com>
Cc: eliz <at> gnu.org, 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: Sun, 15 Oct 2023 22:02:57 -0400

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Oops; I didn't do that, because I thought doc patches didn't need a
  > ChangeLog message.  In hindsight, they need at least a commit message,
  > so that was pretty silly.

the commit message should list what entities you changed, added or
deleted: that is, the doc strings of which functions or variables etc.
And, in a general sense, what the change was about.

Please look at doc string change logs in some of the principal files.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Message #22 received at 66502-done <at> debbugs.gnu.org (full text, mbox):

From: Bob Rogers <rogers <at> rgrjr.com>
To: rms <at> gnu.org
Cc: eliz <at> gnu.org, 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: Sun, 15 Oct 2023 22:39:12 -0700

   From: Richard Stallman <rms <at> gnu.org>
   Date: Sun, 15 Oct 2023 22:02:57 -0400

   [[[ To any NSA and FBI agents reading my email: please consider    ]]]
   [[[ whether defending the US Constitution against all enemies,     ]]]
   [[[ foreign or domestic, requires you to follow Snowden's example. ]]]

     > Oops; I didn't do that, because I thought doc patches didn't need a
     > ChangeLog message.  In hindsight, they need at least a commit message,
     > so that was pretty silly.

   the commit message should list what entities you changed, added or
   deleted: that is, the doc strings of which functions or variables etc.
   And, in a general sense, what the change was about.

   Please look at doc string change logs in some of the principal files.

Thank you, Richard; I realize what I should have done, and how I should
have done it, I just spaced out in this instance.

					-- Bob

Previous Next

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