Parsing Jalali dates from text

Read Jalali dates in Dart from text such as 1403/01/04 or ۴ فروردین ۱۴۰۳, with Persian, Latin or Dari month names, Persian digits and format patterns.

#Parsing

PersianDate.parse('1403/01/01'); // date-only
PersianDate.parse('1403-1-1'); // date-only
PersianDate.parse('۱۴۰۳/۰۱/۰۱ ۱۴:۳۰'); // with a local time of day
PersianDate.parse('1403-01-01T14:30:15'); // with seconds
PersianDate.tryParse('1400/12/30'); // null, 1400 is not a leap year

parse accepts / or - between the parts (the same one twice), one- or two-digit month and day, an optional HH:mm or HH:mm:ss, and ASCII, Persian, or Arabic-Indic digits. It throws FormatException for anything else, including invalid dates; tryParse returns null instead. The output of toString, toJson, and format('yyyy/MM/dd') parses back.

#Parsing with a pattern

PersianDate.parseFormat('۴ فروردین ۱۴۰۳', 'd MMMM yyyy'); // 1403/01/04
PersianDate.parseFormat('1403 Farvardin 4', 'yyyy MMMM d'); // 1403/01/04
PersianDate.parseFormat('سه شنبه ۷ فروردين ۱۴۰۳', 'EEEE d MMMM yyyy'); // 1403/01/07
PersianDate.parseFormat('1403/01/04 2:30 ب.ظ', 'yyyy/MM/dd h:mm a'); // with 14:30
PersianDate.tryParseFormat('دوشنبه ۷ فروردین ۱۴۰۳', 'EEEE d MMMM yyyy'); // null, 7 Farvardin 1403 is a Tuesday

parseFormat reads text written with the format tokens and quoting, so PersianDate.parseFormat(date.format(pattern), pattern) gives the date back. The pattern needs yyyy, a month, and a day; MM and dd need two digits, while M and d take one or two. MMMM reads Persian, Latin, and Dari month names, and EEEE, E, D, Q, a, and B must agree with the date. Persian and Arabic-Indic digits, Arabic ي and ك, and سه‌شنبه written with a space, a zero-width non-joiner, or neither are all accepted. It throws FormatException for text that does not match and ArgumentError for a pattern that cannot identify a date; tryParseFormat returns null for the first.