## New day and date functions

A patch released in late November, 2017 for Allegro CL 10.1 provides a suite of functions for calculating elapsed days, doing things such as determining the number of days between universal times, determining whether two universal times occur on the same day, and so on. See Day and date calculation functions in miscellaneous.htm for the documentation of the new functions. All of the new functions are named by symbols in the :excl package.

In this note, we discuss the new functions and point out some subtleties when using them.

### Definition of days elapsed

The day of a universal time is determined by the year, month, and day of the month, ignoring the time of day. Thus consider time1, 23:59:59 on the 1st of March, 2011, and time2, 00:00:01 on the 2nd of March, 2011. Those times are two seconds apart but are considered one day apart by the day/date calculation functions.

One of the new functions is date+. This function takes a universal time and a number of days as arguments and returns a new universal time which falls on the day which is the number of days later than the argument universal time. Note, however, the time of day of the result universal time may not be the same time of day as the argument universal time.

### The importance of time zones

Right now it is 18:30:00 (6:30 pm) on Thursday, the 4th of January, 2018 (universal time 3724108200). At least, that is the time, day, and date for the writer of this article, who is on the west coast of the United States in the Pacific Standard Time Zone, 8 time zones west of Greenwich, England. In Greenwich, it is 02:30:00 (2:30 am) on Friday, the 5th of January, 2018 (but the same universal time).

Now consider the time 9 hours later (universal time 3724140600), for me 03:30:00 (3:30 am) on Friday, the 5th of January. In Greenwich, it is 11:30:00 (11:30 am), also on Friday, the 5th of January. The function day-difference takes two universal times and calculates the number of days between them. For me, sitting in California, day-difference returns 1. For someone sitting in Greenwich, it returns 0.

The values returned by the various day/date functions depends on the time zone in which they are evaluated. That time zone is specified in you computer set up and Allegro CL is simply polling the operating system to discover the time zone. At the moment, there is no way to select a time zone for these functions to use: they use the machine time zone. Be aware that running the same code different places in the world may produce different results.

### Work days

The two functions already mentioned, date+ and day-difference both take a work-days keyword argument. If specified true, then Satrudays and Sundays are not counted, so if ut1 and ut2 are universal times, with ut1 falling on a Friday and ut2 on the following Monday:

(day-difference ut1 ut2 :work-days nil) RETURNS 3
(day-difference ut1 ut2 :work-days t) RETURNS 1

(date+ ut1 1 :work-days nil) RETURNS a time on Saturday, the day after ut1
(date+ ut1 1 :work-days t) RETURNS a time on Monday, three days after ut1

### Day comparison functions

Functions like date=, date>, and so on (see documented in Day and date calculation functions for a complete list) take two universal times and return true or nil as the times fall on the same day (for date=), or the first falls on a later day (for date>).

### Only proper universal times are supported

All universal time arguments to day/date functions must be non-negative integers. Other Allegro CL time and date functions, described in date-time.htm, do accept negative universal times (indicating times prior of 00:00:00 on the 1st of January, 1900 GMT) but these day/date functions do not.

### Examples

;; All day/date functions are named by symbols in the :excl package.
;; No module needs to be loaded to use the functionality (once the update
;; has been applied).
;;
;; Recall from above universal time 3724108200 is 18:30:00 Janunay 4, 2018
;; in time zone PST and 02:30:00 January 5, 2018 in GMT, while
;; universal time 3724140600 is 03:30:00 on January 5, 2018 in PST
;; and 11:30:00 on January 5, 2018 in GMT.

(setq ut1 3724108200)
(setq ut2 3724140600)

(date= ut1 ut2) RETUNRN nil in PST and t in GMT

cl-user(27): (date+ ut1 6)
3724626600
cl-user(28): (decode-universal-time 3724626600)
0 30 18 10 1 2018 2 nil 8 ;; the last three values are
;; day of the week (2=Wednesday),
;; whether daylight savings time is on effect (no)
;; and the time zone (8 west of GMT)
cl-user(29): (date+ ut1 6 :work-days t)
3724799400
cl-user(30): (decode-universal-time 3724799400)
0 30 18 12 1 2018 4 nil 8 ;; the last three values are
;; day of the week (4=Friday),
;; whether daylight savings time is on effect (no)
;; and the time zone (8 west of GMT)
cl-user(31):