A Flutter/Dart Package for working with dates across several calendar systems. Using a unified
interface, you can convert, manipulate, and compare dates in Gregorian, Persian (Jalali),
Hijri (Umm Al-Qura), and other
calendar systems—all while preserving time components and handling timezone, leap year, and negative
value normalization gracefully.
Date formatting for multiple calendar systems with localization support
Features
Gregorian ↔ Other calendars:
Convert between Gregorian and other dates with high precision, preserving time components (hours,
minutes, seconds, milliseconds, and microseconds).
Leap Year Handling:
Detect and correctly handle leap years and leap days, including automatic correction of invalid
leap dates.
Custom Arithmetic:
Perform date arithmetic using custom implementations of add, subtract, and difference that work
directly on calendar fields.
Negative Normalization:
Automatically normalize negative or overflow values in day, month, hour, minute, second, millisecond, and
microsecond components.
Time Zone Support:
Retrieve the time zone name and offset matching Flutter’s DateTime behavior for both local and UTC
dates.
Parsing and Formatting:
Create custom datetime (PersianDateTime, HijriDateTime) instances from formatted strings.
Flutter Integration:
Full support for MaterialLocalizations and CalendarDelegate for both Persian and Hijri calendars, allowing seamless integration with Flutter's DatePicker.
voidmain() {
// Create a Gregorian date and convert it to Persian dates:PersianDateTime pDate = PersianDateTime.fromDateTime(DateTime(2025, 3, 1));
print(pDate.toString()); // 1403-12-11 00:00:00.000// Create a Persian date directly (auto-normalization applies):PersianDateTime directDate = PersianDateTime(1403, 12, 11, 14, 30);
// Arithmetic:var nextWeek = directDate.add(Duration(days: 7));
}
Hijri Calendar (Umm al-Qura)
voidmain() {
// Create a Gregorian date and convert it to Hijri dates:HijriDateTime hDate = HijriDateTime.fromDateTime(DateTime(2025, 3, 1));
print(hDate.toString()); // 1446-09-01 00:00:00.000// Create a Hijri date directly:HijriDateTime directDate = HijriDateTime(1446, 9, 1);
}
Flutter Integration (Localization & Delegates)
Use the matching CalendarDelegate with Flutter Material date pickers. The
Hijri delegate owns its Umm al-Qura formatting and parsing, so it does not need
a replacement global MaterialLocalizations.
Use with CalendarDatePicker
Pass the corresponding delegate to change the calendar system:
Do not register the Persian and Hijri replacement localization delegates in the
same MaterialApp: both provide MaterialLocalizations, so Flutter can load
only one of them for a locale. If a Persian picker needs the legacy Persian
localization, wrap that picker in Localizations.override. The Hijri delegate
works independently of whichever Material localization is active.
API Overview
Factory Constructors
fromDateTime(DateTime datetime): Converts Gregorian to target calendar.
now(): Current date and time in the target calendar.
isLeapYear: Whether the year is a leap year in that specific calendar.
dayOfYear: 1-based day of the year.
julianDay: The calculated Julian day number.
Generic Current Time
Use the generic interface to get the current time for any supported type:
var nowPersian = GeneralDateTimeInterface.now<PersianDateTime>();
var nowHijri = GeneralDateTimeInterface.now<HijriDateTime>();
Customization
You can extend GeneralDateTimeInterface to support additional calendar systems.
[!IMPORTANT]
Ensure custom calendars define their supported range, normalization rules,
and an independently verified conversion model.
Calendars
Persian Calendar
The Persian calendar (Jalali) is a solar calendar first formalized in 1079 CE under Omar Khayyam
that measures years by the true motion of the Earth around the Sun, yielding an average year length
of approximately 365.2424 days—more accurate over centuries than the Gregorian’s 365.2425-day
average. It begins its era on the vernal equinox of 622 CE (the Hijra), and structures time into
twelve months: the first six of 31 days, the next five of 30 days, and the final month of 29 days in
a common year or 30 days in a leap year. Leap years follow an intricate 33-year cycle (with
occasional 29- or 37-year adjustments), tracked in code by a series of “break points” that align
groups of eight leap years within each cycle. Converting between Persian dates and Gregorian dates uses the
Julian Day Number (JDN) as an intermediary—counting days from a fixed epoch—then applying standard
astronomical floor-division formulas to translate JDN to Gregorian and back. Overflow or negative
values in any date or time component are normalized by carrying into higher or lower units, so that
inputs like “month 13” or “day 0” correctly wrap into valid Persian dates. This blend of astronomical
anchoring, cycle-based leap determination, and normalization yields a calendar that keeps Nowruz (
the spring equinox) synchronized with the real equinox with minimal drift over millennia.
The Hijri calendar is lunar and has 12 months. This implementation uses the
published Umm al-Qura month data used by Unicode ICU and OpenJDK, rather
than the repeating 30-year arithmetic Islamic calendar. The verified range is
AH 1300-01-01 through AH 1600-12-30 (Gregorian 1882-11-12 through
2174-11-25). Dates outside that finite range throw RangeError; the
implementation never silently falls back to a different Hijri calendar.
Month lengths and 354/355-day years come directly from the Umm al-Qura data.
Gregorian conversion, UTC/local behavior, parsing, epoch constructors,
arithmetic, and overflow normalization all preserve the native DateTime
instant at microsecond precision.
