bug#74869: [PATCH] Add predicates for decoded times and time deltas

bug#74869: [PATCH] Add predicates for decoded times and time deltas

[Richard Lawrence]

[-- Attachment #1: Type: text/plain, Size: 1608 bytes --]

Tags: patch

This is a rough draft of a patch to add two new predicates related to
decoded times: `decoded-time-p', which checks that a value is a decoded
time (as documented in `decode-time'), and
`decoded-time-delta-p', which checks that a value is a time delta (as
documented in `decoded-time-add').

Some questions:

1) Should these functions go in simple.el? I put them there because that
is where the structure definition for decoded-time is. (The definition
does not generate a predicate automatically because it uses :type but
not :named; see Info node `(cl)Structures'.) But at least
`decoded-time-delta-p' might be better off in time-date.el, which is
where `decoded-time-add' is defined.

2) Should `decoded-time-p' also check the weekday slot of decoded times?
See the FIXME comment in the middle of the function: `make-decoded-time'
neither sets this slot nor provides an argument to let the caller set
it. This is apparently intentional: there is a comment in the
definition of `make-decoded-time',

  ;; Do not set decoded-time-weekday or decoded-time-dst,
  ;; as encode-time can infer them well enough when unknown.

but if the slot is not meant to be set I don't understand why it's
there. It would be useful, for iCalendar purposes, to have the weekday
slot automatically calculated from the date values when a decoded time
is constructed. I'm not sure if this use was just not envisioned, or if
there was a more substantial reason not to do it in make-decoded-time.

Hopefully I got the commit message right this time, but please let me
know if that needs tweaking too...

Best,
Richard


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-predicates-for-decoded-times-and-time-deltas.patch --]
[-- Type: text/patch, Size: 2621 bytes --]

From a9075f0dc459c1b3b0c3d2e4b7eb33553d7adac9 Mon Sep 17 00:00:00 2001
From: Richard Lawrence <rwl@recursewithless.net>
Date: Sat, 14 Dec 2024 16:36:45 +0100
Subject: [PATCH] Add predicates for decoded times and time deltas

* lisp/simple.el (decoded-time-p): Add predicate for decoded
times.
* lisp/simple.el (decoded-time-delta-p): Add predicate for time
deltas.
---
 lisp/simple.el | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/lisp/simple.el b/lisp/simple.el
index f2ee4a5df67..ac06a49402f 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -11228,6 +11228,41 @@ capitalize-dwim
 the number of seconds east of Greenwich.")
   )
 
+(defun decoded-time-p (val)
+  "Return non-nil if VAL is a decoded time.
+See `decode-time' for the expected format of VAL."
+  (and (listp val)
+       (length= val 9
+       ;; TODO: according to `decode-time', sec can also be a "Lisp
+       ;; timestamp"...is there a predicate for that?
+       (cl-typep (decoded-time-second val) '(integer 0 60))
+       (cl-typep (decoded-time-minute val) '(integer 0 59))
+       (cl-typep (decoded-time-hour val) '(integer 0 23))
+       (cl-typep (decoded-time-day val) '(integer 1 31))
+       ;; FIXME: the weekday slot value should ideally be automatically
+       ;; calculated from month, day, and year on construction, like:
+       ;;   (calendar-day-of-week (list month day year))
+       ;; `make-decoded-time' does not do this at present, and also has no
+       ;; option to set the weekday slot.
+       ;; (cl-typep (decoded-time-weekday val) '(integer 0 6))
+       (cl-typep (decoded-time-month val) '(integer 1 12))
+       (cl-typep (decoded-time-year val) 'integer)
+       (cl-typep (decoded-time-dst val) '(member t nil -1))
+       (cl-typep (decoded-time-zone val) '(or integer null)))))
+
+(defun decoded-time-delta-p (val)
+  "Return non-nil if VAL is a decoded time delta of the sort required by
+`decoded-time-add'."
+  (and (listp val)
+       (length= val 9)
+       ;; weekday, dst, zone can be ignored
+       (cl-typep (decoded-time-second val) '(or null integer))
+       (cl-typep (decoded-time-minute val) '(or null integer))
+       (cl-typep (decoded-time-hour val) '(or null integer))
+       (cl-typep (decoded-time-day val) '(or null integer))
+       (cl-typep (decoded-time-month val) '(or null integer))
+       (cl-typep (decoded-time-year val) '(or null integer))))
+
 ;; Document that decoded-time-dst is problematic on 6-element lists.
 ;; It should return -1 indicating unknown DST, but currently returns
 ;; nil indicating standard time.
-- 
2.39.5

bug#74869: [PATCH] Add predicates for decoded times and time deltas

[Richard Lawrence]

I'm also forwarding a mis-addressed email back to the relevant bug list

-------------------- Start of forwarded message --------------------
From: Richard Lawrence <rwl@recursewithless.net>
To: Paul Eggert <eggert@cs.ucla.edu>
Subject: Re: [PATCH] Add predicates for decoded times and time deltas
Date: Sun, 29 Dec 2024 09:05:03 +0100

Paul Eggert <eggert@cs.ucla.edu> writes:

> On 12/28/24 07:56, Richard Lawrence wrote:
>> I need to use
>> `calendar-extract-month' with a plain date value, but
>> `decoded-time-month' with a date-time value. I need type predicates to
>> do such dispatching.
>
> Not necessarily; you can instead try each function in turn and use the 
> first that works.

Well, in this case, they'll both "work" but can return incorrect values:
`calendar-extract-month' is just implemented as `car', so if I call it
on a decoded time, I'll get the seconds slot value rather than the month
slot value. Similarly, `decoded-time-second' will return the month if
called on a calendar date. 

If both calendar dates and decoded times were implemented as
records/cl-structs, rather than plain lists, then these accessor
functions could signal an error if passed a value of the wrong type. But
they aren't, and that doesn't seem likely to change anytime soon, so
having a predicate seems important.

> I have some qualms about saying that decoded times are a "type". Whether 
> a decoded time is valid depends on the timezone: (0 30 2 10 3 2024 0 t 
> -21600) is a valid decoded time in Phoenix but not in Denver, because 
> clocks sprang forward over that time in Denver but not in Phoenix. When 
> data interpretation gets that complicated, the Emacs notion of "type" is 
> not always the best.

I see. Would it help to change the name, or add some documentation, to
make it clear that the predicate doesn't (can't?) test for cases like
this? What about calling it something like `decoded-time-like-p' or
`maybe-decoded-time-p'? 

The iCalendar standard sets clear limits on the slot values, but these
aren't fine grained enough to rule out cases like the one you gave. All
it says is basically:

a date-time consists of a year, month, month-day, hour, minute, second,
  and (possibly) a UTC offset
a year is a four digit (positive) integer
a month is in the range 1-12
a month-day is in the range 1-28, 1-29, 1-30, or 1-31, depending on the
  month and year
an hour is in the range 0-23
a minute is in the range 0-59
a second is in the range 0-60 (60 represents a leap second)
a UTC offset is a sign together with an hour, minute, and second,
  where the second cannot be 60

So that's what the iCalendar code needs to check for. If it would be
better to keep this predicate in the iCalendar code, I can certainly do
that. I thought it would be more generally useful and should therefore
go with the existing code for decoded times, but maybe I was wrong about
that.

Best,
Richard
-------------------- End of forwarded message --------------------