flutter_hijri_rrule #

A comprehensive RFC 5545 recurrence rule (RRULE) implementation for the Hijri (Islamic) calendar. Supports both Umm al-Qura and Tabular Islamic calendars.

Features #

• RFC 5545 RRULE support adapted for Hijri calendar (date-level recurrence)
• Support for Umm al-Qura and Tabular Islamic calendar systems
• Lazy iteration with Dart generators for memory efficiency
• Human-readable text output in English and Arabic
• Bidirectional conversion between Hijri and Gregorian dates
• Query operations: after(), before(), between()
• Rule sets with inclusions (RRULE, RDATE) and exclusions (EXRULE, EXDATE)
• SKIP parameter support for handling invalid dates (OMIT, FORWARD, BACKWARD)

Installation #

Add to your pubspec.yaml:

dependencies:
  flutter_hijri_rrule: ^1.0.2

Then run:

flutter pub get

Quick Start #

import 'package:flutter_hijri_rrule/flutter_hijri_rrule.dart';

// Create a yearly recurrence for the 1st of Ramadan
final ramadanRule = HijriRRule(HijriRRulePartialOptions(
  freq: Frequency.yearly,
  bymonth: [HijriMonth.ramadan],
  bymonthday: [1],
  dtstart: HijriDate(1446, 9, 1),
  count: 5,
));

// Get all occurrences as Hijri dates
for (final date in ramadanRule.allHijri()) {
  print(date.toLocaleDateString('en')); // "1 Ramadan 1446"
}

// Human-readable text
print(ramadanRule.toText('en')); // "every year on the 1st of Ramadan"
print(ramadanRule.toText('ar')); // "كل سنة في 1 رمضان"

Usage Examples #

Weekly Recurrence (Every Friday) #

final fridayRule = HijriRRule(HijriRRulePartialOptions(
  freq: Frequency.weekly,
  byweekday: [HijriWeekday.fr],
  dtstart: HijriDate(1446, 1, 1),
  count: 4,
));

// Get occurrences as Gregorian DateTime
for (final date in fridayRule.all()) {
  print(date); // DateTime objects
}

Monthly Recurrence (First Friday of Each Month) #

final firstFridayRule = HijriRRule(HijriRRulePartialOptions(
  freq: Frequency.monthly,
  byweekday: [HijriWeekday.fr.nth(1)], // 1st Friday
  dtstart: HijriDate(1446, 1, 1),
  count: 6,
));

Parse RRULE Strings #

final parsed = HijriRRule.fromString(
  'DTSTART;CALENDAR=HIJRI-UM-AL-QURA:14460901\n'
  'RRULE:FREQ=YEARLY;BYMONTH=9;BYMONTHDAY=1;COUNT=3',
);

print(parsed.toString()); // Back to RRULE string

Rule Sets with Exclusions #

final ruleSet = HijriRRuleSet();

// Add a rule for 1st of every month
ruleSet.rrule(HijriRRule(HijriRRulePartialOptions(
  freq: Frequency.monthly,
  bymonthday: [1],
  dtstart: HijriDate(1446, 1, 1),
  count: 6,
)));

// Add an extra date
ruleSet.rdate(HijriDate(1446, 3, 15));

// Exclude specific date
ruleSet.exdate(HijriDate(1446, 2, 1));

for (final date in ruleSet.allHijri()) {
  print(date.toLocaleDateString());
}

Query Operations #

final rule = HijriRRule(HijriRRulePartialOptions(
  freq: Frequency.monthly,
  bymonthday: [1, 15],
  dtstart: HijriDate(1446, 1, 1),
  until: HijriDate(1446, 12, 29),
));

// Get occurrences in a date range
final inRange = rule.betweenHijri(
  HijriDate(1446, 3, 1),
  HijriDate(1446, 6, 1),
  inc: true,
);

// Get next occurrence after a date
final next = rule.afterHijri(HijriDate(1446, 5, 10));

// Get previous occurrence before a date
final prev = rule.beforeHijri(HijriDate(1446, 5, 10));

Date Conversion #

// Gregorian to Hijri
final hijriDate = HijriDate.fromGregorian(DateTime.now());
print(hijriDate.toLocaleDateString('en')); // "15 Jumada al-Akhirah 1446"
print(hijriDate.toLocaleDateString('ar')); // "15 جمادى الآخرة 1446"

// Hijri to Gregorian
final gregorianDate = hijriDate.toGregorian();

Calendar Support #

The library supports two Islamic calendar calculation methods:

Umm al-Qura Calendar (Default) #

The official calendar of Saudi Arabia, based on astronomical calculations.

CalendarConfig.setCalendar(CalendarType.ummAlQura);

Tabular Islamic Calendar #

A rule-based calendar with fixed month lengths following a 30-year cycle.

CalendarConfig.setCalendar(CalendarType.tabular);

// Or specify in RRULE string
final rule = HijriRRule.fromString(
  'DTSTART;CALENDAR=HIJRI-TABULAR:14460101\n'
  'RRULE:FREQ=MONTHLY;COUNT=12',
);

API Reference #

HijriDate #

HijriRRule #

HijriRRuleSet #

Related Projects #

• hijri-rrule - JavaScript/TypeScript version of this library for web and Node.js applications

Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Issues #

Found a bug or have a feature request? Please open an issue at: https://github.com/hb12devtn/flutter_hijri_rrule/issues

License #

This project is licensed under the MIT License - see the LICENSE file for details.