Good interactive tool: https://jkbrzt.github.io/rrule/
Good explanatory page: https://icalendar.org/iCalendar-RFC-5545/3-3-10-recurrence-rule.html
bysetpos
property explainedThe rrule bysetpos
property specifies the array index within a freq
interval. The bysetpos
property is necessary if one wants to write a recurrence rule that recurs on a weekly, monthly, or yearly interval, and it should only happen on weekdays or weekends.
When restricting recurrence to weekdays or weekends, if the interval is weekly, monthly, or yearly, rrule interprets the byday
property to mean "this recurrence string defines a separate recurrence for every byday
selected." Probably not what the user intended:
When restricting recurrence to weekdays for this "weekly" recurring task, notice on the right how the recurrence repeats every day, when weekdays are specified.
Conversely, if weekdays aren't specified, then a weekly recurrence interval is sufficient to ensure that the recurrence only happens once per week.
Enter bysetpos
. It tells the recurrence interpretation engine, that instead of treating a recurrence string as "five separate recurrences" when FREQ=WEEKLY
and BYDAY=MO,TU,WE,TH,FR
, the recurrence should use only the nth index. The "nth index" is the value specified for bysetpos
, and it can be negative to specify "the last of the candidate days."
Here is the same recurrence rule as above, but with a bysetpos
specified:
Adding bysetpos
returns the weekly frequency rule to happening only once per week
What do you suppose happens if this same rule has BYSETPOS=-1
? Here's the answer: hopefully what you had expected?
The bysetpos
property isn't needed when freq
is daily. In that case, the "interval length" is only one day, so there is no effect to specifying the array index of that interval. Put another way, when Rrule.DAILY
is used, you can specify "weekend-only" or "weekday-only" recurrence without needing bysetpos
.