Week Numbering

Today (Thursday, 23 November 2017) is in

A frequent problem in the world is the use of week numbers. Different parts of the world have tended to use different algorithms to calculate the week number, and confusion has resulted.

There is a solution: the International Standards Organisation (ISO) standard ISO8601:1988 defines week numbers.

ISO make their money from paper copies of standards, so the standard itself is not on line. However there is a number of abstracts available on the Web:


ISO 8601:1988 Week Number rules

To save you reading all 14 pages of ISO 8601:1988, it says this about week numbers:

January Calendars (1998-2000)

1998
Week NumberMonTueWedThuFriSatSun
1998W01293031 1 2 3 4
1998W02 5 6 7 8 9 10 11
1998W03 12 13 14 15 16 17 18
1998W04 19 20 21 22 23 24 25
1998W05 26 27 28 29 30 311
1999
Week NumberMonTueWedThuFriSatSun
1998W5328293031123
1999W01 4 5 6 7 8 910
1999W02 11 12 13 14 15 16 17
1999W03 18 19 20 21 22 23 24
1999W04 25 26 27 28 29 3031
2000
Week NumberMonTueWedThuFriSatSun
1999W52272829303112
2000W01 3 4 5 6 7 89
2000W02 10 11 12 13 14 15 16
2000W03 17 18 19 20 21 22 23
2000W04 24 25 26 27 28 2930
2000W05 31 123456

Updating scripts etc.

Finding the week number from a date

Modern flavours of Unix libraries support the ISO 8601:1988 week numbering within strftime() with the %V format character. For example, date +%V under most circumstances returns ISO 8601:1988 week numbers.
However there are often problems at the year transition - such as returning week 00 instead of the last week (52/53) of the previous year, or changing from week 53 to week 01 part way through the week.
For example:
Sat Dec 27 12:00:00 1980 = 1980W52
Sun Dec 28 12:00:00 1980 = 1980W52
Mon Dec 29 12:00:00 1980 = 1980W53 <==
Tue Dec 30 12:00:00 1980 = 1980W53 <==
Wed Dec 31 12:00:00 1980 = 1980W53 <==
Thu Jan 01 12:00:00 1981 = 1981W01
Fri Jan 02 12:00:00 1981 = 1981W01

As Tcl and Perl use strftime() for their time routines, the same applies.

With systems which support the %V format character in strftime(), one can put some extra checks in to solve the problem at the year transition. For example, here is a Tcl routine for calculating ISO 8601:1988 week numbers.

For older flavours of Unix which don't support the %V format character in strftime(), I have written a utility in C to return the ISO 8601:1988 week number in the format specified in the standard, e.g. 1998W25
I've ported the C code to a Perl script to return the ISO 8601:1988 week number in the format specified in the standard, e.g. 1998W25. It's not neat Perl, but it gives the same results as the C code for my test program.

Finding the date from a week number

Sometimes when needs to know when a particular week is. I've written C code to return the date of the start of the week given the week number. It returns -1/-1/<year> if given a bogus week 53. There's some examples of week numbers and their start dates resulting from running this code.

There's also Perl library code to return the time since the epoch of the start of the week given the week number, which can be used with Perl code to return the date of the start of the week given the week number.

Calendar with week numbers

Perl code for a cal "replacement" which works to ISO8601 and shows week numbers

Another Perl approach

Since writing my own routines, I've found that the Perl Date::Manip module can do ISO week numbers with ease.

Seriously geeky stuff on year types and week numbers

There's some seriously geeky stuff on year types and week numbers if you want to get deep down into my code.
This information provided by
Andrew Benham

e-mail Andrew Benham