juliantojd()

Introduzione

La funzione juliantojd() converte una data del calendario giuliano in un Julian Day Count, ovvero un unico numero intero che conta i giorni in modo continuo a partire da mezzogiorno UTC del 1° gennaio 4713 a.C. Poiché ogni data corrisponde a un solo numero, il Julian Day Count rende semplice calcolare il numero di giorni tra due date o tradurre le date tra calendari diversi (gregoriano, ebraico, rivoluzionario francese e così via).

Questo capitolo tratta la firma della funzione, l'ordine degli argomenti (una fonte frequente di bug), gli intervalli validi, i valori restituiti e diversi esempi pratici. Mostra inoltre come il Julian Day Count (un intero, come lo usa PHP) si relazioni con la Julian Date astronomica (che può includere una frazione che indica l'ora del giorno).

Terminologia: le funzioni di calendario di PHP lavorano con il Julian Day Count, cioè un numero intero di giorni interi. Gli astronomi usano la Julian Date, strettamente correlata, che aggiunge una parte frazionaria per l'ora del giorno (una Julian Date inizia a mezzogiorno, quindi JD = count + 0.5 a mezzanotte).

Sintassi

juliantojd(int $month, int $day, int $year): int

L'ordine degli argomenti è mese, giorno, anno, non giorno, mese, anno. Confondere i due ordini è l'errore più comune con questa funzione, e un valore fuori intervallo restituisce silenziosamente 0 invece di generare un errore.

Valore restituito: il Julian Day Count come intero, oppure 0 se la data non rientra nell'intervallo valido.

juliantojd() fa parte dell'estensione Calendar di PHP, che deve essere abilitata (è inclusa nella maggior parte delle distribuzioni PHP).

Esempio di base

Convertiamo il 15 ottobre 1582, il primo giorno del calendario gregoriano in molti paesi, da data del calendario giuliano a Julian Day Count:

<?php
$month = 10;
$day   = 15;
$year  = 1582;

$jdCount = juliantojd($month, $day, $year);
echo $jdCount; // 2299171
?>

Fai attenzione all'ordine: $month viene per primo. Passare per errore il giorno per primo di solito produce un mese non valido (per esempio juliantojd(15, 10, 1582)), e il risultato è 0.

Rilevare le date non valide

Poiché un valore fuori intervallo restituisce 0 invece di lanciare un'eccezione, controlla il risultato prima di usarlo. (Nota che un giorno leggermente fuori intervallo, come il 30 febbraio, viene normalizzato anziché rifiutato; a provocare lo 0 è un mese o un anno fuori intervallo.)

<?php
$jdCount = juliantojd(13, 1, 2024); // Month 13 does not exist

if ($jdCount === 0) {
    echo "Invalid Julian calendar date";
} else {
    echo $jdCount;
}
// Invalid Julian calendar date
?>

Calcolare i giorni tra due date

Un motivo comune per convertire in un Julian Day Count è l'aritmetica: sottraendo due count si ottiene il numero di giorni tra le date, indipendentemente da mesi o anni bisestili.

<?php
$start = juliantojd(1, 1, 2000);  // 2451558
$end   = juliantojd(12, 31, 2000); // 2451923

echo $end - $start; // 365
?>

Julian Day Count e Julian Date astronomica

PHP restituisce un intero di giorni interi. Per ottenere la Julian Date astronomica, che inizia a mezzogiorno, aggiungi 0.5 per un timestamp a mezzanotte:

<?php
$jdCount = 2451558;
$julianDate = $jdCount + 0.5;
echo $julianDate; // 2451558.5
?>

Per fare il percorso inverso, sottrai 0.5 e prendi la parte intera:

<?php
$julianDate = 2451558.5;
$jdCount = (int) floor($julianDate - 0.5);
echo $jdCount; // 2451558
?>

Quando usarla?

• Aritmetica delle date che deve ignorare la lunghezza dei mesi e gli anni bisestili: converti entrambe le date in un count e sottrai.
• Conversione tra calendari: abbina juliantojd() a jdtogregorian() o jdtojewish() per tradurre una data giuliana in un altro calendario.
• Astronomia e cronologia, dove il conteggio continuo dei giorni è il modo standard per riferirsi a eventi storici e celesti.

Funzioni correlate

• jdtojulian(): l'inversa, da Julian Day Count a data del calendario giuliano.
• gregoriantojd(): converte una data gregoriana in un Julian Day Count.
• jddayofweek(): trova il giorno della settimana per un Julian Day Count.
• jdmonthname(): ottiene il nome del mese per un Julian Day Count.

Riepilogo

juliantojd() trasforma una data del calendario giuliano in un Julian Day Count, usando l'ordine degli argomenti mese, giorno, anno. Restituisce un intero (oppure 0 per le date non valide) che puoi sottrarre per misurare intervalli di giorni, usare per convertire tra calendari o per ricavare la Julian Date astronomica aggiungendo 0.5.

graph TD;
    A[Julian calendar date<br/>month, day, year] --> B[juliantojd()];
    B --> C[Julian Day Count<br/>integer];
    C --> D[jdtojulian() / jdtogregorian()];
    D --> E[Calendar date in another system];

Esercizi