jalali_date quick reference
Every PersianDate constructor, getter and method of jalali_date at a glance, and notes for code generators and AI assistants.
Quick reference
Everything is exported from package:jalali_date/jalali_date.dart: the immutable PersianDate class, the PersianDateRange class, the HijriDate and IranianHijri classes, the toPersianDigits, toLatinDigits, and toPersianWords functions, the JalaliEra enum, and the DateTime.toPersianDate() and DateTime.toHijriDate() extensions.
Every class and member is described in the API reference.
Creating
| Member | Description |
|---|---|
PersianDate(int year, int month, int day) | From Jalali values, date-only; throws ArgumentError for an invalid date |
PersianDate.withTime(year, month, day, [hour, minute, second]) | From Jalali values with a local time of day |
PersianDate.now() | Current local date and time |
PersianDate.fromDateTime(DateTime) | From a DateTime; keeps time of day and time zone |
DateTime.toPersianDate() | Extension, the same as fromDateTime |
PersianDate.fromGregorian(int year, int month, int day) | From Gregorian values; overflow rolls over like DateTime |
PersianDate.fromGregorianString(String) | From an ISO 8601 Gregorian string, via DateTime.parse |
PersianDate.parse(String, {era}), tryParse(String, {era}) | From a Jalali string such as 1403/01/01 or ۱۴۰۳-۱-۱ ۱۴:۳۰ |
PersianDate.parseFormat(String, String pattern, {era}), tryParseFormat(...) | From text written with a format pattern, such as ۴ فروردین ۱۴۰۳ |
PersianDate.fromJson(String), toJson() | yyyy-MM-dd for storage and jsonEncode |
PersianDate.min, PersianDate.max | First and last supported day |
copyWith({year, month, day}) | Copy with fields replaced; validates, never clamps |
Reading
| Member | Description |
|---|---|
year, month, day | Jalali year, month (1 to 12), and day of month |
shahanshahiYear | year plus 1180, the Shahanshahi (Imperial) year |
hasTime, hour, minute, second | Time of day; the getters throw StateError when hasTime is false |
dayPeriod | Part of the day: نیمهشب, بامداد, صبح, ظهر, عصر, شب |
isLeapYear, daysInYear | Whether Esfand has 30 days; 365 or 366 |
PersianDate.nowruzMoment(int year) | The March equinox that begins the year (سال تحویل), in UTC |
monthLength | 31, 30, or 29 |
dayOfYear | 1 to 366 |
quarter, season, seasonName | 1 to 4, and بهار to زمستان |
monthName, monthNameLatin, monthNameDari | فروردین, Farvardin, حمل (Afghanistan) |
weekday | ISO weekday, 1 is Monday and 7 is Sunday, like DateTime.weekday |
weekdayPersian | 1 is Saturday and 7 is Friday, the column in a Persian calendar grid |
weekdayName, weekdayNameShort, weekdayNameLatin | شنبه, ش, Shanbeh |
weekOfYear | Saturday-first week number, week 1 contains 1 Farvardin |
isWeekend | Friday |
isToday | Same day as PersianDate.now() |
monthNames, monthNamesLatin, monthNamesDari, weekdayNames, weekdayNamesShort, weekdayNamesLatin, seasonNames | Static name lists; weekday lists are indexed by ISO weekday minus one |
Calculating
| Member | Description |
|---|---|
addDays(int), addMonths(int), addYears(int) | Negative values go back; months and years clamp the day |
differenceInDays(PersianDate) | Whole days from the other date to this one |
differenceInMonths(PersianDate), differenceInYears(PersianDate) | Whole Jalali months or years, counted like addMonths |
firstDayOfMonth, lastDayOfMonth, firstDayOfYear, lastDayOfYear | Anchors |
startOfWeek(), endOfWeek() | Saturday and Friday of the same week |
daysUntil(PersianDate end, {inclusive}) | Lazy sequence of days |
PersianDateRange(start, end) | Inclusive range with length, days, contains, overlaps |
Comparing and converting
| Member | Description |
|---|---|
==, compareTo, <, <=, >, >= | By day only; the time of day is ignored |
isBefore, isAfter, isSameDay, isSameMonth, isSameYear | Readable comparisons |
toDateTime() | Gregorian DateTime |
toHijri() | Lunar Hijri date, see Hijri calendar |
toString({showDate, showTime, showHour, showMinute, showSecond, persianDigits, era}) | yyyy/MM/dd, optionally with HH:mm:ss |
format(String pattern, {persianDigits, era}) | Custom string, tokens listed below |
toPersianDigits(String), toLatinDigits(String) | Digit conversion, Persian and Arabic-Indic input |
toPersianWords(int, {ordinal}) | هزار و چهارصد و سه, بیست و چهارم |
relativeTo(PersianDate, {numeric, persianDigits}), fromNow(...) | دیروز, 3 روز پیش, ماه آینده |
Supported range: Jalali -61/01/01 to 3177/10/11, which is Gregorian 560-03-20 to 3798-12-31.
Notes for code generators and AI assistants
- Import only
package:jalali_date/jalali_date.dart; never import fromsrc/. PersianDateis immutable; there are no setters. UsecopyWith,addDays,addMonths, or a constructor.PersianDate(y, m, d)takes Jalali values; usePersianDate.fromGregorian(y, m, d)for Gregorian values.- Months are 1 to 12, never 0-based.
weekdayis ISO (Monday is 1); useweekdayPersianfor Saturday-first numbering. The name lists are indexed byweekday - 1.==ignores the time of day; comparetoDateTime()when the moment matters.- Check
hasTimebefore readinghour,minute,second, or using time tokens. addMonthsclamps; it never rolls over likeDateTime.- Esfand has 30 days only in leap years; use
monthLengthinstead of hard-coding 29. parseandparseFormatalready accept Persian digits; usepersianDigits: trueortoPersianDigitsfor output.- To read text such as
۴ فروردین ۱۴۰۳, usePersianDate.parseFormat(text, 'd MMMM yyyy'), not a hand-written regex. - For ages and terms use
differenceInMonthsordifferenceInYears; dividingdifferenceInDaysby 30 or 365 gives wrong answers. - For text such as
3 روز پیشorدیروز, userelativeToorfromNow. - For Iranian holidays use the iranian_holidays package (
OfflineHolidaySource, or an online source); never hard-code holiday dates, because the lunar Hijri ones move every year.