Paydays, Last working days and why BYSETPOS is useful

Have you ever wondered how to represent important recurring events like a ‘payday’ or a last business day?

If your calendar application allows you to enter the “set position” along with other recurring rules, then you’ll need to know about BYSETPOS.

In a ical recurring event, the BYSETPOS is a comma separated list of numbers (1 to 366 or -1 to -366). It MUST be used with another ‘BY’ rule such as BYDAY, BYMONTH etc.

It “chooses” the ‘nth’ occurrence within a set of dates determined by the preceding rules.

For example, in a WEEKLY rule, the interval would be one week. (Remember to consider what the “start of the week” is for the set you are using). A set of recurrence instances starts at the beginning of the interval defined by the FREQ rule part.

Formal definition

For the formal definition see http://www.ietf.org/rfc/rfc5545.txt

Examples

The last work day of the month

FREQ=MONTHLY;BYDAY=MO,TU,WE,TH,FR;BYSETPOS=-1

‘PAY DAY’ – the last week day in the month!

RRULE:FREQ=MONTHLY;BYDAY=-1MO,-1TU,-1WE,-1TH,-1FR;BYSETPOS=-1

The 30th of every month; or the last day of the month if the 30th doesn’t exist

FREQ=MONTHLY;BYMONTHDAY=28,29,30;BYSETPOS=-1

For Developers

According to the very useful table of recurring rule precedence of page 43, the BYSETPOS is applied last within an iteration of the ‘FREQ’ on the set of dates generated by the rule.  If you programmaticaly follow the table logic, you should be able to avoid problems implementing BYSETPOS.