teno_rrule 0.0.10

Dart Recurrence Rule library that implements RFC5545 (iCalendar), support timezone (TZDateTime), week start (WKST), exclusion (EXDATES),...

Dart Recurrence Rule implements RFC5545 (iCalendar)

This library is designed to support what are defined in RFC5545 - Recurrence Rule.

Choosing between this library (teno_rrule) and rrule

If you are looking for	Ideal choice
Stable with many usages	rrule
Features like WKST, Timezone, Exdates, ...	teno_rrule
Both above	You decide!

Getting started

This library utilizes timezone to support timezone-based DateTime (TZDateTime), so make sure you follow the instructions there for initializing the location database. In short:

import 'package:timezone/data/latest_10y.dart';
...
initializeTimeZones();

By default, the library uses the standalone version of the timezone package.

Add this library to your pubspec.yaml

dart pub add teno_rrule

And you are good to go!

Usage

Create Recurrence Rule instance from code:

final rrule = RecurrenceRule(
    frequency: Frequency.weekly,
    startDate: DateTime(1997, 9, 2, 9, 0, 0),
    byWeekDays: {WeekDay.monday, WeekDay.wednesday, WeekDay.friday});

Query recurrence instances

final instances = rrule.between(DateTime(1997, 9, 2, 9), DateTime(1997, 10, 2, 9));
// gets: 1997-09-03 09:00:00.000, 1997-09-05 09:00:00.000, ... 1997-10-01 09:00:00.000

The end range is exclusive.

Parse from string

final rruleString = 'DTSTART;TZID=America/New_York:19970902T090000\n'
    'RRULE:FREQ=DAILY;INTERVAL=2';
final rrule = RecurrenceRule.from(rruleString);

You need to initialize the Location database before parsing from string with TZID, otherwise it will throw exception!

To use with timezone, first initialize the location database as shown in the Getting Started section

final rrule = RecurrenceRule(
    frequency: Frequency.daily,
    count: 10,
    isLocal: false,
    startDate: TZDateTime(getLocation('America/New_York'), 1997, 9, 2, 9));

By default, isLocal = true, which means it ignores the timezone in startDate and treats everything as local time. To use with timezone, set this flag to false.

To specify the first day of week

final rrule = RecurrenceRule(
          frequency: Frequency.weekly,
          count: 10,
          weekStart: DateTime.sunday,
          byWeekDays: {WeekDay.tuesday, WeekDay.thursday},
          startDate: DateTime(1997, 9, 2, 9));

By default, WKST takes the value of firstDayOfWeek from teno_datetime, so you can:

1. Override the WKST by setting the weekStart property
2. Override globally by setting firstDayOfWeek, for example:

firstDayOfWeek = DateTime.saturday;

To select the nth occurrence of a day

final rrule = RecurrenceRule(
    frequency: Frequency.monthly,
    interval: 2,
    count: 10,
    byWeekDays: {
        WeekDay.sunday.withOccurrence(1),  // or WeekDay(DateTime.sunday, 1)
        WeekDay.sunday.withOccurrence(-1)  // or WeekDay(DateTime.sunday, -1)
    },
    isLocal: false,
    startDate:
    TZDateTime(getLocation('America/New_York'), 1997, 09, 07, 9));

To exclude a date (EXDATE rule)

final rrule = RecurrenceRule(
    frequency: Frequency.monthly,
    byMonthDays: {13},
    byWeekDays: {WeekDay.friday},
    isLocal: false,
    startDate:
        TZDateTime(getLocation('America/New_York'), 1997, 09, 02, 9),
    excludedDates: {
        TZDateTime(getLocation('America/New_York'), 1997, 09, 02, 9)
    });

copyWith

final anotherRRule = rrule.copyWith(interval: 5, count: 5);

Additional information

This library has been tested with all examples from RFC5545 - section 3.8.5.3. You can have a look at: test/conversions_test.dart test/query_test.dart

You can refer to the current progress at: TODO.md

If you found a bug or have a request

Please submit an issue at https://github.com/hnvcam/teno_rrule/issues. Please give me some time to take a look at it. I may not act on it immediately, but I will reply with my plan.

---

If you find this library is useful