misri_hijri 0.1.4

Hijri calendar dates for Dart/Flutter with a choice of calculation system — Misri (fixed tabular, 30-year cycle) or Umm al-Qura (Saudi official, astronomical lookup table) — behind one shared API.

example/misri_hijri_example.dart

// Run with: dart run example/misri_hijri_example.dart
//
// Shows the two things the package does: pick a calculation system with a
// single [HijriCalendarType] parameter, then use the returned
// [HijriCalendarBase] identically regardless of which system produced it.
import 'package:misri_hijri/misri_hijri.dart';

void main() {
  // --- Today, in each calendar system ---------------------------------------
  final misriToday = Hijri.now(type: HijriCalendarType.misri);
  final uaqToday = Hijri.now(type: HijriCalendarType.ummAlQura);

  print('Today');
  // Today
  print('  Misri:       ${misriToday.format('DDDD, dd MMMM yyyy')}');
  //   Misri:       Saturday, 17 Rabiul Awwal 1448
  print('  Umm al-Qura: ${uaqToday.format('DDDD, dd MMMM yyyy')}');
  //   Umm al-Qura: Saturday, 16 Rabi' Al-Awwal 1448

  // The two tabular/astronomical systems can differ by a day.
  if (!misriToday.isAtSameMomentAs(uaqToday)) {
    print('  (the two systems disagree by a day today)');
    //   (the two systems disagree by a day today)
  }

  // --- Convert a specific Gregorian date -----------------------------------
  final onDate = Hijri.fromDate(
    DateTime(2025, 3, 20),
    type: HijriCalendarType.ummAlQura,
  );
  print('\n2025-03-20 in Umm al-Qura: ${onDate.format('yyyy-mm-dd')} '
      '(${onDate.monthName})');
  // 2025-03-20 in Umm al-Qura: 1446-09-20 (Ramadan)
  print('  back to Gregorian: ${onDate.toDateTime()}');
  //   back to Gregorian: 2025-03-20 00:00:00.000

  // --- Build from explicit Hijri Y/M/D -----------------------------------
  final eid = Hijri.fromHijri(1446, 10, 1, type: HijriCalendarType.ummAlQura);
  print('\n1 Shawwal 1446 falls on ${eid.format('DDDD, dd MMMM yyyy')}');
  // 1 Shawwal 1446 falls on Sunday, 01 Shawwal 1446
  print('  days in that month: ${eid.daysInMonth}');
  //   days in that month: 30

  // --- Date arithmetic ----------------------------------------------------
  final in100Days = misriToday.addDays(100);
  final in3Months = misriToday.addMonths(3);
  print('\n100 days from now (Misri): ${in100Days.format('dd MMMM yyyy')}');
  // 100 days from now (Misri): 28 Jamadal Ukhra 1448
  print('3 months from now (Misri): ${in3Months.format('dd MMMM yyyy')}');
  // 3 months from now (Misri): 17 Jamadal Ukhra 1448

  // --- Localised output (Arabic month names + Arabic-Indic digits) -------
  final ar = Hijri.fromHijri(
    1446,
    9,
    1,
    type: HijriCalendarType.ummAlQura,
    locale: 'ar',
  );
  print('\nArabic locale: ${ar.format('dd MMMM yyyy')}');
  // Arabic locale: ٠١ رمضان ١٤٤٦

  // --- The whole HijriCalendarBase surface is identical either way -------
  void report(HijriCalendarBase date) {
    print('  [${date.calendarType.name}]'
        ' iso=${date.isoFormat}'
        ' leap=${date.isLeapYear}'
        ' daysInMonth=${date.getDaysInMonth(date.year, date.month)}'
        ' yearLen=${date.lengthOfYear()}'
        ' -> ${date.fullDate()}');
  }

  print('\nSame accessors, both systems:');
  report(Hijri.now(type: HijriCalendarType.misri));
  //   [misri] iso=1448-03-17 leap=true daysInMonth=30 yearLen=355 -> Saturday, Rabiul Awwal 17, 1448
  report(Hijri.now(type: HijriCalendarType.ummAlQura));
  //   [ummAlQura] iso=1448-03-16 leap=true daysInMonth=29 yearLen=355 -> Saturday, Rabi' Al-Awwal 16, 1448

  // --- Write an API that accepts either system --------------------------
  void describe(HijriCalendarBase date) {
    print('  [${date.calendarType.name}] ${date.format('DDDD dd MMMM yyyy')}');
  }

  print('\nSame function, both systems:');
  describe(Hijri.now(type: HijriCalendarType.misri));
  //   [misri] Saturday 17 Rabiul Awwal 1448
  describe(Hijri.now(type: HijriCalendarType.ummAlQura));
  //   [ummAlQura] Saturday 16 Rabi' Al-Awwal 1448
}