[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
emacs-29 0ea2d6d9e82 1/2: Document that time-to-days and days-to-time us
From: |
Eli Zaretskii |
Subject: |
emacs-29 0ea2d6d9e82 1/2: Document that time-to-days and days-to-time use different epochs |
Date: |
Sat, 14 Oct 2023 05:01:08 -0400 (EDT) |
branch: emacs-29
commit 0ea2d6d9e82d2f88af4545f4b74c48989bf3415d
Author: Bob Rogers <rogers@rgrjr.com>
Commit: Eli Zaretskii <eliz@gnu.org>
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))