پرش به محتوای اصلی
فهرست مطالب

داده و راستی‌آزمایی

تطبیق متقابل با موتورهای ICU و ICU4X

۶ دقیقه مطالعهبه‌روزرسانی

این مجموعه تست، برای تک‌تک روزهای سال ۱۱۷۸ تا ۳۰۰۰ ه‍.ش (۶۶۵٬۸۳۷ روز در ۱٬۸۲۳ سال)، سه مرجع مستقل رو در هر دو جهت (شمسی به میلادی و میلادی به شمسی) با هم مقایسه می‌کنه:

  1. تاریخ درست (مرجع نجومی): فایل data/years.csv که با جدول رسمی مرکز تقویم دانشگاه تهران مطابقت کامل داره؛
  2. پیاده‌سازی‌های این مخزن: هر ۱۴ زبان موجود در پوشهٔ implementations/؛
  3. تمام نسخه‌ها و پیاده‌سازی‌های استاندارد ICU: شامل ICU4X (در Rust)، ICU4J (در جاوا، کاتلین و اسکالا) و ICU4C از طریق Intl در جاوااسکریپت/تایپ‌اسکریپت، intl در PHP، و فراخوانی مستقیم C API از داخل Python (ctypes)، Ruby (Fiddle)، Go (purego بدون نیاز به cgo)، C#‎ (P/Invoke)، Dart (dart:ffi) و C (dlopen/LoadLibrary).

علاوه بر این‌ها، دو موتور مستقل دیگه هم چک می‌شن: Temporal در جاوااسکریپت (که در Node.js 26 و موتور V8 بر پایهٔ temporal_rs و ICU4X ساخته شده، نه ICU4C) و کلاس System.Globalization.PersianCalendar در دات‌نت. از اونجایی که خود PostgreSQL تقویم شمسی داخلی نداره، توابع SQL ما روی یک موتور واقعی PostgreSQL (PGlite) اجرا می‌شن و روزبه‌روز با ICU و Temporal مقایسه می‌شن.

در این تست‌ها، نسخه‌های ICU 77.1 به بعد باید در تمام روزها دقیقا با تقویم نجومی یکی باشن؛ و برای نسخه‌های ICU 76.1 و قدیمی‌تر (که جدول اصلاحی ۷۸ ساله رو ندارن)، اسکریپت‌ها چک می‌کنن که خروجیِ اون‌ها دقیقا با قاعدهٔ ۳۳ سالهٔ ساده مطابقت داشته باشه.

Engine Called from Version Result across all 665,837 days (1178–3000 AP)
ICU4X icu_calendar (Date API) Rust 2.4.0 ✅ 100% match on every day, both directions
ICU4X calendrical_calculations (fast_persian_from_fixed, fixed_from_fast_persian, is_leap_year) Rust 0.2.4 ✅ 100% match on every day, both directions; identical to our from_jdn across all 73,048,850 days of the full accepted range (−100000…100000 AP)
ICU4J Java, Kotlin, Scala 76.1 ❌ Differs on 28,548 days: matches the plain 33-year rule (first wrong Nowruz is 1503 AP)
ICU4J Java 77.1, 78.1, 78.2, 78.3, 79.1 ✅ 100% match on every day, both directions
ICU4J Kotlin, Scala 78.3, 79.1 ✅ 100% match on every day, both directions
ICU4C JavaScript & TypeScript Intl 76.1 (Node.js 23.3) ❌ Differs on 28,548 days: matches the plain 33-year rule
ICU4C JavaScript & TypeScript Intl 77.1 (Node.js 24.0), 78.3 (Node.js 26.8) ✅ 100% match on every day
ICU4C PHP intl 77.1 (PHP 8.5.12) ✅ 100% match on every day, both directions
ICU4C Python, Ruby, Go, C#, Dart, C 76.1 ❌ Differs on 28,548 days: matches the plain 33-year rule, both directions
ICU4C Python, Ruby, Go, C#, Dart, C 77.1, 78.3, 79.1 ✅ 100% match on every day, both directions
Temporal (temporal_rs, ICU4X) JavaScript, TypeScript, PostgreSQL harness Node.js 26.8 ✅ 100% match on every day, both directions
.NET System.Globalization.PersianCalendar C# .NET 8.0 ❌ Differs on 2,196 days across 12 years (first discrepancy in 1535 AP)
This repository's implementations All 14 languages – ✅ 100% match on every day, both directions

Full accepted range check (−100000…100000 AP): Outside 1178–3000 AP there is no astronomical ground truth, but because ICU 77.1+, ICU4X, Temporal, and our code all implement the same arithmetic calendar, they must agree across the entire range. Our Python (ICU4C), Java (ICU4J), and JavaScript (Temporal) runners also compare the first day, last day, and length of all 200,001 years:

Engine Version Years in −100000…100000 that differ
ICU4C, ICU4J 77.1, 79.1 0
ICU4C, ICU4J 76.1 78 — the exact 78 years of the correction table
Temporal (temporal_rs) Node.js 26.8 0
ICU4X calendrical_calculations 0.2.4 0 (verified on every single day, not just every year)

When did ICU get the 78-year correction table? In ICU 77.1. Although ticket ICU-22736 was committed in September 2024, it was not included in the ICU 76.1 release (verified in the release-76-1 and release-77-1 source tags for both ICU4C and ICU4J). Note that ICU 76.1 is still 100% accurate for every date up through 29 Esfand 1502 (19 March 2124).

نکات مهم دربارهٔ نتایج بالا

پیوند به بخش نکات مهم دربارهٔ نتایج بالا
  • اضافه شدن جدول اصلاحی ۷۸ ساله در ICU 77.1: تغییر مربوط به جدول اصلاحی (ICU-22736) در سپتامبر ۲۰۲۴ ثبت شد و از نسخهٔ ICU 77.1 (مارس ۲۰۲۵) وارد ICU4C و ICU4J شد. نسخهٔ ICU 76.1 این جدول رو نداره، اما تا پایان ۲۹ اسفند ۱۵۰۲ (۱۹ مارس ۲۱۲۴) برای تمام تاریخ‌ها کاملا دقیقه.
  • مقایسهٔ کل بازهٔ ۲۰۰٬۰۰۱ ساله (-100000 تا 100000): در کل این بازه (۷۳٬۰۴۸٬۸۵۰ روز)، خروجی پیاده‌سازی‌های ما با ICU 77.1 به بعد، ICU4X و Temporal بدون حتی یک روز اختلاف، ۱۰۰٪ یکسان است.

How ICU4C is called from Python, Ruby, Go, C#, Dart, and C

پیوند به بخش How ICU4C is called from Python, Ruby, Go, C#, Dart, and C

None of these test scripts require third-party ICU wrapper packages—they call the ICU4C shared library directly via each language's built-in FFI (Go uses purego so it doesn't even need cgo). Using ICU's UCAL_JULIAN_DAY field (which uses the exact same Julian Day Number definition as our to_jdn/from_jdn), the entire cross-check only needs five C functions and pure integer arguments:

C
UCalendar* cal = ucal_open(NULL, 0, "fa_IR@calendar=persian", UCAL_DEFAULT, &status);

// 1. JDN -> Persian (year, month, day)
ucal_clear(cal);
ucal_set(cal, UCAL_JULIAN_DAY, 2460756);              // 2025-03-21
ucal_get(cal, UCAL_EXTENDED_YEAR, &status);           // 1404
ucal_get(cal, UCAL_MONTH, &status);                   // 0   (ICU months are 0-based!)
ucal_get(cal, UCAL_DATE, &status);                    // 1

// 2. Persian (year, month, day) -> JDN
ucal_clear(cal);
ucal_set(cal, UCAL_EXTENDED_YEAR, 1403);
ucal_set(cal, UCAL_MONTH, 11);                        // 11 = Esfand
ucal_set(cal, UCAL_DATE, 30);
ucal_get(cal, UCAL_JULIAN_DAY, &status);              // 2460755 (= 2025-03-20)

(Because ICU appends its major version to exported C symbol names—such as ucal_open_77—our FFI loaders automatically probe both unsuffixed and version-suffixed symbols.)

Language Command (run from its subfolder) Requirements
Rust (ICU4X) cargo run --release Rust 1.85+
JavaScript (Intl, Temporal) node check.mjs (run with each Node.js version you want to test) Node.js
TypeScript (Intl, Temporal) node check.mjs typescript (from javascript/) Node.js 23.6+
Java (ICU4J) javac -cp icu4j-X.jar -d out IcuCheck.java ../../../implementations/java/PersianCalendar.java
java -cp "icu4j-X.jar:out" IcuCheck ../../../data/years.csv (use ; instead of : on Windows)
JDK 17+, ICU4J .jar from Maven Central
Kotlin (ICU4J) kotlinc -cp icu4j-X.jar IcuCheck.kt ../../../implementations/kotlin/PersianCalendar.kt -include-runtime -d check.jar
java -cp "icu4j-X.jar:check.jar" IcuCheckKt ../../../data/years.csv
Kotlin 2, JDK 17+
Scala (ICU4J) scala run IcuCheck.scala ../../../implementations/scala/PersianCalendar.scala --dep com.ibm.icu:icu4j:79.1 --main-class IcuCheck -- ../../../data/years.csv Scala 3 (scala-cli)
PHP (intl) php check.php PHP with intl enabled
Python (ctypes) python check.py [path/to/icu/bin_or_lib] Python 3.8+, ICU4C shared libraries
Ruby (Fiddle) ruby check.rb [path/to/icu/bin_or_lib] Ruby 3+, ICU4C shared libraries
Go (purego) go run . [path/to/icu/bin_or_lib] Go 1.25+, ICU4C shared libraries
C# (P/Invoke + .NET PersianCalendar) dotnet run -c Release -- [path/to/icu/bin_or_lib] .NET 8 SDK, ICU4C shared libraries
Dart (dart:ffi) dart pub get && dart run bin/check.dart [path/to/icu/bin_or_lib] Dart 3, ICU4C shared libraries
C (dlopen/LoadLibrary) cc -std=c99 -O2 check.c ../../../implementations/c/persian_calendar.c -o check
./check <ICU folder> <ICU major version>
C99 compiler, ICU4C shared libraries
PostgreSQL (PGlite) npm install && node check.mjs Node.js 22+

If you don't pass an ICU folder path, the Python, Ruby, Go, C#, and Dart runners automatically search for the system's installed ICU4C library (e.g., /usr/lib/…/libicui18n.so.NN on Linux or Homebrew icu4c on macOS). To test against a specific ICU release, download the prebuilt ICU4C binaries from GitHub Releases (for example, icu4c-79.1-Win64-MSVC2026.zip) and pass the directory containing icuinNN.dll / libicui18n.so.NN:

Shell
python check.py                                   # Ubuntu 24.04: uses system ICU 74 (verified against the plain 33-year rule)
python check.py C:\icu\icu4c-79.1\bin64           # Windows with ICU 79.1
ruby check.rb /opt/homebrew/opt/icu4c/lib         # macOS with Homebrew ICU
go run . ./icu-76.1/lib                           # Any downloaded ICU release folder

Every runner prints a single summary line and exits with a non-zero code if a single day mismatches.