date+

Arguments: ut number-of-days &key work-days

The value returned by date+ 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).

This function returns a universal time whose year/month/date is number-of-days later than the year/month/date of ut. ut must be a non-negative integer and is interpreted as a universal time (see get-universal-time). If work-days is specified true, then Saturdays and Sundays are not counted in the calculation. The hour, minute, and second of the returned universal time may be different from the hour, minute, and second of ut.

So if ut falls on a Friday, (date+ ut 2 :work-days nil) falls on a Sunday and (date+ ut 2 :work-days t) falls on a Tuesday. See Examples below for more 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.

cl-user(106): (setq ut-fri (encode-universal-time 0 0 12 1 12 2017))
3721104012  ;; Friday, December 1, 2017
cl-user(107): (setq ut-sat (encode-universal-time 0 0 12 2 12 2017))
3721233600  ;; Saturday, December 2, 2017
cl-user(110): (day-number ut-fri)
335
cl-user(111): (setq ut-fri-plus-3 (date+ ut-fri 3))
3721363212
cl-user(112): (day-number ut-fri-plus-3)
338  ;; 3 days after Friday, December 1, 2017
cl-user(115): (setq ut-fri-plus-3w (date+ ut-fri 3 :work-days t))
3721536012
cl-user(116): (day-number ut-fri-plus-3w)
340  ;; 5 days after Friday, December 1, 2017 becaue Saturday and Sunday
     ;; are not counted
cl-user(117): (day-of-week ut-fri-plus-3w)
2  ;; Wednesday
cl-user(118): (setq ut-sat-plus-1 (date+ ut-sat 1))
3721320000
cl-user(119): (day-of-week ut-sat-plus-1)
6  ;; Sunday
cl-user(121): (setq ut-sat-plus-1w (date+ ut-sat 1 :work-days t))
3721406400
cl-user(122): (day-of-week ut-sat-plus-1w)
0  ;; Monday
cl-user(123): 

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.