PHP cal_to_jd(): Convertire una data di calendario in un conteggio del giorno giuliano

La funzione cal_to_jd() converte una data da un calendario supportato (Gregoriano, Giuliano, Ebraico o Repubblicano Francese) in un conteggio del giorno giuliano — un singolo intero che identifica univocamente un giorno. Poiché il risultato è semplicemente un numero, rappresenta un comodo denominatore comune per confrontare date, calcolare il numero di giorni tra due date o convertire tra sistemi di calendario.

Questa pagina tratta la firma della funzione, un esempio funzionante, i calendari supportati, gli errori più comuni e i passi successivi.

Nota: cal_to_jd() fa parte dell'estensione Calendar di PHP. L'estensione è inclusa con PHP ma deve essere abilitata (è compilata per impostazione predefinita nella maggior parte delle build). Se la funzione non è definita, abilitare ext-calendar.

Cos'è un conteggio del giorno giuliano?

Il conteggio del giorno giuliano (spesso chiamato numero del giorno giuliano, JDN) è un conteggio continuo di giorni a partire dal 1° gennaio 4713 a.C. nel calendario giuliano prolettivo, definito come giorno 0. Ogni data successiva corrisponde a un intero positivo più grande, mentre le date precedenti sarebbero negative.

Questo conteggio è indipendente dal calendario: non dipende dai mesi, dagli anni bisestili o dal sistema di calendario utilizzato da una cultura. Questo lo rende la rappresentazione "pivot" standard in astronomia, nel calcolo scientifico e in qualsiasi codice che deve interoperare tra diversi calendari.

Non confondere il conteggio del giorno giuliano (un numero di giorno) con il calendario giuliano (il calendario pre-gregoriano). Sono privi di correlazione nonostante il nome simile.

Sintassi

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

Valore restituito: il conteggio del giorno giuliano come int, oppure 0 se la data non è valida per il calendario scelto.

Esempio di base

Convertire il 2 marzo 2023 (Gregoriano) nel suo conteggio del giorno giuliano:

Notare l'ordine degli argomenti: è month, day, year, non day-month-year o year-month-day. Confondere questo ordine è l'errore più comune con cal_to_jd().

Scegliere la costante di calendario

Il primo argomento indica a quale calendario appartengono i valori month/day/year:

La stessa data di calendario può produrre conteggi del giorno giuliano diversi a seconda della costante passata, quindi abbinare sempre la costante al calendario di provenienza dell'input:

<?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
?>

Entrambi stampano lo stesso conteggio del giorno giuliano perché la riforma gregoriana ha saltato 10 giorni: il 15 ottobre gregoriano e il 5 ottobre giuliano sono lo stesso giorno fisico.

Errori comuni

• Le date non valide restituiscono 0, non false. Passare una data inesistente come il 30 febbraio restituisce 0. Validare l'input dell'utente con checkdate() prima della conversione se si ha necessità di rilevare date errate.
• L'ordine degli argomenti è month, day, year. Vedere la nota sopra.
• L'estensione deve essere abilitata. La chiamata dipende da ext-calendar; un errore "undefined function" significa che non è caricata.

Conversione inversa con cal_from_jd()

cal_to_jd() ha un inverso: cal_from_jd() riconverte un conteggio del giorno giuliano in una data di calendario. Insieme permettono di convertire tra sistemi di calendario passando per il conteggio del giorno giuliano come pivot neutro:

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

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

Funzioni correlate

• cal_from_jd() — l'inverso: conteggio del giorno giuliano a data di calendario.
• cal_info() — metadati (nomi dei mesi, ecc.) su un calendario.
• cal_days_in_month() — numero di giorni in un determinato mese.
• gregoriantojd(), juliantojd(), jewishtojd(), frenchtojd() — scorciatoie specifiche per calendario per la stessa conversione.
• Vedere la panoramica completa delle funzioni Calendar PHP.

Conclusione

cal_to_jd() riduce qualsiasi data di calendario supportata a un singolo intero — il conteggio del giorno giuliano — fornendo un modo neutro rispetto al calendario per confrontare date, misurare intervalli e convertire tra calendari. Ricordare l'ordine degli argomenti month, day, year, scegliere la costante di calendario corrispondente all'input e usare cal_from_jd() per convertire nuovamente.

Esercizio