HijriDateTime

A Dart package for handling Hijri (Islamic) calendar dates with support for various regional adjustments and configurations.

Features

• Convert between Gregorian and Hijri dates
• Support for different regional adjustments (Global, India)
• Configurable adjustment settings
• Built-in support for Umm al-Qura calendar
• Accurate date calculations with ILN (Islamic Lunar Number) support

Getting started

Add the package to your pubspec.yaml:

dependencies:
  hijri_date_time: ^1.1.0

Usage

Constructors

HijriDateTime provides several ways to create a date:

// Create from specific Hijri date
final hijriDate = HijriDateTime(
  1445,
  month: 9,
  day: 1,
); // 1 Ramadan 1445

// Create from current date
final now = HijriDateTime.now();

// Create from Gregorian date
final fromGregorian = HijriDateTime.fromGregorian(DateTime(2024, 3, 11));

Adjustments

HijriDateTime supports different adjustment configurations to handle regional variations in Hijri dates:

1. Default Configuration

   final defaultDate = HijriDateTime(1445, month: 9, day: 1,
     adjustmentConfiguration: DefaultHijriAdjustmentConfiguration());
   

2. Global Configuration

   final globalDate = HijriDateTime(1445, month: 9, day: 1,
     adjustmentConfiguration: GlobalHijriAdjustmentConfiguration());
   

3. India Configuration

   final indiaDate = HijriDateTime(1445, month: 9, day: 1,
     adjustmentConfiguration: IndiaHijriAdjustmentConfiguration(
       adjustments: indiaHijriAdjustments
     ));
   

Global Configuration

The global configuration uses adjustments based on the Umm al-Qura calendar data from webspace.science.uu.nl. These adjustments handle various date corrections for important Islamic dates like:

• Ramadan start
• Eid al-Fitr
• Eid al-Adha
• Muharram

India Adjustments

The India configuration includes specific adjustments for the Indian subcontinent, where dates are typically offset by one day. The adjustments are based on the "Hijri - India Corrections.csv" data and include corrections for:

• 1st of Muharram
• 1st of Ramadan
• 1st of Shawwal
• 1st of Dhu al-Hijjah
• 10th of Dhu al-Hijjah

ILN (Islamic Lunar Number)

The package uses ILN for accurate date calculations. ILN is a continuous number that represents the Islamic lunar month, calculated as:

int iln = ((year - 1) * 12) + month;

You can access the ILN of any date:

final date = HijriDateTime(1445, month: 9, day: 1);
print(date.iln); // Prints the Islamic Lunar Number

Date Properties

final date = HijriDateTime(1445, month: 9, day: 1);

// Access date components
print(date.year);      // 1445
print(date.month);     // 9
print(date.day);       // 1
print(date.weekday);   // Day of week (1-7)
print(date.monthLength); // Number of days in the month

// Convert to Gregorian
final gregorian = date.toGregorian();

Utility Functions

HijriDateTime provides several utility functions for date manipulation and comparison:

final date = HijriDateTime(1445, month: 9, day: 1);

// Add duration
final nextWeek = date.add(const Duration(days: 7));
final nextMonth = date.add(const Duration(days: 29)); // Muharram has 29 days
final nextYear = date.add(const Duration(days: 354)); // Approximate Hijri year

// Subtract duration
final lastWeek = date.subtract(const Duration(days: 7));
final lastMonth = date.subtract(const Duration(days: 29));

// Date comparison
final otherDate = HijriDateTime(1445, month: 9, day: 15);
final daysDifference = date.difference(otherDate); // Returns number of days between dates
final isAfter = date.isAfter(otherDate); // Returns true if date is after otherDate
final isBefore = date.isBefore(otherDate); // Returns true if date is before otherDate

// Time components
final dateWithTime = HijriDateTime(1445, month: 9, day: 1, hour: 10, minute: 30);
final nextHour = dateWithTime.add(const Duration(hours: 1));

Updating Adjustments

You can update the adjustment configuration for an existing date:

final date = HijriDateTime(1445, month: 9, day: 1);
final updatedDate = date.updateAdjustmentConfiguration(
  GlobalHijriAdjustmentConfiguration()
);

Additional information

The package uses the Umm al-Qura calendar data for accurate date calculations and includes adjustments for various regions. The date range supported is from 1356 AH (14 March 1937 CE) to 1500 AH (16 November 2077 CE).

For more information about the Umm al-Qura calendar and adjustments, visit:

• Umm al-Qura Calendar
• Hijri Calendar