week-number

Arguments: ut &key (first-day-of-week :monday)

The value returned by week-number 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 the week number of the universal time ut, which must be a non-negative integer and is interpreted as a universal time (see get-universal-time). The week number is defined in detail below but in short, the first full (7-day) week in the year is week 1. The partial week prior to week 1 is week 0. (If January 1 falls on the first-day-of-week, then there is no week 0.) Weeks are numbered sequentially after week 1. The return value is an integer in the range 0 to 53.

The first-day-of-week keyword argument allows you to specify :monday (the default) or :sunday as the week's start. :sunday and :modnday are the only allowable values for this argument.

The week number is calculated as follows: if January 1 falls on the first-day-of-week day, week there is no week 0 and week number 1 is January 1 through January 7, week number 2 is January 8 through January 14, and so on, with the last complete seven day week being week 52, December 24 through December 30 (in a non-leap year), December 23 through December 29 in a leap year, and week 53 is the one day week, December 31 only, in a non-leap year, and the two day week December 30 and 31 in a leap year.

If January 1 is not the first-day-of-week day, then there is a week 0 and it contains less than seven days, from January 1 through the day before the first-day-of-week day, the next seven days are week 1, and so on until the end of the year where, in a non-leap year, week 52 contains December 31 and seven less than the number of days from January 1 to the first-day-of-week day other days (so seven days if January 1 is the day before the first day of the week, six days if Janyaury 1 is two days before the first day of the week, and so on).

In a leap year, week 52 contain one day more unless January 1 is the day before the first-day-of-week day, in which case week 52 contains seven days and week 53 contains only December 31.

Leap years having 54 numbered weeks (0 through 53) are a bit confusing so here is an example. Consider the year 2012 (a leap year) and suppose the first-day-of-week day is the default, :monday. January 1, 2012 is a Sunday and December 31, 2012, is a Monday. Week 0 contains January 1 only. Weeks 1 through 52 all contain 7 days, with week 52 ending on Sunday, December 30 (which is day 365, 364 days after January 1, since 2016 is a leap year). Week 53 contains the single day, Monday, December 31.

;; 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.

;; January 1, 2012 was a Sunday. January 5 the following Thursday, and
;; January 30 a Monday. Here are the universal times for noon on those
;; days:
cl-user(46): (setq ut010112 (encode-universal-time 0 0 12 1 1 2012))
3534436800
cl-user(47): (setq ut050112 (encode-universal-time 0 0 12 5 1 2012))
3534782400
cl-user(48): (setq ut300112 (encode-universal-time 0 0 12 30 1 2012))
3536942400
cl-user(49): 

(week-number ut010112) RETURNS 0 ;; When January 1 is not the first day
                                 ;; of the week, there is a week 0
                                 ;; and it has fewer that 7 days
(week-number ut050112) RETURNS 1 ;; The default first-day-of-week is
                                 ;; :monday so Thursday, January 5
                                 ;; is in week 1
(week-number ut050112 :first-day-of-week :sunday) RETURNS 1
                                 ;; Sunday, January 1 falls on the 
                                 ;; first day of the week so there 
                                 ;; is no week 0 and week 1 is
                                 ;; January 1 through January 7,
                                 ;; which includes January 5

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.