teno_rrule 0.0.5

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.

What is to choose between this library (teno_rrule) vs rrule

If you are looking for	Ideal choice
Stable with many usages	rrule
Features like WKST, Timezone, Exdates, ...	teno-rrule
Both above	You will made

Getting started

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

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

By default, the library will using the standard alone version of the library.

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});

Get its recurrence by

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

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, you first need to initialize location database at getting start 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, means it won't care about the timezone in startDate and treats everything as local time. To use with timezone, please 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 will take the value of firstDayOfWeek from teno_datetime, so you can:

1. Override the WKST by setting value to property weekStart
2. Override globally by setting value to firstDayOfWeek, for ex:

firstDayOfWeek = DateTime.saturday;

To select the n occurrence of 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, issue, or have a request.

Please submit an issue at https://github.com/hnvcam/teno_rrule/issues. And give me sometime to take a look on it. I won't promise to take the action soon, but I will reply you my plan.

---

If you find this library is useful