iCal’s Recurrence Rule and Duration Formats

If you create repeating events in Android using the CalendarContract content provider, the fields for recurrence rules (RRULE) and durations (DURATION) follow the iCal format (RFC 5545). Here I cover the basics of these formats to create valid field values.

This post is somewhat of an oddity on this blog as most of its content is not Android specific.

Recurrence Rule

The recurrence rule is used in Android whenever you deal with events of the CalendarContract content provider. The event table has the column RRULE that takes the recurrence rule as a String value.

This rule is made up of several components that are separated by semicolons.

As the first element every recurrence rule must define the frequency. It covers all intervals from seconds to years. You use the FREQ qualifier to do so, e.g. FREQ=DAILY.

All other elements are optional. To limit the number of events you can specify the interval, the number of occurrences or the enddate. A FREQ=WEEKLY and a INTERVAL=2 would result in a biweekly event. The number of occurrences is given by the COUNT=x qualifier. And finally an enddate can be given using the element UNTIL=yyyymmdd.

It is also possible for you to select certain elements. E.g. a BYDAY=TU would select Tuesdays, a BYMONTH=5 would select May.

There is another obscure but interesting element: BYSETPOS. This is used to denote one element in a set of elements. A BYSETPOS=1 selects the first element – a BYSETPOS=-1 selects the last element. You have to use it together with another BYxyz element.

Some RRULE samples

As I have already mentioned in my post about the CalendarContract content provider the in and outs of the recurrence rule are pretty tedious and unnecessary complex. Most often you do not need to know all the details. The following samples should help you get to grips with most of the rules.

  • FREQ=DAILY;BYDAY=MO,TU,WE,TH,FR;COUNT=15
    This rule describes an event that takes place on every weekday (BYDAY) for the next 15 weekdays (COUNT).
  • FREQ=YEARLY;BYDAY=-1SU;BYMONTH=3;COUNT=2
    Last Sunday (negative value for BYDAY) in March for every year. That’s the day the summer time begins in the EU.
  • FREQ=YEARLY;BYDAY=2SU;BYMONTH=5;COUNT=3
    Mother’s day. This rule describes a yearly that takes place on the second Sunday (BYDAY) in May (BYMONTH).
  • FREQ=YEARLY;INTERVAL=4;BYMONTH=11;BYDAY=TU;BYMONTHDAY=2,3,4,5,6,7,8
    US election day. Every fourth year (INTERVAL) on the first Tuesday (BYDAY) after a Monday (BYMONTHDAY ensures that) in November (BYMONTH).
  • FREQ=MONTHLY;BYDAY=MO,TU,WE,TH,FR;BYSETPOS=1;UNTIL=20131231
    All first weekdays (BYDAY in combination with BYSETPOS) of the month until the end of 2013 (UNTIL).

If you are really into this, have a look at this enormous list of recurrence rules samples.

Duration

The format of the duration element is much easier to grasp. It takes only one page of the spec compared to seven for the recurrence rule.

So let’s me show you one duration value and explain the format with this example as a basis:

+P5W3D

The first thing, you will notice is the plus sign. Surprisingly durations can have a positive or negative value. The positive value is the default and thus the “+” sign can be omitted. Negative durations can be used to trigger alarms before the event starts. But Android uses a fixed time for this so negative values aren’t used on Android.

The next element after the sign is the “P” which is a fixed constant.

And lastly follows a non-separated string of time quantifiers that all are added up to form the duration.

So the sample given above is for five weeks and three days. What’s odd with durations in the spec is that the biggest period is weeks. It’s not possible to specify months or years.

Time qualifiers
Qualifier Meaning
W Week
D Day
H Hour
M Minute
S Second

Since Android doesn’t use durations for the length of an event, durations usually consist of weeks and days only.

Summary

I have covered the basics of the RRULE and DURATION elements of CalendarContracts event table. Since these rules are in a somewhat obscure format I have given you some samples of how they are created. This should get you started whenever you need to create recurring events in your code.

Share this article:

You can leave a response, or trackback from your own site.

2 Responses to “iCal’s Recurrence Rule and Duration Formats”

  1. noobCoder says:

    Thanks a lot for giving a clear tutorial for this.

  2. Ali Reza Barkhordari says:

    Thanks, It was very helpful for me

Leave a Reply

You can also subscribe without commenting.

Subscribe to RSS Feed My G+-Profile Follow me on Twitter!