juliantojd()

Introdução

A função juliantojd() converte uma data do calendário juliano em uma Contagem de Dias Julianos — um único número inteiro que conta os dias de forma contínua a partir do meio-dia UTC de 1.º de janeiro de 4713 a.C. Como cada data corresponde a um único número, a Contagem de Dias Julianos facilita calcular o número de dias entre duas datas ou converter datas entre diferentes calendários (gregoriano, judaico, republicano francês e assim por diante).

Este capítulo aborda a assinatura da função, a ordem dos argumentos (uma fonte comum de bugs), os intervalos válidos, os valores de retorno e vários exemplos práticos. Também mostra como a Contagem de Dias Julianos (um inteiro, como o PHP a utiliza) se relaciona com a Data Juliana astronômica (que pode incluir uma fração correspondente à hora do dia).

Terminologia: as funções de calendário do PHP trabalham com a Contagem de Dias Julianos — um número inteiro de dias completos. Os astrônomos usam a Data Juliana, um conceito muito próximo, que acrescenta uma parte fracionária para a hora do dia (uma Data Juliana começa ao meio-dia, portanto JD = contagem + 0,5 à meia-noite).

Sintaxe

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

A ordem dos argumentos é mês, dia, ano — e não dia, mês, ano. Trocar essa ordem é o erro mais comum com esta função, e um valor fora do intervalo retorna 0 silenciosamente, em vez de gerar um erro.

Valor de retorno: a Contagem de Dias Julianos como um inteiro, ou 0 se a data estiver fora do intervalo válido.

juliantojd() faz parte da extensão Calendar do PHP, que precisa estar habilitada (ela vem incluída na maioria das distribuições do PHP).

Exemplo básico

Converta 15 de outubro de 1582 — o primeiro dia do calendário gregoriano em muitos países — de uma data do calendário juliano para uma Contagem de Dias Julianos:

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

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

Observe a ordem: $month vem primeiro. Passar o dia primeiro por engano normalmente produz um mês inválido (por exemplo, juliantojd(15, 10, 1582)), o que retorna 0.

Detectando datas inválidas

Como um valor fora do intervalo retorna 0 em vez de lançar uma exceção, verifique o resultado antes de usá-lo. (Observe que um dia ligeiramente fora do intervalo, como 30 de fevereiro, é normalizado em vez de rejeitado; o que provoca o 0 é um mês ou ano fora do intervalo.)

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

Calculando os dias entre duas datas

Um motivo comum para converter em uma Contagem de Dias Julianos é a aritmética: subtraia duas contagens para obter o número de dias entre as datas, independentemente dos meses ou dos anos bissextos.

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

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

Contagem de Dias Julianos vs. Data Juliana astronômica

O PHP retorna um inteiro de dias completos. Para obter a Data Juliana astronômica — que começa ao meio-dia — some 0.5 a um carimbo de data/hora da meia-noite:

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

Para fazer o caminho inverso, subtraia 0.5 e tome a parte inteira:

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

Quando eu usaria isto?

• Aritmética de datas que deve ignorar a duração dos meses e os anos bissextos — converta ambas as datas em uma contagem e subtraia.
• Conversão de calendários — combine juliantojd() com jdtogregorian() ou jdtojewish() para traduzir uma data juliana para outro calendário.
• Astronomia e cronologia, onde a contagem contínua de dias é a forma padrão de referenciar eventos históricos e celestes.

Funções relacionadas

• jdtojulian() — o inverso: da Contagem de Dias Julianos de volta para uma data do calendário juliano.
• gregoriantojd() — converte uma data gregoriana em uma Contagem de Dias Julianos.
• jddayofweek() — descobre o dia da semana de uma Contagem de Dias Julianos.
• jdmonthname() — obtém o nome do mês de uma Contagem de Dias Julianos.

Resumo

juliantojd() transforma uma data do calendário juliano em uma Contagem de Dias Julianos, usando a ordem de argumentos mês, dia, ano. Ela retorna um inteiro (ou 0 para datas inválidas), que você pode subtrair para medir intervalos de dias, converter entre calendários ou usar para obter a Data Juliana astronômica somando 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];

Prática