From 0ea2d6d9e82d2f88af4545f4b74c48989bf3415d Mon Sep 17 00:00:00 2001 From: Bob Rogers Date: Thu, 12 Oct 2023 10:23:35 -0700 Subject: [PATCH] Document that time-to-days and days-to-time use different epochs * doc/lispref/os.texi (Time Calculations): * lisp/calendar/time-date.el (days-to-time, time-to-days): Doc fixes. (Bug#66502) --- doc/lispref/os.texi | 8 ++++++++ lisp/calendar/time-date.el | 7 +++++-- 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index 7c8b35236cd..ea27af8edb2 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -2104,6 +2104,14 @@ This function returns the number of days between the beginning of year 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 @@ If DATE lacks timezone information, GMT is assumed." ;;;###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 @@ DATE1 and DATE2 should be date-time strings." ;;;###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)) -- 2.39.2