| Allegro CL version 10.1New since the initial 10.1 release. |

**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

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.

| Allegro CL version 10.1New since the initial 10.1 release. |