rrule

Description:

rrule

🔁 Recurrence rule parsing & calculation as defined in the iCalendar RFC


How to use this package #
Create a RecurrenceRule:
// Every two weeks on Tuesday and Thursday, but only in December.
final rrule = RecurrenceRule(
frequency: Frequency.weekly,
interval: 2,
byWeekDays: {
ByWeekDayEntry(DateTime.tuesday),
ByWeekDayEntry(DateTime.thursday),
},
byMonths: {12},
);
copied to clipboard
And get its recurrences by evaluating it from a start date:
final Iterable<DateTime> instances = rrule.getInstances(
start: DateTime.now().copyWith(isUtc: true),
);
copied to clipboard

⚠️ rrule doesn't care about any time-zone-related stuff.
All supplied DateTimes must have isUtc set to true (because UTC doesn't have complications like summer and winter time), but the actual time zone is then ignored, e.g., when generating human-readable text.
If you have a DateTime instance in the local time zone, you can use rrule's helper dateTime.copyWith(isUtc: true) which keeps the date and time but sets isUtc to true.
To convert the generated instances back to your local time zone, you can use dateTime.copyWith(isUtc: false).

To limit returned instances (besides using RecurrenceRule.until or RecurrenceRule.count), you can use Dart's default Iterable functions:
final firstThreeInstances = instances.take(3);

final onlyThisYear = instances.takeWhile(
(instance) => instance.year == DateTime.now().year,
);

final startingNextYear = instances.where(
(instance) => instance.year > DateTime.now().year,
);
copied to clipboard
Machine-readable String conversion #
You can convert between RecurrenceRules and iCalendar/RFC 5545-compliant Strings by using RecurrenceRuleStringCodec or the following convenience methods:
final string = 'RRULE:FREQ=WEEKLY;INTERVAL=2;BYDAY=TU,TH;BYMONTH=12';
final rrule = RecurrenceRule.fromString(string);

assert(rrule.toString() == string); // true
copied to clipboard
(Same RRULE as the first one)
Human-readable Text conversion #
You can convert a RecurrenceRule to a human-readable Strings by using RecurrenceRule.toText():
// First, load the localizations (currently, only English is supported):
final l10n = await RruleL10nEn.create();

final rrule = RecurrenceRule.fromString(
'RRULE:FREQ=WEEKLY;INTERVAL=2;BYDAY=TU,TH;BYMONTH=12',
);

final text = 'Every other week in December on Tuesday & Thursday';
assert(rrule.toText(l10n: l10n) == string); // true
copied to clipboard
(Same RRULE as the first one)
A few more examples:

RRULE:INTERVAL=4;FREQ=HOURLY: Every 4 hours
RRULE:FREQ=DAILY;BYSETPOS=1,-2;BYMONTH=1,12;BYMONTHDAY=1,-1: Daily in January & December on the 1st & 2nd-to-last instance of the 1st & last day of the month
RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR: Weekly on weekdays
RRULE:INTERVAL=2;FREQ=WEEKLY: Every other week
RRULE:FREQ=MONTHLY;BYDAY=-3TU: Monthly on the 3rd-to-last Tuesday
RRULE:FREQ=YEARLY;BYDAY=+13FR: Annually on the 13th Friday of the year
RRULE:FREQ=YEARLY;BYSETPOS=1,-2;BYMONTH=1,12;BYWEEKNO=1,-1;BYYEARDAY=1,-1;BYMONTHDAY=1,-1;BYDAY=MO,WE: Annually on the 1st & 2nd-to-last instance of every Monday & Wednesday that are also the 1st or last day of the month, that are also the 1st or last day of the year, that are also in the 1st or last week of the year, and that are also in January or December

While this already supports really complex RRULEs, some of them are not (yet) supported. See RecurrenceRule.canFullyConvertToText for more information.
JSON conversion #
You can convert between RecurrenceRules and jCal/RFC 7265-compliant JSON using the following convenience methods:
final json = <String, dynamic>{
'freq': 'WEEKLY',
'interval': 2,
'byday': ['TU', 'TH'],
'bymonth': [12],
};
final rrule = RecurrenceRule.fromJson(json);

expect(rrule.toJson(), json);
copied to clipboard
(Same RRULE as the first one)
Limitations #

custom week starts are not supported (WKST in the specification) – Monday is the only valid value (encoded as MO)
leap seconds are not supported (limitation of Dart's DateTime)
only years 0–9999 in the Common Era are supported (limitation of the iCalendar RFC, but if you have a use case, this should be easy to extend)

Thanks #
The recurrence calculation code of RecurrencRules is mostly a partial port of rrule.js, though with a lot of modifications to use Dart's DateTime and not having to do date/time calculations manually. You can find the license of rrule.js in the file LICENSE-rrule.js.txt.