Skip to main content
Contents

Implementation · Kotlin

Persian (Jalali) calendar in Kotlin

Dependency-free Kotlin implementation of the Jalali (Persian, Solar Hijri) calendar: leap years, date validation, Gregorian and Julian Day conversion, weekday and day of year. Verified day by day for 1178–3000 AP. MIT license.

Requires
Kotlin (JVM/Android, KMP core)
Tested with
Kotlin 2.4
Cross-checked against
ICU4J 76.1–79.1
Language-specific checks
Android-compatible (no API 30+ calls), -Werror
License
MIT
Version
1.0.0

Quick start

  1. Copy or download the source file into your project (no dependencies).

  2. Optionally, run its tests. The .zip keeps the folder layout they expect; from the language folder:

    implementations/kotlin
    kotlinc *.kt -include-runtime -d t.jar && java -jar t.jar
  3. Call the shared API: function reference

Source

PersianCalendar.kt

· 130 lines
Download
// Copyright (C) 2026 Goudarz Jafari <hi@goudarzjafari.com>
// SPDX-License-Identifier: MIT

/*
 * Solar Hijri (Persian, Jalali, Shamsi) calendar.
 *
 * Algorithm: 33-year arithmetic rule + 78-year correction table,
 * the same algorithm as ICU 77.1+ and ICU4X. Matches the astronomical calendar (52.5 E meridian)
 * for 1178-3000 AP. Months are 1-based; weekdays 0 = Saturday ... 6 = Friday.
 *
 * Inputs outside MIN_YEAR..MAX_YEAR / MIN_JDN..MAX_JDN throw IllegalArgumentException.
 * JVM and Android (the java.time helpers need API 26+ or core library desugaring).
 */
package persiancalendar

import java.time.LocalDate

data class PersianDate(val year: Int, val month: Int, val day: Int)

object PersianCalendar {
    /** Years checked against the astronomical calendar. */
    const val VERIFIED_MIN_YEAR = 1178
    const val VERIFIED_MAX_YEAR = 3000

    /** Accepted input range. Within it every intermediate value fits in 32 bits. */
    const val MIN_YEAR = -100_000
    const val MAX_YEAR = 100_000
    /** 1 Farvardin -100000 (Gregorian -99379-03-29). */
    const val MIN_JDN = -34_576_287L
    /** 29 Esfand 100000 (Gregorian 100622-03-13). */
    const val MAX_JDN = 38_472_562L

    private const val EPOCH_JDN = 1948320L
    private const val UNIX_EPOCH_JDN = 2440588L // JDN of 1970-01-01

    private val CORRECTIONS = intArrayOf(
        1502, 1601, 1634, 1667, 1700, 1733, 1766, 1799, 1832, 1865, 1898, 1931,
        1964, 1997, 2030, 2059, 2063, 2096, 2129, 2158, 2162, 2191, 2195, 2224,
        2228, 2257, 2261, 2290, 2294, 2323, 2327, 2356, 2360, 2389, 2393, 2422,
        2426, 2455, 2459, 2488, 2492, 2521, 2525, 2554, 2558, 2587, 2591, 2620,
        2624, 2653, 2657, 2686, 2690, 2719, 2723, 2748, 2752, 2756, 2781, 2785,
        2789, 2818, 2822, 2847, 2851, 2855, 2880, 2884, 2888, 2913, 2917, 2921,
        2946, 2950, 2954, 2979, 2983, 2987,
    )

    /** Years the 33-year rule calls leap but are not; the next year is leap instead (immutable copy). */
    val NON_LEAP_CORRECTION: List<Int> = java.util.Collections.unmodifiableList(CORRECTIONS.toList())

    // Unmodifiable lists: cannot be changed even when cast to MutableList (works on every Android API level).
    val MONTH_NAMES_FA: List<String> = names("فروردین", "اردیبهشت", "خرداد", "تیر", "مرداد", "شهریور",
        "مهر", "آبان", "آذر", "دی", "بهمن", "اسفند")
    val MONTH_NAMES_EN: List<String> = names("Farvardin", "Ordibehesht", "Khordad", "Tir", "Mordad", "Shahrivar",
        "Mehr", "Aban", "Azar", "Dey", "Bahman", "Esfand")
    val WEEKDAY_NAMES_FA: List<String> = names("شنبه", "یکشنبه", "دوشنبه", "سه‌شنبه", "چهارشنبه", "پنجشنبه", "جمعه")
    val WEEKDAY_NAMES_EN: List<String> = names("Saturday", "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday")

    private fun names(vararg n: String): List<String> = java.util.Collections.unmodifiableList(n.toList())

    private fun isCorrection(year: Long) =
        year in 1502L..2987L && CORRECTIONS.binarySearch(year.toInt()) >= 0

    private fun checkYear(year: Int) =
        require(year in MIN_YEAR..MAX_YEAR) { "year out of range [$MIN_YEAR, $MAX_YEAR]: $year" }

    private fun checkJdn(jdn: Long) =
        require(jdn in MIN_JDN..MAX_JDN) { "jdn out of range [$MIN_JDN, $MAX_JDN]: $jdn" }

    /** True if the Persian year has 366 days (Esfand has 30 days). */
    fun isLeapYear(year: Int): Boolean {
        checkYear(year)
        return when {
            isCorrection(year.toLong()) -> false
            isCorrection(year - 1L) -> true
            else -> (25L * year + 11).mod(33L) < 8
        }
    }

    /** 29, 30 or 31. */
    fun daysInMonth(year: Int, month: Int): Int {
        checkYear(year)
        return when (month) {
            in 1..6 -> 31
            in 7..11 -> 30
            12 -> if (isLeapYear(year)) 30 else 29
            else -> throw IllegalArgumentException("month out of range [1, 12]: $month")
        }
    }

    /** True for a real Persian date in the accepted range; never throws. */
    fun isValidDate(year: Int, month: Int, day: Int): Boolean =
        year in MIN_YEAR..MAX_YEAR && month in 1..12 && day >= 1 && day <= daysInMonth(year, month)

    private fun nowruzJdn(year: Long): Long {
        val jdn = EPOCH_JDN + 365 * (year - 1) + (8 * year + 21).floorDiv(33L)
        return if (isCorrection(year - 1)) jdn - 1 else jdn
    }

    private fun daysBeforeMonth(month: Int): Int = if (month <= 7) 31 * (month - 1) else 30 * (month - 1) + 6

    /** Julian Day Number of a Persian date. */
    fun toJdn(year: Int, month: Int, day: Int): Long {
        require(isValidDate(year, month, day)) { "invalid Persian date: $year/$month/$day" }
        return nowruzJdn(year.toLong()) + daysBeforeMonth(month) + day - 1
    }

    /** Persian date of a Julian Day Number in [MIN_JDN]..[MAX_JDN]. */
    fun fromJdn(jdn: Long): PersianDate {
        checkJdn(jdn)
        var year = 1 + (33 * (jdn - EPOCH_JDN) + 3).floorDiv(12053L)
        while (jdn >= nowruzJdn(year + 1)) year++
        while (jdn < nowruzJdn(year)) year--
        val doy = (jdn - nowruzJdn(year)).toInt() // 0-based
        return if (doy < 186) PersianDate(year.toInt(), doy / 31 + 1, doy % 31 + 1)
        else PersianDate(year.toInt(), (doy - 186) / 30 + 7, (doy - 186) % 30 + 1)
    }

    /** 0 = Saturday (شنبه) ... 6 = Friday (جمعه). */
    fun dayOfWeek(year: Int, month: Int, day: Int): Int = (toJdn(year, month, day) + 2).mod(7L).toInt()

    /** 1 ... 365/366. */
    fun dayOfYear(year: Int, month: Int, day: Int): Int {
        require(isValidDate(year, month, day)) { "invalid Persian date: $year/$month/$day" }
        return daysBeforeMonth(month) + day
    }

    // JVM / Android (API 26+, or with desugaring) interop
    fun fromLocalDate(date: LocalDate): PersianDate = fromJdn(date.toEpochDay() + UNIX_EPOCH_JDN)
    fun toLocalDate(year: Int, month: Int, day: Int): LocalDate =
        LocalDate.ofEpochDay(toJdn(year, month, day) - UNIX_EPOCH_JDN)
}

Tests

PersianCalendarTest.kt

133 lines
KotlinDownload
// Copyright (C) 2026 Goudarz Jafari <hi@goudarzjafari.com>
// SPDX-License-Identifier: MIT

// Checks PersianCalendar.kt against /data.
// Run: kotlinc *.kt -include-runtime -d test.jar && java -jar test.jar ../../data
package persiancalendar

import java.io.File
import java.time.LocalDate

private var checks = 0

private fun check(ok: Boolean, context: () -> Any) {
    checks++
    if (!ok) throw AssertionError("failed: ${context()}")
}

fun main(args: Array<String>) {
    val dataDir = args.firstOrNull() ?: "../../data"
    fun csv(name: String) = File(dataDir, name).readLines().drop(1).filter { it.isNotBlank() }.map { it.split(",") }
    val pc = PersianCalendar

    for (r in csv("years.csv")) {
        val y = r[0].toInt()
        val leap = r[1] == "1"
        check(pc.isLeapYear(y) == leap) { "leap $y" }
        check(pc.daysInMonth(y, 12) == if (leap) 30 else 29) { "esfand $y" }
        check(pc.toLocalDate(y, 1, 1) == LocalDate.parse(r[3])) { "nowruz $y" }
        check(pc.toJdn(y, 1, 1) == r[4].toLong()) { "jdn $y" }
        // every day of the year against the ground truth, both directions
        for (doy in 0 until r[2].toInt()) {
            val m = if (doy < 186) doy / 31 + 1 else (doy - 186) / 30 + 7
            val d = if (doy < 186) doy % 31 + 1 else (doy - 186) % 30 + 1
            val jdn = r[4].toLong() + doy
            check(pc.fromJdn(jdn) == PersianDate(y, m, d) && pc.toJdn(y, m, d) == jdn) { "$y/$m/$d" }
        }
        check(pc.dayOfWeek(y, 1, 1) == r[5].toInt()) { "weekday $y" }
    }
    for (r in csv("test-vectors.csv")) {
        val v = r.map { it.toInt() }
        val p = PersianDate(v[0], v[1], v[2])
        val g = LocalDate.of(v[3], v[4], v[5])
        check(pc.toLocalDate(v[0], v[1], v[2]) == g) { p }
        check(pc.fromLocalDate(g) == p) { g }
        check(pc.toJdn(v[0], v[1], v[2]) == v[6].toLong()) { p }
        check(pc.fromJdn(v[6].toLong()) == p) { p }
        check(pc.dayOfWeek(v[0], v[1], v[2]) == v[7]) { p }
    }
    val first = pc.toJdn(PersianCalendar.VERIFIED_MIN_YEAR, 1, 1)
    val lastYear = PersianCalendar.VERIFIED_MAX_YEAR
    val last = pc.toJdn(lastYear, 12, pc.daysInMonth(lastYear, 12))
    var prev = pc.fromJdn(first - 1)
    for (jdn in first..last) {
        val d = pc.fromJdn(jdn)
        check(pc.toJdn(d.year, d.month, d.day) == jdn) { jdn }
        val consecutive = (d.day == prev.day + 1 && d.month == prev.month && d.year == prev.year) ||
            (d.day == 1 && ((d.month == prev.month + 1 && d.year == prev.year) ||
                (d.month == 1 && prev.month == 12 && d.year == prev.year + 1)))
        check(consecutive) { jdn }
        prev = d
    }
    // Extrapolated years: years <= 0 make intermediate values negative (floor division matters).
    check(pc.toJdn(-1000, 1, 1) == 1582713L) { "-1000" }
    check(pc.toJdn(0, 1, 1) == 1947955L) { "0" }
    check(pc.toJdn(4000, 1, 1) == 3408925L) { "4000" }
    check(pc.fromJdn(0) == PersianDate(-5334, 9, 3)) { "jdn 0" }
    check(pc.dayOfWeek(-1000, 1, 1) == 1) { "weekday -1000" }
    check(pc.isLeapYear(-3) && !pc.isLeapYear(-1000)) { "negative leap years" }
    for ((firstYear, lastYear) in listOf(-1000 to 1177, 3001 to 4000)) {
        val a = pc.toJdn(firstYear, 1, 1)
        val b = pc.toJdn(lastYear, 12, pc.daysInMonth(lastYear, 12))
        var p = pc.fromJdn(a - 1)
        for (jdn in a..b) {
            val d = pc.fromJdn(jdn)
            check(pc.isValidDate(d.year, d.month, d.day) && pc.toJdn(d.year, d.month, d.day) == jdn) { jdn }
            val consecutive = (d.day == p.day + 1 && d.month == p.month && d.year == p.year) ||
                (d.day == 1 && ((d.month == p.month + 1 && d.year == p.year) ||
                    (d.month == 1 && p.month == 12 && d.year == p.year + 1)))
            check(consecutive) { jdn }
            p = d
        }
    }
    check(pc.isValidDate(1403, 12, 30)) { "1403/12/30" }
    check(!pc.isValidDate(1404, 12, 30)) { "1404/12/30" }
    check(pc.isValidDate(1404, 6, 31)) { "1404/6/31" }
    check(!pc.isValidDate(1404, 7, 31)) { "1404/7/31" }
    check(!pc.isValidDate(1404, 13, 1)) { "1404/13/1" }
    check(!pc.isValidDate(1404, 0, 1)) { "1404/0/1" }
    check(!pc.isValidDate(1404, 1, 0)) { "1404/1/0" }
    check(runCatching { pc.toJdn(1404, 12, 30) }.isFailure) { "should throw" }
    check(pc.fromLocalDate(LocalDate.of(2025, 3, 21)) == PersianDate(1404, 1, 1)) { "2025-03-21" }
    check(pc.fromLocalDate(LocalDate.of(1979, 2, 11)) == PersianDate(1357, 11, 22)) { "1979-02-11" }
    check(pc.dayOfYear(1404, 7, 1) == 187) { "doy" }
    check(PersianCalendar.WEEKDAY_NAMES_EN[pc.dayOfWeek(1404, 1, 1)] == "Friday") { "friday" }
    // Limits: exact boundaries, and fast rejection of anything outside (no hang, no overflow).
    check(pc.toJdn(PersianCalendar.MIN_YEAR, 1, 1) == PersianCalendar.MIN_JDN) { "MIN_JDN" }
    check(pc.toJdn(PersianCalendar.MAX_YEAR, 12, 29) == PersianCalendar.MAX_JDN) { "MAX_JDN" }
    check(pc.fromJdn(PersianCalendar.MIN_JDN) == PersianDate(-100_000, 1, 1)) { "from MIN_JDN" }
    check(pc.fromJdn(PersianCalendar.MAX_JDN) == PersianDate(100_000, 12, 29)) { "from MAX_JDN" }
    for (bad in listOf(PersianCalendar.MIN_JDN - 1, PersianCalendar.MAX_JDN + 1, Long.MAX_VALUE, Long.MIN_VALUE, 1L shl 53)) {
        check(runCatching { pc.fromJdn(bad) }.exceptionOrNull() is IllegalArgumentException) { "fromJdn $bad" }
    }
    for (bad in listOf(PersianCalendar.MIN_YEAR - 1, PersianCalendar.MAX_YEAR + 1, Int.MAX_VALUE, Int.MIN_VALUE)) {
        check(!pc.isValidDate(bad, 1, 1)) { "isValidDate $bad" }
        check(runCatching { pc.toJdn(bad, 1, 1) }.exceptionOrNull() is IllegalArgumentException) { "toJdn $bad" }
        check(runCatching { pc.isLeapYear(bad) }.exceptionOrNull() is IllegalArgumentException) { "isLeapYear $bad" }
    }
    check(runCatching { pc.fromLocalDate(LocalDate.MAX) }.exceptionOrNull() is IllegalArgumentException) { "LocalDate.MAX" }
    @Suppress("UNCHECKED_CAST")
    check(runCatching { (PersianCalendar.MONTH_NAMES_FA as MutableList<String>)[0] = "X" }.isFailure) { "immutable names" }
    @Suppress("UNCHECKED_CAST")
    check(runCatching { (PersianCalendar.NON_LEAP_CORRECTION as MutableList<Int>)[0] = 1 }.isFailure) { "immutable table" }
    check(PersianCalendar.WEEKDAY_NAMES_FA[3] == "سه‌شنبه") { "ZWNJ" }
    // Every year MIN_YEAR..MAX_YEAR: years are contiguous, first and last day round-trip, and the leap
    // years sit where every other implementation (and ICU 77.1+) puts them (checksums).
    var expected = PersianCalendar.MIN_JDN
    var leaps = 0L
    var nowruzSum = 0L
    for (y in PersianCalendar.MIN_YEAR..PersianCalendar.MAX_YEAR) {
        val nowruz = pc.toJdn(y, 1, 1)
        val leap = if (pc.isLeapYear(y)) 1 else 0
        if (nowruz != expected || pc.fromJdn(nowruz) != PersianDate(y, 1, 1) || pc.daysInMonth(y, 12) != 29 + leap ||
            pc.fromJdn(nowruz + 364 + leap) != PersianDate(y, 12, 29 + leap)
        ) {
            check(false) { "year $y" }
        }
        leaps += leap
        nowruzSum += nowruz
        expected = nowruz + 365 + leap
    }
    check(expected - 1 == PersianCalendar.MAX_JDN && leaps == 48_485L && nowruzSum == 389_592_978_180L) { "full-range checksums" }
    println("OK: $checks checks passed")
}

Other languages