mirror of
https://github.com/acamarata/hijri-core-dart.git
synced 2026-07-01 03:04:28 +00:00
142 lines
4.4 KiB
Markdown
142 lines
4.4 KiB
Markdown
# hijri_core
|
|
|
|
[](https://pub.dev/packages/hijri_core)
|
|
[](https://github.com/acamarata/hijri-core-dart/actions/workflows/ci.yml)
|
|
[](LICENSE)
|
|
|
|
Hijri/Gregorian calendar conversion for Dart and Flutter. Zero dependencies.
|
|
|
|
## Installation
|
|
|
|
```yaml
|
|
dependencies:
|
|
hijri_core: ^1.0.0
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```dart
|
|
import 'package:hijri_core/hijri_core.dart';
|
|
|
|
// Gregorian to Hijri (Umm al-Qura by default)
|
|
final hijri = toHijri(DateTime.utc(2025, 3, 1));
|
|
print('${hijri!.hy}/${hijri.hm}/${hijri.hd}'); // 1446/9/1
|
|
|
|
// Hijri to Gregorian
|
|
final greg = toGregorian(1446, 9, 1);
|
|
print(greg!.toIso8601String().substring(0, 10)); // 2025-03-01
|
|
|
|
// Use FCNA calendar instead
|
|
final fcna = toHijri(
|
|
DateTime.utc(2025, 3, 1),
|
|
options: const ConversionOptions(calendar: 'fcna'),
|
|
);
|
|
|
|
// Validate a Hijri date
|
|
final valid = isValidHijriDate(1444, 9, 1); // true
|
|
|
|
// Days in a Hijri month
|
|
final days = daysInHijriMonth(1444, 9); // 29
|
|
```
|
|
|
|
## API
|
|
|
|
### Top-Level Functions
|
|
|
|
| Function | Description |
|
|
| --- | --- |
|
|
| `toHijri(DateTime date, {ConversionOptions? options})` | Convert Gregorian to Hijri. Returns `HijriDate?`. |
|
|
| `toGregorian(int hy, int hm, int hd, {ConversionOptions? options})` | Convert Hijri to Gregorian. Returns `DateTime?` (UTC). |
|
|
| `isValidHijriDate(int hy, int hm, int hd, {ConversionOptions? options})` | Check if a Hijri date is valid. Returns `bool`. |
|
|
| `daysInHijriMonth(int hy, int hm, {ConversionOptions? options})` | Days in a Hijri month (29 or 30). Throws `RangeError` if out of range. |
|
|
|
|
### Registry Functions
|
|
|
|
| Function | Description |
|
|
| --- | --- |
|
|
| `registerCalendar(String name, CalendarEngine engine)` | Register a custom calendar engine. |
|
|
| `getCalendar(String name)` | Retrieve a registered engine by name. |
|
|
| `listCalendars()` | List all registered engine names. |
|
|
|
|
### Data
|
|
|
|
| Export | Description |
|
|
| --- | --- |
|
|
| `hDatesTable` | 184-entry Umm al-Qura reference table (Hijri 1318-1501). |
|
|
| `hmLong`, `hmMedium`, `hmShort` | Hijri month names (12 entries each). |
|
|
| `hwLong`, `hwShort`, `hwNumeric` | Hijri weekday names (7 entries each). |
|
|
|
|
## Engines
|
|
|
|
### UAQ (Umm al-Qura)
|
|
|
|
The official Saudi Arabian Islamic calendar. Table-driven conversions covering Hijri years 1318-1500 (Gregorian 1900-2076). Returns `null` for dates outside that range.
|
|
|
|
This is the default engine.
|
|
|
|
### FCNA (Fiqh Council of North America)
|
|
|
|
Astronomical calculation using Meeus Chapter 49 new moon algorithm. The FCNA criterion: if the new moon conjunction occurs before 12:00 noon UTC on day D, the new Hijri month begins at midnight starting day D+1. Otherwise it begins at midnight starting day D+2.
|
|
|
|
No fixed date range. Works for any Hijri year >= 1.
|
|
|
|
```dart
|
|
final h = toHijri(
|
|
DateTime.utc(2025, 3, 1),
|
|
options: const ConversionOptions(calendar: 'fcna'),
|
|
);
|
|
```
|
|
|
|
## Custom Engine
|
|
|
|
Implement the `CalendarEngine` abstract class and register it:
|
|
|
|
```dart
|
|
class MyEngine extends CalendarEngine {
|
|
@override
|
|
String get id => 'custom';
|
|
|
|
@override
|
|
HijriDate? toHijri(DateTime date) { /* ... */ }
|
|
|
|
@override
|
|
DateTime? toGregorian(int hy, int hm, int hd) { /* ... */ }
|
|
|
|
@override
|
|
bool isValid(int hy, int hm, int hd) { /* ... */ }
|
|
|
|
@override
|
|
int daysInMonth(int hy, int hm) { /* ... */ }
|
|
}
|
|
|
|
registerCalendar('custom', MyEngine());
|
|
|
|
final h = toHijri(
|
|
DateTime.utc(2025, 1, 1),
|
|
options: const ConversionOptions(calendar: 'custom'),
|
|
);
|
|
```
|
|
|
|
## Architecture
|
|
|
|
The UAQ engine performs a binary search over the 184-entry table: O(log 183) per conversion. The FCNA engine computes new moon times using the Meeus Ch. 49 algorithm. The registry pattern lets consumers add custom calendar engines at runtime.
|
|
|
|
## Compatibility
|
|
|
|
- Dart SDK >= 3.7.0
|
|
- Works with Flutter
|
|
- Zero external dependencies
|
|
|
|
## Related
|
|
|
|
- [hijri-core](https://www.npmjs.com/package/hijri-core) (TypeScript/npm)
|
|
- [nrel-spa](https://www.npmjs.com/package/nrel-spa) (Solar position algorithm)
|
|
- [pray-calc](https://www.npmjs.com/package/pray-calc) (Islamic prayer times)
|
|
|
|
## Acknowledgments
|
|
|
|
The Umm al-Qura calendar table is derived from data published by the King Abdulaziz City for Science and Technology (KACST), Saudi Arabia. The FCNA new moon algorithm follows Jean Meeus, "Astronomical Algorithms," 2nd ed., Chapter 49.
|
|
|
|
## License
|
|
|
|
MIT. Copyright (c) 2026 Aric Camarata.
|