mirror of
https://github.com/acamarata/hijri-core-dart.git
synced 2026-07-01 11:14:28 +00:00
144 lines
3.3 KiB
Markdown
144 lines
3.3 KiB
Markdown
# API Reference
|
|
|
|
## Conversion Functions
|
|
|
|
### toHijri
|
|
|
|
```dart
|
|
HijriDate? toHijri(DateTime date, {ConversionOptions? options})
|
|
```
|
|
|
|
Converts a Gregorian date to a Hijri date. Returns `null` if the date falls outside the engine's supported range.
|
|
|
|
The default engine is UAQ (Umm al-Qura), covering Hijri years 1318-1500 (Gregorian 1900-2076).
|
|
|
|
```dart
|
|
final hijri = toHijri(DateTime.utc(2025, 3, 1));
|
|
// hijri.hy == 1446, hijri.hm == 9, hijri.hd == 1
|
|
```
|
|
|
|
### HijriDate fields
|
|
|
|
| Field | Type | Description |
|
|
| --- | --- | --- |
|
|
| `hy` | `int` | Hijri year |
|
|
| `hm` | `int` | Hijri month (1-12) |
|
|
| `hd` | `int` | Hijri day (1-30) |
|
|
|
|
---
|
|
|
|
### toGregorian
|
|
|
|
```dart
|
|
DateTime? toGregorian(int hy, int hm, int hd, {ConversionOptions? options})
|
|
```
|
|
|
|
Converts a Hijri date to a Gregorian `DateTime` (UTC, midnight). Returns `null` if the date is outside the engine's supported range or is invalid.
|
|
|
|
```dart
|
|
final greg = toGregorian(1446, 9, 1);
|
|
// greg.toIso8601String().substring(0, 10) == "2025-03-01"
|
|
```
|
|
|
|
---
|
|
|
|
### isValidHijriDate
|
|
|
|
```dart
|
|
bool isValidHijriDate(int hy, int hm, int hd, {ConversionOptions? options})
|
|
```
|
|
|
|
Returns `true` if the given Hijri date is valid within the selected engine's calendar. Checks year range, month range (1-12), and day range (1 to the actual days in that month).
|
|
|
|
---
|
|
|
|
### daysInHijriMonth
|
|
|
|
```dart
|
|
int daysInHijriMonth(int hy, int hm, {ConversionOptions? options})
|
|
```
|
|
|
|
Returns the number of days in a Hijri month (29 or 30). Throws `RangeError` if the year or month is out of the engine's supported range.
|
|
|
|
---
|
|
|
|
## ConversionOptions
|
|
|
|
```dart
|
|
const ConversionOptions({String calendar = 'uaq'})
|
|
```
|
|
|
|
| Field | Type | Default | Description |
|
|
| --- | --- | --- | --- |
|
|
| `calendar` | `String` | `'uaq'` | Engine name: `'uaq'` or `'fcna'`, or any registered custom name |
|
|
|
|
---
|
|
|
|
## Registry Functions
|
|
|
|
### registerCalendar
|
|
|
|
```dart
|
|
void registerCalendar(String name, CalendarEngine engine)
|
|
```
|
|
|
|
Registers a custom `CalendarEngine` under the given name. The name is case-sensitive. Registering a name that already exists overwrites the previous engine.
|
|
|
|
### getCalendar
|
|
|
|
```dart
|
|
CalendarEngine getCalendar(String name)
|
|
```
|
|
|
|
Retrieves a registered engine by name. Throws `ArgumentError` if the name is not registered.
|
|
|
|
### listCalendars
|
|
|
|
```dart
|
|
List<String> listCalendars()
|
|
```
|
|
|
|
Returns all registered calendar engine names, including the built-in `'uaq'` and `'fcna'`.
|
|
|
|
---
|
|
|
|
## CalendarEngine (abstract)
|
|
|
|
Implement this class to create a custom calendar engine:
|
|
|
|
```dart
|
|
abstract class CalendarEngine {
|
|
String get id;
|
|
HijriDate? toHijri(DateTime date);
|
|
DateTime? toGregorian(int hy, int hm, int hd);
|
|
bool isValid(int hy, int hm, int hd);
|
|
int daysInMonth(int hy, int hm);
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Data Exports
|
|
|
|
### hDatesTable
|
|
|
|
```dart
|
|
final List<List<int>> hDatesTable
|
|
```
|
|
|
|
The 184-entry Umm al-Qura reference table covering Hijri years 1318-1501. Each entry contains the Gregorian year, month, and day of the first day of that Hijri year. Used internally by the UAQ engine.
|
|
|
|
### Month and weekday name lists
|
|
|
|
| Export | Length | Example |
|
|
| --- | --- | --- |
|
|
| `hmLong` | 12 | `'Muharram'`, `'Safar'`, ... |
|
|
| `hmMedium` | 12 | Abbreviated month names |
|
|
| `hmShort` | 12 | Short month abbreviations |
|
|
| `hwLong` | 7 | `'Al-Ahad'`, `'Al-Ithnayn'`, ... |
|
|
| `hwShort` | 7 | Short weekday names |
|
|
| `hwNumeric` | 7 | Numeric weekday strings |
|
|
|
|
---
|
|
|
|
[Home](Home)
|