rrule 0.1.0

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

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

How to use this package

Note: This package uses time_machine for handling date and time. See its README for how to initialize it on Flutter or the web.

Create a RecurrenceRule:

// Every two weeks on Tuesday and Thursday, but only in December.
final rrule = RecurrenceRule(
  frequency: Frequency.weekly,
  interval: 2,
  byWeekDays: {
    ByWeekDayEntry(DayOfWeek.tuesday),
    ByWeekDayEntry(DayOfWeek.thursday),
  },
  byMonths: {12},
  weekStart: DayOfWeek.sunday,
);

And get its recurrences by evaluating it from a start date:

final Iterable<LocalDateTime> instances = rrule.getInstances(
  start: LocalDateTime.now(),
);

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 == LocalDate.today().year,
);

final startingNextYear = instances.where(
  (instance) => instance.year > LocalDate.today().year,
);

Note: Convenience methods or parameters will be added soon to make these limitations easier.

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;WKST=SU';
final rrule = RecurrenceRule.fromString()

assert(rrule.toString == string); // true

^{(Same rule as the first one)}

Limitations

• leap seconds are not supported (limitation of the time_machine package)
• 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 time_machine and not having to do date/time calculations manually. You can find the license of rrule.js in the file LICENSE-rrule.js.txt.