shahanshahi 0.2.0

Shahanshahi (Imperial Iranian) civil calendar types and conversions — spec-first, pre-1.0
Documentation

shahanshahi

rustfmt clippy test crate package audit MSRV license

Rust library for the Shahanshahi (Imperial Iranian) civil calendar — developed in the spirit of Melliran: open Persian technology and shared digital infrastructure so teams and organizations can adopt spec-backed Persian calendar tooling without fragile one-offs.

Why spec-first: see docs/VISION.md.

How we build and version: see docs/ENGINEERING.md. Badges above map to CI: rustfmt (format), clippy (lint), test (workspace, all features), crate package (cargo publish --dry-run — release-ready packaging, not a deployed server), audit (cargo audit + cargo deny).

What the library does today

The shahanshahi crate implements spec version 2 of SPEC.md for deterministic, offline use:

  • Civil dates: ShahanshahiDate (1925 month grid, Mode A leap on the underlying Hijri Shamsi year) and GregorianDate for bidirectional conversion via Rata Die.
  • Legal era by default: construction rejects dates outside the documented Shahanshahi civil window; enable the proleptic Cargo feature for try_new_proleptic when you need the same grid without era enforcement (see SPEC.md).
  • Leap helpers: public arithmetic aligned with SPEC (e.g. is_shahanshahi_leap_arithmetic).
  • Golden tests: data/reference-dates.json holds vetted Shahanshahi ↔ Gregorian rows with citations; crates/shahanshahi/tests/reference_dates.rs checks them in CI and asserts spec_id matches the crate’s SPEC_VERSION.
  • Optional ecosystem (Cargo features): serde on date types; chrono / time conversion helpers; std is default and can be disabled for #![no_std] (see crate rustdoc Features).

Scope and non-goals (summary): civil Shahanshahi as briefly enacted in Iran; not religious calendars, lunar Hijri, or locale strings beyond what the crate documents. Mode B (ephemeris) is specified but not implemented as runtime code in this crate yet.

Pre-1.0: the public API may still evolve; see docs/MIGRATING.md and CHANGELOG.md. Crate on crates.io: shahanshahi. v0.1.0 readiness and roadmap are tracked on GitHub.

Repository layout

Path Purpose
SPEC.md Authoritative rules this code implements
data/reference-dates.json Vetted Y/M/D pairs + citations for tests
docs/ENGINEERING.md How we build, version, and release the library
CHANGELOG.md Release history (Keep a Changelog)
docs/MIGRATING.md Notes when upgrading between published versions
deny.toml cargo-deny policy (licenses, advisories, sources)
release-plz.toml Release automation config (release-plz)
SECURITY.md How to report vulnerabilities privately
crates/shahanshahi Library crate (API to grow with the spec)
crates/shahanshahi/examples/ Runnable examples (cargo run -p shahanshahi --example …)

Building

From the repository root:

cargo build -p shahanshahi
cargo test -p shahanshahi --all-features

Examples

cargo run -p shahanshahi --example convert_legal_era
cargo run -p shahanshahi --example convert_proleptic --features proleptic

Repository

github.com/melliran/shahanshahi

Roadmap

Tracked on GitHub: roadmap index — issue #9 and milestone v0.1 — spec-backed MVP.

Contributing

See CONTRIBUTING.md.

Security

To report a security vulnerability, use GitHub Security — do not file a public issue. Details: SECURITY.md.

License

Licensed under either of Apache-2.0 or MIT at your option.