How to use calendar-compare-date?

Question

I want to compare today's date with a saved date to see if the saved date is today's or before it. calendar-date-compare seems to be the function I need. The documentation C-h f calendar-date-compare reads,

calendar-date-compare is a compiled Lisp function.

(calendar-date-compare DATE1 DATE2)

Return t if DATE1 is before DATE2, nil otherwise.
The actual dates are in the car of DATE1 and DATE2.

But what are the types of of DATE1 & DATE2? I don't understand what to pass here! calendar-current-date returns a list that looks like this (9 5 2021) but that is not what calendar-date-compare expects as arguments.

Could someone help?

Answer 1

The last sentence in the doc string is the hint you need: The actual dates are in the car of DATE1 and DATE2. IOW, DATE1 and DATE2 are lists: each list's car (i.e. its first element) is the actual date; the rest of the elements in the list does not matter in the comparison, but presumably the calendar package defines the function this way for its own nefarious purposes.

So here is an example of its use:

(setq date1 '((9 5 2021) foo))
(setq date2 '((9 6 2021) bar))

(calendar-date-compare date1 date2)
===> t

where foo and bar are other elements of the lists that don't matter for the date comparison. For your purposes, you can just leave them out. What you cannot leave out is the extra set of parens: that's what makes each value a list whose car is the date (which is a list of three numbers: the month, the day and the year).