day-difference

Arguments: start end &key work-days

The value returned by day-difference and related functions depends on the time zone where the machine running Lisp is located and also on whether daylight saving time is in effect. See the discussion in Day and date calculation functions and their relation to time zones in miscellaneous.htm for examples of how time zone and daylight saving time can affect results.

This function performs calculations on the day/date portion of a universal time, that is the decoded universal time ignoring the second, minute, and hour values (see decode-universal-time).

start and end must be non-negative integers which are interpreted as univeral times (see get-universal-time). This function returns the number of days between start and end, completely ignoring the time of day portion of the time values. When start and end represent the same day, this function returns 0.

If work-days is nil (the default), all days are considered. When work-days is true, Saturdays and Sundays are not counted.

If work-days is nil, the start date is always included and the end date is never included in the returned count, and the return value for consecutive days is 1.

If work-days is true, the situation is more complicated. The start date is included if it is a weekday but not if it is a Saturday or Sunday. The end date is again never included. The return value for consecutive days is 0 if start is a Saturday or Sunday and is 1 if start is any other day. So:

;; *friday*, *saturday*, *sunday*, and *monday* are universal times
;; representing consecutive dates which fall on a Friday, Saturday, 
;; Sunday, and Monday, respectively.

(day-difference *sunday* *monday* :work-days t) RETURNS 0
(day-difference *saturday* *sunday* :work-days t) RETURNS 0
(day-difference *friday* *saturday* :work-days t) RETURNS 1

;; and also

(day-difference *saturday* *monday* :work-days t) RETURNS 0
(day-difference *friday* *sunday* :work-days t) RETURNS 1
(day-difference *friday* *monday* :work-days t) RETURNS 1

If start is greater than end, the negative of the day-difference between end and start is returned.

If date1 <= date2 <= date3, then

(= (day-difference date1 date3 :work-days *wd*) 
   (+  (day-difference date1 date2 :work-days *wd*)
       (day-difference date2 date3 :work-days *wd*)))
;; for any value of *wd*.

Note: only proper Common Lisp universal times (that is, non-negative integers representing seconds since midnight 1/1/1900 GMT) are supported. Negative universal times, supported in the date-time module (see date-time.htm), are not supported by this function.

Examples

;; Results depend on the timezone value and whether daylight saving
;; time is in effect. These are not settable by this function and
;; the values are inherited from the Operating system. To see them,
;; evaluate (decode-universal-time (get-universal-time)):

cl-user(29): (decode-universal-time (get-universal-time))
RETURNS 11 38 14 5 12 2017 1 nil 8

;; That form was evaluated at 2:38:11 PM (14:38:11) on Tuesday,
;; December 5 at Franz Inc. HQ in Oakland, California. The eighth
;; return value (nil) indicates daylight saving time was not in effect.
;; The ninth return value (8) means the timezone was 8, 8 hours
;; earlier than Greenwich Mean Time (GMT). If you are in a different
;; location or the date is different, you will get different values.

(day-difference
 (string-to-universal-time "2000-01-02T15:16:17-08:00")
 (string-to-universal-time "2001-01-02T15:16:17-08:00"))
RETURNS 366 ;; the year 2000 was a leap year

(day-difference
 (string-to-universal-time "2001-01-02T15:16:17-08:00")
 (string-to-universal-time "2002-01-02T15:16:17-08:00"))
RETURNS 365  ;; the year 2001 was not a leap year

(day-difference
 (string-to-universal-time "2002-01-02T15:16:17-08:00")
 (string-to-universal-time "2001-01-02T15:16:17-08:00"))
RETURNS -365  ;; same as previous example with the arguments reversed.
              ;; When START is greater than END, the value is negative or 0.

(day-difference
 (string-to-universal-time "2001-01-01T00:00:01-08:00")
 (string-to-universal-time "2001-01-01T23:59:59-08:00"))
RETURNS 0 ;; the DAY-DIFFERENCE of times on the same day is 0

(day-difference
 (string-to-universal-time "2017-08-20") ; Sun
 (string-to-universal-time "2017-08-26") ; the next Sat
 )
RETURNS 6

(day-difference
 (string-to-universal-time "2017-08-20") ; Sun
 (string-to-universal-time "2017-08-27") ; The next Sun
 )
RETURNS 7

;; Same times as the previous examples, but only counting work days
(day-difference
 (string-to-universal-time "2017-08-20") ; Sun
 (string-to-universal-time "2017-08-26") ; the next Sat
 :work-days t)
RETURNS 5

(day-difference
 (string-to-universal-time "2017-08-20") ; Sun
 (string-to-universal-time "2017-08-27") ; The next Sun
 :work-days t)
RETURNS 5

;; Consecutive days return 1 when WORK-DAYS is NIL:
(day-difference
 (string-to-universal-time "2017-08-20") ; Sun
 (string-to-universal-time "2017-08-21") ; the following Mon
 )
RETURNS 1

;; Consecutive days return 0 or 1 when WORK-DAYS is true
;; depending on whether START is a SATURDAY or SUNDAY or not:
(day-difference
 (string-to-universal-time "2017-08-20") ; Sun
 (string-to-universal-time "2017-08-21") ; the following Mon
 :work-days t)
RETURNS 0

(day-difference
 (string-to-universal-time "2017-08-19") ; Sat
 (string-to-universal-time "2017-08-20") ; the following Sun
 :work-days t)
RETURNS 0

(day-difference
 (string-to-universal-time "2017-08-18") ; Fri
 (string-to-universal-time "2017-08-19") ; the following Sat
 :work-days t)
RETURNS 1

See Day and date calculation functions and their relation to time zones in miscellaneous.htm for more information on this and related functions.

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page is new in the 10.1 release.
Created 2019.8.20.