Crate jalali_calendar 

jalali-calendar

A comprehensive Jalali (Persian / Shamsi) calendar library for Rust.

Add it to Cargo.toml as jalali-calendar = "0.1" and import it as use jalali_calendar::*;.

What’s in the box

• JalaliDate — a naive Jalali calendar date (year, month, day) with validation, conversion to/from Gregorian, calendar arithmetic, and convenience helpers (weekday, ordinal, season, week-of-year, etc.).
• JalaliDateTime — a JalaliDate paired with a time of day.
• Weekday, Season — value types used throughout the API.
• PERSIAN_MONTHS — the canonical Persian month names.
• digits — convert between Latin (ASCII), Persian, and Eastern-Arabic digits.
• strftime-style JalaliDate::format / JalaliDate::parse_format (and the matching JalaliDateTime methods). See the format module docs for the supported tokens.

Quick example

use jalali_calendar::JalaliDate;

// Convert from Gregorian.
let nowruz = JalaliDate::from_gregorian(2024, 3, 20).unwrap();
assert_eq!((nowruz.year(), nowruz.month(), nowruz.day()), (1403, 1, 1));

// Format with strftime-style tokens (Persian month + season).
assert_eq!(nowruz.format("%-d %B (%K)"), "1 فروردین (بهار)");

// Parse Persian-digit input transparently.
let parsed: JalaliDate = "۱۴۰۳/۰۱/۰۱".parse().unwrap();
assert_eq!(parsed, nowruz);

// Calendar arithmetic with month-end clamping.
let next_month = JalaliDate::new(1403, 6, 31).unwrap().add_months(1);
assert_eq!(next_month, JalaliDate::new(1403, 7, 30).unwrap());

Date range

The Pournader-Toossi conversion algorithm is accurate for Jalali years roughly 1..=3177 AP (covering all practical contemporary use). Outside that range the leap-year approximation drifts.

Cargo features

All optional. The crate has zero required dependencies.

Feature	Pulls in	Adds
serde	serde	Serialize/Deserialize for JalaliDate and JalaliDateTime.
chrono	chrono	Interop with chrono::NaiveDate / chrono::NaiveDateTime.
timezone	chrono,chrono-tz	ZonedJalaliDateTime anchored to a chrono_tz::Tz.
full	all of the above	Convenience flag.

Enable via Cargo.toml:

jalali-calendar = { version = "0.1", features = ["serde", "chrono"] }

Modules

digits

Conversion between Latin (ASCII), Persian (Farsi), and Eastern-Arabic digits.

Structs

JalaliDate

A naive date on the Jalali (Persian / Shamsi) calendar.

JalaliDateTime

Jalali date paired with a time of day (hour/minute/second/nanosecond), naive — i.e. without an associated timezone.

ZonedJalaliDateTimetimezone

A Jalali date and time anchored to a specific chrono_tz::Tz.

Enums

Error

Errors returned by this crate.

Season

The four seasons of the Jalali year.

Weekday

A day of the Persian week.

Constants

PERSIAN_MONTHS

The twelve Persian month names in calendar order: Farvardin (فروردین), Ordibehesht (اردیبهشت), …, Esfand (اسفند).

Functions

days_in_month

Number of days in a Jalali month.

is_leap_year

Whether the given Jalali year is a leap year.