cal_to_jd()

PHP cal_to_jd(): Ein Kalenderdatum in eine julianische Tageszahl umwandeln

Die Funktion cal_to_jd() wandelt ein Datum aus einem unterstützten Kalender (Gregorianisch, Julianisch, Jüdisch oder Französisch-Republikanisch) in eine julianische Tageszahl um — eine einzelne Ganzzahl, die einen Tag eindeutig identifiziert. Da das Ergebnis eine einfache Zahl ist, eignet sie sich hervorragend als gemeinsamer Nenner zum Vergleich von Datumsangaben, zur Berechnung der Anzahl von Tagen zwischen zwei Daten oder zur Konvertierung zwischen Kalendersystemen.

Diese Seite behandelt die Signatur der Funktion, ein funktionierendes Beispiel, die unterstützten Kalender, die häufigsten Fehlerquellen und weiterführende Informationen.

Hinweis: cal_to_jd() ist Teil der PHP Calendar-Erweiterung. Die Erweiterung wird mit PHP mitgeliefert, muss aber aktiviert sein (sie wird bei den meisten Builds standardmäßig einkompiliert). Wenn die Funktion nicht definiert ist, aktivieren Sie ext-calendar.

Was ist eine julianische Tageszahl?

Die julianische Tageszahl (oft als Julian Day Number, JDN bezeichnet) ist eine fortlaufende Zählung von Tagen, beginnend mit dem 1. Januar 4713 v. Chr. im proleptischen Julianischen Kalender, der als Tag 0 definiert ist. Jedes spätere Datum wird einer größeren positiven Ganzzahl zugeordnet; frühere Daten wären negativ.

Diese Zählung ist kalenderunabhängig: Sie hängt nicht von Monaten, Schaltjahren oder dem Kalendersystem einer Kultur ab. Daher ist sie die standardmäßige „Pivot"-Darstellung in der Astronomie, im wissenschaftlichen Rechnen und in jedem Code, der über verschiedene Kalender hinweg interoperabel sein muss.

Verwechseln Sie nicht die julianische Tageszahl (eine Tagesnummer) mit dem Julianischen Kalender (dem vorgregorianischen Kalender). Trotz des ähnlichen Namens haben sie nichts miteinander zu tun.

Syntax

cal_to_jd(int $calendar, int $month, int $day, int $year): int

Rückgabewert: die julianische Tageszahl als int, oder 0, wenn das Datum für den gewählten Kalender ungültig ist.

Einfaches Beispiel

Den 2. März 2023 (Gregorianisch) in seine julianische Tageszahl umwandeln:

Beachten Sie die Reihenfolge der Argumente: Sie lautet month, day, year, nicht Tag-Monat-Jahr oder Jahr-Monat-Tag. Diese Verwechslung ist der mit Abstand häufigste Fehler bei cal_to_jd().

Die Kalenderkonstante auswählen

Das erste Argument legt fest, zu welchem Kalender Ihre month/day/year-Werte gehören:

Dasselbe Kalenderdatum kann je nach übergebener Konstante unterschiedliche julianische Tageszahlen ergeben, daher immer die Konstante an den Kalender anpassen, aus dem die Eingabe stammt:

<?php
// October 15, 1582 — the day the Gregorian calendar began.
echo cal_to_jd(CAL_GREGORIAN, 10, 15, 1582), "\n"; // 2299161
echo cal_to_jd(CAL_JULIAN,    10, 5,  1582), "\n";  // 2299161
?>

Beide geben dieselbe julianische Tageszahl aus, da die Gregorianische Reform 10 Tage übersprungen hat: Gregorianischer 15. Oktober und Julianischer 5. Oktober sind derselbe physische Tag.

Häufige Fehlerquellen

• Ungültige Datumsangaben geben 0 zurück, nicht false. Die Übergabe eines nicht existierenden Datums wie dem 30. Februar ergibt 0. Validieren Sie Benutzereingaben mit checkdate(), bevor Sie konvertieren, wenn Sie fehlerhafte Datumsangaben erkennen müssen.
• Die Reihenfolge der Argumente ist month, day, year. Siehe den Hinweis oben.
• Die Erweiterung muss aktiviert sein. Der Aufruf setzt ext-calendar voraus; ein Fehler „undefined function" bedeutet, dass sie nicht geladen ist.

Hin- und Rückkonvertierung mit cal_from_jd()

cal_to_jd() hat eine Umkehrfunktion: cal_from_jd() wandelt eine julianische Tageszahl zurück in ein Kalenderdatum um. Zusammen ermöglichen sie die Konvertierung zwischen Kalendersystemen, indem die julianische Tageszahl als neutraler Pivot verwendet wird:

<?php
$jd = cal_to_jd(CAL_GREGORIAN, 3, 2, 2023);

$date = cal_from_jd($jd, CAL_GREGORIAN);
echo $date['date']; // 3/2/2023
?>

Verwandte Funktionen

• cal_from_jd() — die Umkehrfunktion: julianische Tageszahl in ein Kalenderdatum umwandeln.
• cal_info() — Metadaten (Monatsnamen usw.) zu einem Kalender.
• cal_days_in_month() — Anzahl der Tage in einem bestimmten Monat.
• gregoriantojd(), juliantojd(), jewishtojd(), frenchtojd() — kalenderspezifische Abkürzungen für dieselbe Konvertierung.
• Siehe die vollständige Übersicht der PHP-Kalenderfunktionen.

Fazit

cal_to_jd() reduziert jedes unterstützte Kalenderdatum auf eine einzelne Ganzzahl — die julianische Tageszahl — und bietet damit eine kalender­neutrale Möglichkeit, Datumsangaben zu vergleichen, Zeitabstände zu messen und zwischen Kalendern zu konvertieren. Denken Sie an die Argumentreihenfolge month, day, year, wählen Sie die Kalenderkonstante passend zu Ihrer Eingabe und verwenden Sie cal_from_jd() für die Rückkonvertierung.

Übungen