general-datetime-package

General DateTime (Dynamic Calendar)

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.

Related Packages

Version	Package	Description
	general_date_format	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.

Installation

To use this plugin, add it to your project:

1. Add to pubspec.yaml

dependencies:
  general_datetime: <latest_version>

2. Install from terminal

flutter pub add general_datetime

Usage

Import the package into your Dart code:

import 'package:general_datetime/general_datetime.dart';

Persian Calendar (Jalali)

void main() {
  // 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)

void main() {
  // 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:

import 'package:general_datetime/delegates.dart';

CalendarDatePicker(
  initialDate: HijriDateTime.now(),
  firstDate: HijriDateTime(1440, 1, 1),
  lastDate: HijriDateTime(1460, 12, 29),
  calendarDelegate: HijriCalendarDelegate(),
  onDateChanged: (DateTime date) {
    print("Selected: $date");
  },
)

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.
• utc(...): Creates a UTC date with normalization.
• parse(String formattedString): Parse ISO-like strings.

Core Properties

• year, month, day, hour, minute, second, millisecond, microsecond.
• timeZoneName, timeZoneOffset.
• 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.

Read more: Persian Calendar (EMP) paper

Hijri Calendar (Umm al-Qura)

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.

Data provenance and the Unicode license notice are recorded in THIRD_PARTY_NOTICES.md.

Contributions

Contributions are welcome! If you have suggestions, fixes, or new features, please submit a pull request or open an issue on GitHub.

Licence

This project is licensed under the BSD 3-Clause License. See the LICENSE file for details.