Recurrence Rule

The recurrence rule consists of a collection of rule parts, which define how to calculate an occurrence.

The recurrence is defined in RFC-5545.

  • Frequency  defines the type of recurrence rule. Valid values are:
    • SECONDLY  for events that repeat at an interval of a second or more.
    • MINUTELY  for events that repeat at an interval of a minute or more.
    • HOURLY  for events that repeat at an interval of an hour or more.
    • DAILY  for events that repeat at an interval of a day or more.
    • WEEKLY  for events that repeat at an interval of a week or more.
    • MONTHLY  for events that repeat at an interval of a month or more.
    • YEARLY  for events that repeat at an interval of a year or more.
  • Interval  a positive integer (defaulting to 1) that defines the intervals at which the events occur. For example, a Frequency of DAILY and an Interval of 8 means "every eight days".
  • Week Start  specifies the day on which the working week starts. This is significant when a WEEKLY rule type has an Interval greater than 1, and a BYDAY rule part is specified. This is also significant when a YEARLY rule type has a BYWEEKNO rule part specified. The default value is MO [Monday].
  • Count  defines the number of occurrences after which the recurrence rule finishes. A rule can have either a Count or Until, but not both. If neither Count nor Until are specified, the recurrence rule is infinite.
  • Until  defines the start datetime of the last occurrence of the rule. A rule can have either a Count or Until, but not both. If neither Count nor Until are specified, the recurrence rule is infinite.
  • BY??? rules  such as BYDAY=MO. A collection of rule parts that describe how a date should be adjusted in order to calculate the start of each event. Each type of BY??? rule describes how one element of a date or time is adjusted. Possible rules are BYSECOND, BYMINUTE, BYHOUR, BYDAY, BYMONTHDAY, BYYEARDAY, BYWEEKNO, BYMONTH and BYSETPOS.

These rule parts are applied in a fixed order, and recursively. As the rule parts are applied, the date output by one rule part becomes the input to the next rule part. When all rule parts have been applied, the initial input date is incremented, according to the frequency and interval, and the process repeated. This continues until either the number of calculated events equals the Count, or until the next event would start after the Until date.

The recurrence rule is persisted as an expression, that is, as a string using the grammar defined in RFC-5545. Some examples are:

  • FREQ=WEEKLY;INTERVAL=2;UNTIL=19971224T000000Z;WKST=SU;BYDAY=MO,WE,FR

    The exclusion occurs Monday, Wednesday, and Friday of every fortnight, until 24 December 1997. Weeks start on Sunday.

    This rule is broken down, and interpreted as follows:

    • FREQ=WEEKLY — The rule applies on a weekly basis.
    • INTERVAL=2 — The frequency interval is 2, making it, every 2 weeks.
    • UNTIL=19971224T000000Z — The rule ends on 24 December 1997.
    • WKST=SU —The rule states that Sunday is the first day of a week.
    • BYDAY=MO,WE,FR — The rule applies on first Monday, Wednesday and Friday of the weeks identified by the frequency and interval.
  • FREQ=WEEKLY;INTERVAL=2;COUNT=8;WKST=SU;BYDAY=TU,TH

    Tuesday and Thursday, of every fortnight, for the next eight fortnights. Week starts on Sunday.

  • FREQ=YEARLY;INTERVAL=4;BYMONTH=11;BYDAY=TU;BYMONTHDAY=2,3,4,5,6,7,8

    The event applies on the first Tuesday, between 2 November and 8 November, of every fourth year, indefinitely.

  • FREQ=MONTHLY;INTERVAL=2;COUNT=10;BYDAY=1SU,-1SU

    The first and last Sunday, of every other month, for the next 20 (2 x 10) months.

  • FREQ=WEEKLY;INTERVAL=1;COUNT=8;BYDAY=FR

    Every Friday, for the next eight weeks.