dlowe-net/local-time — pull request #5 by felideon (2012-11-01 14:14:50+00:00)
Title: Implement support for ISO week dates

Probably not used very often, but having ISO week date formatting as a part of local-time would be nice to have. It makes sense for certain accounting/financial applications, and for retail/government according to Wikipedia. Personally, I am hacking on a side project where week manipulation is central.

##### For reference: #####
http://en.wikipedia.org/wiki/ISO_week_date
http://en.wikipedia.org/wiki/ISO_8601#Week_dates

Allegro's date-time API also has support for this and exposes some `date-time-ywd-*` functions:
http://www.franz.com/support/documentation/current/doc/date-time.htm#dt-classes-1

##### Implementation: #####
The implementation is actually very simple thanks to some existing local-time functions and the following algorithm:
http://en.wikipedia.org/wiki/Talk:ISO_week_date#Algorithms

I started out by including three new values* to `decode-timestamp`, but this proved (perhaps) to be wrong as it caused the `encode-timestamp` arglist to become incongruent with the values returned by `decode-timestamp` , failing a test in the project's test suite. Instead, I wrapped the values in a new m-v-b form around the 'beef' in `%construct-timestring`.

Formatted-string tests for this feature are also included in this pull request.

##### Notes: #####
The three values are mapped to the following keywords for `format-timestring`:
`:ISO-WEEK-YEAR`, `:ISO-WEEK-NUMBER`, `:ISO-WEEK-DAY`

The first and last of these, which seem to be redundant, are due to the following:
* The ISO week year can be different than the regular Gregorian calendar year, as an ISO week-numbering year can have 52 or 53 full weeks. http://en.wikipedia.org/wiki/ISO_week_date#Weeks_per_year

* The weekday number is different than the default (assumed) Sunday=0/Saturday=6 convention. In ISO week date format, Monday=1 and Sunday=7.

##### Future consideration: #####
One thing I was on the fence about was whether to expose the ISO week date decoding function in the API. I kept it private for now, as it would be rare to want to have the ISO week number, for example, in isolation from the ISO week year. Conversely, Allegro's API does have this flexibility. For now, it should be easy enough to use `format-timestring` and split the string to get the individual week date components.

There may also be room to better naming conventions than the ones I chose. :)