mirror of
https://github.com/acamarata/luxon-hijri.git
synced 2026-07-02 11:40:42 +00:00
121 lines
3.3 KiB
Markdown
121 lines
3.3 KiB
Markdown
# Advanced Usage
|
||
|
||
## Format tokens
|
||
|
||
`formatHijriDate` supports these tokens:
|
||
|
||
| Token | Example | Description |
|
||
|-------|---------|-------------|
|
||
| `D` | `1`–`30` | Hijri day, no padding |
|
||
| `DD` | `01`–`30` | Hijri day, zero-padded |
|
||
| `M` | `1`–`12` | Hijri month number, no padding |
|
||
| `MM` | `01`–`12` | Hijri month number, zero-padded |
|
||
| `MMMM` | `Ramadan` | Full Hijri month name |
|
||
| `MMMMM` | `Ramaḍān` (transliteration variant) | Extended name (where available) |
|
||
| `YY` | `46` | Last two digits of Hijri year |
|
||
| `YYYY` | `1446` | Full Hijri year |
|
||
|
||
```js
|
||
import { toHijri, formatHijriDate } from 'luxon-hijri';
|
||
|
||
const h = toHijri(new Date('2025-03-20'));
|
||
|
||
console.log(formatHijriDate(h, 'DD/MM/YYYY')); // 20/09/1446
|
||
console.log(formatHijriDate(h, 'D MMMM YYYY')); // 20 Ramadan 1446
|
||
console.log(formatHijriDate(h, 'D MMMM YYYY AH')); // 20 Ramadan 1446 AH
|
||
```
|
||
|
||
## Hijri date arithmetic with Luxon
|
||
|
||
Luxon handles Gregorian arithmetic. Combine with hijri-core conversions for Hijri-aware date math:
|
||
|
||
```js
|
||
import { DateTime } from 'luxon';
|
||
import { toHijri, toGregorian, daysInHijriMonth } from 'luxon-hijri';
|
||
|
||
// Find the last day of this Ramadan
|
||
const today = new Date();
|
||
const h = toHijri(today);
|
||
|
||
if (h) {
|
||
const lastDay = daysInHijriMonth(h.hy, 9); // 29 or 30
|
||
const eidStart = toGregorian(h.hy, 10, 1); // 1 Shawwal
|
||
|
||
const eid = DateTime.fromJSDate(eidStart);
|
||
console.log(`Eid al-Fitr ${h.hy}: ${eid.toFormat('MMMM d, yyyy')}`);
|
||
}
|
||
```
|
||
|
||
## Generating a Hijri month calendar
|
||
|
||
```js
|
||
import { toGregorian, daysInHijriMonth } from 'luxon-hijri';
|
||
import { DateTime } from 'luxon';
|
||
|
||
const HY = 1446;
|
||
const HM = 9; // Ramadan
|
||
|
||
const days = daysInHijriMonth(HY, HM);
|
||
const NAMES = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
|
||
|
||
console.log(`Ramadan ${HY}\n`);
|
||
console.log(NAMES.join(' '));
|
||
|
||
const firstGreg = DateTime.fromJSDate(toGregorian(HY, HM, 1));
|
||
let line = ' '.repeat(firstGreg.weekday % 7); // Sunday = 0
|
||
|
||
for (let d = 1; d <= days; d++) {
|
||
const greg = DateTime.fromJSDate(toGregorian(HY, HM, d));
|
||
line += String(d).padStart(3) + ' ';
|
||
if (greg.weekday === 6) { // Saturday ends row
|
||
console.log(line);
|
||
line = '';
|
||
}
|
||
}
|
||
if (line.trim()) console.log(line);
|
||
```
|
||
|
||
## FCNA vs UAQ differences
|
||
|
||
FCNA and UAQ can differ by a day around month transitions:
|
||
|
||
```js
|
||
import { toHijri } from 'luxon-hijri';
|
||
|
||
const borderDates = [
|
||
new Date('2025-02-28'),
|
||
new Date('2025-03-01'),
|
||
new Date('2025-03-02'),
|
||
];
|
||
|
||
for (const d of borderDates) {
|
||
const uaq = toHijri(d, { calendar: 'uaq' });
|
||
const fcna = toHijri(d, { calendar: 'fcna' });
|
||
|
||
const fmt = h => h ? `${h.hd}/${h.hm}/${h.hy}` : 'null';
|
||
console.log(`${d.toISOString().slice(0, 10)} UAQ: ${fmt(uaq)} FCNA: ${fmt(fcna)}`);
|
||
}
|
||
```
|
||
|
||
## Batch conversion
|
||
|
||
```js
|
||
import { toHijri } from 'luxon-hijri';
|
||
|
||
const isoList = [
|
||
'2025-01-01', '2025-03-01', '2025-03-30',
|
||
'2025-06-06', '2025-12-31',
|
||
];
|
||
|
||
for (const iso of isoList) {
|
||
const h = toHijri(new Date(iso));
|
||
const result = h ? `${h.hd}/${h.hm}/${h.hy} AH` : 'out of range';
|
||
console.log(`${iso} → ${result}`);
|
||
}
|
||
```
|
||
|
||
## Related pages
|
||
|
||
- [API Reference](../API-Reference) — all functions, format tokens, types
|
||
- [Hijri Calendar](../Hijri-Calendar) — background on UAQ and FCNA calendar systems
|
||
- [Architecture](../Architecture) — internals, conversion engine, accuracy
|